/codebase-memory-mcp

name: codebase-memory-mcp
description: 'Use when exploring unfamiliar code, mapping architecture, finding symbols or relationships, tracing callers, callees, data flow or dependencies, assessing impact, auditing dead or complex code, or handling explicit Codebase Memory requests. Otherwise skip tasks confined to a supplied known file, tiny one-file check, exact literal, configuration value, error string, or non-code text.'

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 worktr