MEMORY.md vs CLAUDE.md is a question of who writes the file: CLAUDE.md holds instructions you write, and MEMORY.md holds notes Claude Code writes for itself. AGENTS.md is an open instruction format that other coding agents read too, and Claude Code reads it only when no CLAUDE.md is present, unless you import it or change one setting.
You should not put the same instruction in all 3 files. Copies drift apart, and Anthropic's memory documentation warns that when 2 rules contradict each other, Claude may pick one arbitrarily.
MEMORY.md vs CLAUDE.md vs AGENTS.md at a glance
| CLAUDE.md | MEMORY.md | AGENTS.md | |
|---|---|---|---|
| Written by | You | Claude Code, as auto memory | You |
| Loads | At session start for the project root and above; subfolders when Claude reads files there | First 200 lines or 25 KB at session start; topic files on demand | In Claude Code only when no CLAUDE.md is present, or through an import |
| Scope | Project, user or organisation | One project, on one machine | The project; in other agents the nearest file in the tree wins |
| Size | Under 200 lines, Anthropic recommends | An index; details belong in topic files | Loads into context like CLAUDE.md when Claude reads it |
| Use it for | Rules and conventions for Claude | What Claude learned from your corrections | Instructions shared across coding tools |
Who writes each file, when it loads and what it is for. From Anthropic's memory documentation and the AGENTS.md site.
What CLAUDE.md is for
CLAUDE.md is a Markdown file of instructions that Claude Code loads as context at the start of a session. Files in the project root and the directories above it load at launch; files in subfolders load when Claude reads files there. Anthropic's memory documentation recommends keeping each one under 200 lines, because longer files consume context and reduce adherence. It also states that Claude treats them as context, not enforced configuration.
What MEMORY.md is for
MEMORY.md is the index of auto memory: notes Claude Code writes for itself from your corrections and preferences. The first 200 lines or 25 KB load at the start of every conversation, and the topic files it points to are read when needed. Each project gets its own memory directory under ~/.claude/projects/, and the documentation describes auto memory as machine-local. In this article, MEMORY.md means the Claude Code file.
Does Claude Code read AGENTS.md?
Yes, with one condition. By default Claude Code reads AGENTS.md only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or above it. With both files present, it reads CLAUDE.md only. You can change that in 2 ways: import AGENTS.md from CLAUDE.md with @AGENTS.md, or change the Project instructions setting in /config. Reading AGENTS.md directly needs Claude Code v2.1.277 or later.
AGENTS.md itself is an open format for guiding coding agents, stewarded by the Agentic AI Foundation under the Linux Foundation. Its site lists more than 20 supporting agents, among them OpenAI Codex, GitHub Copilot, Cursor and Google Jules, and more than 60,000 open-source projects using it.
How to use all 3 without duplicates
This is the order I would start with:
- Put the instructions every coding tool needs in AGENTS.md: build steps, test commands, conventions.
- In CLAUDE.md, import it with
@AGENTS.mdand add only what is specific to Claude. - Leave MEMORY.md to Claude. I would open it with
/memoryonce a week and move anything the whole team needs into CLAUDE.md or AGENTS.md, where others can read it.
How I use these files with my agents
I run marketing at EmpoweredHouse with a team of Claude Code agents, one per area of work, and each has its own CLAUDE.md as a role card. The role cards follow our method: every agent has a written role and one folder. I keep the shared state out of MEMORY.md. Auto memory is machine-local, belongs to one project and holds what Claude noted for itself, while the state has to be readable by every agent and by me. So it sits in plain files with an address on every entry, as I describe in my article on AI agent memory architecture.
FAQ
What is the difference between MEMORY.md and CLAUDE.md? Who writes it. You write CLAUDE.md as instructions, and Claude Code writes MEMORY.md from your corrections and preferences.
Where is MEMORY.md stored?
In a memory directory per project under ~/.claude/projects/ on your machine. It is not shared across machines or cloud environments.
Can I use CLAUDE.md and AGENTS.md together?
Yes. Import AGENTS.md from CLAUDE.md with @AGENTS.md, or set Project instructions to load both. Without either, Claude Code reads CLAUDE.md only.
Is CLAUDE.md the same as a system prompt? No. Anthropic's documentation says Claude treats it as context, not enforced configuration, and points to hooks for blocking an action whatever Claude decides.
If you use one coding tool, I would start with CLAUDE.md alone. If your team uses several, keep one AGENTS.md as the source and let CLAUDE.md import it. If you want more setups like mine, with the files behind them, apply to the Empowered Community pilot. It opens on 1 December, and applications are open until 27 November.
Facts checked against Anthropic's documentation and the AGENTS.md site on 7 October 2026.
