Claude Code memory: how CLAUDE.md and auto memory work, and where they stop

Two mechanisms, two authors

Claude Code has two memory systems, and the difference between them is who writes them. You write CLAUDE.md files. They hold instructions: build commands, conventions, where things live, rules you would otherwise repeat in chat. Claude writes auto memory. It holds what Claude learned from working with you: your corrections, your preferences, and project context it could not work out from the code.

Both load at the start of every conversation, and both arrive as context. That second point matters more than it sounds. Anthropic's documentation is explicit that Claude treats these files as guidance it tries to follow, with no guarantee of strict compliance. If something must happen every time, such as a check before each commit, the documented answer is a hook, which runs as a shell command whatever Claude decides. Source.

Everything below was checked against those docs on 30 September 2026. Claude Code ships often, so the version numbers mentioned here will age; the shape of the system has been stable.

What CLAUDE.md loads, and in what order

A CLAUDE.md file is plain markdown. Claude Code looks for it in four scopes, and loads them from the broadest to the most specific, so the most specific instructions are the last thing Claude reads.

Within a project, Claude Code walks up the directory tree. Start it in foo/bar/ and it loads foo/CLAUDE.md, then foo/bar/CLAUDE.md, with any CLAUDE.local.md appended after the CLAUDE.md at the same level. The files are concatenated. Nothing overrides anything, which means two files that disagree leave Claude to pick one, and the docs say it may pick arbitrarily. CLAUDE.md files in subdirectories below where you started load later, on demand, when Claude reads a file in that directory.

Three more pieces round it out. A CLAUDE.md can pull in other files with @path/to/file imports, up to four hops deep; the imported files load at launch too, so imports organise a long file without making it any cheaper. Files in .claude/rules/ split instructions by topic, and a rule with a paths pattern in its frontmatter loads only when Claude touches a matching file. And since version 2.1.277, Claude Code reads a repository's AGENTS.md directly when there is no CLAUDE.md on the path, so a repo set up for Codex or Cursor works without a second file.

To see what actually loaded in a session, run /context and look under Memory files. That one command settles most "why is Claude ignoring my instructions" questions, because the usual answer is that the file never loaded.

What auto memory is, and where it lives

Auto memory is on by default. As Claude works, it saves notes of four kinds, recorded as a type field in each file's frontmatter: user for your role and working preferences, feedback for corrections you gave and approaches you confirmed, project for ongoing work and decisions the code does not show, and reference for where to find things outside the repo, such as a dashboard or an issue tracker. Claude deliberately skips what it can read from the codebase, and anything your CLAUDE.md already says.

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

The <project> name comes from the git repository, so every worktree and subdirectory of one repo shares one memory folder. At the start of each conversation Claude Code loads the first 200 lines or 25KB of MEMORY.md, whichever comes first. The topic files stay on disk until Claude decides it needs one and reads it. When the index nears its limit, Claude Code tells Claude to shorten it; when it goes over, whatever sits past the limit is dropped from the next load.

You can read and edit all of it. Run /memory to open the folder, or to switch auto memory off, which you can also do per project with "autoMemoryEnabled": false in that project's settings. Recent versions also stamp a modified timestamp into each memory file's frontmatter when Claude writes it, so you and Claude can see how old a note is.

The line in the docs worth remembering: auto memory is machine-local. Files are not shared across machines or cloud environments.

What belongs where

The docs give a good test for CLAUDE.md: write down what you would otherwise re-explain. Add a line when Claude makes the same mistake a second time, when a review catches something Claude should have known about the codebase, or when you type a correction you already typed last session. Keep it to facts that matter in every session, and write them so they can be checked.

# Build and test
- Install with `pnpm install`. Never use npm in this repo.
- Run `pnpm test` before committing. The DB tests need `docker compose up db`.

# Conventions
- API handlers live in src/api/handlers/, one file per route.
- Money is stored in integer cents. Never use floats for amounts.

# Decisions
- Background jobs go through the jobs table.
  We tried SQS in 2025 and removed it: see docs/adr/007.

