Sonith ManakkatEvery new Claude Code session starts with a fresh desk. Anthropic's memory documentation says it plainly: each session begins with a fresh context window, and two mechanisms carry knowledge across sessions. One you write (CLAUDE.md). One Claude writes for itself (auto memory). This part covers both, plus the closest thing in the Claude chat app (Projects). Plain pictures first, expert details in the panels.
What CLAUDE.md is
When should you add something? Anthropic's guidance is to treat CLAUDE.md as the place you write down what you would otherwise re-explain:
- Claude made the same mistake twiceWrite the rule down.
- A code review caught somethingClaude should have known it about this codebase.
- You typed the same correction againSame clarification as last session.
- A new teammate would need itThe same context makes people productive too.
Where it lives
| Scope | Location (as documented) | Shared with |
|---|---|---|
| Organisation (managed policy) | macOS: /Library/Application Support/ClaudeCode/CLAUDE.md. Linux and WSL: /etc/claude-code/CLAUDE.md. Windows: C:\Program Files\ClaudeCode\CLAUDE.md | Everyone in the organisation |
| You, all projects | ~/.claude/CLAUDE.md | Only you |
| This project | ./CLAUDE.md or ./.claude/CLAUDE.md | The team, through source control |
| You, this project | ./CLAUDE.local.md (add to .gitignore) | Only you |
Expert viewHow the files combine
Anthropic's documentation says Claude Code loads CLAUDE.md and CLAUDE.local.md from the current working directory and every directory above it. All discovered files are concatenated into context rather than overriding each other, ordered from the filesystem root down to your working directory, so instructions closest to where you launched Claude are read last. Files in subdirectories below the working directory are not loaded at launch; each loads once Claude reads, writes or edits a file in that subdirectory.
Block-level HTML comments (<!-- notes for maintainers -->) are stripped before injection, so you can leave notes for humans without spending context. To skip other teams' files in a large monorepo, the docs describe a claudeMdExcludes setting. --add-dir directories are not loaded by default; an environment variable (CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1) turns that on.
- 1A new session beginsThe context window starts fresh.
- 2CLAUDE.md files are foundFrom your working directory and every directory above it, plus your own and any organisation file.
- 3They are joined, not overriddenOrdered from the filesystem root down, so the closest file is read last.
- 4Auto memory is addedThe first 200 lines or 25KB of MEMORY.md, whichever comes first.
- 5Then you typeSubdirectory CLAUDE.md files load later, when Claude reads a file there.
Takeaway. Claude starts every session already holding both memory systems.
What to put in it
Too vague
- "Format code properly"
- "Test your changes"
- "Keep files organized"
Concrete
- "Use 2-space indentation"
- "Run npm test before committing"
- "API handlers live in src/api/handlers/"
- Build and test commandsThe exact commands to run.
- ConventionsNaming, style, patterns to follow.
- Project layoutWhere things live and why.
- Do and do-not rules"Never edit files under /generated".
Expert viewWriting instructions that stick
Anthropic's guidance: write instructions concrete enough to verify; target under 200 lines per CLAUDE.md file, because longer files consume more context and reduce adherence; use headers and bullets; and avoid contradictions, since Claude may pick one arbitrarily. @path/to/file imports let you split a file but do not reduce its context cost, because imported files also load at launch (recursive imports go up to four hops). For instructions that matter only for part of the codebase, use .claude/rules/ files, optionally scoped with paths: frontmatter so they load only when Claude works with matching files.
Claude treats CLAUDE.md as context, not enforced configuration. The documentation says to block an action reliably with a PreToolUse hook instead. Useful commands: /init generates a starting file from your codebase, /memory opens your memory files, and /doctor prompt-audit (requires v2.1.283 or later) checks instruction files for outdated or conflicting content. If your repository uses AGENTS.md instead, the docs describe how Claude Code can read it in place of CLAUDE.md.
- Organisation The organisation file loads before your own and the project files.
- You, all projects Your personal file adds your habits for every project.
- This project The project file adds what the whole team agreed.
- You, this project CLAUDE.local.md is appended after CLAUDE.md in its directory, so it is read last there.
point from the widest scope to the narrowest, and all of them are joined into context, so avoid contradictions.
Takeaway. Put each rule at the narrowest scope that needs it.
Auto memory: notes Claude writes itself
CLAUDE.md
- You write it
- Instructions and rules
- Project, user or organisation scope
Auto memory
- Claude writes it
- Learnings and patterns
- Per repository, shared across worktrees
Expert viewAuto memory details
Per Anthropic's memory page, auto memory records four kinds of notes (user, feedback, project and reference) and skips anything derivable from the codebase or already in CLAUDE.md. Files live under ~/.claude/projects/<project>/memory/. The first 200 lines or 25KB of MEMORY.md, whichever comes first, load at the start of every conversation; detailed topic files are read on demand. A CLAUDE.md file up to 4 MiB loads in full, but shorter files give better adherence. Subagents do not inherit the main conversation's auto memory, except a fork. You can audit and edit memory with /memory.
- You to Claude You say "we use pnpm, not npm" again.
- You to CLAUDE.md You write the rule down once, in plain words.
- CLAUDE.md to Claude (reply) The next session starts by loading the file.
- Claude to You (reply) You no longer have to repeat the correction.
Takeaway. A rule in the file costs one edit and saves every future correction.
The chat-app cousin: Projects
If you use Claude in the browser or the app, Projects do a similar job. Anthropic's support pages describe a project as a self-contained workspace with its own chat history and knowledge base. Project instructions apply to every chat in the project, and files in the knowledge base are reused across chats.
- Project instructionsHow Claude should behave in every chat of the project
- Knowledge filesReused across every chat in the project
- SharingOn Team and Enterprise plans, members can be given view or edit access
Expert viewLimits worth knowing
The support article says chats inside a project do not share context with each other unless the information is in the knowledge base; the project name and description are not visible to Claude; and on a paid plan, when knowledge nears the context limit, Claude turns on retrieval (RAG) mode to expand capacity. Anthropic's pricing page lists Projects among Pro features and memory among Free features. Plan availability changes, so check your plan.
Write down once what you would otherwise explain every time.
Frequently asked questions
Is CLAUDE.md a guarantee?
No. It is context that Claude follows as well as it can. Use a hook to enforce something every time.
How long should it be?
Under about 200 lines. Move rarely needed material into rules or skills.
Can I keep personal preferences out of the shared file?
Yes. Use ~/.claude/CLAUDE.md for all projects, or CLAUDE.local.md for one project, and keep the local file out of git.