Claude Code Memory: the 3 memory systems most devs don't know about

Claude Code now has 3 distinct memory systems: Memory, Auto Memory, and Agent Memory. Most developers don't even know they exist -- and those who know about CLAUDE.md think that's all there is.

And it's funny because Anthropic keeps adopting patterns that already existed in OpenClaw -- MEMORY.md, auto memory, agent memory, project rules. Feature after feature, it all comes around.

The reality is a 6-layer system with a precise hierarchy. Misconfiguring it means leaving Claude Code running at 30% of its potential.

The 6 layers of Claude Code memory

Each layer has a specific role and priority in instruction resolution:

Layer 1: Managed Policy

The highest layer in the hierarchy. Defined by Anthropic or your organization if you use Claude Code in enterprise. You can't modify it -- it serves as a guardrail and global policy.

Layer 2: Project Memory (CLAUDE.md)

The file everyone knows. Placed at the root of your project, it contains:

• Project conventions (formatting, naming)
• Build and test commands
• Project architecture
• Stack-specific rules

The key point: this file is versioned with git. Your entire team benefits from it.

# CLAUDE.md

## Build
- `pnpm dev` for local dev
- `pnpm build` for production

## Conventions
- TypeScript strict
- Drizzle ORM for DB
- Components in src/components/

Layer 3: Project Rules (.claude/rules/*.md)

The most powerful and least known layer. Markdown files in .claude/rules/ that activate conditionally:

---
globs: src/components/**/*.tsx
alwaysApply: false
---

All React components must use named exports.
Use `cn()` for Tailwind class merging.

The rule only activates when Claude Code works on a file matching the glob. This lets you have specific instructions without polluting the main CLAUDE.md.

Layer 4: User Memory (~/.claude/CLAUDE.md)

Your personal preferences file, stored in your home directory. It applies to all your projects:

• Your preferred editor
• Your global style conventions
• Your communication preferences with Claude

Layer 5: Imports

External files loaded on-the-fly into context. Useful for injecting documentation, specs, or references without putting them in CLAUDE.md.

Layer 6: Auto Memory

The game changer. Claude Code writes its own notes in ~/.claude/projects/<project>/memory/:

~/.claude/projects/<project>/memory/
├── MEMORY.md          <- Index (first 200 lines auto-loaded)
├── debugging.md       <- Debugging notes
├── api-conventions.md <- Learned decisions
└── ...

When you correct Claude Code ("no, use pnpm not npm"), it takes note. When it solves a complex bug, it records the solution. You can also tell it "remember that..." and it writes to its files.

The /memory command lets you see all layers at once and edit them.

Memory vs Auto Memory vs Agent Memory

This is the most common confusion:

Agent Memory is the most advanced: when Claude Code spawns sub-agents, each one maintains its own independent memory that persists between sessions.

The 5-minute setup

1. Create your CLAUDE.md at the project root with your conventions and commands
2. Add rules in .claude/rules/ for conditional rules
3. Configure your User Memory in ~/.claude/CLAUDE.md for global preferences
4. Enable Auto Memory by using Claude Code normally -- it writes on its own
5. Check with /memory to see the complete state

Conclusion

Claude Code's memory system is much more than a simple CLAUDE.md file. It's a 6-layer architecture that, once properly configured, transforms Claude Code into a real collaborator who knows you, knows your project, and learns from its mistakes.

Watch the full video