repo-memory is an MCP (Model Context Protocol) server that gives AI coding agents persistent, structured memory about a codebase. Every time an agent explores a project it re-reads files from scratch, burning tokens on code it has already seen — on a 200-file project that is roughly 43,000 tokens wasted per exploration pass. repo-memory caches compact file summaries, tracks changes via SHA-256 hashing, builds dependency graphs, remembers what has been explored across conversation turns, and measures the token savings. When a file has not changed, the agent gets the cached summary instead of the full file; when it has, a fresh summary is generated automatically so you never see stale data.
Quick Links
- MCP Tools Reference — every tool the server exposes, with inputs and outputs
- Architecture and Caching — how the cache, indexer, and telemetry fit together
- Install and Configuration — getting set up with Claude Code or a global install
- Agent Usage Patterns — recommended exploration patterns for agents
- Developer Guide — contributing, project structure, and conventions
- Design Notes — the design spikes behind the AST summarizer, task memory, the dependency graph, relevance ranking, and diff-aware updates
Key Facts
- What it is: an MCP server (stdio transport) that maintains a per-project cache of file summaries to cut token waste in agentic coding workflows.
- Package:
@blamechris/repo-memory(npm, currently 0.17.0). Storage lives in.repo-memory/cache.db(SQLite) in your project root. - Tech: TypeScript, Node.js 20+, MCP SDK, SQLite via
better-sqlite3. ESM only, MIT licensed. - Summaries: tree-sitter AST extraction by default (0.12.0+; pure WASM, no native deps) — exact exports and semantic purpose lines for TS/JS, Python, Go, Rust, Kotlin, and Java, with automatic per-file regex fallback for other languages and parse errors. For Kotlin and Java the regex engine has no real extraction — AST mode is the first engine to actually parse them. See summarizer config.
- Dependency graph: import edges persist in SQLite and are written alongside summaries; graph queries serve from the stored edges through a freshness gate instead of re-reading the project (0.13.0). Edge targets are real on-disk paths, externals excluded.
- Token-shaped responses: the 0.13.0 audit pass cut response sizes across the navigation tier — dependency-graph adjacency maps (−54%), a depth-2 default project map, and debug-field deletions — so a standard exploration sequence costs roughly a third of what it did. See the audit notes.
- Prewarming: the
repo-memory indexCLI populates the summary cache ahead of agent sessions (git post-merge hook, CI step), so the first session starts with cache hits — without recording telemetry events. See the CLI reference. - Compression: roughly a 3.6x compression ratio of full file versus summary, sustained across project sizes from 10 to 200 files.
- Source of truth: github.com/blamechris/repo-memory.
The 13 Tools at a Glance
Tools are organized into groups: navigation and summaries are on by default; tasks and telemetry are off by default and toggled via the tools block in .repo-memory.json (see configuration).
| Tool | Group | What it does |
|---|---|---|
get_project_map | navigation | Compact structural overview: tree, entry points, language breakdown |
get_related_files | navigation | Related files ranked by relevance |
get_dependency_graph | navigation | File dependency relationships |
get_changed_files | navigation | Files changed, added, or deleted since last check |
get_file_summary | summaries | Cached file summary (exports, imports, purpose, declarations, line count) |
batch_file_summaries | summaries | Summaries for multiple files in one call |
search_by_purpose | summaries | Find files by purpose/exports keywords, optionally scoped to a directory |
force_reread | summaries | Force a fresh summary from disk |
invalidate | summaries | Clear cache entries (single file or all) |
create_task | tasks | Start an investigation task |
get_task_context | tasks | Task state, explored files, unexplored frontier |
mark_explored | tasks | Mark a file explored/skipped/flagged with notes |
get_token_report | telemetry | Token usage and savings telemetry |
See the full tools reference for inputs, outputs, and parameters.