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 8 more) via 14 specialized MCP tools. It claims 99% fewer tokens for structural queries and can index the Linux kernel (28M LOC, 75K files) in 3 minutes. The single static binary has zero runtime dependencies, supports 158 languages via vendored tree-sitter grammars, and is trending with 27,676 GitHub stars (6,309 this week).

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:

  • 27,676 GitHub stars, 6,309 added this week — top 5 trending repos
  • arXiv paper (2603.27277): 83% answer quality, 10× fewer tokens, 2.1× fewer tool calls vs. file-by-file search across 31 repos
  • 158 languages via vendored tree-sitter, 10 languages with Hybrid LSP semantic type resolution
  • 11 AI coding agents auto-detected and configured in one install
  • 100% local processing — no telemetry, no API keys, no Docker

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

With the optional 3D graph visualization UI:

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

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 all installed coding agents on your machine — Claude Code, Codex CLI, Gemini CLI, Zed, OpenCode, Antigravity, Aider, KiloCode, VS Code, OpenClaw, and Kiro — and configures MCP entries, skill instruction files, and pre-tool hooks for each. 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 binary is statically linked, signed, checksummed, and scanned by 70+ antivirus engines before every release. 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 158 vendored tree-sitter grammars compiled into the binary. 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 14 MCP Tools

These are the tools your agent can call after indexing:

ToolWhat It Does
get_architectureLanguages, packages, entry points, routes, hotspots, boundaries, layers, clusters
search_graphRegex name patterns, label filters, min/max degree, file scoping
search_codeGraph-augmented grep over indexed files only
semantic_queryVector search across the entire graph (Nomic embeddings, no API key)
trace_callsResolve function calls across files and packages
get_architectureSingle-call architecture overview
manage_adrArchitecture Decision Records persisted across sessions
detect_changesGit diff → affected symbols with risk classification
find_dead_codeFunctions with zero callers, excluding entry points
cypher_queryMATCH (f:Function)-[:CALLS]->(g) WHERE f.name = 'main' RETURN g.name
bm25_searchFull-text search via SQLite FTS5 + camelCase-aware tokenizer
get_call_chainFull call path from entry point to leaf
find_http_routesAll HTTP endpoints with handlers and middleware
cross_repo_queryArchitecture summary across multiple indexed repos

Hands-On: What It’s Like to Use

I tested 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 clones and runs the install, the index is already there. No re-indexing on CI or for new hires.

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

The Show HN launch hit 179 points and the Reddit discussion on r/LocalLLM generated polarized but engaged feedback:

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, Winget, Chocolatey, AUR, and go install.

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 '{"name_pattern": ".*Handler.*"}'. This outputs JSON directly to stdout — pipe it into jq for ad-hoc analysis. You can also run the graph visualization UI standalone at localhost: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?

codebase-memory-mcp update updates the binary to the latest release. The SQLite cache persists. The binary checks for updates on startup and notifies on the first tool call if a newer release is available.

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 I’ve tested 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