The most expensive thing a coding agent does is read your code

Most conversations about AI coding agents fixate on the model — which one reasons best, which one writes the cleanest diff. In production, that is rarely where the budget goes. It goes to reading.

Before an agent changes a line, it has to find the line. The way most agents find things is the way you would with no editor and no index: grep for a name, open a file, open the file it imports, open the next one, and keep widening until the relevant slice of the system is sitting in the context window. That search is the expensive part of the job, and it is almost entirely invisible in the final diff.

codebase-memory-mcp is one answer to that cost. It is an MIT-licensed, single static binary that indexes a repository into a persistent knowledge graph and exposes it to coding agents over MCP. I want to use it as a way to talk about the underlying problem, because the problem outlives any one tool.

The exploration tax

Every grep and every file read is two things at once: a tool call and a block of tokens. The tool calls add latency and round trips. The tokens are worse, because a file gets pulled into context in full even when a single function is what matters, and that noise stays there, crowding out the parts the model actually needs. On a large codebase, an agent can spend hundreds of thousands of tokens just orienting itself before it has done anything.

The project's own example makes the gap concrete: five structural questions answered from the graph in about 3,400 tokens, versus roughly 412,000 tokens to reach the same understanding by reading files — around 120x fewer. Treat that specific multiple as a best case from one scenario rather than a guarantee. The shape of it is the point: structure you query is cheaper than text you read.

What "codebase memory" actually builds

The idea is to pay the reading cost once. On first index, tree-sitter parses the source into ASTs across 158 vendored language grammars; for eleven of those languages — Python, TypeScript and JavaScript, Go, Rust, Java, C, C++, C#, Kotlin, and PHP — a hybrid LSP layer resolves types, so a call edge points at the actual definition instead of anything that happens to share a name.

What comes out is a graph. Nodes are functions, classes, routes, and services. Edges carry meaning: CALLS, IMPORTS, IMPLEMENTS, INHERITS, DATA_FLOWS, and cross-service links like HTTP_CALLS that match an HTTP route to the place that calls it. Stored once, those relationships answer in under a millisecond.

Then the agent gets verbs instead of a reading assignment. get_architecture returns languages, packages, entry points, routes, and hotspots in a single call. detect_changes maps an uncommitted diff to the symbols it affects and flags the risky ones. There is dead-code detection, near-clone detection, and Cypher-like queries over the graph. Crucially, semantic search runs on embeddings compiled into the binary, so it works with no API key, no Ollama, no Docker, and nothing leaving the machine.

The numbers, read carefully

The project points to a preprint — it cites arXiv:2603.27277 — that evaluates the approach across 31 real-world repositories and reports 83% answer quality, 10x fewer tokens, and 2.1x fewer tool calls versus file-by-file exploration. I have not independently reproduced those figures, and you should not take any single multiplier as load-bearing. What I trust is the consistency of direction across the README's anecdote and the cross-repo average: indexing once and querying structure beats re-reading files, and the savings grow with repo size. Indexing speed makes that practical — the project clocks the Linux kernel, 28 million lines across 75,000 files, in about three minutes, which amortizes comfortably across a working session.

What deserves scrutiny

Be honest about what you are installing. This tool reads your entire codebase and writes to your agent's configuration — MCP entries, instruction files, and pre-tool hooks — across as many as eleven different agents it auto-detects. That is a wide surface for a one-line curl | bash.

The mitigations are real: processing is fully local, the release binaries are signed, checksummed, and scanned, the source is open and auditable, and the installer has a --skip-config flag that touches nothing but the binary. In a regulated or sensitive environment I would still inspect the binary's behavior, prefer manual configuration over the piped install, and scope what the agent's hooks are allowed to do. The convenience and the blast radius here are the same feature; decide deliberately how much of it you want.

Why the shape is right

Strip away this particular binary and the lesson stays. The live constraint for a coding agent on a real system is retrieval, not raw reasoning. A model with a million-token window still should not spend that window re-deriving the call graph every session. Build a structured model of the codebase once, keep it current, and let the agent ask precise questions against it.

I trained as a physicist, and this is an old habit in new clothes: you precompute the invariants of a system so you are not recomputing the field at every step. Whether or not codebase-memory-mcp is the tool that wins, "give the agent a queryable model of the code, not a pile of files to read" is where the serious engineering is heading.