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_changes names 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 -portable build. 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 through query_graph, and semantic search is a parameter of search_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):

ToolWhat It Does
index_repositoryIndex a repository into the graph (async: true for long indexes)
list_projectsList indexed projects; detail: "stats" for node/edge counts
delete_projectRemove a project and its graph data
index_statusIndexing status of a project
check_index_coverageWhether exact paths or a scope are indexed and fresh
search_graphStructural, BM25 and semantic search (semantic search is a parameter here, not a separate tool)
trace_pathCallers, callees, data flow, cross-service, topology, deploy and run paths (alias trace_call_path)
detect_changesGit diff → affected symbols, blast radius and risk; can name the tests a change affects
query_graphRead-only Cypher-like graph queries
get_graph_schemaNode/edge counts, relationship patterns, properties per label
compare_graphsNode/edge additions and removals between two indexed snapshots
get_code_snippetSource of a function by qualified name
get_file_outlineDeclaration outline of one file
get_architectureLanguages, packages, routes, hotspots, clusters, ADR
search_codeGrep-like text search within indexed files
manage_adrRead and edit Architecture Decision Records
ingest_tracesStore 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_changes tool 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 tokens headline 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