KB-OS Context System — How KB-OS Supplies Context

SSOT for how KB-OS gives AI agents and humans the context they need to act. Memory (persistent store / inject / recall) is the core subsystem — but “context” is broader than memory: it also covers the structure work lives in (SMTM), the rules an agent loads (charter chain), how knowledge connects (graphify), and how code is understood (CodeGraph, proposed). This doc maps all of it. Governing rule: CONSTITUTION Operating Principle #8 — memory truth lives in the vault (git-synced markdown); per-device tools cache and index it, never own it. Test: new machine + git clone + reindex = full context. Depends on / configured by: ai-config — the AI dept’s ongoing project that installs and versions every tool named here (hooks, skills, qmd config, CLAUDE.md chain). Change a mechanism there; document what it’s for here.

1 · Context in one picture

Every memory system has exactly three jobs: store, inject, recall. KB-OS runs them across two planes that must never be confused:

Memory plane = what gets injected into context. Small, curated, high-signal. Human-gated by the Capture-Routing save criteria. Nothing auto-writes here.
Archive plane = what can be found when asked. Zero context cost until queried; search returns only the top few hits, so it never dilutes no matter how large it grows.

The design principle: store discipline (memory plane) + recall abundance (archive plane). Curated stays curated; nothing said is ever unfindable.

2 · The tool & structure map

Everything KB-OS uses to supply context, what each contributes, which of the three jobs it serves, and who it primarily serves:

Tool / structure	Context it supplies	Job(s)	Primary user	Home / SSOT
SMTM — tasks, projects, logs, STATUS, LESSONS	What we’re doing & why; decisions; project history	Store (curated) + Inject	Both	`Core/Processes/…/SMTM_System.md`
Charter chain — CONSTITUTION → JOB_DESCRIPTION → Staff → SSOT doc; CLAUDE.md / AGENTS.md	Who the agent is; rules; scope; autonomy level	Inject	Agents	`~/ai-config/AGENTS.md` + dept `JOB_DESCRIPTION.md`
Claude Code auto-memory	Small per-device durable facts (host quirks, preferences)	Store + Inject	Agents	`~/.claude/…/memory/` → promoted to vault at `/task-complete`
Capture-Routing — Inbox → promote/delete	The human gate deciding what becomes permanent	Store (gate)	Human	`Core/Processes/Capture-Routing.md`
qmd — local hybrid search	Find any past decision or fact by keyword or meaning, cited `file:line`	Recall	Both (agent-first)	index `~/.cache/qmd/`; config `~/.config/qmd/index.yml`
Session digests — SessionEnd hook	Searchable archive of every session; save-criteria items → Inbox	Store (auto, recall-only)	Both	`~/.claude/session-digests/` (qmd collection `sessions`)
graphify	How things connect — entities, communities, relationships	Recall (structural)	Both	`/graphify` skill → `graphify-out/` per scope
CodeGraph — `codegraph explore` (CLI) (§5)	Code structure — symbols, call paths, blast radius	Recall (code)	Agents	global CLI `~/.local/bin/codegraph`; index `.codegraph/` per project
Obsidian — wikilinks, Bases, graph view, search	Human navigation & live dashboards	Inject + Recall	Human	the vault
git	Device-agnostic sync — makes the vault the one truth everywhere	(substrate)	Both	`/mnt/d/FSS/KB/`

How to read it: the first four rows are the memory plane (curated, injected). qmd + session digests + graphify + CodeGraph are the archive/recall plane (found on demand, zero standing cost). git underlies everything — it’s what makes “vault = truth” hold across machines.

3 · Memory subsystem (the store / inject / recall core)

The shipped KB-OS Memory v1 — 2026-07-12/13 via Tasks/KB-OS-memory-upgrade.md.

