# 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.