Memory System
Overview
Claude Code has two complementary memory systems: CLAUDE.md (instructions you write) and Auto Memory (patterns Claude learns). Both are loaded at every session start.
Dual Memory System
| CLAUDE.md | Auto Memory | |
|---|---|---|
| Who writes | You | Claude |
| Contains | Instructions and rules | Learned patterns and preferences |
| Scope | Project, user, or org | Per working tree |
| Loaded | Every session | Every session (first 200 lines) |
| Use for | Standards, workflows, architecture | Build commands, debugging insights, preferences |
CLAUDE.md Locations
| Scope | Location | Shared with |
|---|---|---|
| Managed policy | /Library/Application Support/ClaudeCode/CLAUDE.md (macOS) |
All users in org |
| Project | ./CLAUDE.md or ./.claude/CLAUDE.md |
Team via source control |
| User | ~/.claude/CLAUDE.md |
Just you (all projects) |
@Import Syntax
Reference other files from CLAUDE.md:
See @README.md for project overview and @package.json for available commands.
- Git workflow: @docs/git-instructions.md
- Personal overrides: @~/.claude/my-project-instructions.md
- Relative paths resolve from the containing file's directory
- Max depth: 5 hops
.claude/rules/ Directory
Organize instructions into topic-specific files. Supports path-specific rules:
---
paths:
- "src/api/**/*.ts"
---
# API Development Rules
- All endpoints must include input validation
- Use Zod schemas for request body validation
- Error responses must follow a consistent format
Supported patterns:
- Glob patterns:
src/**/*.ts - Brace expansion:
*.{ts,tsx} - Symlinks: Share rules across projects
Auto Memory
How It Works
- Enabled by default (toggle via
/memoryorautoMemoryEnabledsetting) - Storage:
~/.claude/projects/<project>/memory/ - All worktrees in same repo share one directory
MEMORY.mdacts as index; first 200 lines loaded at session start- Topic files loaded on demand
- Customizable location via
autoMemoryDirectorysetting - Disable via
CLAUDE_CODE_DISABLE_AUTO_MEMORY=1
Memory Types
Claude automatically saves these memory types:
| Type | Description |
|---|---|
user |
User role, preferences, skill level |
feedback |
User corrections and guidance for Claude's behavior |
project |
Project goals, decisions, timelines |
reference |
Pointers to info in external systems (Jira, Slack, etc.) |
CLAUDE.md Best Practices
What to Include
| Include | Why |
|---|---|
| Bash commands Claude can't guess | Project-specific build/test commands |
| Code style rules differing from defaults | Team conventions |
| Testing instructions | How to run, how to verify |
| Repo etiquette | Branch strategy, commit conventions |
| Architectural decisions | Context behind key design choices |
| Environment quirks | Platform/dependency caveats |
| Common gotchas | Avoid known pitfalls |
What to Exclude
| Exclude | Why |
|---|---|
| Anything Claude can infer from code | Redundant, wastes context |
| Standard language conventions | Claude already knows |
| Detailed API docs | Too long, link instead |
| Frequently changing info | Goes stale quickly |
| Long explanations | Keep it concise |
| File-by-file descriptions | Claude can read them |
| Self-evident practices | No information gain |
Core Principles
- Target under 200 lines: Concise beats verbose
- Use
/initto generate starter template: Don't start from scratch - CLAUDE.md survives
/compact: Re-read from disk after compaction - Use
--append-system-promptin scripts: Add system-prompt-level instructions - Use
InstructionsLoadedhook for debugging: Confirm which files load
claudeMdExcludes Setting
Skip specific CLAUDE.md files in large monorepos:
{
"claudeMdExcludes": [
"**/monorepo/CLAUDE.md",
"/home/user/monorepo/other-team/.claude/rules/**"
]
}
Subagent Memory
Subagents can also have persistent memory:
memory: project # or user, local
Storage locations:
user→~/.claude/agent-memory/<name>/project→.claude/agent-memory/<name>/local→.claude/agent-memory-local/<name>/
When enabled, subagents automatically get Read/Write/Edit tool access.