How Claude remembers across sessions — the CLAUDE.md hierarchy, modular rules, imports, and the auto memory Claude writes for itself.
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.
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.
CLAUDE_CODE_NEW_INIT=1 claude /init
A multi-phase guided flow that walks you through project setup step by step.
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.
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.
# Project Documentation See @README.md for project overview See @docs/architecture.md for system design # Absolute paths work too @~/.claude/my-project-instructions.md
.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
| 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 |
# 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
~/.claude/projects/<project>/memory/ ├── MEMORY.md # entrypoint ├── debugging.md # on demand └── api-conventions.md # on demand
autoMemoryDirectory in user or local settings moves it anywhere — a synced folder, a custom path. Not settable at project or policy level.
All worktrees and subdirectories of the same git repo read and write one shared auto memory directory.
A memory: user|project|local frontmatter field gives subagents focused context instead of the full hierarchy.
CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 turns it off for a session; =0 forces it on.
// .claude/settings.json { "claudeMdExcludes": [ "packages/legacy-app/CLAUDE.md", "vendors/**/CLAUDE.md" ] }
Skip stale or third-party memory files in big monorepos.
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.
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.