What Claude Code remembers between sessions, and where it keeps it

Three things that carry over

Each row follows Anthropic's documentation. Vendor docs Auto memory is on by default, and it lives outside your repository, in ~/.claude/projects/<project>/memory/. All worktrees and subfolders of one git repository share the same folder. Vendor docs

Ask Claude to remember something

We made an empty git repository with a two-line CLAUDE.md and sent one prompt:

claude -p "Remember for future sessions in this project: sample customer records should use the city Alder Bay."

Claude answered "Saved. In future sessions on this project, sample customer records will use the city Alder Bay." Before the prompt the memory folder didn't exist. Afterwards it held two files. Observed

- [Sample customer city](sample-customer-city.md) — sample customer records use the city Alder Bay

---
name: sample-customer-city
description: Sample customer records in this project should use the city Alder Bay
metadata:
  node_type: memory
  type: project
  originSessionId: …
  modified: 2026-09-25T18:46:43.633Z
---

Sample/fixture customer records should use the city "Alder Bay".

**Why:** User asked for this to be remembered for future sessions in this project.
**How to apply:** When generating sample or seed customer data, set the city to Alder Bay.

We shortened the session ID; everything else is as Claude wrote it. The index gets one line per note, and the note itself carries a name, a one-line description and a timestamp. Claude Code adds the modified field whenever Claude writes a note that has frontmatter. Vendor docs

The folder name is the project's absolute path with every character other than a letter or digit replaced by a hyphen. A repository at /Users/you/code/shop keeps its notes in ~/.claude/projects/-Users-you-code-shop/memory/. Observed

A new session reads it back

We started a fresh session in the same folder and didn't mention the city:

claude -p "Write one sample customer record as JSON with name, email and city. Then tell me in one line where you got the city from."

The record had "city": "Alder Bay", and Claude said the city came from the saved memory note. It answered in a single turn without opening any file, so the line in MEMORY.md was enough on its own. Observed So when you edit the index, keep the fact itself in the line. In this run the line was all the new session used.

Change your mind

claude -p "We're switching: sample customer records should use the city Cedar Point from now on."

Claude edited the existing note instead of adding a second one. The folder still held two files, the index line now said Cedar Point, and the note read should use the city "Cedar Point" (previously "Alder Bay"). Observed If you find two notes that disagree, delete the stale one and its index line yourself. The files are plain Markdown. Vendor docs

Review, move or turn it off

• /memory lists the CLAUDE.md files and the auto memory folder, opens any of them in your editor, and has a switch for auto memory. Vendor docs
• To turn auto memory off for one project, set "autoMemoryEnabled": false in that project's .claude/settings.json. To keep the notes somewhere else, set autoMemoryDirectory. Vendor docs
• The notes stay on the machine that wrote them. They aren't shared across machines or cloud sessions. Vendor docs
• Subagents don't get the main conversation's auto memory, except a fork of the conversation. Vendor docs

If you'd rather a preference went to the whole team, ask Claude to "add this to CLAUDE.md" instead. That file is in the repository, so it goes through review like any other change. Vendor docs

What memory can't do

A note is context for the model. Nothing forces Claude to follow it, and nothing stops a tool call that goes against it. If a rule has to hold, put it in a hook, where Claude Code asks your script before the tool runs. The hooks tutorial shows how.

Auto memory also loads only once, at the start of a session. If a note becomes relevant halfway through a long session, the model has to think of opening it. The Spontaneous Memory tutorial builds a helper that searches your notes on every prompt instead.

Everything past the first 200 lines or 25 KB of MEMORY.md is dropped at session start, and Claude Code tells Claude to shorten the index when it gets close. Vendor docs

What we haven't verified

• The same steps in the Claude desktop app. It runs the same Claude Code build and reads the same folders, as the first tutorial shows, but we ran these prompts only in a terminal.
• What happens once MEMORY.md passes 200 lines.
• Whether Claude saves notes you didn't ask for; our test only covered explicit requests. Not verified