Memory & Context Persistence

Every Claude Code session starts with an empty context window. Two mechanisms carry knowledge from one session into the next: CLAUDE.md files that you write, and auto memory, where Claude keeps notes of its own. This module shows where those files live, in which order they load, and how to phrase instructions Claude actually follows.

Where memory lives and how it loads

Both systems enter the context at the start of every conversation — and to Claude both are context, not enforced configuration. The documentation names four locations for CLAUDE.md : managed policy (organization-wide, rolled out by IT), user instructions in ~/.claude/CLAUDE.md , project instructions in ./CLAUDE.md or ./.claude/CLAUDE.md , and local instructions in ./CLAUDE.local.md , which you add to .gitignore . They are listed in load order, from the broadest scope to the most specific one.

These locations do not override each other. Claude Code walks up the directory tree from your working directory, collects every CLAUDE.md and CLAUDE.local.md it finds, and concatenates them. Ordering runs from the filesystem root downwards, so the instructions closest to your working directory are read last; within one directory, CLAUDE.local.md comes after CLAUDE.md . To see which files actually arrived, run /context and check the list under “Memory files”.

In practice: project memory is for what a new teammate would need — build and test commands, conventions, architecture decisions. User memory is for how you personally work, not for what the project does. Anything that concerns only you and only this project, such as a sandbox URL or your test data, belongs in CLAUDE.local.md and stays out of version control. A rule of thumb: write down whatever you would otherwise explain a second time.

When a single file grows too large, split the instructions into .claude/rules/ — one markdown file per topic, discovered recursively in subdirectories too. The paths frontmatter field binds a rule to specific files, so it only enters the context when Claude works there:

---
paths: src/api/**/*.ts
---
All API endpoints must validate input with Zod. Return 400 with field-level errors on validation failure.

A path-scoped rule like this triggers as soon as Claude reads a matching file — not on every tool use that touches it. Rules without a paths field load at launch, with the same priority as .claude/CLAUDE.md . Personal rules in ~/.claude/rules/ apply to every project on your machine and load before project rules, which gives project rules priority. Claude Code resolves symlinks along the way; circular ones are detected and handled gracefully.

Creating and maintaining memory

The quickest route to a first CLAUDE.md is /init : Claude looks at the codebase and writes down build commands, test instructions, and the conventions it discovers. If the file already exists, /init suggests improvements instead of overwriting it. With CLAUDE_CODE_NEW_INIT=1 you get a multi-phase interactive flow instead, which explores the codebase with a subagent, closes gaps through follow-up questions, and hands you a reviewable proposal before anything is written.

For editing, /memory opens your memory files in your editor and also lists locations where no file exists yet. If you want Claude to remember something, just say so — “remember that the API tests need a local Redis instance” goes into auto memory. If it belongs in CLAUDE.md instead, ask for that explicitly. You do not need to copy existing documentation: the @path/to/file import syntax pulls it into the context at launch:

# Project Standards

@README.md
@docs/architecture.md
@package.json

Imported files may import further, up to a maximum depth of four hops. When a project import resolves outside the working directory — into your home directory, for example — Claude Code lists the files in an approval dialog the first time; if you decline, they stay disabled for good. A path in backticks, by the way, is not read as an import and stays plain text.

Auto memory: what Claude notes down for itself

Auto memory is Claude’s own notebook. While working, Claude records what would be useful in a later session: build commands, debugging insights, architecture notes, your corrections. Each project gets its own directory at ~/.claude/projects/<project>/memory/ , derived from the git repository — so all worktrees of the same repo share one auto memory, and nothing is shared between machines. Inside sits MEMORY.md as the index, alongside any topic files such as debugging.md or api-conventions.md .

Subagents can maintain their own auto memory as well. See the subagent configuration for details.

At the start of every conversation, Claude Code loads the first 200 lines or the first 25KB of MEMORY.md — whichever comes first. Anything beyond that stays out, which is why Claude keeps the index short and moves detail into topic files it reads on demand. You never have to maintain it, but you may read and correct it at any time. Auto memory can be switched off with the toggle in /memory , with CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 , or via autoMemoryEnabled in settings. For a different storage location, set autoMemoryDirectory to an absolute path or one starting with ~/ — from project or local settings the value is honored only after you accept the workspace trust dialog for that folder:

{
  "autoMemoryEnabled": true,
  "autoMemoryDirectory": "/path/to/shared/memory"
}

In a large monorepo, CLAUDE.md files from other teams pile up quickly without contributing anything to your work. claudeMdExcludes skips them using glob patterns that are matched against absolute paths:

{
  "claudeMdExcludes": ["packages/legacy-app/CLAUDE.md", "vendors/**/CLAUDE.md"]
}

CLAUDE.md and CLAUDE.local.md files above your working directory are loaded in full at launch; files in subdirectories only once Claude reads something there. You can set claudeMdExcludes at any settings layer — user, project, local, or managed policy — and the lists merge across layers. Only the managed policy CLAUDE.md cannot be excluded, which is exactly what makes it the dependable place for organization-wide requirements.

Writing instructions Claude follows

Because CLAUDE.md is loaded in every session, every line costs context — the context window visualization shows where that happens and how much room your instructions take. Target under 200 lines per file; longer files consume more context and reduce adherence. What works is concrete, verifiable sentences: “Use 2-space indentation” rather than “format code properly”. If two rules contradict each other, Claude may pick one arbitrarily, so prune outdated instructions regularly. If it still grows too large, move parts into path-scoped rules. And anything that must happen at a fixed point, such as before every commit, does not belong in CLAUDE.md but in a hook.