DeusData/codebase-memory-mcp is a code intelligence MCP server. It indexes a codebase into a persistent knowledge graph, helping agents such as Claude Code, Codex, Gemini CLI, Aider, and OpenCode query project structure faster.
Project repository:
https://github.com/DeusData/codebase-memory-mcp
Documentation site:
https://deusdata.github.io/codebase-memory-mcp/
Quick Answer
Codebase Memory MCP builds a persistent knowledge graph for a repository and exposes it to MCP-compatible coding agents. Install the binary, index one test repository, start the UI on port 9749, and verify that your agent can locate an entry point or trace a call chain before relying on it for code changes.
One-line Installation
macOS / Linux:
|
|
If you also want to install the graphical interface:
|
|
Windows:
|
|
Manual Installation
After extracting on macOS / Linux:
|
|
Windows:
|
|
Open the UI
|
|
Auto Indexing and Updates
Enable auto indexing:
|
|
Update:
|
|
Uninstall:
|
|
How to Use It
It fits large codebases where agents repeatedly read the same files. For example:
- A legacy project has a complex structure and AI often picks the wrong entry point.
- A multi-language repository needs fast dependency lookup.
- You want to reduce the number of files an agent pushes into context.
- You want to share one code memory through MCP across multiple coding tools.
After installation, ask the agent to start with a small task: explain the project structure, find the call chain of an API, or locate a configuration entry. Once you confirm it can query correctly, use it for real code changes.
Troubleshooting and Verification
If the agent cannot see the server, first run codebase-memory-mcp --ui=true --port=9749 directly and confirm that the local UI opens. Then check the MCP client configuration, restart the client so it reloads the server definition, and index a small repository before testing a monorepo. If answers look stale, confirm that auto_index is enabled or trigger a fresh index after large branch changes.
For alternative approaches, compare CodeGraph for local code knowledge graphs and Graphify for repository mapping and call-flow export. These tools overlap, but their installation model, output artifacts, and agent integrations differ.
Comparing Codebase Memory Approaches for AI Agents
When an AI Agent writes code, the most common problem is not that the model cannot write code at all. It is that it does not really know the shape of the codebase.
It may not know where the entry point is, whether a helper already exists, how tests are run, or which directories the team does not want touched. Every new session then repeats the same background explanation, or the Agent repeatedly runs grep, reads files, and floods the context with irrelevant content.
That is the problem codebase memory tools try to solve.
But these tools are not one category. CLAUDE.md and AGENTS.md are rule files. Cursor provides IDE indexing. Serena gives Agents semantic code tools. codebase-memory-mcp builds persistent code knowledge through MCP. RepoPrompt focuses on human-curated context packs. Sourcegraph fits enterprise-scale multi-repo code understanding.
This article compares them by usage scenario: which tool fits personal projects, large repositories, multi-repo teams, and collaboration workflows.
Quick Answer
| Tool or route | Best for | Main value | Poor fit |
|---|---|---|---|
CLAUDE.md / AGENTS.md |
Almost every project | Project rules, commands, forbidden areas, collaboration constraints | Automatic call-graph understanding |
| Cursor codebase indexing | Cursor users, IDE work | Let chat and editing use project index | Cross-tool sharing and complex Agent orchestration |
| Serena MCP | Large repos, semantic navigation, refactoring | Symbol lookup, references, semantic editing | Tiny projects that only need prompts |
codebase-memory-mcp |
Shared code memory across tools | Persistent code knowledge graph via MCP | Users who do not want another service |
| RepoPrompt / RepoPrompt CE | Human-controlled context | Select files, CodeMap, diff, and reviewable context | Fully automatic indexing teams |
| Sourcegraph / Cody | Enterprise multi-repo code understanding | Central indexing, search, permissions, cross-repo context | Small personal projects |
My recommendation:
- Small projects: start with
AGENTS.mdorCLAUDE.md. - Medium projects: rule file plus IDE indexing.
- Large single repo: rule file plus Serena or
codebase-memory-mcp. - Multi-repo teams: rule files plus MCP indexing plus a platform such as Sourcegraph.
- High-risk changes: add RepoPrompt-style human context packaging before the Agent edits.
Do not stack tools from day one. Codebase memory is not about making the Agent know everything. It is about making it guess less, read less wrong context, and waste less context on the current task.
Three Kinds of Memory
1. Rule Memory
Examples: CLAUDE.md, AGENTS.md, GEMINI.md, and AI sections in README.
They record:
- tech stack;
- common commands;
- test commands;
- directory notes;
- files that must not be changed;
- coding style;
- commit and verification rules.
This memory is cheap and stable. It does not automatically understand code relationships.
2. Retrieval Memory
Examples: Cursor codebase indexing, Sourcegraph, code search, vector indexes, knowledge graphs.
They answer:
- where is this function defined;
- who calls this API;
- which files may be related;
- where a config appears;
- where cross-repo dependencies live.
This fits medium and large repos, but needs indexing, refresh, permissions, and ignore rules.
3. Operational Memory
Examples: Serena MCP, semantic editing tools, code intelligence MCP servers.
They give the Agent IDE-like tools:
- find symbols;
- find references;
- inspect file outline;
- replace function bodies;
- rename symbols;
- edit at smaller granularity.
This is useful for large-codebase navigation and refactoring, but setup is more complex.
CLAUDE.md / AGENTS.md: Start Here
If a project has no codebase memory, do not start with a complex index. Start with a short project guide.
|
|
This captures how the project works: package manager, test runner, generated directories, forbidden files, checks after API changes, and final reporting style.
It is simple, versioned in Git, team-shareable, and readable by many tools. Its limitation is obvious: it does not know where a function is called. Treat it as the foundation, not a complete code index.
For layered project memory, see: /en/2026/07/08/claude-code-multi-project-memory-team-workflow/.
Cursor Codebase Indexing
Cursor indexing fits people already developing inside Cursor. It indexes the current codebase so chat, editing, and @Codebase references can find relevant files.
Good fit:
- frontend, full-stack, and mobile IDE work;
- asking “where is this feature implemented?”;
- generating code against the current project;
- avoiding extra MCP services;
- teams mostly using Cursor.
Boundaries:
- mainly serves Cursor workflows;
- limited cross-tool sharing;
- large repos need indexing scope and ignore rules;
- still needs
AGENTS.mdor similar rules; - secrets, production config, and generated output must be excluded.
More index is not always better. The valuable context is the context related to the current task. For context bloat and token issues, see: Why Claude Code Token Usage Suddenly Spikes: Tutorial, Troubleshooting, and FAQ.
Serena MCP
Serena is closer to “IDE capabilities for AI Agents.” It provides semantic code retrieval, editing, refactoring, and debugging tools through MCP.
Good fit:
- large Python, Java, TypeScript, or Go codebases;
- Agents often pick the wrong file or function;
- tasks need symbol, reference, declaration, and implementation lookup;
- cross-file refactoring needs safer operations;
- Claude Code, Codex, OpenCode, Gemini CLI, and other MCP clients should share code tools.
Serena’s advantage is symbol-level operation. Instead of reading entire files and guessing, the Agent can navigate like an IDE.
It is not necessary for small scripts or one-file bug fixes. It shines when the project structure is complex and the Agent often gets lost.
For MCP troubleshooting, see: .
codebase-memory-mcp
DeusData/codebase-memory-mcp indexes a codebase into a persistent knowledge graph and exposes it through MCP.
Good fit:
- you use Claude Code, Codex, Cursor, Aider, OpenCode, or multiple tools;
- several Agents should share one code index;
- the project is large and Agents repeatedly read the same files;
- you want less source pasted into context;
- you want local, repeatable code queries.
Its value is persistence and cross-tool use. The cost is maintaining another component: install, update, re-indexing, MCP config, permission scope, ignore rules, and client compatibility.
If you only ask AI to change two lines occasionally, skip it. If you switch between Agents every day, it becomes more valuable.
Site tutorial: /en/2026/06/22/codebase-memory-mcp-code-intelligence-guide/.
RepoPrompt
RepoPrompt and RepoPrompt CE do not aim to automatically read the whole repo. They help a human assemble a reviewable context pack.
Good fit:
- you want exact control over what the model sees;
- complex tasks require selecting key files first;
- automatic indexing brings too much irrelevant content;
- you want files, CodeMap, tree, and Git diff in one package;
- high-risk refactoring, architecture review, or code review.
A stable flow:
- Human selects entry files, related modules, and diff.
- RepoPrompt builds a context pack.
- AI designs, reviews, or suggests changes.
- Scope is narrowed before code is edited.
If a team often complains that the AI used the wrong context, this style is worth considering.
Sourcegraph
Sourcegraph is closer to an enterprise code-understanding platform. It focuses on indexing, search, permissions, and code evolution across large codebases and many repositories.
Good fit:
- multi-repo enterprise teams;
- large monorepos;
- cross-service migrations;
- SSO, audit, central search, and permissions;
- Agents need context beyond the local repo;
- security and governance matter.
Individual developers usually do not need it first. Its value appears at scale.
Choosing by Project Size
Personal Small Project
|
|
Keep it light. Define commands, directories, and forbidden areas. The priority is not remembering every file; it is avoiding wrong commands, accidental deletion, and unrelated edits. For deletion safety, see: .
Medium Business Project
|
|
Rules provide stable constraints, IDE indexing handles daily questions, and Serena handles complex navigation.
Large Single Repository
|
|
Do not let the Agent treat a large repo as one giant text blob. Add root rules, local directory notes, symbol tools, read-only impact analysis, and small edit scopes.
If you use Claude Code subagents, split code retrieval and specialized review roles: .
Multi-Repo Team
|
|
Here, codebase memory becomes engineering governance: which repos can be read, which can be changed, how services depend on each other, which migrations need phases, and which production configs are forbidden.
Seven Questions Before Choosing
- How large is the codebase?
- Is the Agent missing rules or missing code relationships?
- Do you use one IDE or many tools such as Codex, Claude Code, Cursor, and Aider?
- Does the team need shared rules and indexes?
- Are there secrets, production configs, or customer data?
- Do you often do cross-file refactors and migrations?
- Can you maintain an extra MCP server or enterprise platform?
If rules are the main issue, start with AGENTS.md / CLAUDE.md.
If code discovery is the issue, consider Cursor indexing, Serena, or codebase-memory-mcp.
If multi-repo governance is the issue, consider Sourcegraph.
If high-risk context must be reviewable, consider RepoPrompt.
Common Mistakes
Turning Memory Files Into an Encyclopedia
CLAUDE.md and AGENTS.md should contain stable operational rules, not every historical detail.
Indexing Too Much
Exclude:
|
|
Use .gitignore, .cursorignore, tool-specific ignore files, or MCP config. Otherwise context becomes expensive, slow, and noisy.
Treating Search Results as Truth
Search results are evidence, not conclusions. The Agent still needs to read entry files, follow call chains, inspect tests and configs, run minimal verification, and report uncertainty.
Forgetting Permissions and Privacy
Before using memory tools, check whether code is uploaded, where indexes live, who shares them, whether .env and customer data are included, whether the MCP server is scoped to the repo, and whether logs expose secrets.
Too Many Tools, Too Few Rules
Many teams install every tool but have no shared project rules. First define how the Agent should work; then add indexes.
Recommended Rollout
- Add a short
AGENTS.mdorCLAUDE.md. - Document stack, commands, directories, forbidden areas, and verification.
- Configure
.gitignore,.cursorignore, or index excludes. - Use Cursor or built-in indexing for daily IDE work.
- Add Serena or
codebase-memory-mcpwhen Agents repeatedly find the wrong code. - Use RepoPrompt before high-risk changes.
- Consider Sourcegraph for multi-repo teams.
Combining code-review-graph, Claude.md, and Codex Skills
Many people say an AI Agent needs “codebase memory”. But that phrase is too broad. Some want the Agent to remember project rules. Some want it to find call chains. Some want it to avoid scanning the whole repository every time. Others want it to run a fixed review workflow automatically.
Those four needs sound similar, but they require different tools.
Claude.md and AGENTS.md are project rule files.
code-review-graph is closer to a code relationship graph and review assistant.
codebase-memory-mcp is a shared code index service across tools.
Codex Skills are reusable workflow instructions.
If you choose the wrong one, the problem is not just “one fewer feature”. The real cost is higher maintenance. This article is not another single-tool tutorial. It is a selection guide.
The Short Answer
For small projects, start with AGENTS.md or Claude.md.
For medium projects, add Codex Skills to freeze repeatable workflows.
For code review tasks, look at code-review-graph first.
When several tools need to share the same code index, then consider codebase-memory-mcp.
Do not install all four at the beginning. A better order is: rules first, workflows second, structural indexing third, MCP service last. If you have read AI Agent codebase memory tools compared, this article is the narrower hands-on selection table.
Four Tools, Four Problems
| Tool | Main problem solved | Best fit | Biggest risk |
|---|---|---|---|
Claude.md / AGENTS.md |
Project rules and long-term constraints | Small teams, single repos, stable conventions | Too long, polluting context |
Codex Skills |
Repeatable task workflows | Publishing, translation, deployment, SEO, review | Freezing a workflow before it is proven |
code-review-graph |
Call relationships and change impact | PR review, architecture impact analysis | Stale graph or poor ignore rules |
codebase-memory-mcp |
Shared code index across tools | Multiple Agents, multiple IDEs, large repos | Service permissions and index maintenance |
The important column is “main problem solved”. These are not four brands of the same tool. They are four layers. The rule layer tells the Agent how to work. The workflow layer tells it what repeated process to follow. The structure layer tells it how code connects. The service layer lets different Agents query one shared index.
First Identify the Missing Memory
Ask four questions before choosing:
- Is the Agent forgetting project conventions?
- Is it failing to find related code?
- Is it repeating the same steps every time?
- Is context inconsistent between multiple tools?
If it only forgets rules, write AGENTS.md.
If it repeats the same process, write a Skill.
If it misses call chains and impact areas, use a code graph.
If Codex, Claude Code, and Cursor all need the same structured index, add MCP.
Do not mix every tool together just because the word “memory” sounds useful.
Claude.md and AGENTS.md: Project Rules
The value of Claude.md and AGENTS.md is that they are short.
They should tell the Agent stable rules, not become a project encyclopedia.
Good content includes:
- Startup commands.
- Test commands.
- Code style.
- Directories that must not be changed.
- Pre-release checks.
- Common pitfalls.
- Security boundaries.
- Language and copy requirements.
Poor content includes:
- Complete business background.
- Old discussion notes.
- Detailed explanations of every module.
- Long design documents.
- One-off task logs.
- Unverified personal preferences.
A good rule file is a signpost. It reminds the Agent not to walk the wrong path. It should not become a thick manual. For rule-file tuning, keep following the principle that a longer Claude.md is not automatically better.
Codex Skills: Workflow Memory
A Skill is not a code index. It remembers “how to do the work”.
For example, this site’s new-post workflow includes:
- Decide whether this is a new article.
- Find the next post number.
- Create only
index.zh-cn.md. - Set front matter.
- Control the publish date.
- Check line count.
- Do not generate other languages.
Those steps should not be typed into every prompt. They belong in a Skill.
Good Uses for Skills
- Content publishing workflows.
- Multilingual translation workflows.
- Deployment workflows.
- SEO cooldown checks.
- Local rewrite workflows.
- Security checklists.
- Fixed-format reports.
- Code review steps.
Poor Uses for Skills
- One-off debugging.
- Workflows still being explored.
- Tasks requiring lots of case-by-case judgment.
- Tasks without stable acceptance criteria.
- Prompt bundles whose only purpose is longer answers.
The best Skill is light on explanation and heavy on constraints. It should reduce the chance that the Agent makes the same fixed mistake again. To write one from scratch, see How to write your own Codex Skills workflow.
code-review-graph: Change Impact
code-review-graph is not for remembering chat history.
It focuses on code structure.
It uses a graph mindset to answer:
- Who calls this function?
- Which modules does this route affect?
- Which call chains changed in this PR?
- Which tests may need to be added?
- Which files should be reviewed together?
Ordinary prompts are unstable for these questions. If the Agent only reads the diff, it may miss indirect impact. If it searches the whole repo, it wastes context.
The graph is useful because it computes structure ahead of time. The Agent queries it when needed.
code-review-graph Fits
- People who review PRs often.
- Repositories with complex module calls.
- Teams that want Codex or Claude Code to review change impact.
- People who do not want the Agent to scan the whole repo every time.
- Teams that want review support in GitHub Actions.
code-review-graph Does Not Fit
- Tiny scripts with only a few files.
- Projects without PR or diff workflows.
- Users who only want chat memory.
- Teams unwilling to maintain index output.
- Repos where generated files and source files are not separated.
For usage, read How to use code-review-graph. For CI, read Adding code-review-graph to GitHub Actions.
codebase-memory-mcp: Shared Index
codebase-memory-mcp fits multi-tool environments better.
If you only use one Agent, you may not need it.
But if you use Codex, Claude Code, Cursor, and Gemini CLI at the same time, problems appear. Each tool has its own context. Each tool may rescan code. Each tool may understand the project structure differently.
An MCP-style code index is useful here. It exposes repository structure as a service to different Agents. The Agent does not rebuild its understanding every time.
codebase-memory-mcp Fits
- Large repositories.
- Multi-language repositories.
- Multiple Agents sharing one project.
- Local-first code indexing.
- Unified access through MCP.
- Reducing repeated scan cost.
Think Before Using It
It is a service. A service has runtime state. A service has ports, permissions, indexed directories, and upgrade concerns.
If nobody on the team maintains it, this kind of tool easily becomes “installed once, never touched again”. It fits teams that already have stable Agent habits. It does not fit people still experimenting. For setup, see codebase-memory-mcp tutorial.
Choose by Repository Size
Repository size strongly affects the right choice. A script repo and a large monorepo should not use the same memory setup.
Under 10 Files
No complex memory is needed. Keep:
README.md.AGENTS.md.- Basic test commands.
- Git diff review.
If the Agent still cannot find files, the problem is usually that the task description is too broad.
10 to 200 Files
Add lightweight structure:
- Module directory notes.
- Common command list.
- One development or publishing Skill.
code-review-graphwhen needed.
The rule file should still stay short.
Do not put every module into AGENTS.md.
200 to 2000 Files
Change impact becomes real. Add:
- Call graph.
- Change impact review.
- Minimal test strategy in CI.
- Shared team rules.
- Ignore rules for generated directories.
code-review-graph becomes more valuable at this layer because it helps the Agent guess less.
Large Multi-Language Repos
These projects need shared indexing and service-like capability. Add:
codebase-memory-mcp.- Unified MCP configuration.
- Index update strategy.
- Permission allowlists.
- Service monitoring.
- Upgrade notes.
At this point, the tool is infrastructure. It cannot rely only on one person’s habits.
Choose by Task Type
Different tasks need different memory.
Fixing Bugs
Bug fixing needs reproduction and related files. Priority:
- Error logs.
- Reproduction commands.
- Recent changes.
- Related tests.
- Call relationships.
For local bugs, MCP is usually unnecessary. For cross-module bugs, a graph helps.
Building Features
Feature work needs boundaries. Priority:
- Requirement scope.
- Out-of-scope areas.
- Data structures.
- API contracts.
- Test entry points.
Rule files prevent the Agent from casually changing architecture. Skills can preserve the fixed implementation process.
Code Review
Review needs change impact. Priority:
- Diff.
- Callers.
- Callees.
- Route entry points.
- Test coverage.
- Security boundaries.
Here code-review-graph is more useful than a long prompt.
Docs and Publishing
Docs and publishing need workflow memory. Priority:
- Front matter.
- File naming.
- Build rules.
- Multilingual sync.
- Link checks.
- Release checks.
These tasks fit Skills best.
Update Strategy
Codebase memory becomes harmful if it is stale. Different tools update differently.
Rule files are maintained by people.
Skills update when workflows change.
code-review-graph should be rebuilt or incrementally updated after code changes.
codebase-memory-mcp needs service and index maintenance.
When to Update
- New modules.
- Deleted directories.
- Route structure changes.
- Test command changes.
- Build tool changes.
- Generated directory changes.
- Team permission changes.
- CI workflow changes.
- Agent tool upgrades.
- MCP service upgrades.
Acceptance Checks
- Can the Agent name entry files?
- Can it find related tests?
- Does it avoid generated directories?
- Can it explain a real diff?
- Does it respect forbidden edit areas?
- Can it call the right Skill?
- Does MCP return current files?
- Does graph output match actual code?
Failure Cases and Fixes
Rule File Too Long
Symptom: the Agent reads slowly and cites irrelevant rules. Fix: delete. Keep stable constraints. Move workflows to Skills. Move background to docs.
Skill Too Broad
Symptom: every task is forced into one process. Fix: split it. One Skill should serve one kind of work. For example, separate publishing, translation, deployment, and review.
Graph Includes Generated Directories
Symptom: the Agent focuses on build artifacts instead of source code.
Fix: update ignore rules.
Exclude dist/, public/, node_modules/, and cache directories.
MCP Permissions Too Broad
Symptom: the Agent can access too many unrelated resources. Fix: tier permissions. Read-only tools first. Separate approval for write tools. Production tools off by default.
How to Combine Them
For personal small projects: AGENTS.md, a little project documentation, Git diff, and the shortest useful test command.
For medium web projects: AGENTS.md, one publishing or testing Skill, code-review-graph, and a PR review template.
For multi-Agent team projects: AGENTS.md, team Skills, code-review-graph, codebase-memory-mcp, CI review, and permission boundary docs.
For content sites and automation workflows: publishing Skill, translation Skill, SEO cooldown rules, deployment Skill, and a small amount of site directory documentation.
The key is not tool count. The key is that each layer solves a different problem.
Selection Tree
First ask: does the Agent often violate project rules?
If yes, write AGENTS.md or Claude.md.
Does the Agent repeat the same steps often? If yes, write a Skill.
Does the Agent often miss call chains or impact scope?
If yes, use code-review-graph.
Do multiple Agents need to share one code index?
If yes, consider codebase-memory-mcp.
If no, do not add another tool yet. This order avoids making simple problems complicated.
How to Link Existing Articles
This article works as a selection entrance. Leave single-tool setup to existing articles.
Use 7/99 for concrete code-review-graph commands.
Use 7/137 for GitHub Actions integration.
Use 6/113 for codebase-memory-mcp setup.
Use 4/118 for rule-file thinking.
Use 7/42 for the general memory roadmap.
Readers should choose a direction first, then enter a specific tutorial.
Final Recommendation
If you only want the Agent to avoid fixed mistakes, choose AGENTS.md or Claude.md.
If you want it to follow a fixed process, choose Codex Skills.
If you want change impact analysis, choose code-review-graph.
If you want multiple Agents to share code structure, choose codebase-memory-mcp.
Mature codebase memory is not about remembering everything. It is about putting rules, workflows, structure, and services in the right place.