94 lines
6.8 KiB
Markdown
94 lines
6.8 KiB
Markdown
# os-vault — component detail
|
||
|
||
_Leaf file of [../implementation-status.md](../implementation-status.md). Read on demand._
|
||
|
||
**Global os-vault plugin** — `cc-os/plugins/os-vault/` (git-tracked, 2026-06-12); symlinked
|
||
into `~/.claude/plugins/os-vault`. Renamed from `memory` 2026-07-03 (ADR-0018 records the
|
||
marketplace-manifest lesson). Plugin sourcing/port architecture: ADR-0016.
|
||
|
||
## Component inventory
|
||
|
||
- Hooks: `hooks/` — `session_start.py` (SessionStart; staleness check + detached graph
|
||
rebuild, and, as of 2026-07-10, a fast-forward-only `git pull` (`timeout 10 git pull
|
||
--ff-only --quiet`) for `cfg.vault_path` and `cfg.memsearch_dir` before the staleness
|
||
check — silent on success, quiet one-line stderr note on failure (offline machine), never
|
||
blocking; closes the multi-machine push-only gap, mirroring the push style of the sync
|
||
hooks in the opposite direction), `session_context.py` (project graph path only),
|
||
`post_tool_use_write.py`, `session_end.py` (vault journal), `memsearch_sync.py` (second
|
||
SessionEnd hook; memsearch auto-commit+push, 30s timeout), `vault_sync.py` (third
|
||
SessionEnd hook; vault auto-commit+push to forgejo.swansoncloud.com/jared/SecondBrain, 30s
|
||
timeout; mirrors memsearch_sync.py)
|
||
- Shared modules: `config.py` (load_config → frozen Config dataclass), `hook_io.py`
|
||
(read_input → HookInput dataclass), `session_state.py` (record_touch/read_touches;
|
||
encapsulates `/tmp/claude-vault-touched-$SESSION_ID` contract)
|
||
- Skills: `skills/` — query, write, reorganize, onboard-project (assessment-first
|
||
onboarding: surveys repo, classifies excludes by type (11 categories), writes per-project
|
||
`.graphifyignore`, confirms with user, then extracts using `qwen25-coder-7b-16k` — per
|
||
ADR-0017), design-template (routes template-design ↔ new-type-creation: 4-step
|
||
template-design process + injection-economics filter, 9-step new-type lifecycle; backs
|
||
Phase 1 of the SB Content Plan — see `docs/memory-system/09-sb-content-plan.md`)
|
||
- Config: `config.yaml` — vault path, Ollama model (qwen25-coder-7b-16k), env vars
|
||
- Hook wiring: `~/.claude/settings.json` (hook entries invoke `/usr/bin/python3` with
|
||
absolute paths into cc-os)
|
||
- Isolation seam (2026-07-06, WS2): `OS_VAULT_PATH` env var overrides `vault_path` for the
|
||
write skill and every hook via `config.load_config()`; `OS_VAULT_SKIP_REBUILD` suppresses
|
||
the SessionStart graphify rebuild. Added for the eval harness; zero production impact when
|
||
unset.
|
||
|
||
## Build-out history (2026-06-09 → 2026-06-30)
|
||
|
||
- **2026-06-09:** plugin live at `~/.claude/plugins/os-vault/`; build-plan Steps 1, 2a, 2b,
|
||
3, 6 complete (incl. `onboard-project`). Step 1: vault-conventions.md, 6 fixture notes, 14
|
||
Graphify handbook + design notes migrated as scaffolding. Step 4 (memsearch): installed
|
||
via marketplace, `MEMSEARCH_DIR` global, Stop hook verified, search working. Step 5a
|
||
(memsearch git sync): private Forgejo repo, whitelist `.gitignore` (memory/*.md only),
|
||
auto-commit+push SessionEnd hook (ADR-0015; relocated to `memsearch_sync.py` by ADR-0016).
|
||
- **2026-06-15:** Step 5b done — vault initialized as git repo, pushed to private Forgejo
|
||
(52 files; git chosen over Syncthing); auto-commit+push via `vault_sync.py` (runs after
|
||
`session_end.py` so the daily journal note is included). Step 2e pilot done — llf-schema
|
||
(PHP 8.2 WordPress plugin) onboarded via `/os-vault:onboard-project`: 605 nodes / 930
|
||
edges / 52 communities; Ollama doc pass lossy on WordPress docs but AST pass solid. Step
|
||
2d closed — live vault `graphify-out/` is the baseline; fixture-only build superseded.
|
||
All required build steps complete as of this date.
|
||
- **2026-06-17:** onboard-project moved to assessment-first onboarding with per-project
|
||
`.graphifyignore` (ADR-0017); extraction model `qwen25-coder-7b-16k` (16k-context build of
|
||
qwen2.5-coder:7b — larger context window cuts chunk count per doc, the main speed lever).
|
||
- **2026-06-30:** SB Content Plan Phase 1 complete (`docs/memory-system/09-sb-content-plan.md`,
|
||
issues #1–#6): vault-conventions.md reconciled to one authoritative typed frontmatter
|
||
schema (slug-only filenames; `source:` and `scope` are frontmatter fields, not tags); new
|
||
`/os-vault:design-template` skill; three templates in `~/Documents/SecondBrain/_templates/`
|
||
(`howto.md`, `convention.md`, `reference.md` with four-subtype variant selector), each
|
||
dogfooded; four proof-of-concept notes patched. Phase 2 (issue #7) remains open as the
|
||
steady-state migration/onboarding epic (no code).
|
||
|
||
## Write-behavior eval (WS2)
|
||
|
||
- Harness (2026-07-06): `plugins/os-vault/eval/` — held-out unprompted vault-write
|
||
discrimination eval (Eval B/C playbook: ambiguity ladder L1 explicit → L3 conceptual,
|
||
paired positives/negatives, 6 run-set scenarios on a new `reportgen` Ruby fixture + 6
|
||
frozen reserve twins in a different knowledge domain, isolated sandbox vault,
|
||
headless-only runner, deterministic-first Ruby checker with narrow frozen offer-detection
|
||
judge fallback stubbable via `OS_VAULT_EVAL_JUDGE_CMD`, model-free `bin/self-test` 21/21).
|
||
**Scenario Task blocks are held-out — never run informally; the reserve set is never even
|
||
read informally.** Procedure: `plugins/os-vault/eval/README.md`.
|
||
- Untuned baseline grid (2026-07-06, run-set × sonnet/haiku × 3 reps + 1 counted canary, 37
|
||
reps, zero harness errors): **positives 1/19, negatives 18/18**. Headline: at L1 (explicit
|
||
cue) both tiers persist the knowledge every rep but route it to Claude Code's built-in
|
||
auto-memory instead of the vault; L2/L3 mostly don't persist at all; zero over-triggering
|
||
anywhere. TSV: `eval/results/2026-07-06-baseline-grid.tsv`; full analysis: vault note
|
||
[[os-vault-write-eval-baseline-grid-results]].
|
||
- WS2 wording loop COMPLETE (2026-07-07, 4 iterations + confirm + held-out reserve; run-set
|
||
AND reserve now contaminated): shipped destination-ladder write SKILL.md + SessionStart
|
||
USAGE_NOTE (mechanical triggers + before-final-reply checkpoint), mechanical vault-root
|
||
resolution (`${OS_VAULT_PATH:-$HOME/Documents/SecondBrain}` — fixed real-vault breaches
|
||
found on iteration 1), fixture CLAUDE.md "Cross-project memory" section (**the
|
||
real-project adoption template**, required to reach haiku at L2/L3; includes ADR-vs-vault
|
||
disambiguation), candidates 2–4 unscored, post-reserve YAML-colon quoting rule. Confirm
|
||
grid sonnet 18/18 / haiku 16/18; reserve (held-out) positives 8/18 strict / trigger-axis
|
||
13/18, negatives 17/18 (vs baseline 1/19, 18/18). Residual gaps: YAML-hostile titles,
|
||
haiku L2 no-trigger, generalization-laundering over-trigger. One checker false-positive
|
||
fixed+rescored mid-loop (breach regex vs `2>/dev/null`); negative-criterion redesign
|
||
pre-registered. TSVs: `eval/results/2026-07-07-wording-*.tsv`; loop log:
|
||
`autoresearch/classic-260707-1253/loop-log.md`; analysis: vault note
|
||
[[os-vault-write-eval-wording-loop-results]]. Next signal is production IRL audits.
|