# 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) 1. **Depends on**: nothing. Independent of 010, 011 and quality 003. 2. **Timing**: implementation starts once the running agent lanes are done. 3. **Automatic per repository** (amended by the operator 2026-11-14, pick "auto_index off"): the daemon's `auto_index` stays off; the skills `make install` sets `codebase-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 no `index_repository` by hand and no operator step beyond the one-time config: a root with more files than `queue_file_threshold` (tracked plus untracked, not ignored) or with a `.gitmodules` file is enqueued through `kvb-org-queue` under `queue_task` and never started by the hook; a smaller root starts only while `kvb-org-organize` reports the memory stage ok. Afterwards the graph stays fresh incrementally through the watcher of the permanent daemon (decision 5). Rejected: the daemon's `auto_index` for 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 in `src/discover/discover.c`) fails on the first symlink or unreadable directory, measured as 1210 `daemon.autoindex.skipped reason=unsafe_or_unavailable_path files=-1` lines for infinito-nexus-core, whose `playbooks/*/group_vars` are committed symlinks. 4. **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 calling `index_repository` per session (a manual step). 5. **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 `PreToolUse` hook 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, calls `index_repository` with `async: true` and stays connected until the job succeeds, once per root and session. A permanent daemon (`codebase-memory-mcp daemon start`, run by a systemd user unit `kvb-code-graph.service` that `make install` enables) keeps the watch after the helper leaves: upstream keeps a watch past its last session only under `daemon 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 call `index_repository` (a manual step that costs a turn); `codebase-memory-mcp cli index_repository` (no watch, so the graph goes stale). 6. **Missing daemon, once per session**: upstream rate-limits its own notice per cache folder to once in 900 s (`MAIN_HOOK_NOTICE_INTERVAL_SECONDS` in `src/main.c`), not per session, so a second session within 15 minutes hears nothing; `.hook-daemon-absent-notice` was last written 2026-11-14 12:21. The skills hook checks `codebase-memory-mcp daemon status` at 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): with `kvb-code-graph.service` installed but inactive `codebase-memory-mcp: no permanent daemon; run: systemctl --user enable --now kvb-code-graph.service`, and only this command becomes one `kvb-org-operator` row; 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, the `journalctl` check. Upstream refuses `daemon start` while a session-managed daemon runs, so the supervisor does not start one then; it checks `daemon status` every 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 install` restarts a running supervisor (`try-restart`), so a reinstall takes effect at once. 7. **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 needs `persistence: true` writes into the main checkout after every index and a copy step at worktree creation, for a saving not yet measured). 8. **Prune with the worktree**: removing a worktree deletes its graph in the same step, inside the existing cleanup. `pkgmgr worktree cleanup` deletes the project of each checkout it removes, and `pkgmgr 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-w1` to `w4`, 174 MiB together) and `/tmp/release-17.0.0` is no git repository. The pkgmgr part is a package-manager task in the `kvb-org-rasci` register. Rejected: a separate prune timer (a second cleanup source). 9. **Local only**: graphs are never committed; `.codebase-memory/` goes into each repository's `.gitignore`, the "not shared" branch of `kvb-agent-optimize`. Measured: skills, infinito-nexus-core, gui, package-manager and quality ignore it nowhere today. 10. **Graph first, grep after**: skills and AGENTS.md keep sending code questions to `search_graph`, `trace_path` and `get_architecture` first. 11. **Sandbox-proof checks (proposed)**: `codebase-memory-mcp config get auto_index` fails inside the agent sandbox with "could not load saved runtime settings", because `~/.cache/codebase-memory-mcp` lies outside `allowWrite`; opening `_config.db` read-only works there. Checks read the setting read-only or ask the daemon (`index_status`), never through `config get` from the sandbox. ## Approach ```mermaid 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 `.log`; the queue job and the helper write to `.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 -c` prints exactly `1 graph: queue`, before and after the job ran. - [ ] Fresh clone: a session started in a new `git clone` of skills finds the clone in `list_projects` with more than 0 nodes, with no `index_repository` call in its transcript and no new operator row. - [ ] Second session: a second session in the same clone adds no `autoindex` line for it to `cbm-daemon.log`, `list_projects` still holds exactly one entry for that root, and `index_status` reports `watch.watched: true`. - [ ] Fresh incrementally: after a commit that adds a function to the clone, `search_graph` finds the function within one watcher poll, with no `index_repository` call. ### 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 exited `index_status` reports `watch.watched: true` for it. - [ ] `make install` enables `kvb-code-graph.service`, and after the last agent session closes `codebase-memory-mcp daemon status` still reports a running daemon. ### Worktrees and pruning - [ ] A new linked worktree of skills gets its own entry in `list_projects` from the first session or tool call in it. - [ ] `pkgmgr worktree cleanup --apply --branch ` removes that worktree's project: `list_projects` no longer lists it and its `.db` file under `~/.cache/codebase-memory-mcp/` is gone. - [ ] `pkgmgr gc --json` lists 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-operator` row, 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.zst` exits 0 in the main checkouts of skills, infinito-nexus-core, gui, package-manager and quality. - [ ] `kvb-agent-optimize/SKILL.md` step 2 says `make install` turns the daemon `auto_index` off 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.md `` prints 2. - [ ] `agents.py` reports `auto_index` from inside the agent sandbox by opening `_config.db` read-only. - [ ] `AGENTS.md` of 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_root` and `test_hook_skips_non_git`: an indexed root and a path outside git start nothing. - [ ] `test_notice_once_per_session` and `test_notice_silent_with_daemon`. - [ ] `test_auto_index_read_only`: `agents.py` reads `auto_index` from a read-only `_config.db` fixture. - [ ] `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 different `CBM_CACHE_DIR` while 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 under `daemon start`. - [ ] `test_code_graph_worktree_prune`: a worktree's graph is gone after `pkgmgr worktree cleanup --apply`. - **E2E** - [ ] `tests/e2e/test_code_graph_e2e.py`: a headless agent session in a fresh clone answers one structural question through `search_graph` with no `index_repository` call in its transcript, and a second session adds no `autoindex` line for that root.