Token-saving requirements picked by the operator on 2026-11-14: the code graph is initialised automatically per repository, security scan results are cached per file by content, and green test results are reused only under an exact key. Implementation follows once the running lanes land; the shared result store is requirement 003 of the quality repository. 🎯 Fix: 95 % 💥 Break: 1 % 💸 Tokens: 100 % ⏱️ Velocity: 100 % 🛡️ Security: 100 % 🏆 Score: 94 🚦 Gate: ✅ 90/5, tokens and velocity <= 100, security 100 % Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
11 KiB
11 KiB
009 - Code Graph by Default
User Story
As the operator running many agent sessions across repositories and worktrees, I want every repository a session opens to carry a current codebase-memory-mcp graph without any manual step, so that agents answer structural questions from the graph instead of reading files and spend fewer tokens.
Decisions (operator-confirmed 2026-11-14; do not re-litigate)
- Depends on: nothing. Independent of 010, 011 and quality 003.
- Timing: implementation starts once the running agent lanes are done.
- Automatic per repository: a session that opens a repository without a
graph indexes it itself, with no
index_repositoryby hand and no operator step; afterwards the graph stays fresh incrementally through the watcher. Mechanism found in codebase-memory-mcp 0.12.1: both, with separate jobs. The daemon'sauto_indexindexes and watches the MCP session root when a session connects (application_background_initialize_implinsrc/daemon/application.c). The SessionStart hook (hook-augment) only adds context: it never indexes and never spawns a daemon (src/main.c). Measured 2026-11-14:_config.dbholdsauto_index = true, so the skillsmake installdid switch it on (scripts/install.sh), yetcbm-daemon.logholds 1113daemon.autoindex.skippedlines for infinito-nexus-core and 8 for thefeature-store-i18nworktree, allreason=unsafe_or_unavailable_path files=-1, and not oneautoindex.done.files=-1means the bounded admission count (5 s deadline, or an entry it cannot observe) failed, not the file limit; the last graph was written 2026-11-12 22:24. - Fix the refusal, no workaround: the root cause of that admission
refusal is found and removed, in our repositories or upstream through an
issue. Rejected: raising
auto_index_limit(the count fails, the limit is not reached); an agent callingindex_repositoryper session (a manual step). - Other repositories (proposed): the daemon auto-indexes only the
session root, so additional working directories and worktrees made during
a session stay unindexed. A skills
PreToolUsehook resolves the git root of each path a tool call touches; for a root without a graph it starts a detached helper that holds one MCP connection, callsindex_repositorywithasync: trueand stays connected until the job succeeds, once per root and session. A permanent daemon (codebase-memory-mcp daemon start, run by a systemd user unitkvb-code-graph.servicethatmake installenables) keeps the watch after the helper leaves: upstream keeps a watch past its last session only underdaemon start, registers an async index only while its session is connected, and a CLI index registers none (README, Indexing and Session Coordination Daemon). Rejected: the hook telling the agent to callindex_repository(a manual step that costs a turn);codebase-memory-mcp cli index_repository(no watch, so the graph goes stale). - Missing daemon, once per session: upstream rate-limits its own notice
per cache folder to once in 900 s (
MAIN_HOOK_NOTICE_INTERVAL_SECONDSinsrc/main.c), not per session, so a second session within 15 minutes hears nothing;.hook-daemon-absent-noticewas last written 2026-11-14 12:21. The skills hook checkscodebase-memory-mcp daemon statusat the first tool call of a session, after the MCP servers connected, and on a missing daemon prints once per session id:codebase-memory-mcp: no daemon; run: systemctl --user enable --now kvb-code-graph.service. The same command becomes onekvb-org-operatorrow. - Worktrees get their own graph: codebase-memory-mcp registers every
project under its absolute root, so each linked worktree is a separate
index (
docs/CONFIGURATION.md,ignore_worktrees); one graph cannot serve two checkouts. A worktree gets its graph through decision 3 or 5 and loses it with decision 8. Rejected:ignore_worktrees true(a worktree session would get no graph); seeding a worktree from a copied.codebase-memory/graph.db.zst(README, Bootstrap: possible, but it needspersistence: truewrites into the main checkout after every index and a copy step at worktree creation, for a saving not yet measured). - Prune with the worktree: removing a worktree deletes its graph in the
same step, inside the existing cleanup.
pkgmgr worktree cleanupdeletes the project of each checkout it removes, andpkgmgr gc, the single deterministic cleanup source picked 2026-11-14, lists every graph whose root is gone or is no git repository as a low-risk candidate. Measured: of the 10 graphs, 5 belong to removed skills worktrees (chore-requirement-001-audit,feature-workbench-w1tow4, 174 MiB together) and/tmp/release-17.0.0is no git repository. The pkgmgr part is a package-manager task in thekvb-org-rasciregister. Rejected: a separate prune timer (a second cleanup source). - Local only: graphs are never committed;
.codebase-memory/goes into each repository's.gitignore, the "not shared" branch ofkvb-agent-optimize. Measured: skills, infinito-nexus-core, gui, package-manager and quality ignore it nowhere today. - Graph first, grep after: skills and AGENTS.md keep sending code
questions to
search_graph,trace_pathandget_architecturefirst. - Sandbox-proof checks (proposed):
codebase-memory-mcp config get auto_indexfails inside the agent sandbox with "could not load saved runtime settings", because~/.cache/codebase-memory-mcplies outsideallowWrite; opening_config.dbread-only works there. Checks read the setting read-only or ask the daemon (index_status), never throughconfig getfrom the sandbox.
Approach
flowchart TD
subgraph P["🧭 0 · Preparation"]
P1["📋 Write requirement"] --> P2{"✅ Operator approves?"}
P2 -- "✏️ corrections" --> P1
end
P2 -- "🤖 yes" --> A1
subgraph A["🔍 A · Session root"]
A1["🩺 Find the admission refusal"]
A1 --> A2["🔧 Remove its cause"]
A2 --> A3{"🧪 Fresh clone indexed and reused?"}
A3 -- "🔴 no: fix" --> A1
end
A3 -- "🟢 yes" --> B1
subgraph B["🪝 B · Other repositories and notice"]
B1["🗂️ Hook indexes other git roots"]
B1 --> B2["📢 Daemon notice once per session"]
B2 --> B3{"🧪 Hook tests green?"}
B3 -- "🔴 no: fix" --> B1
B3 -- "🟢 yes" --> BF{"💬 Operator feedback?"}
BF -- "✏️ changes" --> B1
end
BF -- "👍 fits" --> C1
subgraph C["🧹 C · Prune and ignore"]
C1["🗑️ Prune in pkgmgr cleanup and gc"]
C1 --> C2["🙈 Ignore .codebase-memory/"]
C2 --> C3{"🧪 Removed worktree leaves no graph?"}
C3 -- "🔴 no: fix" --> C1
C3 -- "🟢 yes" --> CF{"💬 Operator feedback?"}
CF -- "✏️ changes" --> C1
end
CF -- "👍 fits" --> D1["🏁 Review, commit with operator OK, hand-over"]
Acceptance Criteria
Session root
- The commit that fixes the admission refusal names its root cause, and
a new session in infinito-nexus-core then writes
autoindex.donefor it to~/.cache/codebase-memory-mcp/logs/cbm-daemon.log. - Fresh clone: a session started in a new
git cloneof skills finds the clone inlist_projectswith more than 0 nodes, with noindex_repositorycall in its transcript and no new operator row. - Second session: a second session in the same clone adds no
autoindexline for it tocbm-daemon.log,list_projectsstill holds exactly one entry for that root, andindex_statusreportswatch.watched: true. - Fresh incrementally: after a commit that adds a function to the clone,
search_graphfinds the function within one watcher poll, with noindex_repositorycall.
Other repositories
- A session rooted in skills that reads a file of an unindexed
package-manager clone leaves that root in
list_projects, and once the helper has exitedindex_statusreportswatch.watched: truefor it. make installenableskvb-code-graph.service, and after the last agent session closescodebase-memory-mcp daemon statusstill reports a running daemon.
Worktrees and pruning
- A new linked worktree of skills gets its own entry in
list_projectsfrom the first session or tool call in it. pkgmgr worktree cleanup --apply --branch <b>removes that worktree's project:list_projectsno longer lists it and its.dbfile under~/.cache/codebase-memory-mcp/is gone.pkgmgr gc --jsonlists each graph whose root is missing or no git repository as a low-risk candidate; on the state of 2026-11-14 it names the 5 removed skills worktrees and/tmp/release-17.0.0.
Daemon notice
- With no daemon running, the first tool call of a session prints the notice with the exact command once, later tool calls of that session print nothing, and a second session prints it once again.
- The command appears as one
kvb-org-operatorrow, not one per session. - With a daemon running, no notice is printed.
Local only and instructions
git check-ignore -q .codebase-memory/graph.db.zstexits 0 in the main checkouts of skills, infinito-nexus-core, gui, package-manager and quality.kvb-agent-optimize/SKILL.mdstep 2 names the daemonauto_indexfor the session root and the hook for every other repository, and no longer saysmake installalone indexes every repository a session opens.agents.pyreportsauto_indexfrom inside the agent sandbox by opening_config.dbread-only.AGENTS.mdof skills still sends code questions to the graph first and to grep after.
Tests
- Unit
test_hook_resolves_git_root: a path in a subfolder, in a linked worktree and in a submodule each resolves to its own root.test_hook_indexes_once_per_root: two tool calls on one unindexed root start one helper.test_hook_skips_indexed_rootandtest_hook_skips_non_git: an indexed root and a path outside git start nothing.test_notice_once_per_sessionandtest_notice_silent_with_daemon.test_auto_index_read_only:agents.pyreadsauto_indexfrom a read-only_config.dbfixture.test_gc_lists_orphan_graphs(package-manager): a graph of a missing root and one of a non-git root are listed, a live root's is not.
- Integration
test_code_graph_fresh_clone: the real binary, a temporary clone under the real cache root (upstream refuses a differentCBM_CACHE_DIRwhile the live daemon runs): the first MCP session indexes, the second reuses; the test deletes its project afterwards.test_code_graph_helper_watch: the hook's helper indexes an additional root and the watch outlives the helper underdaemon start.test_code_graph_worktree_prune: a worktree's graph is gone afterpkgmgr worktree cleanup --apply.
- E2E
tests/e2e/test_code_graph_e2e.py: a headless agent session in a fresh clone answers one structural question throughsearch_graphwith noindex_repositorycall in its transcript, and a second session adds noautoindexline for that root.