Job	Layer	How
Store — curated	The vault itself	SMTM task files, STATUS/LESSONS/logs, dept docs. Human-gated by the Capture-Routing save criteria. Unchanged — this was always the strength.
Store — automatic	Session digests + Inbox bullets	A `SessionEnd` hook distills every substantive Claude Code session into `~/.claude/session-digests/` (per-device archive, never in the vault). Items passing the save criteria become one bullet in the owning dept’s `Inbox.md` — promote or delete, same as any captured idea.
Inject	CLAUDE.md chain + charter-chain autoload + Claude Code auto-memory + SessionStart hook	Mechanism, not just convention as of Phase 3 (2026-07-13): `~/.claude/hooks/session-start-inject.sh` (SSOT `ai-config/claude/hooks/`) silently injects Biggest Rocks + open `_active.md` lines (≤2000 chars) on `startup`/`clear`, plus a detached `qmd update`.
Recall	qmd (local hybrid search)	`qmd search` finds by keyword in seconds; `qmd query` finds by meaning (paraphrase-proof); every hit cites `file:line` + score. Collections: `kb` (the vault, minus Clippings/archive noise) and `sessions` (digests).

What Talbot needs to know about qmd

Nothing is required day-to-day. qmd is primarily an agent tool — Claude runs it per the AGENTS.md recall convention (qmd before broad grep for historical/decision questions). Two optional human uses:

Terminal one-liner when you want a cited answer yourself: qmd search "task naming convention" -n 5
Ask Claude naturally: “what did we decide about X?” — the convention makes Claude search the vault + session archive first.

Mode cheat-sheet: search = fast BM25 (default workhorse) · query = hybrid + rerank, best quality but minutes on this CPU (deep recall only) · vsearch = vector-only, weak alone — skip.

Reindexing policy (continually-revised vault)

Automatic: the SessionEnd digest hook runs qmd update + qmd embed at the end of every substantive session — so the index tracks the vault at session granularity with zero thought.
Manual (rare): after a large out-of-session content drop (bulk import, big restructure): qmd update && qmd embed. update is incremental (~17 s full vault); embed only processes changed chunks. If embed reports “LLM session expired” errors, just rerun it — it’s resumable.
The index (~/.cache/qmd/) is a disposable per-device cache. Delete it any time; rebuild = qmd update && qmd embed (~40 min first time per device).

Pieces & homes (SSOT map)

Piece	Home
Memory principle	`Core/CONSTITUTION.md` Operating Principle #8
Recall convention + reindex rule	`~/ai-config/AGENTS.md` § Vault memory & recall (deploys into global CLAUDE.md)
Digest hook (2a/2b)	`~/.claude/hooks/session-digest.sh`, registered as `SessionEnd` in settings (source: `~/ai-config/claude/settings.wsl.json`)
Save-criteria gate	Quoted inside the hook prompt from Capture-Routing — editable guidelines, not code
Auto-memory promotion (2c)	`/task-complete` step 4 (source: `~/ai-config/claude/commands/task-complete.md`)
qmd config (collections, ignore rules, models)	`~/.config/qmd/index.yml`
Session digests	`~/.claude/session-digests/` (per-device, gitignored by location)

4 · Real benefits — by audience

The point of the whole system: the right context shows up at the right time, for both users, without either of you doing extra work.

For AI agents

Start every session already briefed — identity, rules, dept scope, autonomy level, and current priorities load unasked via the charter chain + CLAUDE.md. No re-explaining who they are or what matters.
Answer “have we decided/solved this before?” in seconds, cited — qmd recall replaces blind grep (misses synonyms) and, worse, confident hallucination. Answers come with file:line + score, so the agent quotes the actual decision instead of inventing one.
Stay in the right lane — the charter chain gates what an agent may do alone vs. escalate, per dept autonomy (A0–A4).
Understand code without reading everything — (once CodeGraph lands, §5) symbols, call paths, and blast radius in one call instead of many grep/read round-trips.
Nothing said is lost — session digests + Inbox capture catch decisions and lessons that never got formally logged, so a future session can find them.

For your normal (human) use

