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

Updated October 23, 2026 · 5 min read

Claude Code remembers a project through two kinds of markdown file that load at the start of every session: CLAUDE.md files that you write, and auto memory notes that Claude writes for itself under ~/.claude/projects/<project>/memory/. Run /memory to open or create either kind and to turn auto memory on or off, and /context to see which instruction files loaded.

Each session starts with a fresh context window, so anything that is not in one of those files, or in a tool Claude can call, does not carry over.

Where Claude Code looks, in load order

The locations come from Anthropic’s memory docs. They load from the broadest scope to the narrowest, and Claude Code joins them all into context. A later file does not override an earlier one, so two files that disagree leave Claude to pick.

Claude Code also walks up the directory tree. Started in foo/bar/, it loads foo/CLAUDE.md before foo/bar/CLAUDE.md, so the file nearest your working directory is read last. A rule file in .claude/rules/ with paths: frontmatter loads only when Claude opens a matching file.

The CLAUDE.md guide covers what to put in these files, and CLAUDE.md examples from 270 top GitHub repos shows what popular projects put in theirs.

Imports, AGENTS.md and size limits

A CLAUDE.md can pull in other files with @path/to/file, up to four hops deep. Imported files load together with the file that imports them, which helps organize a long file without making it any smaller in context. The first time a project imports a file from outside its own directory, Claude Code asks you to approve it.

From v2.1.277, Claude Code reads AGENTS.md when there is no CLAUDE.md or CLAUDE.local.md in your working directory or above it. When there is one, it reads only the CLAUDE.md files unless you set Project instructions to claude-md-and-agents-md in /config. So a personal CLAUDE.local.md added to a repo that relies on AGENTS.md stops Claude from reading AGENTS.md for you. The AGENTS.md guide has the rest.

The limits:

• A CLAUDE.md that loads at launch arrives whole, up to 4 MiB; a larger file does not load at all. Anthropic’s target is under 200 lines.
• MEMORY.md is cut at 200 lines or 25KB, whichever comes first. The topic files beside it load only when Claude chooses to read them.
• In a session with a 200K context window, a subdirectory CLAUDE.md or a path-scoped rule is cut at 40,000 characters.
• After /compact, Claude re-reads the project-root CLAUDE.md from disk. An instruction you gave only in chat is gone.

Claude treats all of this as context rather than enforced configuration. For a rule that must hold every time, such as a check before each commit, the docs point to hooks. Our context engineering guide covers how to keep the context lean.

What auto memory saves

Claude records four kinds of note, each marked in the file’s type field: user, feedback, project and reference. It skips what it can work out from the code and what your CLAUDE.md already says, and it does not save something in every session. Ask Claude to remember something and the note goes to auto memory; ask it to add the note to CLAUDE.md if your team should get it too.

The memory folder is keyed to the git repository, so every worktree of one repo shares it. Outside a git repository the key is the directory you started in. The notes stay on the machine that wrote them.

What we found on our own machine

We run five AI agents on one Mac, and they start Claude Code sessions all day. On 2026-10-23 we counted what was in ~/.claude there:

• 191 project folders under ~/.claude/projects/, holding 2,694 session transcripts, 2,357 of them since October 1.
• 144 auto memory folders, and not one file in any of them. All 144 belong to temporary directories under /private/var/folders and /private/tmp.
• 38 project folders made by our task board, one per task. Each task runs in a new directory that is not a git repository, so each gets its own memory folder, and a note saved during one task would never load in the next.
• No ~/.claude/CLAUDE.md, and a ~/.claude/settings.json that sets only the theme.

Of the 18 git repositories in our code folder, two have instruction files:

• expresso-www has a 22-line, 874-byte AGENTS.md and a CLAUDE.md that is a symlink to it. The symlink works on every Claude Code version. When Claude edits the instructions, it writes to AGENTS.md, because its Edit tool will not write through a link.
• vantasoft-hermes-agent, our fork of the agent framework the fleet runs on, has only an AGENTS.md, at 1,562 lines and 82,028 bytes, nearly eight times Anthropic’s 200-line target. The Claude Code installed on this Mac is v2.1.274, older than v2.1.277, so in that repo Claude reads none of it. A CLAUDE.md holding @AGENTS.md would fix that on any version and would load all 82 KB into every session.

The rules all five agents share live in one fleet file outside Claude Code, at 148 lines and 28,267 bytes. That is under the 200-line target and over the 25KB that Claude Code reads from a MEMORY.md, because its lines average 191 bytes.

Memory that other agents and teammates can read

Auto memory stays on one machine under one directory, and a repo’s CLAUDE.md reaches only sessions started in that repo. The facts our agents need in every task and every repo go in a shared wiki instead: Dexio, a wiki of linked pages that Claude Code, our other agents and our team read and write over MCP, from any machine. Each agent names itself on every change, so a page’s history shows which one wrote what.

That is one kind of agent memory; other MCP memory servers store short facts or session logs instead. To connect Claude Code, follow Connect your agent in the docs. The Claude Code MCP guide covers server scopes, including a project .mcp.json your team shares through git.

Sources

• https://code.claude.com/docs/en/memory
• https://code.claude.com/docs/en/mcp