Anthropic suggests keeping each CLAUDE.md under about 200 lines, because a longer file costs context on every turn and lowers how reliably Claude follows it. Claude Code skips a CLAUDE.md larger than 4 MiB entirely. When a file grows, move the parts that only matter in one area into a path-scoped rule, and move multi-step procedures into a skill, which loads only when it is needed.

A rough sorting guide:

• Project CLAUDE.md: commands, layout, conventions, and decisions every contributor must respect.
• CLAUDE.local.md or your user CLAUDE.md: your sandbox URLs, your editor habits, your preferred test data.
• .claude/rules/ with paths: rules for one part of the tree, such as the migrations folder.
• Auto memory: leave it to Claude. When you say "remember that the API tests need a local Redis", it goes here. If you want it in CLAUDE.md instead, say "add this to CLAUDE.md".

Once a month, run /doctor prompt-audit. It reads your instruction files, flags references to files that no longer exist and instructions that contradict each other, and proposes edits without changing anything until you approve them.

Where it stops

Used this way, the built-ins cover a solo developer on one project very well, and they cost nothing. They run out in five specific places, and it helps to know which one you are hitting.

Auto memory stays on one machine. Open the same repo on a second laptop, in a cloud dev environment, or in a teammate's checkout, and none of what Claude learned comes along. The committed CLAUDE.md travels; the learned notes do not.

It stays in one tool. Cursor and Codex do not read Claude Code's auto memory. AGENTS.md now gives instructions a shared home across tools, which is a real improvement, but only for what you write by hand. What one agent learned on Tuesday is invisible to a different agent on Wednesday.

Nothing marks a line as no longer true. In March you write that jobs go through the queue table. In June you remove the queue table. The CLAUDE.md line keeps loading until someone notices and deletes it, and the agent reading it has no way to tell that it is out of date. The modified timestamp on auto memory and the prompt audit both help you find stale lines. Neither retires one on its own. We wrote about this failure in detail in why markdown rot breaks agent memory.

It loads whether or not it is relevant. Every line of the project CLAUDE.md and the first 200 lines of the memory index arrive in every session, whatever the task. Path-scoped rules soften this for code areas. There is no equivalent for a decision that matters to one feature and no other.

Team sharing means pull requests. A committed CLAUDE.md is shared, which is its great strength: it is reviewed with the code it describes. It also means every lesson one person's agent learned needs someone to write it down, open a pull request, and get it merged before anyone else's agent benefits. In practice most of it never makes the trip.

The built-ins answer "what should Claude know in this repo". They do not answer "what did the last agent learn, and is it still true".

When you outgrow it

Most people never need to. If you work alone, in Claude Code, on one machine, a tidy CLAUDE.md plus auto memory is the right setup, and adding a tool on top would be complexity without payoff.

If you hit one of the limits above, the fix depends on which one. Local plugins such as claude-mem or agentmemory capture sessions automatically and can share one store between several agents on the same computer. Hosted memory services such as Mem0 or Supermemory follow you across machines, and some offer a pool a team shares. Tools that keep a reviewable project record, such as ByteRover or Stele, aim at teams who want what agents learn to be visible and correctable. We compared eleven of them, with prices and sources, in the best memory tools for AI coding agents.

Whichever you try, run one test first: change a fact, start a fresh session a day later, and ask about it. A memory that serves the old fact next to the new one without saying which is current will eventually mislead an agent at a bad moment.

Where Stele fits

This is ours, so weigh it accordingly. Stele is a shared project record that sits outside any one tool. Claude Code, Cursor, Codex and other MCP clients read it before they act and write back decisions, lessons, risks and tasks as they learn them. A fact can be superseded by a newer one, expire on a date, or retire when the task it describes closes, so the agent is not handed last quarter's rule as today's. It works alongside CLAUDE.md: keep your build commands and conventions in the file, and let the record hold what changes.

It is a hosted service, it asks agents to write facts deliberately, and it is young. The free plan covers unlimited public projects and one private project; Pro is $12 a month, with reads never metered. The getting started guide walks through setup, and pricing has the limits.

Frequently asked questions