Every AI coding assistant hits the same wall. You drop into a new codebase, ask something structural — "what calls this function?" or "what talks to this service?" — and the agent starts reading files. One by one. Burning tokens on boilerplate it doesn't need, missing context it can't see because it never built a mental model of the whole thing.
codebase-memory-mcp fixes that.
What It Is
codebase-memory-mcp is an MCP server that parses your entire codebase using tree-sitter — the same parser generator used by Neovim, Helix, and GitHub's semantic code search — and builds a persistent knowledge graph of functions, classes, call chains, HTTP routes, and cross-service links. It then exposes 14 structured query tools so your coding agent can ask structural questions against that graph instead of re-reading files from scratch every session.
A quick clarification: MCP (Model Context Protocol) is Anthropic's standard for connecting external tools and data to AI models. Think of it as a plugin API. Your agent — Claude Code, Codex CLI, Gemini CLI, and others — can call into MCP servers to get structured results instead of relying entirely on reading files from disk. codebase-memory-mcp is one of those servers. It's the one that understands your entire codebase's structure.
It ships as a single static binary. No Docker, no runtime dependencies, no API keys, no setup ceremony.
Why It's Worth Your Time
The numbers are concrete. Five structural queries cost roughly 3,400 tokens via codebase-memory-mcp versus 412,000 tokens via file-by-file exploration. That's a 99.2% reduction. On a medium codebase, that's the difference between a query that eats half your context window and one that barely registers.
What makes this different from code search or grep: it's a graph, not an index. You can trace who calls a function, map the blast radius of a change before you commit it, detect dead code, and visualize cross-service HTTP links. An agent can ask "who calls ProcessOrder?" and get a structured call chain back in under 10ms — not because it read ten files, but because that relationship was already indexed and persisted from the first time you ran it.
Tree-sitter produces an Abstract Syntax Tree — a structured representation of your code that understands syntax, not just text patterns. What codebase-memory-mcp adds on top is a relational model: nodes for Functions, Classes, Routes, and Files; edges for CALLS, IMPORTS, IMPLEMENTS, HTTP_CALLS, DATA_FLOWS, and more. That model is what lets you run Cypher-like graph queries against your codebase:
MATCH (f:Function)-[:CALLS]->(g) WHERE f.name = 'main' RETURN g.name
Cypher is the query language made popular by Neo4j — it reads like SQL but for graphs. You describe the shape of the relationship you're looking for, and the graph engine finds it.
For 11 languages including Python, TypeScript, Go, Rust, and Java, the tool goes further with what they call Hybrid LSP — a C implementation of type-resolution algorithms compatible with pyright, gopls, and tsserver. That means it understands return types, generic substitution, and trait resolution. Structural analysis, not just symbol matching.
The semantic search is powered by bundled Nomic embeddings compiled directly into the binary. No Ollama, no API key, no external model. Vector search — the kind that finds "functions that are conceptually similar" rather than "functions whose names match this pattern" — is included at no extra cost or configuration.
Hands On
Install (macOS / Linux):
curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash
On Arch (AUR):
yay -S codebase-memory-mcp-bin
The installer auto-detects your coding agents. Claude Code gets an entry in ~/.claude/.mcp.json. It handles Codex CLI, Gemini CLI, VS Code, Zed, Aider, and others — including OpenClaw — automatically.
Restart your agent after install.
Indexing a project:
Tell your agent: "Index this project." Or from the CLI:
codebase-memory-mcp cli index_repository '{"repo_path": "/path/to/your/repo"}'
The knowledge graph persists in ~/.cache/codebase-memory-mcp/ as a SQLite database. Once indexed, every subsequent session starts with the full graph — no re-indexing, no warm-up period.
Enable automatic indexing:
codebase-memory-mcp config set auto_index true
With this on, new projects are indexed on first connection. Previously-indexed projects are watched with git-based change detection — it tracks what changed, not what didn't.
Query from the CLI:
# Find all functions matching a name pattern
codebase-memory-mcp cli search_graph '{"name_pattern": ".*Handler.*", "label": "Function"}'
# Trace who calls a function (and what it calls)
codebase-memory-mcp cli trace_path '{"function_name": "ProcessOrder", "direction": "both"}'
# Map the blast radius of your uncommitted changes
codebase-memory-mcp cli detect_changes '{}'
Benchmarks from the README (Apple M3 Pro — your mileage will vary, but these are in the right ballpark):
| Operation | Time |
|---|---|
| Linux kernel (28M LOC, 75K files) — full index | 3 minutes |
| Django — full index | ~6 seconds |
| Cypher query | <1ms |
| Call path trace (depth=5) | <10ms |
There's an optional graph visualization UI that serves a 3D interactive view at localhost:9749. If you want to actually see your codebase's call graph as a navigable graph, it's there:
curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash -s -- --ui
Honest Verdict
This is a well-engineered tool. The single binary philosophy, the bundled tree-sitter grammars for 158 languages, the bundled embeddings — whoever designed this understood that tool adoption dies at friction. The install works. The problem being solved is real. And unlike most "AI tooling" projects that appeared overnight and will be abandoned by August, this one has a published research paper behind it, benchmarks against real-world repos, and genuine technical depth.
Two honest caveats.
First: it reads your codebase and writes to your agent config files. The README is upfront about this. The source is auditable, every release binary is checksummed and scanned by 70+ antivirus engines, and all processing happens locally — your code never leaves your machine. But if you're working on sensitive code, audit the installer before you run it. That's not paranoia. It's just good hygiene for anything that touches your agent configs.
Second: Hybrid LSP type resolution covers 11 languages well. Outside that list, you get structural analysis only. Totally fine for most stacks. Worth knowing if yours is unusual.
What this is not: a replacement for reading code. For complex logic, tricky algorithms, or architectural decisions, your agent still needs to read source. What codebase-memory-mcp gives you is a dramatically cheaper first pass — find the right files, trace the dependencies, map the blast radius — before the expensive read operations. That's the workflow shift.
Who it's actually for: anyone running Claude Code, Codex CLI, or any MCP-compatible agent against a non-trivial codebase, frustrated with how much context gets burned on basic structural navigation. The bigger the repo, the bigger the payoff.
Go Try It
Install it. Index a real project you work on. Ask your agent something structural — "what calls this function?" or "show me the architecture of this service." See whether it reads files or queries the graph.