Give Claude Code a Memory with codebase-memory-mcp
· Tutorials
Step-by-step MCP setup that indexes your codebase into a queryable knowledge graph — cutting Claude Code tokens by 98.5% on structural questions.
Last updated: July 16, 2025 · 9-minute read
Claude Code burned 120,000 tokens on a single "explain this codebase" question. That's $0.54 on Anthropic's API pricing — for a query that should cost fractions of a cent.
The problem isn't Claude. It's that Claude Code has no structural memory of your code. Every session, it re-reads files, re-parses imports, re-traces call chains. A thread on r/ClaudeCode titled "Codebase-Specific Memory for Claude Code?" hit the exact frustration: "Has anyone found a solution for this that plugs into Claude Code? Likely an MCP server that's good for bridging the gap between context window and actual understanding."
I've been running codebase-memory-mcp for three weeks. It indexes your repo into a persistent knowledge graph, and Claude Code queries it instead of re-reading your entire codebase. The benchmarks from the r/mcp thread are real: the Linux kernel (28M lines, 75K files) indexes in 3 minutes on an M3 Pro, and queries return in under 1ms.
What codebase-memory-mcp Actually Does
It's an MCP server — which means it runs as a local process and exposes tools that Claude Code (or Cursor, or Codex) can call. It does two things:
1. Index: Parses your entire codebase into a knowledge graph — functions, classes, imports, call chains, file relationships. This runs once (or on change) and persists to disk. 2. Query: Exposes MCP tools like searchnodes, getreferences, and getcallgraph that let Claude Code ask structural questions without reading every file.
The result: instead of Claude Code reading 40 files to answer "what calls this function," it makes one MCP tool call and gets back the answer in a few hundred tokens.
The Token Math That Matters
From the dev.to benchmark and the r/mcp post, five typical structural queries on a mid-sized codebase:
That's not a cherry-picked benchmark. That's what "where is this function called" and "what depends on this module" cost on repeat. If you do 20 structural queries a day across sessions, you're saving $30/month on token costs alone — and your context window stays clean for actual problem-solving instead of codebase navigation.
Setup: The Exact Config
Here's what I'm running. Tested on Claude Code CLI v1.0.x, macOS and Linux.
Step 1: Install the MCP Server
Step 2: Add to Claude Code's MCP Config
Edit your Claude Code MCP settings. The config file lives at ~/.claude/claudedesktopconfig.json (Claude Desktop) or in your project's .claude/settings.json for Claude Code:
Replace /absolute/path/to/codebase-memory-mcp with where you cloned the repo.
Step 3: Index Your Codebase
Restart Claude Code. Then tell it:
Index this codebase using the codebase-memory MCP server.
Claude Code will call the indexcodebase tool. On my portfolio site (about 50 files, 8K lines), this took under 2 seconds. The knowledge graph persists to disk — you don't re-index unless your code changes significantly.
Step 4: Query Instead of Read
After indexing, you can ask things like:
- "What functions call the blog post renderer?"
- "Show me the import chain from App.tsx to the animation components."
- "Which files depend on framer-motion?"
Claude Code will use the MCP tools instead of reading files. The difference in speed and token usage is immediate.
The Reddit Thread That Convinced Me
Over on r/mcp, the post "codebase-memory-mcp: how it actually works under the hood" broke down what's happening: the server builds 2.1M nodes and 4.9M edges for the Linux kernel, then answers structural queries by traversing the graph instead of reading source files. The post author tested across 372 repositories and measured consistent 98-99% token reduction on structural queries.
The r/ClaudeAI thread "do you use any kind memory MCP servers with Claude Code?" had a comment that stuck with me: "A well-designed memory MCP should NOT inject at session start. It should expose search tools that the agent calls mid-task when it needs context." That's exactly how codebase-memory-mcp works — it doesn't pollute your context window, it waits until Claude Code actually needs structural information.
When It Doesn't Work
I'm not pretending this is flawless. Here's where I hit walls:
- Claude sometimes ignores the MCP tools. There's an open GitHub issue (#69) titled "Claude never uses codebase-memory-mcp except if I edit CLAUDE.md." The fix: add a line to your project's CLAUDE.md file telling Claude to prefer the codebase-memory tools for structural questions. Without this nudge, Claude sometimes defaults to file reading out of habit.
- Semantic questions still need file reading. "What does this function do?" requires reading the actual code. The knowledge graph knows structure (what calls what, where things are defined), not semantics. Don't expect it to replace code review.
- Re-indexing on large changes. If you restructure your project (move directories, rename files), you need to re-index. On large codebases, this takes minutes. There's no automatic file-watching yet.
- Not great for single-file scripts. If your project is one 200-line Python file, you don't need a knowledge graph. This tool shines at 50+ files where the import graph is complex enough that even a human loses track.
TL;DR
- codebase-memory-mcp indexes your codebase into a queryable knowledge graph — the Linux kernel (28M LOC) indexes in 3 minutes, queries return in under 1ms
- Token savings are 98.5% on structural queries (340K tokens down to 3.4K per batch)
- Setup is a 4-step process: clone, add to MCP config, index, query
- Add a hint in CLAUDE.md so Claude Code actually uses the tools instead of defaulting to file reading
- Doesn't replace semantic understanding — it handles "where" and "what calls what," not "what does this code do"
I'm running this on every project over 30 files now. Combined with the setup from the Google Antigravity 2.0 post for multi-agent workflows, Claude Code with structural memory feels like a different tool. The Lovable replacement post covers the component side of my workflow — this handles the understanding side.
---
Not affiliated with DeusData or Anthropic. Tools used: codebase-memory-mcp, Claude Code CLI.