CLAUDE.md vs AGENTS.md: is a rules file enough, or do I need a real memory tool? is the question developers end up asking once they use more than one AI coding agent. CLAUDE.md is the instruction file Claude Code reads at the start of a session. AGENTS.md is a shared convention that many other agents read, including Codex and Cursor. Both are hand-written rules files: static, project-scoped and kept up to date by you. A memory tool works differently. It captures what actually happens in your sessions, such as decisions, fixes and preferences, and feeds the relevant parts back into every tool on its own. Short answer: a rules file is enough for a small set of rules that rarely change. Once you switch tools or machines, or your project's history grows past what you can keep pasting in, you need memory.
At Open Agentic Brain & Memory (OpenAB), we built a free, open-source memory layer because we kept hitting that limit ourselves. This guide covers what each file does well, where rules files stop working, and how to tell when it's time to add memory. It also covers the token savings, which are larger than most people expect.
What CLAUDE.md and AGENTS.md actually are
Both files do the same job for different readers. They're plain Markdown files in your repo, or in a global location, that an agent loads into context before it starts working. You use them to state things the agent can't easily work out from the code, for example:
"Use pnpm, never npm or yarn."
"Run pnpm test --filter api before saying a change is done."
"We use SQLite for the job queue. Don't suggest Redis."
"API handlers live in src/routes; don't create new top-level folders."
CLAUDE.md is Claude Code's version. AGENTS.md is a vendor-neutral name that a growing number of other agents read. Gemini-based tools read GEMINI.md. The format is the same in every case: whatever you write, the agent reads.
The practical difference between the two files
The main difference is which tools read which file, not what goes in them. If your team uses only Claude Code, CLAUDE.md is enough. If people use Cursor, Codex and Claude Code in the same repo, you'll want AGENTS.md as well, and that's where the trouble starts: two or three files that are meant to say the same thing and slowly stop doing so. Many teams make one file the source of truth and point the others at it. That fixes duplication. It doesn't fix anything else in the next section.
Where a rules file is enough
Rules files deserve credit. They're simple, easy to review in a pull request, and you can see exactly what's in them. A rules file is probably all you need if:
You work in one or two repos and mostly use one AI tool.
Your conventions are stable and fit on one screen.
You mostly work on one machine.
You're willing to edit the file by hand every time something changes.
If that's you, keep the file short, specific and current. Remove rules that no longer apply. A tidy CLAUDE.md beats a long, outdated one.
Where rules files break down
The problems appear slowly, and they come from the same cause: a rules file only knows what you remembered to write down.
1. Sessions still start from zero
Say you spend an hour in Claude Code on Monday finding out that a flaky test fails because of a timezone assumption in a date helper. You fix it. Unless you stop and write that down, the knowledge disappears when the chat ends. On Tuesday, Cursor reaches the same failure and investigates it from scratch. Rules files hold what you planned to tell the agent. They don't hold what you learned along the way.
2. No tool knows what the others learned
Even with AGENTS.md and CLAUDE.md in sync, neither one is updated by the agents. Claude Code doesn't tell Cursor that you dropped Redis for SQLite last week. Codex doesn't know you told Claude Code to stop adding comments to every function. Each tool keeps its own small amount of knowledge, if it keeps any.
3. Machines drift
Global rules files sit in your home directory. If you have a work laptop and a personal one, you end up with two versions that differ. Project files travel with git, but personal preferences and lessons from other projects don't.
4. Files grow, and every session pays for them
When you notice the forgetting, the usual fix is to add more to the file: history notes, past bugs, architecture decisions. Every line goes into context in every session, whether or not it's relevant to the task. A 600-line CLAUDE.md costs tokens each time it loads, and models tend to pay less attention to a long, flat block of instructions than to a short, relevant one.
5. It's always manual
Writing rules takes discipline, and discipline gives way under deadlines. The decisions that mattered most, the ones made at 6 p.m. while fixing a production bug, are the ones least likely to get written down.
What a real memory tool adds
A memory layer doesn't replace your rules file. It sits next to it and handles what the file can't. Here is how a good one should behave:
Capture. It records decisions, fixes and preferences from real sessions, so you don't have to remember to write them down.
Distill and rank. It turns raw session history into short memories and ranks them by relevance to the current project and task.
Inject a bounded briefing. At session start, it gives the agent a short, relevant summary rather than everything it has stored.
Recall on demand. Mid-task, the agent can ask for something specific ("what did we decide about the queue?") and get an answer quickly.
Work across tools and machines. One store, read by every agent you use, on every laptop.
How Open Agentic Brain & Memory approaches it
At Open Agentic Brain & Memory (OpenAB), we built exactly that. OpenAB is one memory shared across Claude Code, Cursor, Codex, Antigravity and Kilo Code (beta). Tell one tool and every tool knows. Decide something in Claude Code on Monday and Cursor already knows it on Tuesday. It's free, open source under Apache-2.0, and self-hosted. You can see how it fits together on the OpenAB project site.
Project-aware, not walled off
Memories are tagged by project, and OpenAB finds the project by walking up to the nearest .git folder. When you open a repo, that repo's history comes first. OpenAB also keeps a map of up to 20 projects in your global CLAUDE.md, AGENTS.md and GEMINI.md, so every agent knows what else you work on. Recall can search one project or all of them. That helps when a fix you found in one repo applies in another.
Fast, bounded context
A start-up hook injects a briefing of at most 2,000 tokens in 84 ms (p50). For specific questions, agents use MCP tools: brain_recall, brain_remember, brain_context and load-my-brain. Recall across 10,000 memories takes 28 ms (p50). Search is hybrid, combining keywords and meaning, so "why did we drop Redis" finds the memory even if it was written as "switched job queue to SQLite."
It works with your rules files
OpenAB doesn't ask you to delete CLAUDE.md or AGENTS.md. It writes its project map into those files and leaves your hand-written rules alone. Keep your rules for the short, stable things. Let memory handle the history.
The token argument: why memory beats a bigger rules file
This is the part most people miss. If you keep re-explaining a project, or pasting long notes into every chat, you're spending tokens you don't need to spend. Each tool that uses OpenAB gets a briefing under 2,000 tokens instead.
The numbers are large. Loading context for a 10,000-memory store with OpenAB takes 1,325 tokens. Loading the same history in full would take 1,131,367. On the LoCoMo long-conversation benchmark, OpenAB keeps 97% of the full-conversation score while reading 18% of the tokens.
Day to day, fewer tokens per session means you hit your Claude, Cursor or Codex usage limits later. Your context window also has more room for the code you're actually working on. A rules file that grows to cover everything you've learned keeps getting more expensive. A ranked, bounded briefing doesn't.
Privacy and ownership: who holds your memory?
Your project memory is sensitive. It includes architecture choices, internal service names, sometimes the shape of customer data. Many hosted memory APIs ask you to send that to their servers. OpenAB doesn't.
No account and no server of ours. Memory is stored in a local SQLite database on your machine.
Encrypted sync you own. To sync between machines, OpenAB stores your memory as an age-encrypted blob, uploaded as a Release asset on your own private GitHub repo. The key is kept only in your OS Keychain.
Leaks expose nothing readable. If the repo or a token leaks, the attacker gets an encrypted blob they can't read.
Same briefing everywhere. At start-up, OpenAB merges in what your other laptops learned, so your work and personal machines give the same briefing.
Transparency: memory you can read and edit
A common worry about memory tools is that they quietly collect wrong or stale facts. A rules file is easy to inspect, and a memory tool should be just as easy. OpenAB includes a local control panel where you can read, edit, pin or delete every memory. You can start from past AI work or start fresh. Memories carry outcome scores, so a fix that worked ranks above one that didn't. The brain eval command scores recall against your own history, so you can check how well it works rather than trust a benchmark.
A simple decision guide
To pick what you need, ask yourself these questions:
Do I use more than one AI coding tool? If yes, a rules file per tool will drift. Add shared memory.
Do I work on more than one machine? If yes, you need sync, and it should be encrypted and owned by you.
Do I keep re-explaining the same decisions? That's the clearest sign. Rules files hold intentions. Memory holds history.
Is my CLAUDE.md or AGENTS.md longer than one screen? You're probably paying tokens for context that doesn't matter to most tasks.
Do I care where my project knowledge is stored? If yes, choose local-first and self-hosted over a hosted API.
If you answered no to all of these, keep your rules file tidy and you're fine. If you answered yes to two or more, a memory layer will save you time and tokens.
A practical setup that uses both
Here's the setup we recommend at OpenAB:
Keep one short rules file as the source of truth for stable conventions, such as package manager, test command and folder layout. Point CLAUDE.md and AGENTS.md at the same content.
Let OpenAB capture everything else: decisions made mid-task, bug causes, preferences you state in passing.
Review the control panel now and then. Pin the memories that matter and delete the ones that are out of date.
Run brain eval after a few weeks to see how well recall works on your real history.
For more depth, our blog has guides on AI memory layers, context engineering, long context vs RAG vs memory, agent hooks, and self-hosted memory privacy.
FAQ
Should I use CLAUDE.md or AGENTS.md?
Use CLAUDE.md if you only use Claude Code. Use AGENTS.md for other agents that support it. If you use both kinds of tool, keep one source of truth and point the other file at it.
Does a memory tool replace my rules file?
No. Rules files are best for short, stable instructions. Memory handles the changing history that rules files can't keep up with. OpenAB works alongside both files.
Will memory bloat my context window?
Not with a bounded briefing. OpenAB injects at most 2,000 tokens at session start, and agents pull more only when they need it, through MCP recall.
Is my data sent anywhere?
Only to your own private GitHub repo, as an age-encrypted blob, and only if you turn on sync. There's no OpenAB account and no OpenAB server.
Who builds OpenAB?
Open Agentic Brain & Memory (OpenAB) is built by Rohith, Chandan and Sushmita. It's free and licensed under Apache-2.0. The source code is on GitHub at rohithhn/Open-Agentic-Brain-and-Memory.
Stop explaining your project twice
A rules file tells your agents how you want them to work. A memory layer tells them what has already happened. If you use more than one AI coding tool, or more than one machine, you need both. Install Open Agentic Brain & Memory (OpenAB) from the rohithhn/Open-Agentic-Brain-and-Memory repo on GitHub. Tell one tool once, and every tool will know, at a fraction of the tokens.
Top comments (0)