# Claude Code Memory Claude Code has two complementary memory systems, both loaded at every session start: | | CLAUDE.md files | Auto memory | |---|---|---| | **Who writes it** | You | Claude | | **What it contains** | Instructions and rules | Learnings and patterns | | **Scope** | Project, user, or org | Per working tree | | **Loaded into** | Every session (full) | Every session (first 200 lines of MEMORY.md) | | **Use for** | Coding standards, workflows, architecture | Build commands, debugging insights, preferences | ## 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. Since v2.1.277 (2026-09-18), Claude Code falls back to `AGENTS.md` when no `CLAUDE.md` exists. See [[AGENTS.md (File Convention)]]. If both exist, `CLAUDE.md` wins, so the usual trick still applies: keep the instructions in `AGENTS.md` and make `CLAUDE.md` import it (`@AGENTS.md`) or symlink it. Custom subagents can skip `CLAUDE.md` files entirely with `omitClaudeMd` in their frontmatter (v2.1.271). Managed policy still loads. ## 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. ```markdown --- 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. ## CLAUDE.md vs skills vs commands vs plugins - **CLAUDE.md**: always loaded, every turn. Simplest, and the most expensive per line. Only what applies to every conversation - **Skills**: instructions that load when relevant (Claude decides) or when invoked (`/name`). Same content in a skill costs nothing until it's used. See [[Claude Code Skills]] - **Slash commands**: the older, user-triggered form of the same idea; merged into skills in 2.1.x - **Plugins**: a distribution unit that bundles skills, agents, hooks, and MCP servers. A plugin can be a single skill. See [[Claude Code Plugins]] Rule of thumb: start with no CLAUDE.md. When you catch yourself telling Claude the same thing a third time, add it (ask Claude to put it in the project or the global file; it knows which). When an instruction only matters sometimes, it's a skill or a `.claude/rules/` file with a `paths:` glob, not a CLAUDE.md line. Review the file periodically against recent transcripts; instructions rot as the project moves, and Claude can do that review for you. ## 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. | Threshold | Behavior | |-----------|----------| | **< 30%** of context window | Sweet spot for high-stakes work | | **~40%** | "Dumb zone" — degradation begins to show | | **> 60%** | Wrap up the session or `/compact` aggressively | | **300–400k tokens** (1M context) | Materially noticeable decay even on 1M models | 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://docs.anthropic.com/en/docs/claude-code/memory - Auto memory: https://code.claude.com/docs/en/memory ## Related - [[Claude Code]] - [[Claude Code Configuration]] - [[Claude Code Skills]]