CLAUDE.md vs memory in Claude Code: two systems
CLAUDE.md vs memory is a difference of authorship: CLAUDE.md holds instructions you write, auto memory holds notes Claude writes itself, and Claude Code loads both at the start of every session. Each session begins with a fresh context window, and these are the two mechanisms Anthropic lists for carrying knowledge across sessions Anthropic docs.
This page sets the two side by side using Anthropic's documentation, then covers what some Claude Code users in forum posts did when the built-in memory fell short.
Are CLAUDE.md and memory the same?
Anthropic's docs describe two mechanisms that carry knowledge across sessions: CLAUDE.md files, which are instructions you write, and auto memory, which is notes Claude writes itself based on your corrections and preferences Anthropic docs. The docs call these "two complementary memory systems", so CLAUDE.md counts as one kind of Claude Code memory and auto memory is the other Anthropic docs.
| CLAUDE.md files | Auto memory | |
|---|---|---|
| Who writes it | You Anthropic docs | Claude Anthropic docs |
| What it contains | Instructions and rules Anthropic docs | Learnings and patterns Anthropic docs |
| Scope | Project, user, or org Anthropic docs | Per repository, shared across worktrees Anthropic docs |
| Loaded into | Every session Anthropic docs | Every session (first 200 lines or 25KB) Anthropic docs |
| Use for | Coding standards, workflows, project architecture Anthropic docs | Your preferences, corrections you give Claude, and project context Claude can't derive from the code Anthropic docs |
Anthropic's guidance is to use CLAUDE.md files when you want to guide Claude's behavior, and to let auto memory pick up your corrections without manual effort. Subagents can also maintain their own auto memory Anthropic docs. For a wider view of what survives between sessions, see Claude Code memory: what carries over between sessions.
When does each one load?
Both systems are loaded at the start of every conversation Anthropic docs. CLAUDE.md and CLAUDE.local.md files in the directory hierarchy above the working directory are loaded at launch, and files in subdirectories load on demand Anthropic docs. For auto memory, the docs give a limit of the first 200 lines or 25KB Anthropic docs.
Anthropic says Claude treats both as context, "not enforced configuration", and that the more specific and concise the instructions are, the more consistently Claude follows them Anthropic docs. To block an action regardless of what Claude decides, the docs point to a PreToolUse hook Anthropic docs.
On length, the docs target under 200 lines per CLAUDE.md file, because longer files consume more context and reduce adherence. Imports help organize a long file but do not reduce its context cost, since imported files also load at launch Anthropic docs. Instructions that matter for only part of the codebase can move into path-scoped rules, which load only when Claude works with matching files Anthropic docs.
Where do CLAUDE.md files live?
The docs list CLAUDE.md locations from broadest scope to most specific, so a project instruction appears in context after a user instruction Anthropic docs.
- Managed policy: organization-wide instructions managed by IT or DevOps, at
/Library/Application Support/ClaudeCode/CLAUDE.mdon macOS,/etc/claude-code/CLAUDE.mdon Linux and WSL, andC:\Program Files\ClaudeCode\CLAUDE.mdon Windows Anthropic docs. - User instructions at
~/.claude/CLAUDE.mdhold personal preferences for all projects and are visible only to you Anthropic docs. - Project instructions at
./CLAUDE.mdor./.claude/CLAUDE.mdare shared with the team through source control Anthropic docs. - Local instructions at
./CLAUDE.local.mdhold personal project-specific preferences, and the docs say to add the file to .gitignore Anthropic docs.
If a repository uses AGENTS.md, Claude Code can read it in place of CLAUDE.md Anthropic docs. The two filenames are compared in CLAUDE.md vs AGENTS.md: the difference. The excerpt of the docs read for this page stops before the storage location section, so where auto memory files sit on disk is not covered here.
What do people do about it?
Anthropic's page describes what the two systems are meant to do. Forum posts show what some users did when the built-in memory fell short. Reading the last 30 days in the Arctic Shift archive, we counted 4 of 11 distinct people across 5 threads adding a third-party memory plugin on top of Claude Code, with the reason given that its own memory forgets corrections or goes stale. The count covers 11 people in 10 threads and describes those posters only.
Two of the posts open like this.
"I built an open-source plugin that keeps Claude Code's memory from going stale" Reddit, r/ClaudeAI
"Code graphs didn't change the answers, memory did" Reddit, r/ClaudeAI
A third post, titled as a memory plugin for Claude Code, reports "10/10 vs 8.3/10" on "continue yesterday's work" at "+10% tokens" Reddit, r/ClaudeAI. The first post cites 550 runs and 60 blind judges, and the second cites 1,500 graded runs. These are the posters' own figures, and they were not reproduced here. The archive text for each of the three ends in "[removed]", so only the opening lines were available.
Other threads ask the question directly. One title, "Does anyone here actually use Claude Code's auto memory?", appears in two threads Reddit, r/ClaudeCode Reddit, r/ClaudeCode (second thread). Another is titled "Problem with the memory.md file? hooks?" Reddit, r/ClaudeCode. A third reports "six months of Claude Code auto memory" on one project, with 65 files Reddit, r/ClaudeCode. A fourth pairs a "CLAUDE.md protocol" with a MEMORY.md file and reports going from 12 clarifying questions to 0 on one task, which is the poster's claim Reddit, r/ClaudeAI. Only the titles of these four were read.
The route Anthropic describes is to write the repeated correction into CLAUDE.md. Its list of reasons to add an entry includes Claude making the same mistake a second time, and typing the same correction into chat that you typed last session Anthropic docs. The guide How to write a CLAUDE.md or AGENTS.md, with a template covers the writing itself.
How do you check what loaded?
To confirm a CLAUDE.md file loaded, the docs say to run /context in a session and check the list under Memory files Anthropic docs. Running /init generates a starting CLAUDE.md from your codebase, and if one already exists, /init suggests improvements rather than overwriting it Anthropic docs.
The docs page also has a section on viewing and editing memory with /memory, and troubleshooting entries titled "Claude isn't following my CLAUDE.md", "I don't know what auto memory saved" and "Instructions seem lost after /compact" Anthropic docs. The excerpt read for this page ends before those sections, so what they say is not reproduced here. The compaction case has its own guide, Why Claude Code forgets the plan after compaction.
Common questions
Does Claude Code load both at the start of every session?
Yes. Anthropic's docs say both memory systems are loaded at the start of every conversation, and that auto memory loads the first 200 lines or 25KB Anthropic docs.
Can CLAUDE.md force Claude to follow a rule?
The docs say Claude treats CLAUDE.md and auto memory as context, not enforced configuration. To block an action regardless of what Claude decides, they point to a PreToolUse hook Anthropic docs.
Who writes auto memory?
Claude does, based on your corrections and preferences. The notes are kept per repository and shared across worktrees Anthropic docs.
How long should a CLAUDE.md file be?
Anthropic's target is under 200 lines per file, since longer files consume more context and reduce adherence Anthropic docs.
How we checked
Anthropic's page "How Claude remembers your project" was read on 7 October 2026. The copy read cuts off partway through the section on writing effective instructions, so later sections such as storage location and troubleshooting are known here by their headings only.
The forum count covers 11 people in 10 threads from the last 30 days in the Arctic Shift archive. The 4 of 11 people across 5 threads are those whose posts matched one theme, adding third-party memory plugins on top of Claude Code. Thread titles and opening lines were read, and no plugin figures were reproduced.
Last verified 7 October 2026. Checked against Anthropic's Claude Code memory page on 7 October 2026, with the forum count drawn from the last 30 days of the Arctic Shift archive.
Sources
- Anthropic, how Claude remembers your project checked 7 October 2026
From the publisher
Mover (our product)
Since Claude Code treats both files as context it may not follow, Mover is a $49 one-time planning tool that runs inside Claude Code or Codex, keeps your plan in plain files on your own computer, loads it into each session, and says so when your work drifts from it.
Mover is a $49 one-time planning tool that runs inside Claude Code or Codex, keeps your plan in plain files on your own computer, and says so when your work drifts from it. It is the wrong choice if you want something that keeps running while your computer is off.
One payment. 30-day money-back guarantee.