CLAUDE.md vs auto memory
Two halves of the same system — one you write and commit, one Claude writes and keeps to itself.
Last verified August 21, 2026
The short answer
CLAUDE.md is for what the team needs Claude to know: standards, intent, commands, conventions. Auto memory is for what Claude works out along the way. If it matters beyond your machine, it belongs in CLAUDE.md and in version control.
Can you use both? They are designed to work together and are documented on the same page.
Side by side
Option A
CLAUDE.md
A markdown file in your project root, read at the start of every session. Written by you, committed to the repository, shared with everyone who clones it.
Pick it when
The information is intentional — a standard, a decision, a checklist, how to run the build. Anything a new team member would also need.
Option B
Auto memory
Learnings Claude saves across sessions on its own — build commands, debugging insights, project quirks — without you writing anything.
Pick it when
You do not choose this one. It accumulates. The decision is whether to promote something from it into CLAUDE.md.
Side by side
CLAUDE.md |
Auto memory | |
|---|---|---|
| Author | You | Claude |
| Location | Your repository | Claude Code’s storage |
| Version controlled | Yes | No |
| Shared with the team | Yes | No |
| Reviewable in a PR | Yes | No |
| Content | Standards, intent, commands | Discovered facts |
| Read | Every session | Every session |
The rows that matter are shared and reviewable. Auto memory is convenience; CLAUDE.md is
infrastructure.
The promotion habit
The useful workflow is treating auto memory as a staging area. Claude works out that the test suite needs a service running first, and remembers it. That is fine for you.
The moment a second person hits the same wall, it should have been in CLAUDE.md — where it is
reviewed, versioned, and available to everyone.
Periodically asking “what has Claude learned that the team should know?” and moving it into the file is a small habit with a large return.
Keep CLAUDE.md short
It is read on every request. That has two costs: tokens, and attention. A file that has grown into a project encyclopedia makes every session more expensive and dilutes the instructions that actually matter.
The rule that works: CLAUDE.md holds what is true always. Anything true only for a particular
kind of task belongs in a Skill, which loads on demand and costs nothing when
it does not apply.
The four-mechanism map
| Question | Mechanism |
|---|---|
| What should Claude always know? | CLAUDE.md |
| What has Claude worked out? | Auto memory |
| How should Claude do this specific thing? | Skill |
| What must happen regardless? | Hook |
Most configuration confusion in Claude Code is one of these four being used to solve another’s problem.
Common misconceptions
- "Auto memory means I do not need CLAUDE.md." Auto memory is not shared and not version-controlled. Your colleagues get none of it.
- "Longer CLAUDE.md is better." It is read on every request. Past a point it costs context on every turn and gets followed less reliably. Procedures belong in a Skill.
- "Memory is the same as Projects." Projects are a Claude apps feature. This is Claude Code.
Sources
- 01How Claude remembers your project — Claude Code docsOfficialcode.claude.com