codebase-memory-mcp: A Tree-Sitter Knowledge Graph for AI Coding Agents

What It Solves: The Token and Latency Problem in Code Exploration

AI coding agents that read a repository file by file burn tokens and time. A typical exploration cycle involves dozens of grep and read operations, each one a round trip to the model. codebase-memory-mcp attacks that directly. It builds a persistent knowledge graph of functions, classes, call chains, HTTP routes, and cross-service links, then exposes that graph through 15 MCP tools. The README claims a 120x token reduction: five structural queries use about 3,400 tokens versus roughly 412,000 for file-by-file search. The target user is a developer running a local coding agent like Claude Code or Continue on a large repository, where the cost of repeated reads becomes the bottleneck. The project positions itself as the fastest option, with the Linux kernel (28M LOC, 75K files) indexed in 3 minutes and sub-millisecond query responses. Those numbers come from the project's preprint, not from independent testing, so treat them as vendor claims until you reproduce them.

The Mechanism: Tree-Sitter ASTs, Hybrid LSP, and a RAM-First Pipeline

The indexing engine is built in C and uses vendored tree-sitter grammars compiled directly into the binary. That is why it supports 161 languages with no external runtime or grammar installation. Parsing produces an AST for each file, and the project adds a layer called Hybrid LSP for semantic type resolution in 12 languages: Python, TypeScript, JavaScript, JSX, TSX, PHP, C#, Go, C, C++, Java, Kotlin, Rust, and Perl. This is the key differentiator from a plain tree-sitter index: it resolves types and symbols that pure syntax parsing cannot, such as cross-file imports and inferred types. The pipeline is described as RAM-first: LZ4 compression, in-memory SQLite, and fused Aho-Corasick pattern matching. The graph is persisted, so queries do not re-parse the repository each time. The README also mentions infrastructure-as-code indexing, where Dockerfiles, Kubernetes manifests, and Kustomize overlays become graph nodes with edges like IMPORTS, which is unusual and useful for platform engineers. The built-in 3D visualization at localhost:9749 is served from the binary itself, giving a human-readable view of the graph without a separate service.

Installation and First Run: One Command, Then a Phrase

The install path is deliberately short. On macOS or Linux, the one-liner is:

curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash

Windows uses a PowerShell script: download install.ps1, optionally inspect it with notepad, unblock it with Unblock-File, then run it. The install command auto-detects installed coding agents and configures their MCP settings. It also strips macOS quarantine attributes and ad-hoc signs the binary, so you do not need manual xattr or codesign steps. There is a --skip-config option that installs only the binary without touching agent configurations, and --dir=<path> to control the install location. After installation, you restart your agent and say "Index this project". The manual route is equally direct: download the archive for your platform, extract it, and run install.sh or install.ps1. The README warns that Microsoft Defender may flag the binary as Trojan:Script/Wacatac.B!ml, which it calls a known false positive, with typically 61 of 62 engines returning clean. That warning is a real adoption hurdle, and the project addresses it by publishing VirusTotal results for each release candidate and linking them from release notes.

The 15 MCP Tools and What They Actually Do

The README lists the tool categories but does not give the full API surface for each one. What is visible: search, trace, architecture, impact analysis, targeted index-coverage checks, Cypher queries, dead code detection, cross-service HTTP linking, ADR management, and more. The Cypher query tool is notable because it exposes the knowledge graph directly, letting a user run arbitrary graph queries beyond the predefined tools. That is a power feature for debugging the index itself. Cross-service HTTP linking is a differentiator: it connects HTTP routes across services, which is useful for microservice repositories where file-by-file search cannot see the service boundary. Dead code detection is another tool that would normally require a separate static analysis pass. The tool set is broad enough that the project could replace several single-purpose tools, but the README does not specify the exact input and output schemas for each tool. An adopter should expect to read the source or the MCP schema after installation to understand the exact parameters.

Limitations and Failure Modes: False Positives, Config Writes, and Language Gaps

The most obvious limitation is the antivirus false positive. The README itself warns that Defender may flag the binary, and while the project provides evidence of a false positive, a security-conscious team may still refuse to run it. The tool also writes to your agent configuration files. That is by design, but it means the install step has side effects beyond placing a binary. If you do not want that, the --skip-config flag exists, but then you must configure the MCP endpoint manually. Another limitation: Hybrid LSP semantic resolution is only claimed for 12 languages. The other 149 languages get tree-sitter syntax parsing, which gives you symbols and structure but not the same type-resolution quality. If your primary language is, say, Ruby or Swift, you will get a graph but not the full semantic enrichment. The README also says the tool reads your codebase; it processes everything locally, so no data leaves the machine, but that is a trust statement, not a verified claim. Finally, the indexing speed claim of milliseconds for an average repo depends on RAM availability and repository size; the Linux kernel takes 3 minutes, so the 'milliseconds' figure applies to small repositories only.

Alternatives: File-by-File Search and Other MCP Servers

The most direct alternative is no MCP server at all: letting the agent read files directly. That is the baseline the project compares against, with 120x fewer tokens and 2.1x fewer tool calls. The trade-off is that the agent loses the ability to see raw file contents unless it queries the graph and then reads specific files. A more structured alternative is a semantic code search tool like Sourcegraph's Cody or a local indexer such as ctags-based navigation, but those do not expose a knowledge graph via MCP. The preprint compares against file-by-file exploration, not against other MCP servers. If you want a similar graph-based approach without a compiled binary, you could build a custom MCP server that uses tree-sitter directly, but you would need to implement the graph persistence and query layer yourself. The key difference is that codebase-memory-mcp ships as a single static binary with zero runtime dependencies, while a custom solution would require a language runtime and dependency management. For teams that already use an MCP-compatible agent, this project is a drop-in; for teams on a different protocol, it is not.

Maintenance and Upgrade Cost: Release Cadence and Provenance

The project is under active development. The last push is 2026-08-19, with three releases on consecutive days: v0.10.8, 0.10.7, and v0.10.6. That cadence suggests rapid iteration, which is good for bug fixes but implies frequent upgrades. The install script handles updates by re-running it, but each upgrade may change the MCP tool schemas or the graph format. The README mentions a release policy in SECURITY.md that includes submitting three behaviourally identical executable candidates to VirusTotal before testing, then packaging the selected candidate with its SHA-256 unchanged. That is a strong provenance practice, but it also means you should verify the SHA-256 after every upgrade, not just the first install. The project is licensed under MIT, which permits commercial use and modification with attribution. There is no mention of a hosted service or API key, so the maintenance cost is entirely on your side: you manage the binary, the graph storage, and any agent config changes. The project also publishes a preprint on arXiv, which gives you a reference for the design and benchmarks, but that is not a guarantee of ongoing support.

Editorial conclusion

Adopt codebase-memory-mcp if you run an AI coding agent on a large codebase and want to cut token usage and tool calls by replacing grep/read cycles with graph queries. Skip it if you need a hosted service, multi-user collaboration, or if you cannot accept the risk of a binary that modifies your agent config files and may trigger antivirus false positives. Before adopting, verify the release artifact's SHA-256 against the release notes, run the binary in a sandbox first, and test the Hybrid LSP resolution on your primary language, since the README only claims semantic type resolution for 12 languages. Also confirm that your agent is among the 45 supported client surfaces, or you will have to configure the MCP endpoint manually.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes