Does Claude Code remember between sessions? How memory works

Only what you or Claude wrote down. Every Claude Code session starts with a fresh context window, and two things carry over into it: the CLAUDE.md files you write, and auto memory, the notes Claude keeps in ~/.claude/projects/<project>/memory/. Your past conversations stay on disk, but a new session sees one only if you resume it.

Most "Claude forgot" moments come from expecting more than that. Everything below is from Anthropic's Claude Code docs as we read them on 22 October 2026.

What Claude Code remembers between sessions#

From Anthropic's memory page: "Each Claude Code session begins with a fresh context window. Two mechanisms carry knowledge across sessions."

Nothing else carries over by default. Say you told Claude yesterday to run pnpm test instead of npm test: a new session doesn't know that unless the line reached a CLAUDE.md or MEMORY.md. The same goes for a decision you made together, or a file Claude read.

claude --continue reopens the most recent conversation in this folder with its full history, and claude --resume lets you choose one from a list (resuming a Claude Code session has both). That isn't memory. It is the same conversation, opened again.

CLAUDE.md: the memory you write#

CLAUDE.md files are plain Markdown that Claude reads at the start of every session. They can live in four places, loaded from the broadest to the most specific:

Four rules in the docs explain most surprises:

• Files add up; they don't override. Claude Code loads the CLAUDE.md in your working folder and in every folder above it, and concatenates them. The one closest to where you started is read last.
• A CLAUDE.md in a subfolder loads only once Claude reads or edits a file in that folder.
• Since v2.1.277, Claude Code reads a repository's AGENTS.md when there is no CLAUDE.md or CLAUDE.local.md in your folder or above it. With both present, it reads only the CLAUDE.md files unless you change the Project instructions setting in /config.
• CLAUDE.md is context, not a rule engine. It is delivered as a message after the system prompt, and Anthropic says "there's no guarantee of strict compliance". For something that must happen every time, use a hook.

Auto memory: the notes Claude keeps#

Auto memory is on by default in local sessions. As Claude works, it saves four kinds of notes: who you are and how you like to work (user), corrections you gave it (feedback), ongoing work and decisions it can't read from the code (project), and where to find things outside the repo (reference). It skips anything it can work out from the code, and anything your CLAUDE.md already says.

The notes live in ~/.claude/projects/<project>/memory/: one MEMORY.md index, one line per memory, plus a topic file per memory. Only the start of MEMORY.md loads at startup; Claude opens the topic files when it needs them. "Saved 2 memories" or "Recalled 2 memories" in the session means that folder is being written or read.

Every worktree and subfolder of one git repository shares a single memory folder. The folder doesn't leave the computer either: "Auto memory is machine-local," so your laptop and your server each keep their own. Subagents don't get the main conversation's auto memory, except a fork.

To turn it off, use the toggle in /memory, set "autoMemoryEnabled": false in a project's settings, or set CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.

How to add to Claude Code's memory#

1. For a note about you, say it in plain words: "remember that the API tests need a local Redis". Claude saves it to auto memory.
2. For a rule the whole team should follow, say "add this to CLAUDE.md", or open the file yourself with /memory.
3. In a project without a CLAUDE.md, run /init. Claude reads the codebase and writes a starter file with build commands, test instructions and conventions. If one exists, it suggests improvements instead.
4. For private notes on one project, create CLAUDE.local.md at the project root and add it to .gitignore.
5. To check what loaded, run /context and look under Memory files.

The current docs describe asking in plain words. They don't mention the old # shortcut, so don't rely on it.

Anthropic's docs name four moments to write something down:

• Claude makes the same mistake a second time.
• A review catches something Claude should have known.
• You type the same correction you typed last session.
• A new teammate would need the same context.

How to keep it short#

CLAUDE.md and the first lines of MEMORY.md ride along on every request, which is why they appear in why Claude Code uses so many tokens. Short files are followed better. What belongs in the file at all is the subject of CLAUDE.md best practices.

• Aim for under 200 lines per CLAUDE.md. Anthropic's words: "Longer files consume more context and reduce adherence." Claude Code warns at startup when a file is over the recommended length.
• Ask of every line: "Would removing this cause Claude to make mistakes?" If not, cut it.
• @path/to/file imports organise a file but pull the other file in at launch, so the import costs the same.
• Put what only matters in one part of the repo in .claude/rules/ with a paths: list. It loads only when Claude touches a matching file.
• Move procedures such as a release checklist or a review routine into skills, which load only when used.
• Block-level HTML comments (<!-- like this -->) are stripped before Claude sees the file, so notes for humans can stay.
• /doctor proposes cuts for things Claude can read from the code, and /doctor prompt-audit (v2.1.283 or later) looks for stale and conflicting instructions.

Auto memory trims itself: when MEMORY.md nears its 200-line or 25KB limit, Claude Code reminds Claude to shorten the index and move detail into topic files.

Why did Claude forget something?#

Usually one of these:

• It was only said in chat. After /compact, the conversation becomes a summary. The project-root CLAUDE.md and auto memory are re-read from disk; anything you only typed may not survive.
• It sits in a subfolder file that hasn't loaded yet. Nested CLAUDE.md files and path-scoped rules load when Claude touches a matching file, and after compaction only when it touches one again.
• The file didn't load. Check /context under Memory files. A CLAUDE.md in the folder or above it beats your AGENTS.md, for example.
• Two instructions disagree. The docs warn that Claude "may pick one arbitrarily"; /doctor prompt-audit finds them.
• You're on another computer, and auto memory doesn't travel.

If you run Claude Code in Shuriken#

Shuriken doesn't add a memory of its own. Each chat is a Claude Code session in your project, so everything above works the same.

Each Claude account you add runs Claude Code with its own config folder. Shuriken links your ~/.claude/CLAUDE.md, your ~/.claude/projects folder (where auto memory lives), your settings, skills, agents and commands into every one, so a chat that moves to another of your accounts finds the same notes (keeping the same chat across Claude accounts).

Every chat also gets its own git worktree. Auto memory is shared across worktrees, but a gitignored CLAUDE.local.md only exists in the checkout where you made it. List it in the project's .worktreeinclude, with anything else you need such as .env, and Shuriken copies it into each new worktree.

A project's settings have a Knowledge section with its instruction files, Claude's memory for the project and its skills. It warns when an always-loaded file passes 1,000 lines.

One limit stays: auto memory is per computer, and Shuriken doesn't copy it between your machines. A chat you run on another computer works with that computer's notes, so anything every machine needs belongs in CLAUDE.md.