Claude Code Memory

Canonical version: Claude Code Memory.

Claude Code has two complementary memory systems, both loaded at every session start:

CLAUDE.md files

Stored in different locations:

• Managed policy: /Library/Application Support/ClaudeCode/CLAUDE.md (macOS), /etc/claude-code/CLAUDE.md (Linux/WSL)
• Project memory: project root/CLAUDE.md or .claude/CLAUDE.md
• Project memory (local): project root/CLAUDE.local.md (added to .gitignore!)
• User memory: ~/.claude/CLAUDE.md

Editable via the /memory command.

How memory files are located/loaded

Claude Code reads memories recursively, starting in the current working directory (cwd). Then it recurses up to /, reading any CLAUDE.md or CLAUDE.local.md files along the way.

Files nested in subtrees under cwd are NOT loaded at launch, but only when Claude reads files in those subtrees.

Memory file imports

Memory files can import additional instructions using @path/to/import:

See @README for project overview and @package.json for available npm commands.

## Additional Instructions
- git workflow @docs/git-instructions.md

Both relative and absolute paths are allowed. Home dir files too: @~/.claude/project-preferences.md.

Imports are NOT evaluated inside Markdown code spans and code blocks. Imported files can recursively import other files, with a maximum depth of five hops.

Project rules (.claude/rules/)

For larger projects, instructions can be organized into multiple files under .claude/rules/. Each .md file covers one topic. Rules can be scoped to specific file paths using YAML frontmatter with a paths field (glob patterns). Rules without paths load unconditionally at launch.

---
paths:
  - "src/api/**/*.ts"
---
# API Development Rules
- All API endpoints must include input validation

User-level rules can be placed in ~/.claude/rules/.

Quick add

The fastest way to add a memory is to start your input with #. Claude Code will then ask where to store it.

Auto memory

Auto memory lets Claude accumulate knowledge across sessions automatically. It decides what's worth remembering based on whether the information would be useful in a future conversation.

• On by default. Toggle via /memory or set "autoMemoryEnabled": false in project settings. Disable via env: CLAUDE_CODE_DISABLE_AUTO_MEMORY=1
• Storage: ~/.claude/projects/<project>/memory/ — contains a MEMORY.md entrypoint and optional topic files
• Loading: first 200 lines of MEMORY.md loaded at session start. Topic files loaded on demand
• Scope: machine-local, shared across all worktrees/subdirectories within the same git repo
• Editable: plain Markdown files, edit or delete at any time via /memory

Subagents can also maintain their own auto memory.

Best practices

• Be specific
• Use structure (Markdown headings and bullet points)
• Target under 200 lines per CLAUDE.md file. Production-tested teams (e.g. HumanLayer) keep their root CLAUDE.md closer to 60 lines — every line is reloaded every session
• Move non-critical details into .claude/rules/*.md with paths: globs so they only load when relevant files are touched
• Wrap critical, must-not-skip instructions in conditional priority tags so the model surfaces them when matched: <important if="editing migrations"> ... </important>
• Review regularly and update as the project evolves
• Auto-compaction order: older tool outputs are cleared first, then conversation summarized. Persistent rules belong in CLAUDE.md so they survive compaction (skill descriptions are also reloaded after compaction)

Context budget rules of thumb

Source: practitioner reports on Claude Code at scale.

Implications:

• Push exploration to subagents — their final report is the only thing that returns to main context (the highest-leverage token move)
• Manually /compact BEFORE auto-compact fires (auto-compact runs at the lowest-intelligence point of a long session)
• Use /clear instead of /compact when starting genuinely new work — it drops everything except what you carry forward explicitly
• Use /rewind (or double-Esc) when Claude takes a wrong turn — better than stacking correction prompts in a polluted context

References

• Memory management: https://code.claude.com/docs/en/memory
• Auto memory: https://code.claude.com/docs/en/memory

Related

• Claude Code
• Claude Code Configuration
• Claude Code Skills

About Sébastien

I'm Sébastien Dubois, and I'm on a mission to help knowledge workers escape information overload. After 20+ years in IT and seeing too many brilliant minds drowning in digital chaos, I've decided to help people build systems that actually work. Through the Knowii Community, my courses, products & services and my Website/Newsletter, I share practical and battle-tested systems.

I write about Knowledge Work, Personal Knowledge Management, Note-taking, Lifelong Learning, Personal Organization, Productivity, and more. I also craft lovely digital products and tools.

If you want to follow my work, then become a member and join our community.

Ready to get to the next level?

If you're tired of information overwhelm and ready to build a reliable knowledge system:

• 📚 KM for Beginners — 10+ hours of structured video lessons
• 🚀 Obsidian Starter Kit — Ready-made vault with 40+ templates
• 💼 Knowledge Worker Kit — Complete guides + lifetime community
• 🦉 1-on-1 Coaching — Personalized guidance
• 🎯 Join Knowii — Community + ALL courses & tools