How to Choose Codebase Memory Tools: code-review-graph, codebase-memory-mcp, Claude.md, and Codex Skills Compared

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

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, read Claude.md is not better just because it is longer.

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-graph when 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.