Memory in Claude Code
How Claude remembers across sessions — the CLAUDE.md hierarchy, modular rules, imports, and the auto memory Claude writes for itself.
Claude forgets everything between sessions — memory files are the fix
What memory is
Plain Markdown files — CLAUDE.md — loaded automatically every time Claude Code launches. They carry project standards, personal preferences, and directory-specific rules across sessions, and they live in your repo so you can version-control them.
Two forms, one idea
claude.ai synthesizes memory automatically every 24 hours. Claude Code uses files on disk — explicit, inspectable, git-trackable. This chapter is about the files: what loads, from where, and in what order.
Eight tiers of memory load at launch — higher tiers win
/init writes your first CLAUDE.md in one command
What it does
- Creates CLAUDE.md in your project root
- Documents conventions, structure, and standards
- Gives the whole team a shared starting template
Interactive mode
CLAUDE_CODE_NEW_INIT=1 claude /init
A multi-phase guided flow that walks you through project setup step by step.
The # shortcut is gone — update memory with /memory or just ask
/memory — the editor route
Opens your memory files in your system editor and lets you pick the tier: managed policy, project, user, or local. Best for extensive edits, reorganizing, and periodic review.
Conversational — the fast route
Remember that we always use TypeScript strict mode in this project.
Claude asks which memory file it belongs in, writes it, and reloads. Best for single rules as they come up.
@imports let CLAUDE.md reference docs instead of duplicating them
# Project Documentation See @README.md for project overview See @docs/architecture.md for system design # Absolute paths work too @~/.claude/my-project-instructions.md
- Relative and absolute paths both supported — content lands in Claude's context automatically
- Recursive imports up to 5 levels deep
- First-time imports from external locations trigger a security approval dialog
- Not evaluated inside code spans or code blocks — documenting them in examples is safe
.claude/rules/ breaks memory into modular, path-scoped files
.claude/rules/
├── code-style.md
├── testing.md
└── api/
└── conventions.md
~/.claude/rules/ # personal, all projects
└── preferred-patterns.md
--- paths: src/api/**/*.ts --- # API Development Rules - Validate all input with Zod - Document parameters and response types
Pick the memory tier by who needs to see it
| Managed policy | Company security policy — applies to every project organization-wide |
| ./CLAUDE.md | Team code style guide — shared with everyone via git |
| ~/.claude/CLAUDE.md | Your personal preferences — follow you across all projects, never shared |
| ./CLAUDE.local.md | Personal *and* project-specific — git-ignored, just for you, just here |
| src/api/CLAUDE.md | Module standards — a directory-level file that overrides root for that subtree |
A good project CLAUDE.md reads like a team handbook
# Project Configuration ## Project Overview — name, tech stack, team size ## Architecture — @docs/architecture.md @docs/api-standards.md ## Code Style — Prettier, ESLint airbnb, 2-space indent ## Naming — kebab-case files, PascalCase classes ## Git Workflow — feature/ branches, conventional commits ## Testing — 80% coverage, Jest + Cypress ## Common Commands — npm run dev / test / lint / migrate ## Known Issues — pool limit 20 at peak → query queuing
Auto memory: Claude writes notes to itself as it works
~/.claude/projects/<project>/memory/ ├── MEMORY.md # entrypoint ├── debugging.md # on demand └── api-conventions.md # on demand
- Claude records learnings, patterns, and insights automatically during sessions
- First 200 lines / 25KB of MEMORY.md load at session start
- Topic files load on demand, not at startup
Auto memory is controllable — location, sharing, scope, on/off
1Custom location
autoMemoryDirectory in user or local settings moves it anywhere — a synced folder, a custom path. Not settable at project or policy level.
2Worktrees share
All worktrees and subdirectories of the same git repo read and write one shared auto memory directory.
3Subagent memory
A memory: user|project|local frontmatter field gives subagents focused context instead of the full hierarchy.
4Kill switch
CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 turns it off for a session; =0 forces it on.
Two levers tune which CLAUDE.md files actually load
Exclude noise
// .claude/settings.json { "claudeMdExcludes": [ "packages/legacy-app/CLAUDE.md", "vendors/**/CLAUDE.md" ] }
Skip stale or third-party memory files in big monorepos.
Add directories
CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1
claude --add-dir /path/to/other/project
Load CLAUDE.md from a sibling project alongside your own — built for multi-project setups.
Specific beats vague — the habits of healthy memory
Do
- Be specific — "2-space indent for JS", not "best practices"
- Structure with clear markdown sections
- Import existing docs with @path
- Document the commands you run repeatedly
- Commit project memory; review it as the project evolves
Don't
- Store secrets, keys, tokens, or PII — ever
- Duplicate content that imports could reference
- Let a file sprawl past ~500 lines
- Over-organize with excessive directory overrides
- Leave stale rules — outdated memory misleads
Run /init today, then let the hierarchy do the work
Memory is files: an eight-tier hierarchy from managed policy down to auto memory, loaded automatically, higher tiers winning. /init starts it, /memory and conversational requests maintain it, @imports keep it DRY, and .claude/rules/ keeps it modular and path-scoped. Claude pulls its own weight too — auto memory accumulates learnings while you work.