Codebase Memory MCP

Codebase Memory MCP

Use a configured Codebase Memory graph as a discovery accelerator, confirm graph-derived conclusions against source snippets or local files, and fall back to normal repository exploration when the server, project, index, or capability is unavailable.

Use it for graph-backed discovery, natural-language exploration, and moderate-only index caveats.

When to invoke

• "Use Codebase Memory to understand this module."
• "Trace callers and callees with the code graph."
• "What depends on this symbol?"
• "Use the MCP graph for impact analysis."
• "Find the architecture clusters for this repo."

Procedure

1. Discover the Codebase Memory tools exposed by the current MCP client; clients may prefix or rename tool namespaces.
2. Call list_projects when available and use the exact indexed project name.
3. If the repository is not indexed, continue with local exploration or ask before calling index_repository when graph access is important.
4. Before branch-sensitive or edit-sensitive conclusions, use index_status and verify the actual version-control state.
5. 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 status or diff before claiming no impact.
6. Use get_architecture once for unfamiliar structure. Request clusters to discover de-facto module seams.
7. 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.
8. Use search_graph for definitions, implementations, routes, classes, interfaces, and related symbols. Prefer natural language for discovery and name or qualified-name patterns for known symbols. Narrow by label or path and set a result limit.
9. For exhaustive claims, increase offset by limit while has_more is true.
10. Use search_code or normal repository search for literal strings, configuration keys, test identifiers, error messages, and non-code files.
11. After graph search, use get_code_snippet with the returned qualified name. If source snippets are unavailable, open the local file before relying on the result.
12. Use trace_path for callers, callees, dependency paths, data flow, cross-service paths, and impact analysis. Include tests when the claim covers them. While truncated is true, pass next back as cursor with every other argument unchanged.
13. After identifying candidate files, call check_index_coverage for every cited path.
14. Before negative or exhaustive claims, also check relevant scopes; advance scope_offset to each next_offset while has_more is true.
15. Use get_graph_schema before custom query_graph calls. Reserve custom queries for bounded multi-hop or aggregate questions, apply LIMIT or max_rows, and use graph="missed" to audit files the main graph did not fully index.
16. Complete every relevant result stream before an exhaustive claim. When graph and checked-out source disagree, treat source as current and report likely index drift.

Tool decision table

Indexing modes

Safety and fallbacks

• Do not install Codebase Memory or another third-party skill from this workflow.
• Do not call delete_project, ingest traces, update ADRs, or index a repository unless the user explicitly requested or approved the action; announce it before execution.
• Do not invent graph results. If the MCP server, project, index, or tool is unavailable, continue with normal repository exploration.
• Treat index coverage metadata as best-effort, not proof of completeness. Inspect local source for partial, skipped, excluded, stale, or otherwise uncovered paths.

Output template

## Codebase Memory result

**Status:** graph used | local fallback | blocked
**Project:** `<indexed project or not available>`

| Question | Tool or fallback | Evidence | Confidence |
| --- | --- | --- | --- |
| `<symbol/flow/module>` | `search_graph` / `trace_path` / local search | `<snippet, path, or result id>` | high/medium/low |

### Coverage and freshness
- `index_status`: `<result or not available>`
- `check_index_coverage`: `<paths/scopes checked or not available>`
- Source confirmation: `<files opened or snippets confirmed>`

### Limitations
- `<pagination, truncation, stale index, or fallback notes>`

Quality gate

• Graph conclusions are confirmed with source snippets or local files before edits or strong claims.
• Project, index freshness, and branch/change status are checked when relevant.
• Paginated has_more, offset, scope_offset, next_offset, truncated, and cursor streams are completed for exhaustive claims.
• Literal strings and config keys use search_code or local repository search, not broad graph discovery.
• Custom query_graph calls are schema-informed and bounded by LIMIT or max_rows.
• Unsafe actions such as delete_project, trace ingestion, ADR updates, or indexing are not performed without explicit user request or approval.
• Fallback behavior is reported when graph capability is unavailable or stale.