Claude Memory: Memory, CLAUDE.md, and Auto Memory

What is Claude memory, and why does it have three layers?#

You open Claude.ai on Tuesday and tell it about your audience, response format, and writing style. On Thursday, you return in a new chat — and Claude already remembers. That’s Memory at work.

You open Claude Code in the terminal, spend two weeks figuring out a project, and explain the folder structure, deployment rules, and favorite libraries. You close the session, open it again an hour later — and the agent starts from scratch again. Memory doesn’t work here. To make things different, you need CLAUDE.md.

A third layer arrived in 2026. Auto Memory in Claude Code means the agent writes notes about your project itself: which commands work, which tests pass, which paths in the repository are sensitive. These notes live locally on your disk and are automatically loaded in the next session.

The main confusion: people hear that “Claude remembers now” and think it works everywhere automatically. It doesn’t. Memory from claude.ai doesn’t carry over to Claude Code — the official Claude Code documentation describes two memory mechanisms, and Chat Memory isn’t one of them. CLAUDE.md and Auto Memory work in Claude Code — entirely different systems. The same goes for the Anthropic API: it has a separate Memory tool unrelated to chat memory.

This guide covers all three so you know what to put where and why Claude suddenly “forgets” a project even though you “set up memory.”

What is Memory in Claude.ai, and who gets it for free in 2026?#

How Memory collects information

Anthropic calls this Memory Synthesis. About once a day, Claude processes your recent conversations, identifies what will be useful long-term, and writes short summary blocks to your Memory profile. These aren’t verbatim quotes from your messages — they’re condensed statements such as “the user is a marketer, runs an online project, and prefers short answers without filler.”

In your next conversation, these summaries are automatically added to the beginning of the context. Claude knows who you are, what you do, and what response style you like — without your having to repeat it in every chat.

Which plans support Memory

Anthropic rolled out Memory in stages: September 11, 2025 — Team and Enterprise; October 23, 2025 — Pro and Max; March 2, 2026 — free for all plans, plus the Import tool from ChatGPT, Gemini, and Grok.

This matters: Memory works where there’s a Claude.ai web interface or mobile app. Wherever you use Claude through your own code or the CLI, Memory is absent.

Where to view and edit it

In claude.ai: Settings → Capabilities → Memory. Direct URL: claude.ai/settings/capabilities?modal=memory. A list of everything Claude has saved about you will open. Three buttons:

• Pause — Claude will keep the memory it has accumulated, but stop using it and adding to it.
• Reset memory — erases everything.

  Once you select this option and click 'Reset memory,' this cannot be undone.

• Edit individual entries — you can manually delete individual entries.

Inline controls work right in the chat: tell Claude “remember X” or “forget Y” — and Memory will be updated without going to Settings.

One more important thing: Projects in Claude.ai have separate memory.

That means conversations inside a Project don’t leak into general Memory, and vice versa.

You can ask Claude directly

In any chat, write: “What do you remember about me?” Claude will list what it remembers for this conversation. This is the quickest way to check what made it into your Memory profile.

Privacy

Anthropic explicitly says your memory is private to your account and isn’t shared with other users. By default, Anthropic may use your conversations (including those that make it into Memory) to improve its models. You can turn this off in Privacy settings — under Data Controls.

What is CLAUDE.md in Claude Code, and how does it differ from Memory?#

Memory collects information about you as a person — your style, preferences, and profession. CLAUDE.md is about a specific project: this repository, these commands, these code-work rules. The difference is fundamental: Memory puts together “who I am in general,” while CLAUDE.md says “how this work is organized.”

Where Claude Code looks for CLAUDE.md

In four places at once, in order of priority from lowest to highest:

All four files load at the same time and are concatenated; they don’t override one another.

The order runs from broad scope to narrow. Project and Local come last — so they end up at the end of the context, closer to the request. That’s why you should keep everything critical in the project’s CLAUDE.md.

What people usually put in it

• Project stack — Next.js / Prisma / PostgreSQL / Redis
• Commands — how to run tests, build, and deploy
• Sensitive paths — which folders not to touch without an explicit request
• Conventions — commit style, file naming format
• Business rules — what matters to the project (for example, never hardcode prices)
• Context pointers — “for business logic, see docs/business/; for the design system, see docs/design/” (the folder names are up to you; the main thing is not to cram everything into one file)

For a complete breakdown, see the guide to CLAUDE.md with a ready-to-use template.

How CLAUDE.md DIFFERS from Memory

In one sentence: Memory is your head; CLAUDE.md is the project instructions posted on the office wall.

What is Auto Memory in Claude Code, and where is it stored?#

How Auto Memory differs from CLAUDE.md

CLAUDE.md contains your instructions. Auto Memory contains notes the agent writes to itself. They’re different kinds of content.

You write CLAUDE.md by hand: “always reply in the user’s preferred language,” “publish with npm run deploy,” “don’t touch the legacy/ folder.” These are rules you set in advance.

Auto Memory is what Claude learns as it goes. It runs a test, which fails because a package is missing — Claude writes down, “in this project, run npm install before the tests.” It won’t repeat the same mistake in the next session.

