Probe sandboxes gain the channels, quietBubbles and known.now the merged branches added; the hub view keeps queue_jobs apart from the job list; the image ships sandbox_paths.py; kvb-match writes pages into the council root pages folder; the install test scaffolds the council parts and agent roots; skill texts move detail into their side files to stay under the word caps. 🎯 Fix: 88 % 💥 Break: 4 % 💸 Tokens: 98 % ⏱️ Velocity: 100 % 🛡️ Security: 100 % 🏆 Score: 86 🚦 Gate: ⛔ fix 88 % < 90 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
13 KiB
13 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 (amended by the operator 2026-11-14, pick
"auto_index off"): the daemon's
auto_indexstays off; the skillsmake installsetscodebase-memory-mcp config set auto_index false. The skills PreToolUse hook (kvb-agent-optimize/scripts/graph.py hook) indexes every git root a tool call touches, the session root included, once it has no graph, with noindex_repositoryby hand and no operator step beyond the one-time config: a root with more files thanqueue_file_threshold(tracked plus untracked, not ignored) or with a.gitmodulesfile is enqueued throughkvb-org-queueunderqueue_taskand never started by the hook; a smaller root starts only whilekvb-org-organizereports the memory stage ok. Afterwards the graph stays fresh incrementally through the watcher of the permanent daemon (decision 5). Rejected: the daemon'sauto_indexfor the session root, because it indexes with no queue and no memory gate (the class of the 2026-11-14 13:15 host freeze), and because upstream 0.12.1 refuses every repository holding a symlink: its bounded admission count (cbm_discover_count_bounded, count-only mode insrc/discover/discover.c) fails on the first symlink or unreadable directory, measured as 1210daemon.autoindex.skipped reason=unsafe_or_unavailable_path files=-1lines for infinito-nexus-core, whoseplaybooks/*/group_varsare committed symlinks. - 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 without a permanent daemon prints once per session id the remedy that holds (amended 2026-11-14, skeptic round 5): withkvb-code-graph.serviceinstalled but inactivecodebase-memory-mcp: no permanent daemon; run: systemctl --user enable --now kvb-code-graph.service, and only this command becomes onekvb-org-operatorrow; with the unit active and a session-managed daemon that the service takes over after the last session ends, nothing to do; with the unit active and no daemon, thejournalctlcheck. Upstream refusesdaemon startwhile a session-managed daemon runs, so the supervisor does not start one then; it checksdaemon statusevery 30 s and starts the permanent daemon within one round after the last session ends. Only consecutive failing starts wait longer, doubling up to 1 h (amended 2026-11-14, skeptic round 6).make installrestarts a running supervisor (try-restart), so a reinstall takes effect at once. - 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 first tool call of a new session in infinito-nexus-core enqueues
core once and starts nothing itself (decision 3, amended 2026-11-14).
The hook writes its decisions alone to
<project>.log; the queue job and the helper write to<project>.index.log. In~/.local/state/kvb-code-graph/logs/,grep -o '^graph: [a-z]*' home-kevinveenbirkenbach-Repositories-github.com-kevinveenbirkenbach-infinito-nexus-core.log | sort | uniq -cprints exactly1 graph: queue, before and after the job ran. - 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 and the unit inactive, 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 the unit active no row is added. - With a permanent 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 saysmake installturns the daemonauto_indexoff and the hook indexes every git root, the session root included (decision 3, amended 2026-11-14):grep -Fc -e '`auto_index` off' -e 'the session root included' skills/kvb-agent-optimize/SKILL.mdprints 2.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.