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.

…