Persistent query layer for code structure
codebase-memory-mcp is a structural analysis backend for MCP clients. It parses repositories and writes functions, classes, imports, call chains, HTTP routes and cross-service relationships to a SQLite knowledge graph.
All 158 languages first use tree-sitter to produce syntactic structure. Hybrid LSP further resolves types for Python, TypeScript / JavaScript, PHP, C#, Go, C / C++, Java, Kotlin, Rust and Perl. The graph is stored in ~/.cache/codebase-memory-mcp/ and can be reused across sessions.
The server does not include an LLM. The agent converts natural-language requests into MCP tool calls; the server handles indexing, search, graph traversal, impact analysis and Architecture Decision Records.
Discover
Index
Search
Trace
Verify
Assess
Persist
codebase-memory-mcp is a structural analysis backend — it builds and queries the knowledge graph.
Executable installation and agent configuration
Use the official installation command on macOS or Linux. Add --ui if you need the 3D graph interface; the default installation is a headless server.
curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash
# Optional: include 3D graph UI
curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash -s -- --uiWindows PowerShell installation
Download and inspect the official script first, then remove the Mark-of-the-Web restriction and run it. If an execution policy error occurs, change the policy only in the current Process scope.
Invoke-WebRequest -Uri https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.ps1 -OutFile install.ps1
notepad install.ps1
Unblock-File .\install.ps1
.\install.ps1Index creation and change impact analysis
The tools cover index management, structural search, source verification, architecture analysis and optional graph writes. Use list_projects to confirm the project first, then choose a narrow query for the question. Obtain explicit authorization before deleting an index or writing an ADR.
Index · 01
index_repository
Repository indexing
Parse the specified repository to create or update a persistent knowledge graph.
Index · 02
list_projects
Index directory
List indexed projects and each project's node and edge statistics.
Index · 03
index_status
Index status
Check indexing progress, project health and scope not included in the index.
Index · 04
check_index_coverage
Evidence coverage
Check cited paths and scope for parsing gaps, exclusions or skipped items.
Search · 05
search_graph
Structural and semantic search
Search nodes by label, name regex, file scope, degree or semantic query.
Trace · 06
trace_path
Call-chain traversal
Use BFS to query a function's callers, callees and bidirectional call paths.
Verify · 07
get_code_snippet
Exact source
Read source snippets for functions, classes or symbols by qualified name.
Explore · 08
get_graph_schema
Graph structure
Return node, edge, relationship pattern and label property definitions.
Explore · 09
get_architecture
Architecture overview
Summarize languages, packages, entry points, routes, hotspots, layers and clusters.
Search · 10
search_code
Graph-enhanced text search
Run grep-like searches within indexed files while retaining symbol relationships.
Query · 11
query_graph
Cypher-like queries
Execute a read-only openCypher subset for multi-hop relationship patterns.
Impact · 12
detect_changes
Diff impact analysis
Map git diffs to affected symbols, blast radius and risk classifications.
Persist · 13
manage_adr
Architecture decision records
Create, update and read Architecture Decision Records.
Runtime · 14
ingest_traces
Runtime traces
Import runtime traces to supplement relationships such as HTTP_CALLS with actual data.
Index · 15
delete_project
Index deletion
Remove the specified project and all its graph data; confirm the project name before execution.
Tool selection by question
| Question | Starting tool | Verification tool |
|---|---|---|
| Where are the repository's main modules and entry points? | get_architecture | get_code_snippet |
| Who calls the specified function? | search_graph | trace_path |
| Which symbols could the current diff affect? | detect_changes | trace_path |
| Can query results support complete or negative conclusions? | index_status | check_index_coverage |
Index checks and conclusion scope
These operating principles are based on the official README, tool schemas and SECURITY.md. Every conclusion must retain project, index generation, pagination and coverage boundaries.
Indexed project list
Call list_projects on first use. Run index_repository only when the target repository is absent from the list.
Source · Official MCP instructions
Architecture overview and verification direction
Use get_architecture for broad questions, then verify specific claims with symbol searches and source snippets.
Source · Official README · MCP Tools
qualified name lookup
Use search_graph to find the exact symbol name before get_code_snippet or trace_path.
Source · Official tool schemas
trace_path call relationships
The degree in search_graph is the number of graph edges; use trace_path for caller and callee relationships.
Source · Official tool schemas
query_graph multi-hop relationships
Use search_graph and pagination for general exploration; use the read-only Cypher subset when multi-hop patterns are needed.
Source · Official README · CLI Mode
Coverage checks for complete conclusions
Call check_index_coverage for every cited path. A clean result means there are no recorded gaps; it does not establish completeness.
Source · Official Multi-Agent Support
Scope checks for negative claims
Claims of "no callers" or "no affected symbols" require checks of the relevant scope, pagination and skipped files.
Source · Official Multi-Agent Support
.cbmignore project scope
Use gitignore syntax to exclude generated files, fixtures or large datasets. Hardcoded ignores and the repository's .gitignore still apply first.
Source · docs/cbmignore.md
CLI streaming output
--progress writes progress to stderr; stdout retains tool results. Add --json when a complete MCP envelope is needed.
Source · Official README · CLI Mode
Version updates and agent restart
codebase-memory-mcp update switches the account-wide binary; restart open coding-agent sessions after it succeeds.
Source · Official README · Coordination Daemon
Repository indexing and change impact conclusions
The query workflow does not rely on statistics from a specific repository. The agent selects an index, then uses architecture, search, trace, snippet and coverage to produce a verifiable answer.
$ You ›
Find the callers of ProcessOrder and explain which paths the current diff affects.
claude: Agent ›
First confirm the available project and index status, then query symbols and call chains.
claude: Agent ›
The architecture overview is ready; next, search for symbols only in the relevant package.
hl: After finding candidates, retain qualified_name, file path and pagination status.
claude: Agent ›
The call chain is available; now map the working tree diff to symbols and blast radius.
[evidence set]
1. Exact symbol name and source file
2. inbound callers and query depth
3. Symbols directly affected by the diff
4. Affected downstream paths
5. index coverage for each cited path
ok: RESULT:
ok: caller and impact claims include project, generation, qualified name,
ok: file path, pagination and coverage limits.
claude: Completeness claims unsupported by the index have been replaced with statements of limitations.
Use graph tools first.
Required evidence fields
Results must include the project, index generation, qualified symbol, file path and query direction. For tools with pagination, also record has_more, limit and offset.
When check_index_coverage reports gaps, read the relevant file ranges directly. Graph query results cannot replace evidence outside the index.
Index coverage and local access boundaries
Single repositories and cross-service graphs
After indexing and querying a single repository, enable auto-indexing, cross-repository relationships, runtime traces or shared graph artifacts. Record the project, generation and coverage again whenever you expand scope.
Advanced configuration
1. Enable automatic indexing. Run codebase-memory-mcp config set auto_index true. Set auto_watch false when you need to limit the watcher.
2. Configure custom file extensions. Map nonstandard extensions to existing parsers in global or per-project configuration, then rebuild the index.
3. Create cross-repository relationships. Index multiple services into the same store. Use CROSS_* edges and architecture summaries to query cross-service routes and dependencies.
4. Import runtime traces. Use ingest_traces to supplement HTTP_CALLS relationships in the static graph; confirm the data source and persistence scope before execution.
5. Share a compressed graph. Commit .codebase-memory/graph.db.zst when the team needs a shared graph; after cloning, incremental indexing adds local differences.
Three further documents
① README.md: Installation, 15 tools, CLI and Multi-Agent Support.
② docs/CONFIGURATION.md: Runtime settings, environment variables and extension mapping.
③ SECURITY.md: Local processing, update checks, binary verification and disclosure procedures.
One graph query replaces dozens of grep/read cycles.