Stop Telling Your AI Agent to grep the Whole Repo — Use codebase-memory Instead

We’ve all been there.

“Read src/utils/helpers.ts.”

reads

“Now read src/services/userService.ts.”

reads

“Grep the repo for anything calling processOrder.”

greps, returns 47 matches across 23 files

“Read the first 10 of those files.”

context window explodes

This is how most of us interact with coding agents. File by file. Grep by grep. Burning tokens like they’re free (they’re not) and watching our context windows fill up with code the agent doesn’t actually need.

There’s a better way.

The Tool: codebase-memory-mcp

codebase-memory is a code intelligence MCP server that does one thing extremely well: it indexes your entire codebase into a persistent knowledge graph, then answers structural queries in under 1 millisecond.

The numbers are absurd:

• Linux kernel (28M lines, 75K files): 3 minutes to index
• Your repo: probably seconds
• Token savings: 99.2% reduction vs file-by-file exploration
• Query speed: sub-millisecond for relationship traversal

Instead of your agent reading 47 files to understand what calls processOrder, it runs one graph query and gets the answer instantly.

Install in 60 Seconds

One command:

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

That’s it. The installer:

1. Downloads the right binary for your platform (macOS/Linux/Windows, arm64/amd64)
2. Auto-detects which coding agents you have installed
3. Configures MCP entries for all of them

It supports 11 agents out of the box:

• Claude Code
• Codex CLI
• Gemini CLI
• Zed
• OpenCode
• Antigravity
• Aider
• KiloCode
• VS Code
• OpenClaw
• Kiro

Restart your agent. Done.

The Two Prompts That Change Everything

Here’s the practical part. Send these to your coding agent:

Prompt 1: Index the Project

Index this project with codebase-memory

First time only. Takes seconds for most repos. The graph persists — you don’t re-index every session.

Prompt 2: Use the Graph

Now instead of “read this file” and “grep for that function”, you say:

Use codebase-memory to find all functions that call processOrder and trace the call chain back to the entry points

Or:

Use codebase-memory to get the architecture overview of this project

Or:

What would break if I change the return type of getUserById? Use codebase-memory to trace the impact.

The agent uses the trace_path, get_architecture, detect_changes, and search_graph tools instead of reading dozens of files.

What You Get: 14 MCP Tools

Once indexed, your agent has access to:

Tool	What It Does
search_graph	Structural search — regex patterns, label filters, degree constraints
trace_path	Call graph traversal — who calls what, inbound/outbound
get_architecture	Full overview — languages, packages, entry points, routes, hotspots
semantic_query	Vector search across the graph (bundled embeddings, no API key)
detect_changes	Git diff → affected symbols with risk classification
search_code	Graph-augmented grep (only indexed files)
cypher_query	Raw graph queries: MATCH (f:Function)-[:CALLS]->(g) WHERE f.name = 'main'
Dead code detection	Functions with zero callers
ADR management	Persist architectural decisions across sessions

Plus HTTP route detection, cross-service linking, gRPC/GraphQL support, and infrastructure-as-code indexing (Dockerfiles, K8s manifests, Kustomize).

The Benchmark Numbers

From the research paper (arXiv:2603.27277), evaluated across 31 real-world repositories:

• 83% answer quality on complex structural queries
• 10× fewer tokens on structural queries
• 2.1× fewer tool calls vs file-by-file exploration

The token math is stark: five structural queries consumed ~3,400 tokens via codebase-memory versus ~412,000 tokens via grep exploration.

That’s not an optimization. That’s a different category.

How It Works Under the Hood

codebase-memory doesn’t embed an LLM. It’s pure structural analysis:

1. Tree-sitter parsing across 158 languages (grammars compiled into the binary)
2. Hybrid LSP semantic type resolution for 11 languages (Python, TS, Go, Rust, etc.)
3. Knowledge graph of functions, classes, calls, imports, routes, dependencies
4. Persistent SQLite storage in ~/.cache/codebase-memory-mcp/
5. Background watcher for automatic re-indexing on file changes

Your existing agent (Claude Code, Codex, whatever) is the intelligence layer. codebase-memory is the structural backend that makes that intelligence useful.

Team Sharing: Skip the Reindex

Here’s a nice touch: commit .codebase-memory/graph.db.zst to your repo, and your teammates skip the reindex entirely.

When they clone and run codebase-memory for the first time, it decompresses the artifact and runs incremental indexing for just their local changes. The .gitattributes merge strategy is auto-configured to avoid conflicts.

When to Use This

Use codebase-memory when:

• Exploring unfamiliar codebases
• Tracing call chains and dependencies
• Impact analysis before refactoring
• Finding dead code
• Understanding architecture quickly
• Any structural query that would require multiple file reads

Still use direct file reads when:

• You need the exact implementation details
• You’re editing specific lines of code
• The query is about file contents, not structure

The two approaches complement each other. Graph for structure, files for content.

How codebase-memory Fits the Modern Coding Agent Stack

codebase-memory isn’t the only tool tackling the “agent needs codebase context” problem — but it occupies a specific niche that complements others rather than competing with them.

The Landscape:

Tool	Approach	Best For
codebase-memory	Tree-sitter AST → knowledge graph, sub-ms queries	Pure structural queries, call chains, impact analysis
SocratiCode	Hybrid semantic + BM25 search, AST-aware chunking	Semantic questions, finding conceptually related code
Graphify	Knowledge graph for any folder (code, docs, images)	Mixed-content folders, Karpathy’s “/raw” style dumps
Superpowers	7-phase TDD workflow enforcement	How the agent works, not what it knows

The tools stack together:

• codebase-memory for “what calls this function?” (structural)
• SocratiCode for “where is rate limiting implemented?” (semantic)
• Graphify for “what papers mentioned this algorithm?” (multimodal)
• Superpowers for “don’t ship until tests pass” (workflow)

Think of it as layers: Superpowers controls agent behavior, codebase-memory provides structural intelligence, SocratiCode adds semantic search, and Graphify handles everything that isn’t code.

Most developers will start with one and add others as needed. If you’re doing heavy refactoring or architecture work, codebase-memory’s call graph and impact analysis are hard to beat. If you need to find code by concept rather than by name, SocratiCode’s hybrid search shines. If your “codebase” includes research papers and design screenshots, Graphify is the answer.

The practical pattern: install codebase-memory for structural queries (it’s a single binary with zero setup), and add SocratiCode when you need semantic search. They coexist fine — different MCP tools, different strengths.

The Bottom Line

Stop burning tokens on grep and read cycles. Index once, query forever.

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

Then tell your agent: “Index this project.”

Your context window will thank you.

---

Related Posts:

• SocratiCode: Give Your AI Instant Knowledge of Your Entire Codebase — Hybrid semantic + BM25 search, 37x faster than grep
• Graphify: One Command Turns Any Folder Into a Knowledge Graph — Built for Karpathy’s /raw folder problem
• Superpowers: Turn Any Coding Agent Into a Senior Developer — 7-phase TDD workflow enforcement

---

codebase-memory-mcp is open source, MIT licensed, and processes everything locally. No API keys, no cloud dependencies, no data leaving your machine. GitHub repo.