Codebase Memory MCP

Codebase Memory MCP

Use the configured Codebase Memory graph as a discovery accelerator, not as the sole source of truth. Confirm graph-derived conclusions with source snippets or local files before editing code or making strong claims.

Evidence Levels

• Scout — Provisional positive orientation only. Do not make absence, exhaustive, dead-code, or complete-impact claims.
• Verify — Default for task-directed work. Check freshness where material, exact source snippets, relevant traces, path coverage, and every result page needed by the claim.
• Auditor — Use for negative, exhaustive, security, dead-code, architecture-boundary, and complete-impact work. Require the current index generation, a bounded scope, complete result streams, coverage inspection, and source checks for gaps.

Match the evidence level to the claim. If Auditor evidence cannot be completed, state the bounded limitation instead of making an absolute claim.

Workflow

1. Discover the Codebase Memory tools exposed by the current MCP client and use their callable schemas; clients may prefix or rename tools and expose different parameters.
2. Call list_projects first. Select only the entry whose canonical root_path matches the live checkout, and retain both its exact project name and root for later calls. If no match appears and has_more is true, continue with offset=next_offset before concluding the index is absent. For an absent index, follow the authorization rule in Safety and Fallbacks or use rooted local exploration; never substitute a similarly named project.
3. Before branch-sensitive or edit-sensitive conclusions, use index_status and verify the actual version-control state. Use detect_changes only when its Git base and head are valid for the checkout. If it unexpectedly reports zero changes, or the checkout uses another VCS, inspect that VCS's status or diff before claiming no impact.
4. Use get_architecture once for unfamiliar structure. Request clusters to discover de-facto module seams. Treat cycles as an opt-in whole-call-graph scan: path does not scope cycle detection, so verify relevant cycles before making module-local claims.
5. Use search_graph for definitions, implementations, routes, classes, interfaces, and related symbols. Prefer a BM25 query for keyword discovery and a name or qualified-name pattern for known symbols. Use semantic_query for vocabulary mismatch and verify matches with source snippets; similarity scores are not confidence probabilities. Narrow by label or path and set a result limit. Continue the main stream with offset=next_offset while has_more is true, not by adding the requested limit: output budgets can return fewer rows. Page semantic results independently with semantic_offset=semantic_next_offset while semantic_has_more is true.
6. Use search_code or normal repository search for literal strings, configuration keys, test identifiers, error messages, and non-code files. Do not turn a precise text lookup into a broad graph query.
7. After graph search, use get_code_snippet with the returned qualified name. For a File, Module, Class, or Interface node spanning more than 200 lines, source_mode="auto" returns an outline; continue members with member_offset=next_member_offset. To read such a container's body, pass source_mode="full": start_line and max_lines alone do not switch off the outline. With full, page the body with start_line/max_lines and continue from next_start_line while source_clipped is true and a continuation is available. To list a file's declarations without reading it, use get_file_outline(file_path=...); this tool uses offset += returned while has_more is true. If source snippets are unavailable, open the local file before relying on the result.
8. Use trace_path for callers, callees, dependency paths, data flow, cross-service paths, and impact analysis. Include tests when the claim covers them. When has_more and a continuation are present, pass next (tree output) or next_cursor (json output) back as cursor, keeping traversal arguments unchanged; the output budget may increase. truncated=true alone does not promise another page: engine ceilings can yield a lower-bound total (gte) without a cursor. With direction="both" callers are paged after all callees, so page 1 can show zero callers while callers_total is positive; ask direction="inbound" when the question is who calls a symbol.
9. After identifying candidate files, call check_index_coverage for every cited path. Page paths with path_offset=path_next_offset while path_has_more is true. Before negative or exhaustive claims, also check relevant scopes; independently advance scope_offset=next_offset while has_more is true. This metadata is best-effort, not proof of completeness. Inspect local source for partial, skipped, excluded, stale, or otherwise uncovered paths.
10. Use get_graph_schema before custom query_graph calls; request diagnostics="full" and needed schema pages when queryable properties are unknown. Reserve Cypher for scoped multi-hop or aggregate questions. LIMIT changes the query result; max_rows only controls the visible page (default 200), not computation. Continue with next_cursor, keeping query/project/graph unchanged. On a stale_cursor error, re-run the original query without cursor. Use graph="missed" to audit files the main graph did not fully index.
11. When two snapshots of one repository are indexed (for example base and head worktrees), compare_graphs(base_project, target_project) lists added and removed node and edge identities with exact totals; treat a truncated set as incomplete.
12. Complete every relevant result stream before an exhaustive claim; inspect counts and omission flags even when diagnostic arrays are empty. If a page cannot fit a result, increase its output budget for a bounded retry. If no supported continuation exists, narrow the request or state the limitation; do not invent a cursor or treat a lower-bound total as exact. For bounded discovery, stopping early is acceptable when the result states its limit or truncation. When graph and checked-out source disagree, treat source as current and report likely index drift.

Rooted Filesystem Fallback

• Anchor fallback exploration at the canonical checkout root or a narrower requested path. Set the command working directory there or use explicit absolute operands that remain within it.
• Do not silently broaden to a parent, an unrelated current directory, the user's home, a temporary directory, or a workspace root. Do not enable recursive symlink following (--follow or -L); resolve and inspect only targets that remain inside the canonical root.
• If the canonical root is missing, unreadable, otherwise inaccessible, or mismatched, report that condition and bound the claim to content actually inspected.
• Before a negative source claim, state whether the search included or excluded tracked, untracked, ignored, generated, vendored, submodule, binary, symlinked, and inaccessible content. rg exit 1 proves only that no match was found in the paths actually searched.

Indexing Modes

• Pass mode="moderate" explicitly for normal indexing: the tool defaults to full. Moderate filters files while retaining similarity and semantic edges. Pass persistence=false (the default) unless the user explicitly requests a shared .codebase-memory artifact.
• Use fast only for an explicitly requested smoke index, or when moderate is blocked and a degraded fallback is useful. Disclose that similarity and semantic edges are absent.
• Use full when the question needs supported content that moderate omits: files excluded by moderate's discovery filters (generated, docs, scripts, tools, build, fixtures, *.test.*, lockfiles and similar) or #define Macro nodes in C-preprocessor languages (C, C++, CUDA, GLSL, Objective-C, ISPC), and the extra indexing cost is justified. Full still honors .gitignore, .cbmignore, symlink exclusions, and always-ignored suffixes. It also skips the built-in skip directories unless a .cbmignore negation such as !target/ re-includes one; .git, node_modules, .worktrees, and .claude-worktrees can never be re-included. Full and moderate both compute similarity and semantic edges; only fast omits them. A project already indexed full stays full: a later moderate request is promoted, not downgraded. Source inspection remains a bounded alternative.

For lightweight positive discovery, an optional read-only endpoint may use --tool-profile=scout. For Verify or Auditor read-only analysis, it may use --tool-profile=analysis. Treat these as supplemental restricted profiles, not as the only primary server when an explicitly approved mutation is required.