Claude Code memory

Claude Code memory is what carries over from one session to the next, since every session starts with a fresh context window. There are two kinds: CLAUDE.md files you write, and auto memory notes Claude writes about you and the project. This page is what Anthropic's docs say about both, then what not to put there.

TL;DR

• Two things persist: CLAUDE.md files (yours) and auto memory (Claude's). Both load at the start of every session.
• Keep CLAUDE.md under 200 lines and put in how you work: commands, conventions, project layout.
• Do not put this week's priorities or customer evidence in it. They change too often. Keep them in a shared plan every agent reads, and decisions as principles every agent reads.

Everything below about Claude Code comes from Anthropic's memory documentation, read on 21 October 2026. Check the page for changes; the product moves fast.

What does Claude Code remember between sessions?

Anthropic puts it directly: each session "begins with a fresh context window", and two mechanisms carry knowledge across sessions.

The docs also say Claude treats both as context, not enforced configuration. A line in CLAUDE.md shapes what Claude does. It does not guarantee it. To make something run every time, such as a check before each commit, Anthropic points you to a hook instead.

Where does CLAUDE.md live?

The docs list four places, from broadest to most specific:

• Managed policy. Organization-wide instructions set by IT, at a system path (for example /Library/Application Support/ClaudeCode/CLAUDE.md on macOS).
• User. ~/.claude/CLAUDE.md: your preferences across all projects.
• Project. ./CLAUDE.md or ./.claude/CLAUDE.md: shared with your team through source control.
• Local. ./CLAUDE.local.md: your private notes for one project. Add it to .gitignore.

Claude Code loads these from your working directory and every directory above it, and joins them rather than overriding. Files in subdirectories load on demand, once Claude reads or edits a file there. You can also split a large file into .claude/rules/, where a rule can be scoped to certain file paths with a paths field, and pull other files in with an @path/to/file import.

What is auto memory, and where is it?

Auto memory is notes Claude writes for itself as it works. The docs describe four kinds: user (your role and preferences), feedback (corrections you gave and approaches you confirmed), project (ongoing work and decisions Claude cannot get from the code) and reference (where to find things outside the project). Claude skips anything it can derive from the codebase, and it does not save something every session.

• On by default in local sessions. Turn it off from /memory, or set autoMemoryEnabled to false.
• Where: ~/.claude/projects/<project>/memory/. A MEMORY.md index sits beside one file per memory.
• What loads: the first 200 lines or 25KB of MEMORY.md, whichever comes first. Topic files load only when Claude needs them.
• Machine-local. Worktrees of the same repository share it. Other machines do not. Subagents do not get the main conversation's auto memory.

How do I edit it?

• /memory lists your CLAUDE.md files and the auto memory folder. Pick one and it opens in your editor. It also toggles auto memory.
• /init writes a starting CLAUDE.md from your codebase. If one exists, it suggests improvements instead of overwriting.
• Ask Claude. "Always use pnpm, not npm" goes to auto memory. To put it in CLAUDE.md, say "add this to CLAUDE.md".
• /context shows which memory files loaded this session. If a file is not listed, Claude cannot see it.
• Plain Markdown. Open and edit any of it, or delete it. Auto memory files are yours to audit.

What are the limits?

• Size. Anthropic's target is under 200 lines per CLAUDE.md. Longer files "consume more context and reduce adherence". A file over 4 MiB is skipped. Imports help you organize but do not cut the context cost, because imported files load at launch.
• Contradictions. If two instructions conflict, "Claude may pick one arbitrarily". Review your files now and then. /doctor prompt-audit will look for outdated or conflicting ones.
• Compliance. Vague lines work worse than checkable ones. "Use 2-space indentation" beats "format code properly".
• Compaction. The project-root CLAUDE.md is re-read after /compact. An instruction you gave only in chat is not, so move it to the file.
• One machine. Auto memory is not shared across machines or with teammates. CLAUDE.md is, if you commit it.

What is memory not for?

Memory is for things that stay true. It works poorly for things that change faster than you edit files.

This week's priorities. "We are working on onboarding this sprint" is stale in days. It is also invisible to every other agent. Cursor, Codex and Grok do not read your Claude auto memory, and the folder sits on one machine.

Customer evidence. Who asked, in what words, from which account, worth how much. It arrives daily from Slack, calls and support. A note Claude saved last Tuesday does not know about Thursday's call.

Decisions that every agent must follow. A call such as "no left accent bars on rows" saved to one agent's memory is learned by one agent. The next session of a different tool makes the old mistake. A decision wants to be a principle that all of them read.

The pattern that works:

1. Rules file: how you work. Commands, conventions, project layout. Slow-moving, in the repo.
2. A shared plan: what to build and why. Ranked priorities, the evidence behind each, and a spec with Done When lines.
3. Principles: what you decided. Written once, read by every agent. This is what a decision log holds.

Annsa is the second and third. It keeps the ranked priorities and each spec with its evidence, and Claude Code, Cursor, Codex and Grok connect to it over MCP and read the same plan. Decisions you save as principles are read by every agent: decide once, every agent learns. That is product memory as opposed to session memory. Annsa does not write or edit your CLAUDE.md. See AI agent memory.

Should I use CLAUDE.md or AGENTS.md?

If Claude Code is your only agent, CLAUDE.md. If you run more than one, keep one shared AGENTS.md. Per the docs, Claude Code reads AGENTS.md when your repository has no CLAUDE.md. If you also have a CLAUDE.md, make it import the shared file:

@AGENTS.md

## Claude Code

Use plan mode for changes under src/billing/.

Anthropic notes that reading AGENTS.md directly needs a recent Claude Code version, and that a CLAUDE.md with an @AGENTS.md import is the way to share one file in sessions that cannot read it. Run /context and confirm CLAUDE.md appears under Memory files.

A starter CLAUDE.md

Short on purpose. Fill the brackets, delete what you do not need, and keep it under 200 lines.

# [Project name]

@AGENTS.md

## Commands
- Install: [command]
- Test: [command]   Run it before saying a job is done.
- Build: [command]
- Lint: [command]

## Layout
- [folder]: [what lives there]
- [folder]: [what lives there]

## Conventions
- [One checkable rule, e.g. "Use 2-space indentation"]
- [One checkable rule, e.g. "API handlers live in src/api/handlers/"]

## Before you start a job
- Read the spec for the job and its Done When lines.
- Ask me if a Done When line is unclear. Do not guess.

## Not in this file
- This week's priorities, customer requests and open decisions.
  They live in the shared plan, which you read at the start of each job.

A memory check-up, once a month

• Open /memory. Read every file once.
• Delete any line that is a priority, a date or a customer. Those belong in the plan.
• Delete any line Claude could learn from the code.
• Fix any pair of lines that disagree.
• Turn "should" into a checkable line, or a hook if it must always run.
• If a rule matters to your other agents too, move it to AGENTS.md.