KB-OS Memory v1 → Context System → CodeGraph

Close-out log for KB-OS-memory-upgrade (opened 2026-07-12, closed 2026-07-13). Started as “review Simon Scrapes’ Claude Code memory plan and propose an upgrade”; grew into the KB-OS Context System and the CodeGraph adoption. SSOT for the resulting system: KB-OS-Context.

What shipped

Memory v1 (2026-07-12/13)

CONSTITUTION Operating Principle #8 ratified: memory truth lives in the vault (git-synced markdown); per-device tools cache/index it, never own it. Test: new machine + git clone + reindex = full memory.
qmd installed as the recall engine over the vault (BM25 search in seconds = workhorse; hybrid query = deep recall, minutes on CPU; vsearch weak — skip). Collections kb (vault minus Clippings/archive noise) + sessions. Recall convention added to ~/ai-config/AGENTS.md (qmd before broad grep for historical/decision questions).
SessionEnd digest hook (~/.claude/hooks/session-digest.sh): distills each substantive session into ~/.claude/session-digests/ (per-device archive, never in the vault, qmd collection sessions). Items passing the Capture-Routing save criteria become one Inbox bullet in the owning dept — promote/delete, same gate as any capture. Auto-capture feeds the pipeline; it never writes vault content directly. Also runs qmd update && qmd embed so the index tracks the vault at session granularity.
Auto-memory promotion (Phase 2c): /task-complete step 4 harvests durable ~/.claude auto-memories into the vault, slimming the local copy to a pointer.

Context System (2026-07-13)

Renamed Memory.md → KB-OS-Context.md (“KB-OS — Context System”): memory reframed as the core subsystem of a wider context layer. Chose the KB-OS- prefix over a generic Context.md to avoid first-occurrence-wins wikilink collision.
Added the tool & structure map (SMTM · charter chain / CLAUDE.md-AGENTS.md · auto-memory · Capture-Routing · qmd · session digests · graphify · CodeGraph · Obsidian · git — each with the context it supplies, its store/inject/recall job, and primary user), benefits-by-audience (agent vs human), and a bidirectional link with ai-config (ai-config owns the mechanisms; the Context System doc owns their purpose).

CodeGraph (2026-07-13) — code-dev recall, CLI-first

Installed the CLI globally (v1.4.1, ~/.local/bin/codegraph, telemetry off; self-contained bundle — no pnpm/npm global-store involvement). Whole mbr monorepo indexed at the root (375 source files → 2,644 nodes / 7,332 edges in ~2 s). Verified end-to-end: codegraph explore resolved cross-package flow (sd-app → packages/sd-math strategies) with verbatim source + call paths + a blast-radius report flagging untested symbols.
CLI-only, no MCP — codegraph explore returns identical output to the codegraph_explore MCP tool, so the standing CLI>MCP preference is honored with no exception. .codegraph/ is a per-device disposable index → gitignored (Principle #8). Agent convention added to the monorepo CLAUDE.md (Code Navigation section) + AGENTS.md: prefer codegraph explore over grep for structure questions.
Division of labour: graphify = default for everything non-code (“how does it connect”); CodeGraph = specialist for code-dev projects (“what is this code / what breaks if I change it”).

Key decisions & rationale

Two planes, kept separate. Memory plane = what gets injected (small, curated, human-gated — nothing auto-writes here). Archive plane = what’s findable on demand (zero context cost until queried). Simon’s step-3 “capture everything” and claude-mem both conflate these; the split is what let auto-capture coexist with Talbot’s save-discipline without diluting the vault.
Borrow > build. Simon’s semantic-search spec is qmd’s feature list — adopted qmd rather than hand-rolling. Rejected the heavy frameworks (mem0/Letta/Zep/cognee) — server/SQLite-owned stores violate Principle #8 + SSOT + simplification-first.
Native auto-memory already does Simon’s “curated writes” (step 2) — governed it (Phase 2c promotion) rather than rebuilding it.
Model tiering: Fable/Opus for direction-setting (architecture, ratifiable principles, reviewing cheaper work); Sonnet for specified execution (installs, hooks-to-spec, batch edits). Maps to /task-prep (big model) → execute (cheaper).

Gotchas / warnings

Hybrid qmd query is minutes-per-query on CPU — not interactive. search (BM25) is the everyday tool; reserve query for deep recall when keywords miss and the answer matters.
.codegraph/ and the qmd index are per-device disposable caches — never commit them; rebuild is one command. Both are gitignored.
codegraph uninit needs -f/--force, not --yes; a stray index dir can just be rm -rf’d (it’s disposable).
git mv then content-Write leaves the content unstaged — re-git add before committing (validated the existing LESSONS entry).

Lessons captured

Promoted to ai-config/AGENTS.md (CLI vs MCP): “MCP-primary” marketing ≠ MCP-only — verify the CLI surface before treating a tool as a CLI>MCP violation. Full entry in KB-OS LESSONS.

Commits

KB: b6fc545 (Memory v1) · d1be90a (Context System) · 4a3e771 (CodeGraph installed) · 3c47855 (CodeGraph wired up) · plus this close-out.
ai-config: 4c8878c (recall convention) · AGENTS.md CLI-vs-MCP refinement (this session).
monorepo: 0076bd5 (CodeGraph gitignore + Code Navigation convention).

Deferred (parked in KB-OS-Context §5 / UPGRADES)

Memory Phase 3 — SessionStart inject hook (convention → mechanism).
Hybrid-query speed (qmd flags / GPU offload in WSL).
Transcript bootstrap import (sentinel-guarded; low marginal value — vault already curated).
graphify high-quality full-vault re-run.
CodeGraph MCP integration — deliberately not done (CLI suffices); only if a future need justifies it, wire through ai-config (not a raw codegraph install, which edits deployed config directly).