Claude Code memory explained: what persists and where
Claude Code has two official memory systems. Learn what each remembers, where it lives, and how to refactor a bloated setup.
Claude Code has two official ways to carry knowledge across sessions: CLAUDE.md files that you or your team write, and auto memory that Claude writes as local notes. Use CLAUDE.md for stable instructions and auto memory for useful learnings Claude discovers. Put procedures, temporary task state, deep references, and hard restrictions elsewhere.
Rules, Skills, handoff files, and knowledge bases can also provide context. They are useful adjacent layers, but Anthropic does not describe them as additional Claude Code memory systems.
The two official memory systems
Every session starts with fresh working context. The official memory documentation identifies two mechanisms that reload information into it.
CLAUDE.md is authored memory. A user file at ~/.claude/CLAUDE.md can hold preferences across local projects. A project can use ./CLAUDE.md or ./.claude/CLAUDE.md for shared instructions, while ./CLAUDE.local.md holds personal details for one checkout.
Claude Code discovers these files from the filesystem root down toward your working directory. At the same directory level, CLAUDE.local.md is appended after CLAUDE.md. The files are additive, not a guaranteed configuration-style override system. A more specific instruction is read later, but contradictory prose can still produce unpredictable behavior.
Auto memory is Claude-authored memory. It is enabled by default in Claude Code v2.1.59 or later and stored under ~/.claude/projects/<project>/memory/. Its uppercase MEMORY.md file is the startup index; optional topic files can be read later. The first 200 lines or 25 KB of the index, whichever comes first, load at session start.
Auto memory is scoped to a Git repository and stored locally. Worktrees and subdirectories from the same repository share its default directory. Outside Git, Claude Code uses the project root to determine the memory directory. Auto memory does not follow you to another computer, teammate, or cloud session.
Choose the narrowest useful layer
This table is our editorial placement guide, not an official Anthropic taxonomy.
| Information | Best home | When it loads | Shared? |
|---|---|---|---|
| Personal preference across projects | ~/.claude/CLAUDE.md | Every local session | One user and machine |
| Stable team project instruction | Project CLAUDE.md | Project session startup | Yes, if committed |
| Personal project detail | CLAUDE.local.md | Project session startup | One checkout |
| Rule for one path or file type | .claude/rules/*.md with paths | When Claude reads a matching file | Yes, if committed |
| Learning Claude discovered | Auto-memory MEMORY.md or topic file | Index at startup, topics on demand | Repository or non-Git project on one machine |
| Repeatable procedure | Skill | When invoked or relevant | Yes, if committed or packaged |
| Current task state | Handoff or task file | When explicitly loaded | Only if deliberately shared |
| Deep reference material | Project docs or knowledge base | On demand | Depends on storage |
| Non-negotiable restriction | Settings, permissions, or hook | At configuration or event time | Depends on scope |
Before saving anything, ask: Does every session need it? Is it an instruction, learning, procedure, or temporary state? Should teammates receive it? Must software enforce it?
This is the persistence side of Claude Code context engineering. Context engineering chooses the evidence for the current task. Memory decides which stable information should return in later sessions.
What loads later, and what survives compaction
Claude Code loads project-root instructions at startup, not every file below the working directory. A nested CLAUDE.md becomes relevant when Claude reads in that subdirectory. A rule with paths loads when Claude reads a matching file.
Splitting a large CLAUDE.md with @path/to/file imports can improve organization, but imported content still loads with the parent. Relative imports resolve from the file containing the import, recursive imports stop after four hops, and external imports require approval the first time Claude Code encounters them. Imports are not an on-demand context-saving mechanism. For a long procedure, use a Skill. For path-specific guidance, use a scoped rule.
Compaction also has a precise boundary. Anthropic's context-window documentation says project-root CLAUDE.md, unscoped rules, and auto memory are re-injected from disk. Nested instructions and path-scoped rules are absent until Claude reads a relevant file again. Conversation-only requests may be summarized or lost.
Memory survives by being re-read or re-injected, not because every word remains untouched. /memory shows active instruction and memory files. Anthropic's configuration debugging guide also documents the InstructionsLoaded hook for recording what loaded and why.
Refactor one bloated memory file
You can test a cleaner structure without claiming that it makes Claude a particular percentage more accurate. Create a disposable repository with an intentionally bloated root CLAUDE.md: personal writing preferences, project commands, detailed API rules, a release checklist, current task notes, copied provider documentation, and two conflicting commands.
Then give every kind of information one canonical owner.
Keep a short project router
Leave the project's purpose, architecture map, canonical commands, and pointers to deeper material in the root CLAUDE.md.
Move conditional guidance
Put API-only instructions in a path-scoped .claude/rules/api.md file and the release checklist in a Skill.
Separate local and temporary facts
Move a sandbox URL to gitignored CLAUDE.local.md and current decisions or open questions to a handoff file.
Move deep reference material
Store copied provider documentation under docs/reference and load it only for tasks that need it.
Enforce the real boundary
Replace the prose request not to read .env with an appropriate deny permission or hook.
Inspect fresh and compacted sessions
Use /memory, read a non-API file and then an API file, run /compact, and record which layers load again.
Save both fixtures as separate commits. Ask the same questions in fresh sessions about the test command, API rule, release procedure, and current task state. Record loaded files and behavior, not a claim that memory “feels smarter.”
We have not run and preserved this comparison for this article, so we report no before-and-after result. The procedure is reproducible; any later performance claim needs repeated runs and saved evidence. Claude Code verification explains how to turn that evidence into a checkable receipt.
Memory does not travel everywhere
The local CLI and the Code tab in Claude Desktop use the same underlying local engine. Anthropic's Desktop documentation says they share configuration and project memory through project files, although their session histories remain separate.
Claude Code on the web runs work in a fresh cloud virtual machine cloned from a repository. Committed project files such as CLAUDE.md and .claude/rules/ can arrive with that clone. Your laptop's user-level file and local auto-memory directory do not. See Anthropic's web environment documentation before assuming a local setup exists remotely.
Normal Claude chat memory and Cowork project memory are separate product features. They are not synchronized versions of Claude Code's auto memory.
Memory can also preserve bad information. Auto memory may retain a stale command; authored files may contradict each other; local Markdown is not a secrets manager. Review /memory, delete obsolete notes, and keep one owner for each durable fact. If you are new to folders, permissions, and project instructions, Claude Code for non-developers covers those foundations. For a bounded investigation that should not fill the main conversation, consider a Claude Code subagent.
This site is independent and is not affiliated with Anthropic. Product behavior changes quickly, so recheck the official documentation before treating a path, limit, or control as permanent.
What is Claude Code memory?
Claude Code memory currently has two cross-session mechanisms: human-authored CLAUDE.md instructions and Claude-authored auto memory. They reload useful information into fresh sessions, but they do not provide unlimited recall.
Where does Claude Code store auto memory?
By default, Claude Code stores it under ~/.claude/projects/<project>/memory/. The uppercase MEMORY.md file is the startup index, while optional topic files can be read on demand.
Does Claude Code memory survive /compact?
Root project instructions, unscoped rules, and auto memory are re-injected from disk. Nested instructions and path-scoped rules return only after Claude reads a relevant file again.
Does Claude Code memory sync across computers?
Auto memory does not automatically sync across computers, teammates, or cloud sessions. Committed project instructions can travel with a repository, but user instructions and local auto memory stay in their original environment.