Where it’s stored

Locally on your disk, in a separate folder for each project:

~/.claude/projects/[project-name]/memory/

The main file inside is MEMORY.md. An important detail: Claude Code loads CLAUDE.md in full, but MEMORY.md has a limit — only the first 200 lines or 25KB are loaded, whichever comes first. This keeps Claude from drowning in its own notes accumulated over months of work. The notes persist in a local directory outside the project repository. The loaded text becomes part of the conversation context sent to your configured model service; local persistence is not a promise of offline processing. Do not put secrets in these files.

When it works

Auto Memory works in Claude Code starting with version v2.1.59+ and is enabled by default in fresh installations. To check its status and manage it, use the command:

/memory

This command opens an editor for all memory layers — both CLAUDE.md and MEMORY.md. You can see what Claude has already recorded about your project, edit it, or clear it. To disable Auto Memory completely, set autoMemoryEnabled: false in ~/.claude/settings.json or use the environment variable CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.

What usually goes in it

• Commands that worked or failed
• Project structure the agent figured out
• Antipatterns it encountered
• Names of key files and functions

The official Claude Code documentation from Anthropic describes the difference directly:

In other words: CLAUDE.md = instructions you write. Auto Memory = notes Claude writes to itself, based on your corrections and preferences.

Memory or CLAUDE.md: which system handles which task?#

Decision matrix

Memory and CLAUDE.md don’t duplicate each other. They work in different products and store different things. They’re like a personal calendar and a company policy — both are useful, but no one confuses them.

When to enable Memory: 3 scenarios where it really helps#

Scenario 1. You use claude.ai as a personal assistant

You write to Claude every day: rewrite an email, analyze a spreadsheet, come up with an idea. The topics vary, but you’re the same person. Memory saves you from saying, “Hi, I’m a marketer, I run an online project, and this is the response style I like.”

After a week of use, Claude knows your profession, response format, favorite formats, length, and tone. Every new chat starts with that. You save 30–60 seconds per conversation.

Scenario 2. You write a lot of content in the same style

Ads, social media posts, email newsletters — the same brand voice. Memory will learn your style: which words not to use, what tone to use, and how long paragraphs should be.

Once, over the course of a couple of weeks, tell Claude: “in our writing, no em dashes, a friendly tone, no more than 3 paragraphs.” It’ll be recorded. Then each new piece will already be in your style without reminders.

Scenario 3. You need role context

You’re a designer with a specific stack — Figma + Sketch, not Photoshop. You’re a SaaS product manager, not an e-commerce one.

Memory will pick up this role context and automatically tailor responses to it. Fewer generic answers, more that fit your specific work.

When Memory isn’t needed

If you mainly work with Claude Code in the terminal, Memory gives you nothing. It simply doesn’t work there. Use CLAUDE.md instead, and don’t confuse the two.

If you use Claude through the API in your code, it doesn’t work there either. Add instructions manually to the system prompt.

If you have one kind of task and don’t mind repeating the context at the start of every chat, Memory isn’t critical. It’s a convenience, not a requirement.

What should go in CLAUDE.md, and what will Auto Memory pick up by itself?#

What must go in CLAUDE.md

1. Project description in one paragraph — what it is, who it’s for, and why.
2. Project technologies — which frameworks, libraries, and databases.
3. Commands — tests, build, publishing. The exact commands.
4. Sensitive directories — what not to touch without an explicit request.
5. Conventions — commit style, file naming format, response language.
6. Context pointers — for example, “business logic is in docs/business/; design is in docs/design/.” Folder names are up to you.

What to leave to Auto Memory

1. Local environment details — on this machine, Python is at /usr/local/bin/python3.11.
2. Project changes — which command failed yesterday and why.
3. Interim discoveries — where the tests for a particular module are located.
4. Workflow tips — which script to run after which step.

What must be in neither

• API keys, passwords, tokens — they belong in .env, not memory files.
• Clients’ personal data.
• Information that may soon become outdated (prices, cohort dates, temporary campaigns).
• Prompts for one-off tasks — they clutter the context.

The 200-line rule

Anthropic recommends keeping CLAUDE.md around 100–200 lines in its documentation. After 200 lines, Claude starts reading it less effectively — long context consumes resources and lowers accuracy. When the file grows, move sections into separate .md files nearby, and leave short pointers in CLAUDE.md: “for code style, see docs/code-style.md.”

For a detailed breakdown of the file’s structure, see the guide to a second brain for Claude Code, which explains how the structure grows from CLAUDE.md to five folders of context.

What are the 5 mistakes that break Claude memory, and how can you avoid them?#

Mistake 1. Confusing Memory with CLAUDE.md

The most common mistake. Someone hears that “Claude remembers now,” enables Memory in claude.ai, then opens Claude Code in the terminal and wonders why the agent has “forgotten” again.

Memory in claude.ai doesn’t carry over to Claude Code. They’re different products with different architectures. If you want Claude to remember a project in the terminal, write CLAUDE.md. If you want Claude to remember you in the browser, enable Memory.

