Claude Code memory: how CLAUDE.md and auto memory work

How does Claude Code memory work?

Claude Code memory is two systems that load at the start of every session: CLAUDE.md files, which are instructions you write, and auto memory, which is notes Claude writes for itself. Each session begins with an empty context window, so these files are how Claude knows your build commands, conventions and preferences without being told again. Both are plain Markdown on your disk that you can read and edit.

The official memory docs sum up the split like this:

One thing to keep in mind throughout: Claude treats memory as context, not as enforced configuration. Specific, short instructions get followed more reliably than long, vague ones. If something must happen every time, such as running a formatter after each edit, write a hook instead.

This page explains how memory loads and behaves. For what to put in the file, see our CLAUDE.md guide.

Where do CLAUDE.md files live?

CLAUDE.md files can sit in four places. They are listed here from broadest to most specific, which is also the order they appear in Claude's context.

To create a starting project file, run /init. Claude scans the codebase and writes build commands, test instructions and conventions it finds. If a CLAUDE.md already exists, /init suggests improvements instead of overwriting it.

How memory loads: parent folders and subfolders

Loading follows the folder tree, and the details matter in monorepos.

Parent folders load at launch. Claude Code reads CLAUDE.md and CLAUDE.local.md from your current folder and every folder above it. Start Claude in foo/bar/ and it loads foo/bar/CLAUDE.md, foo/CLAUDE.md, and any CLAUDE.local.md beside them.

Files are joined, not overridden. Everything discovered is concatenated into context, ordered from the filesystem root down to your working folder. So foo/CLAUDE.md comes before foo/bar/CLAUDE.md, and the instructions closest to where you started are read last. Within one folder, CLAUDE.local.md comes after CLAUDE.md.

Subfolders load on demand. A CLAUDE.md in a subfolder below where you started does not load at launch. It loads once Claude reads, writes or edits a file in that subfolder. This is how each package in a monorepo can carry its own notes without crowding every session.

Extra folders are skipped by default. Folders you add with --add-dir give Claude file access, but their CLAUDE.md files do not load unless you set an environment variable:

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config

Other teams' files can be excluded. In a large monorepo, the claudeMdExcludes setting skips specific CLAUDE.md files by path or glob. You cannot exclude the managed policy file.