One curated vault, never a junk drawer — your save discipline is preserved absolutely; you decide what becomes permanent (promote/delete). Auto-capture only ever feeds the Inbox, never the vault body.
Ask in your own words, get a sourced answer — “what did we decide about naming task files with dates?” returns the actual note, its date, and where it lives — your own memory jogged, with a citation, not a vague paraphrase.
Device-agnostic — git clone on any machine + one reindex = full context restored. Nothing important is trapped on one laptop.
Dashboards surface state without digging — Bases views, Biggest Rocks, Focus pages show “what’s true right now” at a glance.
A safety net for what you didn’t log — you don’t have to remember to capture everything; the digest archive holds “that thing we tried three weeks ago and never wrote down,” findable by meaning — while the human gate still protects what’s permanent.

5 · Roadmap / additions

Tracked under KB-OS ROADMAP M3.6 — Memory & Context layer. Deferred items live in the UPGRADES parking lot (single SSOT); active work is promoted to KB-OS/Tasks/.

Shipped ✅

CodeGraph — code-dev recall, CLI-first (2026-07-13). Pre-indexed code knowledge graph (tree-sitter → SQLite/FTS5, 30+ languages, local, no API keys). codegraph init builds the graph; codegraph explore "<question>" returns verbatim source + call paths + a blast-radius report (callers + which lack test coverage) in one shot. Ships a real CLI whose output equals the codegraph_explore MCP tool → used via Bash, no MCP server (matches CLI>MCP). Whole mbr monorepo indexed at root; .codegraph/ gitignored (Principle #8). Division of labour: graphify = default for everything (“how does it connect”); CodeGraph = specialist for code-dev (“what is this code / what breaks if I change it”). MCP integration deliberately not enabled — only if a future need justifies it, wired via ai-config.
Memory Phase 3 — SessionStart inject hook (2026-07-13). ~/.claude/hooks/session-start-inject.sh (SSOT ai-config/claude/hooks/, registered in settings.wsl.json) injects Biggest Rocks + open _active.md lines (≤2000 chars, line-boundary truncated) on startup/clear only via hookSpecificOutput.additionalContext; backgrounds qmd update (detached, non-blocking); recursion-guarded. Also closed a pre-existing gap: session-digest.sh was untracked (hand-placed in ~/.claude/hooks/, no ai-config copy, no deploy.sh step) — migrated it into ai-config alongside the new hook and added the missing hooks/ copy step to deploy.sh. Commit 6f86d15.

Shipped ✅ (cont’d)

graphify high-quality full-vault re-run (2026-07-13). Whole-vault (/mnt/d/FSS/KB), --mode deep: 541 files, 2,103 nodes, 2,671 edges, 329 communities. Supersedes the two stale partial runs (MBR/graphify-out/, Core/Misc/graphify-out/). .graphifyignore extended to mirror qmd’s kb collection noise exclusions plus a new exclusion for ~85 auto-generated daily rate-scanner ops reports (near-zero unique-entity value). Output stays at vault-root graphify-out/ (already gitignored via **/graphify-out/). qmd handoff: GRAPH_REPORT.md added as its own qmd collection (graphify) so the community/connection narrative is BM25-searchable — qmd = meaning, graphify = connections, and now graphify’s connection narrative is itself qmd-findable. Full write-up: KB-OS/logs/2026-07-13_Graphify-Fullvault-Rerun.md.

Deferred → UPGRADES

Hybrid-query speed (qmd flags / WSL GPU) · Transcript bootstrap import · CodeGraph MCP integration.

Deliberately NOT built (and why)

No auto-writes into the vault — the save criteria + human promote-or-delete gate stay absolute; auto-capture only feeds the Inbox pipeline. Searchable ≠ stored-in-memory: archives have zero context cost until queried.
No claude-mem / mem0 / Letta / Zep — server- or SQLite-owned stores would violate Principle #8 + SSOT + simplification-first. Borrowed claude-mem’s detached-capture architecture instead.