codebase-memory

Codebase Memory — Knowledge Graph Tools

Graph tools return precise structural results in ~500 tokens vs ~80K for grep.

Always prefer MCP graph tools over grep, glob, or file search for code discovery.

Priority Order

1. search_graph — find functions, classes, routes, and variables by pattern.
2. trace_path — trace who calls a function or what it calls.
3. get_code_snippet — read specific function or class source code.
4. check_index_coverage — validate candidate paths and missed ranges before claims.
5. query_graph — run Cypher queries for complex patterns.
6. get_architecture — get a high-level project summary.

Quick Decision Matrix

Use project="@current" for eligible graph reads in the active checkout, or use the exact project="<name>" returned by list_projects. Never replace @current with its borrowed source project in later graph calls because the alias revalidates the worktree on every call.

Question	Tool call
Who calls X?	trace_path(project="<name>", function_name="X", direction="inbound")
What does X call?	trace_path(project="<name>", function_name="X", direction="outbound")
Full call context	trace_path(project="<name>", function_name="X", direction="both")
Find by name pattern	search_graph(project="<name>", name_pattern="...")
Dead code	search_graph(project="<name>", max_degree=0, exclude_entry_points=true)
Cross-service edges	query_graph(project="<name>", query="<cypher>")
Impact of local changes	detect_changes(project="<name>")
Risk-classified trace	trace_path(project="<name>", function_name="X", risk_labels=true)
Text search	search_code(project="<name>", pattern="...") or Grep

Current Worktree Resolution

• index_status(project="@current") resolves an existing current-root index first.
• In an unindexed linked worktree, @current borrows a canonical checkout graph only when both trees are clean, share one Git common directory and HEAD, and the graph-recorded Branch snapshot matches.
• Keep using @current for search_graph, query_graph, trace_path, get_code_snippet, get_graph_schema, get_architecture, and index_status so each call revalidates the borrowed snapshot.
• Inspect pi_cbmem_resolution; borrowed_canonical_base means the result is read-only borrowed graph evidence rather than a worktree index.
• Borrowed get_code_snippet reads the reported lines from the current worktree.
• Do not use @current with search_code, check_index_coverage, detect_changes, manage_adr, ingest_traces, delete_project, or index_repository.
• For required coverage on borrowed evidence, call check_index_coverage once with the reported source project, read flagged paths from the current worktree, then rerun index_status(project="@current") before relying on the result. Do not use the reported source project for graph reads.
• If @current rejects a dirty, divergent, stale, missing, or ambiguous context, do not bypass the guard with the canonical project name. Index the worktree or use current-root file reads and grep instead.
• Treat borrowed coverage as best-effort because Codebase Memory exposes no immutable generation lease or complete semantic-input comparison.