{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

To see what actually loaded, run /context and look under Memory files. A subfolder CLAUDE.md will not show there until it loads; when it does, a Loaded line with its path appears in the terminal.

Imports with @

A CLAUDE.md can pull in other files with @path/to/file. The imported file loads into context alongside the CLAUDE.md that references it.

See @README for project overview and @package.json for available npm commands.

- git workflow @docs/git-instructions.md

The rules, from the official docs:

• Relative paths resolve from the file that contains the import, not your working folder.
• Imports can nest up to four hops deep.
• Imports inside code spans and fenced code blocks are ignored, so wrapping a path in backticks keeps it literal.
• The first time a project imports a file outside your working folder, Claude Code asks you to approve it.

Imports help you organize a long file, but they do not save context: an imported file loads together with the file that imports it. A handy trick if you use git worktrees is to import a personal file from your home folder, such as @~/.claude/my-project-instructions.md, because a gitignored CLAUDE.local.md only exists in the worktree where you created it.

Rules in .claude/rules

For bigger projects, you can split instructions into topic files in .claude/rules/, such as testing.md or api-design.md. All .md files there are found recursively, so subfolders like frontend/ work too.

A rule without frontmatter loads at launch, with the same priority as .claude/CLAUDE.md. A rule with a paths field only loads when Claude touches a matching file, which keeps it out of context the rest of the time:

---
paths:
  - "src/api/**/*.ts"
---

# API rules

- Every endpoint validates its input
- Use the standard error response format

Personal rules in ~/.claude/rules/ apply to every project on your machine and load before project rules. If a user rule and a project rule disagree, Claude may follow either, so keep them consistent.

Rules sit between CLAUDE.md and skills. If an instruction is a multi-step procedure you only need sometimes, a skill is a better fit, because skills load only when invoked or relevant.

What is auto memory?

Auto memory lets Claude build up knowledge across sessions without you writing anything. As it works, Claude saves four kinds of notes, recorded as a type field in each memory file's frontmatter:

• user: your role, expertise and working preferences
• feedback: corrections you give and approaches you confirm
• project: ongoing work, deadlines and decisions it cannot get from the code or git history
• reference: where to find things outside the project, such as an issue tracker or dashboard

Claude skips anything it can work out from the codebase, and anything your CLAUDE.md already says. It does not save something every session; it decides based on whether the note would help later. When it does, you see messages such as "Saved 2 memories" or "Recalled 2 memories".

Where auto memory is stored

Each project gets its own folder at ~/.claude/projects/<project>/memory/. The project path comes from the git repository, so every worktree and subfolder of one repo shares the same memory. Auto memory is machine-local and is not synced across machines or cloud environments.

~/.claude/projects/<project>/memory/
├── MEMORY.md           # index, one line per memory
├── user_role.md        # one memory
├── feedback_testing.md # one memory
└── ...

The first 200 lines of MEMORY.md, or the first 25KB, whichever comes first, load at the start of every session. Topic files such as feedback_testing.md do not load at startup; Claude reads them when it needs them. That is why Claude keeps MEMORY.md as a short index and moves detail into topic files. You can move the whole folder with the autoMemoryDirectory setting, which takes an absolute path or one starting with ~/.

Turning auto memory on or off

Auto memory is on by default in local sessions. To toggle it, open /memory and use the auto memory switch, which saves autoMemoryEnabled to ~/.claude/settings.json. For a single project, put this in that project's settings:

{
  "autoMemoryEnabled": false
}

The environment variable CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 also turns it off.

Using /memory and asking Claude to remember

/memory is the control panel. It lists your CLAUDE.md, CLAUDE.local.md and other memory files across user and project scopes, including ones that do not exist yet. Select one to open it in your editor; selecting a missing file creates it. It also has the auto memory toggle and a shortcut to open the auto memory folder.

The quickest way to add memory is to just say it. According to the docs, when you ask Claude to remember something, like "always use pnpm, not npm", Claude saves it to auto memory. If you want it in CLAUDE.md, where your team will see it, say "add this to CLAUDE.md" or edit the file through /memory. You may see a # prefix for adding memories in older tutorials; the current interactive mode reference does not list one, so use the plain-language route.

What survives /compact?

When a conversation gets long, /compact summarizes it to free space. Memory behaves differently from chat:

• The project-root CLAUDE.md survives. After compaction, Claude re-reads it from disk and adds it back.
• Subfolder CLAUDE.md files and path-scoped rules reload on demand the next time Claude touches a matching file.
• Anything you only said in chat may be lost in the summary.

If an instruction disappeared after compaction, it probably lived only in conversation. Put it in CLAUDE.md to make it stick. The context window docs have the full breakdown.

Memory, subagents and AGENTS.md

Subagents. The main conversation's auto memory is not loaded into subagents, except a fork, which inherits the parent conversation. A subagent can keep its own separate auto memory through its memory setting. The built-in Explore and Plan subagents also start without your CLAUDE.md files to keep research fast.

AGENTS.md. If your repo uses AGENTS.md for other coding agents, recent versions of Claude Code read it directly when there is no CLAUDE.md or CLAUDE.local.md in your working folder or above it. If you have both, Claude reads CLAUDE.md only by default; you can change that with the Project instructions setting in /config, or put @AGENTS.md at the top of your CLAUDE.md. Our AGENTS.md guide covers sharing one file across tools.

Best practices for Claude Code memory

• Keep each CLAUDE.md under about 200 lines. The docs say longer files use more context and reduce adherence. Claude Code skips any file over 4 MiB entirely.
• Write instructions you could check. "Run npm test before committing" beats "test your changes".
• Remove contradictions. If two files disagree, Claude may pick either. /doctor prompt-audit asks Claude to find outdated or conflicting instructions and propose edits.
• Move narrow rules into .claude/rules/ with paths. They load only when relevant.
• Review auto memory now and then. It is plain Markdown. Run /memory, open the folder, and delete anything stale or wrong.
• Use HTML comments for human notes. Block-level <!-- notes --> in CLAUDE.md are stripped before Claude sees them, so they cost no context.
• Enforce with hooks and permissions, not memory. Memory shapes behavior; it does not guarantee it.

Good memory files tend to get copied from project to project. Kipt keeps prompts and skills as Markdown in a private GitHub repo you own, so a CLAUDE.md block you reuse, or a procedure that has outgrown it and should become a skill, is one Cmd+K search away in your next repo.