Claude Code Memory: CLAUDE.md and Auto Memory Explained

Claude Code memory works through two systems: CLAUDE.md instruction files that you write and Claude loads at launch, and an automatic memory where Claude records its own learnings in a MEMORY.md index per repository. As of July 2026 the hierarchy runs from a managed org-wide policy file down to ~/.claude/CLAUDE.md (user), ./CLAUDE.md (project), and ./CLAUDE.local.md (personal, per project), with auto memory on by default and stored under ~/.claude/projects/<project>/memory/. This guide maps the full system against the official memory documentation: what loads when, how imports work, the /memory and /init commands, and how to keep all of it from bloating your context window.

What Claude Code Memory Is

Claude Code memory is the set of files the agent reads at the start of every session so it does not re-learn your project from scratch. It splits cleanly into two layers: instructions you write (CLAUDE.md files with coding standards, build commands, and conventions) and learnings Claude writes (the auto memory system, where Claude records debugging insights and workflow patterns it discovers while working).

The distinction matters because the two layers answer different questions. CLAUDE.md answers "how should you behave in this codebase", auto memory answers "what have you already figured out here". Both are plain markdown on disk, which is why the same CLAUDE.md conventions transfer to other agents; our CLAUDE.md vs skills comparison covers when instructions belong in memory versus a reusable skill.

The Memory File Hierarchy

Claude Code recognizes four memory scopes, loaded from broadest to most specific, per the official docs as of July 2026:

Two clarifications worth pinning down. First, content is concatenated, not overridden: a project CLAUDE.md adds to the user file rather than replacing it, and within a directory CLAUDE.local.md is appended after CLAUDE.md. Second, CLAUDE.local.md is still fully supported as of July 2026 despite recurring rumors of deprecation.

How Memory Files Load (and Imports)

Claude Code discovers memory by walking up the directory tree from your working directory, loading every CLAUDE.md and CLAUDE.local.md it finds along the way in full at launch. CLAUDE.md files in subdirectories below you are not loaded upfront; they load on demand the first time Claude reads files in those directories, which keeps monorepo context lean.

Memory files can also import other files with the @path syntax:

# Inside CLAUDE.md
See @README.md for the project overview
Follow the API conventions in @docs/api-style.md
Personal overrides live in @~/.claude/my-defaults.md

Imports resolve relative to the file containing them, support absolute and home-directory paths, and can nest up to four hops deep. Import parsing skips markdown code spans and fenced code blocks, so a backtick-wrapped @handle in your docs will not accidentally pull a file into context. In monorepos where an ancestor CLAUDE.md is irrelevant, the claudeMdExcludes setting filters it out.

Auto Memory: MEMORY.md and Topic Files

Auto memory is the newer half of the system: Claude Code automatically records useful learnings per repository, on by default as of July 2026. The store lives at ~/.claude/projects/<project>/memory/, where MEMORY.md acts as a concise index and Claude spins detailed notes into topic files like debugging.md or api-conventions.md as needed.

The loading rule is precise: the first 200 lines or 25KB of MEMORY.md, whichever comes first, load at the start of every conversation, and topic files are read only on demand. Since v2.1.191 (June 24, 2026), Claude is reminded to compact the index when it nears that limit, per the official changelog. Auto memory records things like build commands, architecture notes, and debugging insights, and it is machine-local: nothing syncs across machines or to the cloud.

Control it three ways: the /memory command's toggle, the autoMemoryEnabled setting, or the environment variable CLAUDE_CODE_DISABLE_AUTO_MEMORY=1. A custom location can be set with autoMemoryDirectory. Saying "remember that we always use pnpm" in a session routes the note into auto memory for you.

The /memory and /init Commands

Two slash commands manage the whole system. /memory lists every memory file loaded in the current session (CLAUDE.md, CLAUDE.local.md, and rules files), lets you open any of them in your editor, and is where you enable or disable auto memory and view its entries. /init bootstraps a project: it analyzes your codebase and generates a starting CLAUDE.md with build commands, test instructions, and conventions, or suggests improvements if one already exists. Setting CLAUDE_CODE_NEW_INIT=1 switches /init to an interactive flow that also walks through skills, hooks, and personal memory files.

One historical note: early Claude Code versions documented a # shortcut for quickly appending a memory line. That shortcut no longer appears in the official memory or commands documentation as of July 2026; the supported paths are the /memory command and simply asking Claude to remember something, which lands in auto memory. The full command list lives in our Claude Code commands cheat sheet.

Rules Files and Subagent Memory

The .claude/rules/ directory complements CLAUDE.md by splitting instructions into modular files that can be path-scoped: a YAML paths: field with glob patterns makes a rule load only when Claude works on matching files, which saves context in large repos. User-level rules in ~/.claude/rules/ load before project rules, so project rules win on conflict. Our Claude Code rules guide goes deeper on structuring these.

Subagents interact with memory in a specific way per the subagents docs: the built-in Explore and Plan subagents skip your CLAUDE.md files to keep research cheap, while every other built-in and custom subagent loads them. Custom subagents can even get their own persistent memory with a memory: user|project|local frontmatter field, stored under agent-memory/ directories with the same 200-line/25KB index rule.

Best Practices for CLAUDE.md

The official guidance targets under 200 lines per CLAUDE.md file, because longer files consume more context and measurably reduce adherence. Since v2.1.169, the "CLAUDE.md too long" warning threshold scales with the active model's context window.

• Be verifiable, not vague. "Use 2-space indentation" and "run npm test before committing" work; "format code properly" does not.
• Use structure. Markdown headers and bullets beat dense paragraphs; Claude scans structure the way readers do.
• Push detail down. Long reference material belongs in @imported files or path-scoped rules, not the top-level file.
• Review periodically. Conflicting instructions across nested CLAUDE.md files and rules quietly degrade behavior.

If you are starting from zero, run /init or use our CLAUDE.md generator, then trim toward the 200-line target. These files also pay off beyond Claude Code itself; see how to turn a CLAUDE.md into an OpenClaw skill.

Limitations and Tradeoffs

Memory is context, and context is not free: every loaded line of CLAUDE.md, rules, and MEMORY.md consumes tokens on every request, so an overgrown memory stack slows sessions and dilutes instruction-following. Auto memory also cuts both ways; because Claude decides what is worth remembering, a wrong conclusion recorded early ("this project uses yarn") can persist until you audit the memory directory with /memory.

The other boundary is scope. Auto memory is per repository and per machine, with no cross-machine sync, and CLAUDE.md is not a secrets store or a settings file: permissions and tool policy belong in settings.json, which Claude does not read as prose context. For the broader picture of how memory fits into the whole tool, start with our complete Claude Code guide.

Related Guides

• Claude Code Rules: CLAUDE.md, Permissions, and Loop Control
• Claude Code Best Practices in 2026
• Claude Code VSCode: The Official Extension Guide
• OpenClaw Skills vs CLAUDE.md Files: When to Use Each