cc-os/docs/implementation-status/os-vault.md

os-vault — component detail

Leaf file of ../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.