Memory

Claude Code starts every session with a fresh context window. Two built-in systems still give you persistence: CLAUDE.md (and related instruction files) for rules you write, and auto memory for notes Claude adds when it learns something worth keeping. Official reference: How Claude remembers your project.

Skills load on demand. CLAUDE.md (and rules) plus auto memory cover what loads every session and what Claude persists. Together they separate what should load every time, what loads on demand, and what Claude records for itself.

CLAUDE.md vs auto memory

Summarized from the memory documentation:

Skills (see the skills page) load on demand when relevant or when you run a slash command. They are a third way to avoid stuffing everything into always-on context.

Auto memory

Auto memory lets Claude save notes for later sessions based on what happened in chat: for example useful build steps, debugging findings, or preferences you corrected. It does not write on a fixed schedule; Claude chooses what seems worth keeping.

• Default: enabled. Turn it off with autoMemoryEnabled: false in settings, CLAUDE_CODE_DISABLE_AUTO_MEMORY=1, or the toggle inside /memory (see below).
• Storage: under ~/.claude/projects/<project>/memory/, where <project> is derived from the git identity of the repo (all worktrees of that repo share one memory directory). Outside git, the project root is used. Files are machine-local, not synced to the cloud.
• Layout: a MEMORY.md index plus optional topic files (for example debugging.md). Only the start of MEMORY.md is injected at startup; detailed notes are supposed to live in topic files that Claude can read with tools when needed.
• Signals in the UI: messages such as Saved 2 memories or Recalled 2 memories mean Claude updated or read that folder.

You can edit or delete any auto memory file by hand; it is plain Markdown.

Custom directory

To change where auto memory is stored, set autoMemoryDirectory in settings.json. Current Claude Code accepts it at user, project, local, policy, and --settings scopes, so review shared project settings before trusting a custom location. See Settings.

The /memory command

Run /memory in a session to:

• List instruction-file locations and open those files for editing.
• Toggle auto memory on or off.
• Open the auto memory folder or pick a file to edit.

If you say remember that … in chat, Claude usually stores that in auto memory. If you want it in CLAUDE.md instead, say so explicitly (for example add this to CLAUDE.md) or edit the file yourself via /memory.

Example prompts

Pin a rule to git, not only auto memory:

For this repo we always run `npm run build` before opening a PR. Add that under a "## Checks" section in CLAUDE.md (create the section if it is missing). Do not rely on memory alone for this one.

Confirm what is loading:

I am starting a fresh session in this repo. What CLAUDE.md / rules files should load, and where does auto memory for this working tree live on disk? If anything is ambiguous, tell me exactly what to open or run (no secret file contents).

Subagents

Subagents can maintain their own auto memory. See Subagent configuration in the Claude Code docs.

Practical tips

• Prefer CLAUDE.md for rules you want in version control and reviewed like code.
• Let auto memory capture one-off discoveries; prune the folder occasionally so MEMORY.md stays within the startup budget.
• If Claude ignores instructions, run /context to verify which instruction files actually loaded, then make rules more specific. Use /memory to list locations, open files, and manage auto memory.

Tighten a rule that is not sticking:

Claude keeps ignoring "use pnpm not npm". Open CLAUDE.md, strengthen that rule to a single imperative line with the exact commands, and remove any older line that still says npm. Keep the rest of the file unchanged.