CLAUDE.md vs CLAUDE.local.md vs auto memory: what goes where
CLAUDE.md, CLAUDE.local.md, user and managed CLAUDE.md files, and auto memory compared: who writes each, who sees it, when it loads, what goes in it.
An engineer adds "use my staging database at db-dev-arjun.internal" to CLAUDE.md and pushes it. The next morning, three teammates' sessions are pointing at Arjun's database. The line belonged in CLAUDE.local.md.
Claude Code has several memory files with different owners and audiences. This guide sorts them out from Anthropic's memory documentation, checked on 16 November 2026.
The short answer
| File | Who writes it | Who sees it | Committed? | Use for |
|---|---|---|---|---|
Managed policy CLAUDE.md | IT or DevOps | Everyone in the organization | Deployed, not committed | Company coding standards, security rules |
./CLAUDE.md | The team | Everyone in the repo | Yes | Build commands, conventions, architecture |
./CLAUDE.local.md | You | Only you, this project | No; gitignore it | Your sandbox URLs, test data |
~/.claude/CLAUDE.md | You | Only you, all projects | No | Personal style and tooling preferences |
| Auto memory | Claude | Only you, this repo | No | Corrections and preferences Claude learned |
Managed policy paths are /Library/Application Support/ClaudeCode/CLAUDE.md on macOS, /etc/claude-code/CLAUDE.md on Linux and WSL, and C:\Program Files\ClaudeCode\CLAUDE.md on Windows.
CLAUDE.md
The shared, committed file. Put what every teammate's session needs: build and test commands, conventions, architecture notes. Anthropic suggests keeping each file under 200 lines, since longer files use more context and reduce adherence; move area-specific instructions into path-scoped rules. See CLAUDE.md examples.
CLAUDE.local.md
Your private notes for one project. It loads alongside CLAUDE.md and is treated the same way. Add it to .gitignore.
One catch: a gitignored file exists only in the worktree where you created it. If you work in several worktrees, import a file from your home directory instead.
~/.claude/CLAUDE.md
Your preferences for every project: how you like code formatted, tools you use. Only you see it.
Auto memory
Notes Claude writes for itself. Per Anthropic's docs, it saves four kinds:
- user: your role, expertise, and working preferences
- feedback: corrections you give and approaches you confirm
- project: ongoing work, deadlines, and decisions it can't derive from the code
- reference: where to find outside information, such as a tracker
It skips what it can derive from the code and what CLAUDE.md already says. It's stored per repository at ~/.claude/projects/<project>/memory/, shared across that repo's worktrees, and loaded each session up to the first 200 lines or 25KB. Change the location with autoMemoryDirectory. See auto memory.
How they load
Claude Code loads CLAUDE.md and CLAUDE.local.md from the working directory and every directory above it at launch, and from subdirectories on demand. They're concatenated, not overridden, ordered from the filesystem root down. Auto memory loads at session start too.
Context, not enforcement
Anthropic is explicit: memory files are context, not enforced configuration. Claude reads them and usually follows them, but nothing guarantees it. To block an action no matter what, use a PreToolUse hook or permission rules. See why Claude Code ignores CLAUDE.md.
The gap: team decisions
None of these files is a good home for decisions that change and need an owner. CLAUDE.md is edited by whoever opens a pull request; auto memory is per person and written by Claude. A decision like "the v1 API stays frozen until March" needs one owner, one current version, and a way to reach every teammate's session.
Where Lockstep fits
Lockstep holds those decisions. It captures them from PRDs, Slack, and pull requests, routes each to its owner for approval, and briefs every Claude Code session on the ones that apply, for every teammate, without anyone editing a memory file.
See how it works.
Sources checked 16 November 2026
Related reading
For the full memory picture, see how Claude Code memory works. For what survives compaction, see Claude Code context window. For AGENTS.md and README.md, see AGENTS.md vs README.md.
Frequently asked questions
- What is CLAUDE.local.md?
- A file at the project root for your private, project-specific preferences, such as sandbox URLs or preferred test data. It loads alongside CLAUDE.md and is treated the same way. Anthropic's docs say to add it to .gitignore so it isn't committed.
- What is the difference between CLAUDE.md and CLAUDE.local.md?
- CLAUDE.md is committed and shared with everyone who works in the repository. CLAUDE.local.md is gitignored and only for you in that project. Both load at launch from the working directory and the directories above it.
- What is the difference between CLAUDE.md and auto memory?
- You write CLAUDE.md: instructions and rules. Claude writes auto memory: learnings such as your preferences, corrections, and project context it can't derive from the code. Auto memory is stored per repository under ~/.claude/projects/<project>/memory/ and loads at the start of each session, up to the first 200 lines or 25KB.
- Does CLAUDE.local.md work across git worktrees?
- Not automatically. A gitignored CLAUDE.local.md only exists in the worktree where you created it. Anthropic's docs suggest importing a file from your home directory instead if you want personal instructions in every worktree.
- Do CLAUDE.md instructions guarantee Claude follows them?
- No. Anthropic's docs say Claude treats memory files as context, not enforced configuration. To block an action regardless of what Claude decides, use a PreToolUse hook or permission rules.
Keep reading