The files Claude Code reads
| File | Where | For |
|---|---|---|
| User instructions | ~/.claude/CLAUDE.md | Your preferences, in every project |
| Project instructions | ./CLAUDE.md or ./.claude/CLAUDE.md | The team's rules, shared through Git |
| Local instructions | ./CLAUDE.local.md | Your own notes for one project; add it to .gitignore |
| Rules | .claude/rules/*.md (one project) or ~/.claude/rules/ (all projects) | One topic per file; can be limited to certain paths |
How they load. Claude Code reads CLAUDE.md and CLAUDE.local.md in the folder you start it in and every folder above it. They are combined, not replaced: from the top folder down, so the file in the folder you started in is read last. A CLAUDE.md in a subfolder loads when Claude starts working with files there.
Imports. A line like @docs/style.md pulls another file into your CLAUDE.md.
Keep it short. The docs suggest under 200 lines per CLAUDE.md. Move topic rules into .claude/rules/.
AGENTS.md
If a project has an AGENTS.md (the file Codex and other agents read) and no CLAUDE.md or CLAUDE.local.md, Claude Code reads the AGENTS.md instead. If both exist, by default it reads only CLAUDE.md. To use one file for both, import it: put @AGENTS.md in your CLAUDE.md. More on AGENTS.md: Codex page.
Auto memory: the notes Claude writes itself
Auto memory is on by default. As it works, Claude Code saves notes about you, your feedback, the project and where to find things. They live in:
~/.claude/projects/<project>/memory/
MEMORY.md there is the index; the first 200 lines (or 25 KB) load at the start of each session. You can turn auto memory on or off with the /memory command.
These are plain Markdown files you can read and edit. Check them from time to time: a wrong note affects every new session until you fix or delete it.
Reading these files on a Mac
On a Mac, PilcrowMD (free, beta):
- Add your project folder in My folders. Files Claude Code writes, such as plans, specs and reports, show up marked N (new) or U (updated). An open note reloads when Claude Code or another app changes it.
- Highlight changes shows what changed in a file you already read: blue for added, orange for removed or edited. Handy for a
MEMORY.mdor a plan Claude keeps updating. - Compare side by side shows two versions. With file history on, File › Show History… lets you go back to an earlier version.
~/.claudeis a hidden folder. In the Open panel, press ⌘⇧. (Command-Shift-Period) to show hidden folders.- No internet connection; your notes stay on your Mac.
PilcrowMD for Mac (beta) · More on reading agent files
Common questions
Claude ignores my CLAUDE.md. Why? Run /context in a session and check it is listed under Memory files. Long or contradictory files are followed less reliably.
Should CLAUDE.local.md go into Git? No, it is for your own notes. Add it to .gitignore.
Can I read these files on my phone? If the project folder syncs to Google Drive, add it in My folders in PilcrowMD for Android. Open a note to see its latest version; there is no live reload on Android.
Also on Mac: PilcrowMD for Mac (beta)