If you use an AI coding agent — Claude Code, Codex CLI, Gemini CLI, Cursor, Zed, Aider, whatever — you've probably watched it burn through tens of thousands of tokens just trying to figure out who calls a function or where a route is defined. It greps, it reads files, it greps again, it reads more files. Eventually it answers your question, but it took a small forest of tokens and several tool calls to do it.
codebase-memory-mcp is an open-source MCP server built to fix exactly that. It indexes your codebase into a persistent knowledge graph — functions, classes, call chains, HTTP routes, cross-service links — and lets your agent ask structural questions directly instead of reading its way through the filesystem.
Here's what's actually in it for you.
The pitch in one paragraph
You install a single static binary. You tell your agent "index this project." A few seconds to a few minutes later (yes, even the Linux kernel — 28 million lines of code — takes about 3 minutes), your agent can ask things like "what calls ProcessOrder?" or "show me the architecture of this service" and get an answer in under a millisecond, instead of grepping and reading dozens of files. No Docker, no API keys, no separate database to run. It's just a binary that talks MCP.
Why this matters: the token math
This is the number that should get your attention. According to the project's own benchmarks, five typical structural queries cost roughly 3,400 tokens through codebase-memory-mcp, versus about 412,000 tokens doing the equivalent file-by-file grep-and-read exploration. That's a 99 percent reduction. Less context burned on exploration means more budget left for the agent to actually reason about your problem — and a noticeably faster, cheaper session.
What it actually does
At its core, codebase-memory-mcp is a structural analysis backend, not another LLM wrapper. It parses your code with tree-sitter, builds a graph of how everything connects, and exposes that graph through 14 MCP tools. Your agent is still the brain — it just stops having to rediscover your codebase from scratch every session.
A typical interaction looks like this:
You: "what calls ProcessOrder?"
Agent calls: trace_call_path(function_name="ProcessOrder", direction="inbound")
codebase-memory-mcp: executes the graph query, returns structured results
Agent: presents the call chain in plain English
No extra LLM, no extra API key, no extra cost layer — the agent you're already paying for does the translation from natural language to graph query.
The features that actually matter day to day
It's fast, even on huge repos. RAM-first indexing pipeline (LZ4 compression, in-memory SQLite, single dump at the end). Benchmarked on an Apple M3 Pro, the Linux kernel indexes in about 3 minutes; a mid-sized project like Django takes around 6 seconds. Memory is released back to the OS once indexing finishes.
It speaks 155 languages. Tree-sitter grammars for all of them are vendored directly into the binary, so there's nothing extra to install. Go, C, C++, and the TypeScript/JavaScript/JSX/TSX family additionally get LSP-style hybrid type resolution — proper parameter binding, return-type inference, generic substitution, and JSDoc inference for plain JS files.
It plugs into 11 coding agents automatically. Running the installer auto-detects Claude Code, Codex CLI, Gemini CLI, Zed, OpenCode, Antigravity, Aider, KiloCode, VS Code, OpenClaw, and Kiro, and configures MCP entries, instruction files, and hooks for whichever ones you have installed.
It understands more than just application code. Dockerfiles, Kubernetes manifests, and Kustomize overlays get indexed as graph nodes too, with cross-references between them — useful if your agent needs to reason about infrastructure as well as application logic.
It finds dead code, traces blast radius, and detects near-duplicates. Beyond simple search, there's Louvain community detection for discovering functional modules, git-diff impact mapping that classifies risk for uncommitted changes, dead code detection (excluding entry points), and MinHash-based near-clone detection.
It can visualize the graph. An optional UI binary variant ships a built-in 3D graph visualization you can open in a browser at localhost:9749, running alongside the MCP server as a background thread.
Your team doesn't all have to reindex separately. A .codebase-memory/graph.db.zst artifact can be committed alongside your source — a zstd-compressed snapshot of the graph. When a teammate clones the repo and runs the indexer for the first time, it imports that snapshot and only does an incremental diff locally, instead of a full reindex. It's entirely optional and gitignore-friendly if you'd rather everyone start fresh.
Getting started
The one-line install on macOS or Linux:
curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash
Add -s -- --ui on the end if you want the graph visualization included.
On Windows, download install.ps1 and run it from PowerShell. There's also a manual route if you'd rather inspect everything first: download the platform-specific archive from the latest release, extract it, and run the bundled install script.
Once installed, restart your coding agent and just say:
"Index this project"
That's the entire setup. If you want indexing to happen automatically whenever you open a new project, turn on auto-index:
codebase-memory-mcp config set auto_index true
After the initial index, a background watcher keeps the graph in sync with your git changes, so you're not manually re-indexing every time you commit.
What you get to ask it
Once a project is indexed, here's a sample of what's available through the 14 MCP tools:
-
search_graph— structured search by label, name pattern, file pattern, or degree filters -
trace_call_path— BFS traversal showing what calls a function and what it calls, up to depth 5 -
get_architecture— a one-call overview of languages, packages, entry points, routes, hotspots, and clusters -
detect_changes— maps your current git diff to the symbols it affects, with risk classification -
query_graph— Cypher-like queries, e.g.MATCH (f:Function)-[:CALLS]->(g) WHERE f.name = 'main' RETURN g.name -
semantic_query— vector search over the whole graph using bundled embeddings, no API key required -
manage_adr— CRUD operations for Architecture Decision Records, so design decisions persist across sessions -
get_code_snippet,search_code,ingest_traces, and several more
Everything is also callable directly from the command line if you want to script against it:
codebase-memory-mcp cli search_graph '{"name_pattern": ".*Handler.*", "label": "Function"}'
codebase-memory-mcp cli trace_call_path '{"function_name": "Search", "direction": "both"}'
On trust and security
Reasonable question to ask of any tool that reads your entire codebase: every release binary is scanned by 70+ antivirus engines on VirusTotal before publishing, carries SLSA Level 3 build provenance you can verify with gh attestation verify, is signed with Sigstore cosign, and ships SHA-256 checksums. There are zero runtime dependencies — every library is vendored at compile time, so there's no transitive supply chain to worry about. All processing happens locally; your code doesn't leave your machine.
Should you use it?
If your agent sessions are eating context on repetitive file exploration, or you work in a large monorepo where "where is this used" is a constant question, this is a low-effort, high-leverage addition to your setup. It's a single binary, the install is one command, and the worst case is you uninstall it and you're back where you started — codebase-memory-mcp uninstall cleanly removes configs, hooks, and instructions without touching your binary or databases.
Repo's here if you want to dig in further or check the source before running it: github.com/DeusData/codebase-memory-mcp
Top comments (0)