TL;DR
codebase-memory-mcp by DeusData is an open-source Model Context Protocol (MCP) server that indexes your entire codebase into a persistent knowledge graph — functions, classes, call chains, HTTP routes, cross-service links — and serves it to AI coding agents (Claude Code, Codex CLI, Gemini CLI and many more) via 17 MCP tools (14 when this review was published). The project first claimed 99% fewer tokens for structural queries; its preprint reports 10× fewer tokens. It can index the Linux kernel (28M LOC, 75K files) in 3 minutes (the project’s own benchmark). The self-contained binary needs no runtime dependencies, supports 164 languages and file formats via vendored tree-sitter grammars (158 at publication), and had 48,846 GitHub stars on November 19, 2026 (27,676 at publication).
The core insight is deceptively simple: AI coding agents spend most of their token budget reading files one-by-one to understand code structure. A query like “find all API handlers that call the auth middleware” requires grepping, reading imports, tracing call chains — 10–20 individual file reads, each gobbling context. codebase-memory-mcp pre-indexes all that structure into a local SQLite graph, then answers the same question in one tool call with ~3,400 tokens instead of ~412,000.
Key facts:
- 48,846 GitHub stars and 4,060 forks (November 19, 2026); 27,676 at publication in July
- Latest release: v0.12.1 (October 16, 2026), MIT license
- arXiv paper (2603.27277): 83% answer quality, 10× fewer tokens, 2.1× fewer tool calls vs. file-by-file search across 31 repos
- 164 languages via vendored tree-sitter, plus Hybrid LSP semantic type resolution for supported languages
- 46 client integrations (40 auto-detected, 6 conditional) configured by one install — 11 agents at publication
- 100% local processing — no telemetry, no API keys, no Docker
Not run by us for this refresh: our test lab (a throwaway GitHub Actions container) could not start on November 19, 2026 because GitHub refused the job over a billing limit on the account. Our recorded run of an earlier version (0.11.0, October 4, 2026) is in our other codebase-memory-mcp review.
What changed as of November 2026
Re-checked against the repository, README and release notes on November 19, 2026.
- v0.12.0 (October 15, 2026) was the project’s biggest release: 231 merged pull requests. It added CBM Lens (beta), a browser interface for people that ships inside the binary and listens on loopback only; documentation in the graph (doc comments, Markdown, reStructuredText, AsciiDoc, PDF, ADRs, diagrams and OpenAPI specs linked to the code they name); Smart CI, where
detect_changesnames the tests a diff can affect; and infrastructure as code (Kubernetes, Helm, Flux, Argo CD, Compose, Dockerfiles, CI jobs) as graph nodes. - v0.12.1 (October 16, 2026) fixed npm, PyPI and Go installs, which could not install v0.12.0 on any platform, and moved Homebrew on Linux to the static
-portablebuild. It also removed winget and Chocolatey from the listed install channels because they are not published. - The tool list changed. There are now 17 MCP tools; several names in our original table no longer exist (call tracing is
trace_path, Cypher queries run throughquery_graph, and semantic search is a parameter ofsearch_graph). The table below now lists the current tools. - After upgrading, the first index of each existing project is a full rebuild, once.
Why This Matters
If you’ve used Claude Code or Codex CLI on a nontrivial codebase, you’ve hit the wall. The agent can’t keep the full project in context. It reads files one at a time, builds a mental model file-by-file, and by the time it’s navigated through 40 source files, the original task is buried in the context window. Token costs mount. The agent gets confused. You reach for grep -r and lose the agent flow entirely.
codebase-memory-mcp front-loads that structural understanding into an offline index, then exposes it as 14 MCP tools the agent calls in under 1 millisecond per query. Instead of “read file, parse imports, read next file, trace calls,” the agent fires:
get_architecture → returns all packages, entry points, routes, and layers
One call. 3,400 tokens. Done.
This is the same philosophy that made MCP successful — separate the “understanding” from the “doing.” The agent stops being a slow grep and starts being a fast architect.
Installation
One-liner for macOS / Linux:
curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash
Since v0.12.0 the standard release includes the CBM Lens UI. Start it after installing:
codebase-memory-mcp daemon start --open --port=9749
Windows (PowerShell):
Invoke-WebRequest -Uri https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.ps1 -OutFile install.ps1
Unblock-File .\install.ps1
.\install.ps1
The installer auto-detects installed coding agents on your machine — Claude Code, Codex CLI, Gemini CLI, Zed, OpenCode, Antigravity, Aider, KiloCode, VS Code, OpenClaw, and Kiro at publication; 46 client integrations as of v0.12.1 — and configures MCP entries, skill instruction files, and hooks where each client supports them. Restart your agent, say “Index this project,” and you’re live.
If you prefer manual install, grab the archive from the latest release:
tar xzf codebase-memory-mcp-*.tar.gz
./install.sh
Zero dependencies. The executable is self-contained (the Linux -portable archives are fully static), every release ships a checksums.txt, and release binaries are scanned on VirusTotal before publishing. The Windows build is unsigned, so SmartScreen may warn. The installer even strips macOS quarantine attributes and ad-hoc signs the binary automatically — no xattr ceremonies.
What It Actually Does
The indexer parses your source tree through vendored tree-sitter grammars compiled into the binary (158 at publication, 164 as of November 2026). Nothing to install, nothing to configure, nothing that breaks when you update Homebrew. The output is a SQLite graph database in ~/.cache/codebase-memory-mcp/ containing:
- Functions: signatures, parameters, return types, docstrings, bodies
- Classes: hierarchies, inheritance chains, implemented interfaces
- Call chains: who-calls-who across files and packages
- HTTP routes: REST endpoints, gRPC services, GraphQL resolvers, tRPC procedures
- Channels: Socket.IO, EventEmitter, pub-sub patterns across 8 languages
- Docker/Kubernetes: Dockerfiles, K8s manifests, Kustomize overlays as graph nodes
- Data flows: arg-to-param mapping with field access chains
- Near-clones: MinHash + LSH for similar code detection
And it does this fast. “Average repo in milliseconds” is not a boast — the RAM-first pipeline uses LZ4 compression and in-memory SQLite, releasing memory after the final dump. The Linux kernel (28M LOC, 75K files) indexes in 3 minutes.
The 17 MCP Tools (November 2026)
These are the tools your agent can call, per the README for v0.12.1 (the table at publication listed 14 tools, several under names that no longer exist):
| Tool | What It Does |
|---|---|
index_repository | Index a repository into the graph (async: true for long indexes) |
list_projects | List indexed projects; detail: "stats" for node/edge counts |
delete_project | Remove a project and its graph data |
index_status | Indexing status of a project |
check_index_coverage | Whether exact paths or a scope are indexed and fresh |
search_graph | Structural, BM25 and semantic search (semantic search is a parameter here, not a separate tool) |
trace_path | Callers, callees, data flow, cross-service, topology, deploy and run paths (alias trace_call_path) |
detect_changes | Git diff → affected symbols, blast radius and risk; can name the tests a change affects |
query_graph | Read-only Cypher-like graph queries |
get_graph_schema | Node/edge counts, relationship patterns, properties per label |
compare_graphs | Node/edge additions and removals between two indexed snapshots |
get_code_snippet | Source of a function by qualified name |
get_file_outline | Declaration outline of one file |
get_architecture | Languages, packages, routes, hotspots, clusters, ADR |
search_code | Grep-like text search within indexed files |
manage_adr | Read and edit Architecture Decision Records |
ingest_traces | Store observed call paths under a run label |
Example Session (illustrative, not a recorded test)
Editor’s note (November 19, 2026): this walkthrough was written at publication without a saved test record, so treat its timings and token figures as illustrative, not measured. It also uses tool names from the July version (trace_calls, find_dead_code); today call tracing is trace_path. Our recorded run — codebase-memory-mcp 0.11.0 indexing Flask in a clean Linux container on October 4, 2026 — is in our other codebase-memory-mcp review.
The session below describes using codebase-memory-mcp on a mid-sized TypeScript monorepo (~200 files, ~50K LOC) with Claude Code.
Indexing: The index command took 14 seconds. The installer had already configured Claude Code’s .claude/settings.json with the MCP server entry. I restarted Claude Code, typed “Index this project,” and it worked immediately.
First real query: “Show me the architecture.” One MCP tool call — get_architecture — returned a structured breakdown: 4 packages, 2 entry points (src/index.ts, src/api/server.ts), 38 HTTP routes organized by middleware layer, 6 external service integrations, and a dependency graph. The full response was 2,100 tokens. Doing the same manually would have required grepping through 15+ files for route registrations, tracing middleware imports, reading each handler file — easily 80,000 tokens of context.
Second query: “Find all places that call the auth middleware.” trace_calls authMiddleware → 12 call sites across 8 files, each with file path, line number, and the calling function’s context. Took 800ms.
Third query: “What changed in the last commit?” detect_changes → 4 modified files, each mapped to the affected functions, with a risk classification (low/medium/high). Two changes were flagged as medium risk because they touched functions called by the auth middleware.
Fourth query: “Find dead code.” find_dead_code → 3 exported functions with zero callers. One was a vestigial formatDate helper from a refactor last month. Another was a WebSocket handler for a feature that got scrapped. I removed all three. That’s 20 minutes of cleanup in one command.
Token savings: Over a 45-minute session making ~30 structural queries, codebase-memory-mcp consumed an estimated 102,000 tokens for code understanding. File-by-file equivalent would have been at least 800,000–1,200,000 tokens — probably an 8–10× reduction in practice.
Where It Shines
Large monorepos
This is the killer use case. If your team has a 500-file monorepo with services, shared packages, and infrastructure code, the agent spends 80% of its context window just learning the layout. codebase-memory-mcp flattens that to milliseconds.
Cross-service refactoring
The cross_repo_query tool links nodes across multiple repos indexed under the same store. If you’re renaming an API endpoint in Service A and need to trace all callers in Service B, the graph follows CROSS_HTTP_CALLS edges automatically.
Onboarding new agents
Switching from Claude Code to Codex CLI? The knowledge graph persists. codebase-memory-mcp stores everything in ~/.cache/ — all 11 supported agents read from the same database. No re-indexing needed.
Team-shared artifacts
Your team can commit .codebase-memory/graph.db.zst (a zstd-compressed snapshot of the knowledge graph) to the repo. When a teammate indexes a clone that has the artifact, CBM imports it and applies only their local changes. The artifact is opt-in: as of November 2026 it is written only when index_repository is called with persistence: true.
Honest Limitations
The 83% answer quality trade-off
The arXiv paper is candid: 83% answer quality vs. 92% for file-by-file exploration. That’s a 9-point gap. The graph sometimes misses context — a function’s body might be simplified, a dynamic import might not resolve, a complex type might lose its generic parameters. For precision-sensitive work (e.g., “find the exact line that handles this specific error code”), file-by-file is still better.
”99% fewer tokens” is relative
An independent benchmark confirmed that the 99% claim uses an unoptimized baseline (grep + cat everything). In practice, you’ll see 8–12× savings, which is still remarkable — but the marketing number assumes the worst possible alternative.
Initial indexing time for huge repos
3 minutes for the Linux kernel is genuinely fast, but those 3 minutes are a blocking operation. You clone a repo, run index, wait. The background watcher handles incremental changes after that, but the first index can’t be skipped.
Not a replacement for reading files
codebase-memory-mcp gives you structure, not full source. Your agent still needs to read_file for implementation details — the graph tells it where to look, not what the code says. This is by design (that’s how it saves tokens), but some workflows feel fragmented: “The function exists at src/handler.ts:142, let me read it.” Two calls instead of one.
Hybrid LSP isn’t full LSP
The Hybrid LSP resolver covers 10 languages but is a lightweight C implementation of type-resolution algorithms. It handles parameter binding, return-type inference, generic substitution, JSX dispatch, and JSDoc/namespace/etc. for those languages. But it’s not a full language server — you won’t get go-to-definition precision for every edge case. The project acknowledges this and the tree-sitter AST is always the fallback.
Community Reaction
Correction (November 19, 2026): this section originally said the Show HN launch “hit 179 points” and linked to a Hacker News item that turned out to be unrelated. We found no such thread: Hacker News search shows codebase-memory-mcp submissions with single-digit points. We also could not trace the quotes below to their original threads when we re-checked, so treat them as unverified.
Feedback quoted at publication:
Positive:
“Just tested this on our 300-file Next.js app. Indexed in 11 seconds. The
detect_changestool alone saved me from a deployment-breaking refactor. Game changer.” — r/LocalLLM
“I’ve been wanting something like this since MCP launched. The single binary install is chef’s kiss — no Docker, no npm, no 500MB of Python dependencies. This is how tools should ship.” — HN comment
“Tried it with Codex CLI on a Go monorepo. Cross-service route mapping worked out of the box. The HTTP route → call-site matching with confidence scores is genuinely useful.” — GitHub issue
Constructive criticism:
“It’s fast, but I ran into several cases where the semantic query returned irrelevant results. The vector search needs tuning — or maybe my codebase is just weird.” — r/LocalLLM
“The speed is impressive but 83% accuracy concerns me for mission-critical refactoring. I’d use it for exploration but still double-check manually before a production deploy.” — HN comment
“Would love to see better C++ support. The tree-sitter grammar works but the Hybrid LSP doesn’t cover template metaprogramming edge cases.” — GitHub discussion
“The
99% fewer tokensheadline is doing a lot of work. My actual savings were more like 85% on my TypeScript project. Still great, but the marketing is aggressive.” — Reddit
Pricing
Free and open-source (MIT license). No paid tiers, no cloud, no API keys, no telemetry. Every release binary is signed, checksummed, and scanned by 70+ antivirus engines. The project is entirely local-first.
Available from: npm, PyPI, Homebrew, Scoop, AUR, and go install (November 2026). Winget and Chocolatey were listed at publication but are not published, per the v0.12.1 release notes.
FAQ
What’s the difference between codebase-memory-mcp and grep?
grep searches text. codebase-memory-mcp understands structure — it knows that authMiddleware is a function with 12 callers across 8 files, that it’s typed as (req: Request, res: Response, next: NextFunction) => void, and that it’s registered on routes matching /api/*. grep gives you lines. The graph gives you a map.
Does it work with VS Code extensions?
Yes — the installer auto-configures VS Code via MCP settings. Any VS Code extension that supports the Model Context Protocol (like Continue.dev or Cline) can use the 14 tools. The install.sh script adds the MCP entry to VS Code’s global settings.
Can I run it without any AI agent?
Yes, in CLI mode: codebase-memory-mcp cli search_graph --project <name> --name-pattern '.*Handler.*' (cli list_projects --format json gives you the project name). You can also open the CBM Lens UI with codebase-memory-mcp daemon start --open --port=9749, which serves it at http://127.0.0.1:9749.
How does the semantic search work without an API key?
The binary bundles a quantized Nomic nomic-embed-code model (40K vocabulary, 768-dimension int8) compiled directly into the binary. It uses an 11-signal combined scoring system: TF-IDF, RRI, API/Type/Decorator signatures, AST profiles, data flow analysis, Halstead-lite complexity, MinHash, module proximity, and graph diffusion. Everything runs locally — no API key, no Ollama, no Docker.
Does it watch for file changes?
Yes. After indexing, a background watcher detects file modifications and re-indexes changed files incrementally. You can disable this with config set auto_watch false if you’re working across many projects and want each session contained to explicit indexing. Automatic indexing on session start is controlled separately with config set auto_index true.
What happens when I update it?
As of November 2026, codebase-memory-mcp update prints the exact installer command to run rather than replacing the binary itself; npm and pip installs update through the package manager (npm install -g codebase-memory-mcp@latest / pip install -U codebase-memory-mcp). Indexes persist, but the first index of each project after upgrading to v0.12.x is a full rebuild.
How do I uninstall?
codebase-memory-mcp uninstall removes all agent configs, skills, hooks, and instructions from every auto-detected agent. The binary and SQLite databases are left in place in case you change your mind — delete them manually if you want a full cleanup.
Verdict
codebase-memory-mcp is the most practical code-intelligence tool we have reviewed for AI coding agents. The 83% accuracy trade-off is real and worth knowing about, but for exploratory queries, architecture overviews, change impact analysis, and dead code detection, the speed and token efficiency make it an obvious default. You keep file-by-file reading for the final mile of implementation — but you stop wasting 80% of your agent’s context on structural discovery.
Who it’s for: Anyone using Claude Code, Codex CLI, Gemini CLI, or any MCP-compatible agent on a codebase larger than ~50 files. Monorepo teams will get the most value.
Who should skip it: If you mostly work on single-file scripts or tiny projects, the setup overhead outweighs the benefit. Stick with grep.
The single binary, zero-dependency, auto-configure-for-11-agents approach sets a new bar for how MCP servers should ship. DeusData has built a reference implementation for the category.
Sources
- codebase-memory-mcp GitHub Repository — README, tool list, install channels (48.8K stars on November 19, 2026)
- v0.12.0 release notes — CBM Lens, documentation graph, Smart CI
- v0.12.1 release notes — install fixes, winget/Chocolatey removed
- arXiv Paper: Codebase-Memory: Tree-Sitter-Based Knowledge Graphs for LLM Code Exploration via MCP — 83% accuracy, 10× token reduction benchmarks
- r/LocalLLM thread — submitted by andrew.ooo
- DEV.to: High-Performance Code Intelligence Review — Third-party review
- Hacker News search for codebase-memory-mcp — checked November 19, 2026