How to avoid it. Before setting up memory, decide where you mainly work. If it’s claude.ai, use Memory. If it’s Claude Code, use CLAUDE.md and Auto Memory. If it’s both, configure both systems instead of trying to combine them.

Mistake 2. Forgetting that filenames are case-sensitive

CLAUDE.md is a case-sensitive filename. The uppercase CLAUDE.md will be read by the agent. claude.md and Claude.md won’t. The same goes for CLAUDE.local.md. This is a typical failure for people setting up Claude Code for the first time: they create a file, write instructions, wonder why it doesn’t work — but the filename is lowercase.

How to avoid it. Check the case before saving. On a Mac, select the file in Finder and press Enter — the full name will be visible. In the terminal: ls -la CLAUDE*. If it shows claude.md, rename it: mv claude.md CLAUDE.md.

Mistake 3. CLAUDE.md has grown to 800 lines

You get a ready-made template, add all the rules that seem important, and end up with an 800-line file. Claude now takes longer to read it, but the quality of responses drops. Long context consumes the model’s attention.

How to avoid it. Keep CLAUDE.md around 100–200 lines. After 200, move sections into separate .md files and leave pointers in CLAUDE.md: “for code style, see docs/code-style.md.” It’s the same principle as any human documentation — don’t cram everything into one file.

Mistake 4. Keeping secrets in CLAUDE.md or Auto Memory

API keys, passwords, and tokens must not be in memory files. CLAUDE.md is usually committed to git, so secrets will leak into the repository. Auto Memory is stored locally, but could appear in a screenshot, a shared conversation, or a leak through an MCP server with disk access.

How to avoid it. Keep secrets in .env (with .env in .gitignore). Mention only variable names in CLAUDE.md: “API key in STRIPE_KEY; get it from .env.”

Mistake 5. Expecting Auto Memory to figure out your business logic on its own

Auto Memory collects technical observations — commands, errors, structure. It won’t learn business rules on its own (“for a real estate agency, don’t take orders below a certain threshold,” “don’t use certain vocabulary in the writing”). Those belong in CLAUDE.md or in separate .md files referenced by CLAUDE.md.

How to avoid it. Separate them: technical details go into Auto Memory automatically. Business rules, style, and conventions go into CLAUDE.md by hand. Don’t expect one to replace the other.

How do you set up Memory + CLAUDE.md in an evening (step-by-step guide)?#

1. Enable Memory in Claude.ai. Open Settings → Capabilities → Memory. Turn on the toggle. Check Privacy settings right away — decide whether to allow Anthropic to use your conversations to train models. It’s your choice.

2. Talk to Claude as yourself. In your next 2–3 chats, tell it who you are, what you do, and what response style you like. Memory Synthesis will record this within a day.

3. Check what was recorded the next day. In any chat, write: “What do you remember about me?” Claude will list its memories. If you don’t like something, delete it through Settings → Memory or ask Claude to forget it.

4. Create CLAUDE.md in your project. In the root of your main project, create a file named CLAUDE.md (uppercase letters). Get the ready-made template from the guide to CLAUDE.md — it has 6 sections, and the recommended length is around 200 lines, per Anthropic.

5. Fill in the sections for your project. Describe the stack, commands, sensitive paths, and conventions. No more than 200 lines — after that, Claude reads it less effectively.

6. Check Auto Memory. In Claude Code, enter the command /memory. An editor for all layers will open. Auto Memory is one of them. Read what Claude already knows about your project.

7. Commit CLAUDE.md to git. It’s part of the project. If you work on a team, everyone will see the rules.

8. Continue working as usual. After each agent mistake, add one line to CLAUDE.md saying “don’t do that.” After a month, you’ll have a living set of rules, and Claude will stop falling into familiar traps.

What doesn’t work: 3 patterns Claude memory doesn’t retain#

Session state isn’t retained when switching models

You work in Claude Code on Opus 4.8, then switch to Sonnet 4.6 — the session context may reset because the models have different context windows. CLAUDE.md and Auto Memory will load automatically in the new session, but the active discussion won’t.

Files you haven’t shown aren’t loaded

Claude sees only what’s in CLAUDE.md, what’s in Auto Memory, and what you explicitly opened in the current session. If your project has 500 files and you write, “look at how I handle payments,” the agent doesn’t know which file to inspect. You need to provide the path explicitly or add a pointer in CLAUDE.md.

Memory doesn’t work for one-off conversations through the API

Each request to the Claude API is isolated. No memory is loaded. If you build a chatbot through the API, you pass the system prompt and message history manually. Memory, CLAUDE.md, and Auto Memory don’t help with this.

What’s next: memory as an entry point to a Second Brain#

CLAUDE.md and Auto Memory give Claude memory of how the code is organized. That’s enough for technical tasks: refactoring, bugs, migrations, tests.

But as soon as you need to make business decisions — whom to email, how to phrase an offer, what price to set — technical memory isn’t enough. You need context: who your customers are, how they make decisions, and how your business economics work.

That’s the Second Brain — a folder of business knowledge alongside the project, which Claude accesses through pointers in CLAUDE.md. Memory of code plus memory of the business — and the agent stops being “a smart assistant that hallucinates” and becomes your co-author.