What Is an MD File in Claude? CLAUDE.md vs MEMORY.md
Claude's md files explained: what CLAUDE.md and MEMORY.md do, where each lives, and a simple rule for which file each instruction belongs in.
On this page
TL;DR: What is an md file in Claude? A plain markdown file that Claude Code loads into context when a session starts. CLAUDE.md is the one you write; MEMORY.md holds notes Claude writes for itself. Start with one short project CLAUDE.md, kept under 200 lines, and route everything else by the rules below.
| File | Who writes it | Where it lives | When it loads |
|---|---|---|---|
| User CLAUDE.md | You | ~/.claude/CLAUDE.md | Every session, all projects |
| Project CLAUDE.md | You, shared with the team | Project root | Session start in that project |
| Local CLAUDE.md | You, personal | Project, not committed | Last, after project |
| Subdirectory CLAUDE.md | You | e.g. src/persistence/CLAUDE.md | When Claude reads files there |
| MEMORY.md (auto memory) | Claude | Claude's memory store | Session start, with a size limit |
| Verdict | Start with one short project CLAUDE.md |
What is an md file in Claude, and what does Claude do with it?
An md file here is plain markdown that doubles as standing orders for the assistant. Start Claude Code anywhere inside a folder that holds a CLAUDE.md and the tool pulls that file into context on its own (codewithmukesh.com). Nobody has to invoke it, import it manually or nudge Claude to look.
Skip the file and every session begins with no knowledge of your project layout, your conventions or the command that runs your tests (codewithmukesh.com). That is the cost of having no CLAUDE.md.
Keep one distinction straight. A README speaks to human readers, while a CLAUDE.md speaks to the coding assistant (news.ycombinator.com). Claude will not treat your README as a stand-in, so anything that exists only there (the test command, the branch rule) has to be repeated in the file Claude really loads.
Where does a CLAUDE.md file live, and which one loads first?
Files load from broadest scope to most specific: managed policy, user, project, then local (codewithmukesh.com). Project instructions therefore appear in context after your user instructions, and your personal local notes are read last.
- User level:
~/.claude/CLAUDE.mdholds global preferences across all projects (codewithmukesh.com). Put your own habits here, such as how you like answers formatted. - Project level: the file in the repo root. Commit it so the team shares it.
- Local level: a personal file for one project that you do not commit.
- Subdirectory level: Claude walks up the directory tree from where you launched, loading every CLAUDE.md it finds, so launching from a monorepo subfolder still picks up the repo-root file (codewithmukesh.com). Going the other way, subdirectory files are pulled in automatically when Claude reads a file in that directory (news.ycombinator.com).
That last behavior is the useful one. If you have a database layer with critical caveats, a commenter recommends putting them in src/persistence/CLAUDE.md instead of the main file (news.ycombinator.com). Claude then sees them only when it works there.
How is MEMORY.md different from CLAUDE.md?
Authorship is the simplest split: you write CLAUDE.md, Claude writes MEMORY.md. Auto memory arrived in v2.1.59, and it lets Claude jot notes for itself while it works and read them back at the start of each session, with nothing to configure (codewithmukesh.com).
There is also a practical difference in size handling. A cap applies to MEMORY.md alone, whereas CLAUDE.md is read in full whatever its length (codewithmukesh.com). That might tempt you to write a long CLAUDE.md, but the length section below explains why that is a trap.
Trust and visibility differ too. Auto memory stays on your machine. When one of its notes records a decision your whole team made, copy it into a versioned file so everyone gets it (stevekinney.com). For where the file lives on disk and how to inspect it, see Claude MEMORY.md: What It Is, Where It Lives, Limits.
Which file should each instruction go in?
Run each instruction through these questions in order. Stop at the first yes.
- Must it be enforced, every time? Then it is not an instruction at all. If something must be enforced, encode it in tests, lint, permissions, hooks or continuous integration (stevekinney.com). Memory files are context, not enforcement. Our Claude Code Hooks Preset Generator builds the hook version.
- Is it a multi-step workflow with phases, scripts or assets? Make it a skill. Rules shape the session; skills run a workflow (stevekinney.com). One commenter goes further and advises skills first, before littering a project with config files (news.ycombinator.com).
- Does it only matter in one folder? Put it in that folder's CLAUDE.md so it loads only when Claude works there (news.ycombinator.com).
- Is it domain knowledge Claude needs only sometimes? Consider a retrievable document or an MCP server, so Claude fetches it on demand instead of carrying it in every session (xda-developers.com). This is one writer's opinion, but it fits the pattern: less front-loaded text, better focus.
- Is it shared project policy? Project CLAUDE.md, committed. Do not rely on local-only memory for shared project policy (stevekinney.com).
- Is it a personal preference across projects? User CLAUDE.md.
- Is it a small fact Claude picked up while working? Leave it in auto memory, and promote it to a versioned file if the team ends up depending on it (stevekinney.com).
When a CLAUDE.md is the wrong tool
If the rule is "never edit this file" or "always run lint before commit", a CLAUDE.md line is a request, not a guarantee. Someone reports Claude not starting sessions with all of the CLAUDE.md loaded, and losing it mid-session (news.ycombinator.com). Use a hook or a CI check for anything where a miss is costly.
What belongs in a CLAUDE.md, and what should you leave out?
Anthropic recommends organizing the file around three layers (codewithmukesh.com):
- What: your stack and project structure.
- Why: the architectural decisions that are not obvious from code.
- How: commands and workflow rules, such as how to build and test.
The authors of a recent study suggest including the minimum necessary requirements, such as specific tools or commands (xda-developers.com). That is the test for every line: would Claude get this wrong without it?
Leave out:
- High-level overviews. They are functionally useless, as the model can glean this from studying your codebase (xda-developers.com).
- Secrets. Never put API keys, connection strings or passwords in the file (codewithmukesh.com).
- Anything not universally applicable. The more information in the file that is not relevant to the task at hand, the more likely Claude is to ignore your instructions, according to one commenter (news.ycombinator.com). Move folder-specific notes to subdirectory files.
For maintainer notes that Claude does not need, block-level HTML comments are stripped before the content reaches Claude's context (codewithmukesh.com).
How long should it be, and how do you know Claude is following it?
Anthropic's official guidance, as relayed by codewithmukesh, is to aim for under 200 lines per file, since a longer file eats more context and lowers adherence (codewithmukesh.com). Because nothing trims CLAUDE.md for you, the length discipline is yours to apply.
Doubt the assumption that more context always helps. Earlier studies of repository-level context files reported gains of up to 36%, though those studies are two years old or older (xda-developers.com). Studies from 2026 report up to 5% over baseline, and in some cases a negative effect when AI generated the files. The same coverage adds that context files make agents take more steps and push reasoning token use up by as much as 20%. We'd pick a short file you have checked by hand over a giant one pasted in wholesale.
To check adherence, plant a canary. One Hacker News commenter describes a friend who tells Claude to always call him "Mr Tinkleberry" and takes the name vanishing as proof Claude has stopped paying attention to the file (news.ycombinator.com). Add a harmless line of that kind. When it stops showing up mid-session, the file has been dropped or buried, so trim it or restart the session.
How do you create your first one?
Prerequisites: Claude Code installed, and a project folder you can open it in.
- Generate a starter. Use the Claude MD Generator, or write three short headings by hand: stack, decisions, commands. Expected result: a draft that fits comfortably under 200 lines (codewithmukesh.com).
- Save it in the project root as
CLAUDE.md. Expected result: the file sits next to your package manifest or equivalent. - Cut it. Delete overviews, secrets and anything that only applies to one folder. For example rule shapes, see Claude Code Rules: What to Put in CLAUDE.md. Expected result: every remaining line is a command, a decision or a convention Claude would otherwise guess.
- Start a new session in that directory. Expected result: the contents are loaded automatically (codewithmukesh.com).
- Check it with a canary line, as above. Expected result: Claude follows it from the first message.
When this is the wrong move
If your project is tiny or throwaway, skip the file and let auto memory pick up what it needs. If your pain is Claude ignoring one rule, fix it with a hook, not more prose. If you want a ready-made set of habits instead of writing your own, the Karpathy CLAUDE.md is a short, opinionated starting point.
ClockedCode: Upgrade your Claude Code setup in one paste A curated Claude Code setup: vetted tools, subagents, and a tuned CLAUDE.md, compiled into one master prompt you paste once.
Frequently asked questions
Where do I put the CLAUDE.md file?
For a project, in the repo root, so it loads whenever you start a session there. For preferences that follow you everywhere, use ~/.claude/CLAUDE.md [1]. Folder-specific notes go in a CLAUDE.md inside that folder.
Does Claude read my README instead?
No. READMEs are written for people and CLAUDE.md files for coding assistants [4]. If the README holds commands Claude needs, copy the essential ones into CLAUDE.md rather than hoping it finds them.
Can CLAUDE.md files import other files, and does that save context?
They can, but imports do not save context, because imported files are loaded at launch [1]. They are useful for personal preferences you do not want committed, such as a file in your home directory referenced from the project file [1]. For real savings, split by folder instead.
Your next action: open a terminal in your project, write the three headings, and save the file before your next session.
Frequently asked questions
Where do I put the CLAUDE.md file?
For a project, in the repo root, so it loads whenever you start a session there. For preferences that follow you everywhere, use ~/.claude/CLAUDE.md [1]. Folder-specific notes go in a CLAUDE.md inside that folder.
Does Claude read my README instead?
No. READMEs are written for people and CLAUDE.md files for coding assistants [4]. If the README holds commands Claude needs, copy the essential ones into CLAUDE.md rather than hoping it finds them.
Can CLAUDE.md files import other files, and does that save context?
They can, but imports do not save context, because imported files are loaded at launch [1]. They are useful for personal preferences you do not want committed, such as a file in your home directory referenced from the project file [1]. For real savings, split by folder instead.
Your next action: open a terminal in your project, write the three headings, and save the file before your next session.