Memory across sessions and projects

TL;DR. A Claude Code session forgets everything when it ends, so durable knowledge lives in files on disk that are re-loaded at the start of the next session. There are three layers, and keeping them straight is the whole skill: the conversation transcript (resumed with --continue and --resume), the CLAUDE.md hierarchy you write (managed, then user ~/.claude/CLAUDE.md, then project, then local, then per-subdirectory), and auto memory, which Claude writes itself to ~/.claude/projects/<project>/memory/. The CLAUDE.md user layer and your user-level rules are what make knowledge follow you across every project; the project layer and the per-repo auto memory are what make a single codebase smarter over time.

Contents

Three layers of memory
Within a session: the window and compaction
Across sessions: resuming the transcript
The CLAUDE.md hierarchy
Auto memory: what Claude writes for itself
Across projects: the user layer
Further reading
Takeaways

Chapter 17 ended at the window's edge: a session is one context, and when it ends, the model retains nothing. This chapter is how knowledge crosses that edge. It is the agent-memory and compaction levers as Claude Code actually implements them, and it is the part most people use shallowly, so getting it right is a real edge.

Three layers of memory

It helps to see all of it at once before the detail. Three distinct things persist beyond a single turn, on three different timescales and in three different places.

   TIMESCALE            WHAT                         WHERE                          WHO WRITES
   ───────────────────────────────────────────────────────────────────────────────────────────
   within a session     the conversation +           the context window             you + Claude
                        tool results                 (RAM; compacted when full)
   ───────────────────────────────────────────────────────────────────────────────────────────
   across sessions,     the transcript               ~/.claude session history      the tool
   same project         (resume it)                  (resumed with --resume / -c)    (automatic)
   ───────────────────────────────────────────────────────────────────────────────────────────
   across sessions,     instructions & rules         CLAUDE.md hierarchy (managed,   YOU
   forever              (re-loaded every session)    user, project, local, subdir)
   ───────────────────────────────────────────────────────────────────────────────────────────
   across sessions,     learned facts & habits       ~/.claude/projects/<proj>/      CLAUDE
   per repository       (MEMORY.md index loaded)     memory/MEMORY.md + topic files  (automatic)
   ───────────────────────────────────────────────────────────────────────────────────────────
   across PROJECTS      your personal instructions   ~/.claude/CLAUDE.md and         YOU
                                                      ~/.claude/rules/               (once)

The mental model: the window is working memory, wiped each session. The transcript is an episodic record you can replay. The CLAUDE.md hierarchy is the instructions layer you maintain. Auto memory is the facts layer the agent maintains. And the user layer at the top of the hierarchy is the slice that follows you from repo to repo. The rest of the chapter is those rows, one at a time.

Within a session: the window and compaction

Covered in depth in Chapter 11 and Chapter 17, so just the controls here. As a session approaches the window limit, Claude Code auto-compacts: it summarizes the older turns so the conversation can continue. You can trigger it yourself with /compact, optionally with a focus instruction (/compact keep the repro steps and the failing test) so the summary protects what matters. You can also set a default focus in CLAUDE.md under a "Compact instructions" heading. Other in-session controls:

/clear wipes the conversation to start fresh on unrelated work, so stale context stops being re-sent. Pair it with /rename first so you can find the session again, then /resume to return.
/rewind (or double-Escape) restores the conversation and the code to an earlier checkpoint, which is the cheapest fix when Claude has gone down a wrong path.
Plan mode (Shift+Tab) explores and proposes before editing, so you spend tokens on a reviewed plan instead of on re-work.

One subtlety worth knowing: after /compact, the project-root CLAUDE.md is re-read from disk and re-injected, so its instructions survive compaction. Instructions you gave only in the chat, or that live in a nested subdirectory CLAUDE.md, may not survive, which is a concrete reason to write durable rules into CLAUDE.md rather than saying them once in conversation.

Across sessions: resuming the transcript

Claude Code saves each session's transcript to disk on your machine, so you can pick it back up. This is episodic memory: the actual back-and-forth, not a distilled version.

claude --continue (or claude -c) reloads the most recent conversation in the current directory and drops you back into it.
claude --resume <id-or-name> (or claude -r) resumes a specific session, or shows an interactive picker. You can name a session up front with claude --name "auth-refactor" (or -n), or rename mid-session with /rename, and then resume it by that name.
claude --resume <id> --fork-session resumes but starts a new session id, branching from the old transcript instead of continuing it in place. Useful when you want to try a different direction without disturbing the original.
claude --no-session-persistence (print mode) disables saving entirely, for one-off scripted runs you do not want recorded.

To make resume fast, Claude Code summarizes previous conversations in the background, which is one of the small idle token costs the documentation notes. The practical point: resuming is for continuing a specific thread. It is not how durable facts persist, because the transcript is one conversation. For knowledge that should be present in every session, you want the next two layers.

The CLAUDE.md hierarchy

CLAUDE.md files are the instructions layer, and they are not a single file. They form a hierarchy that is discovered, ordered, and concatenated at the start of every session. From broadest to most specific, in load order:

   1. MANAGED POLICY   /Library/Application Support/ClaudeCode/CLAUDE.md   (macOS)
                       /etc/claude-code/CLAUDE.md                          (Linux/WSL)
                       C:\Program Files\ClaudeCode\CLAUDE.md               (Windows)
                       org-wide, deployed by IT, cannot be excluded
   2. USER             ~/.claude/CLAUDE.md            your prefs, EVERY project (see below)
   3. PROJECT          ./CLAUDE.md or ./.claude/CLAUDE.md    team-shared, in source control
   4. LOCAL            ./CLAUDE.local.md             your private project notes (gitignore it)
   5. SUBDIRECTORY     foo/bar/CLAUDE.md             loaded ON DEMAND when Claude reads foo/bar/

The loading rule is precise and worth knowing. Claude Code walks up the directory tree from your working directory and loads every CLAUDE.md and CLAUDE.local.md it finds, plus the managed and user files. They are concatenated, not overridden, ordered from the filesystem root down to your working directory, so the most specific instructions are read last (and a project rule appears after a user rule). Subdirectory CLAUDE.md files are the exception: they are not loaded at launch, but pulled in on demand when Claude reads a file in that subdirectory, which keeps a big monorepo's per-team instructions out of your window until they are relevant.

Three features turn this from a single file into a system:

@path imports. A CLAUDE.md can pull in another file with @path/to/file. Imports expand at launch, resolve relative to the importing file, and can nest up to four hops deep. Import parsing skips fenced code blocks and backtick spans, so `@README` stays literal while @README imports. This is how you keep a CLAUDE.md readable while composing it from parts, and how you point Claude at an existing AGENTS.md (@AGENTS.md) so one file feeds every coding tool.
.claude/rules/. Instead of one long CLAUDE.md, you can split topics into .claude/rules/*.md. A rule with no frontmatter loads every session like CLAUDE.md. A rule with paths: frontmatter is path-scoped: it only enters the context when Claude touches a file matching its glob (for example src/api/**/*.ts). Path-scoped rules are the cleanest way to keep specialized instructions out of the window until they apply, which directly serves the "lean context" goal from Chapter 1.
claudeMdExcludes. In a large monorepo, ancestor CLAUDE.md files from other teams get picked up by the walk-up rule. This setting skips them by glob, so your window is not taxed by instructions you do not need. (Managed policy CLAUDE.md cannot be excluded.)

Remember. CLAUDE.md is concatenated top-down and re-read every session, so it is your one reliable channel for "things Claude should know in every conversation." But it is paid for on every turn (Chapter 17), so put facts and always-on rules here, push path-specific guidance into .claude/rules/ with a paths: glob, and push multi-step procedures into a skill (Chapter 19) that loads only when invoked.

Auto memory: what Claude writes for itself

The CLAUDE.md hierarchy is what you write. Auto memory is what Claude writes, on its own, as it learns your codebase: build commands it discovered, a debugging insight, a preference you corrected. You do not maintain it; the agent decides what is worth keeping.

The internals are specific and worth knowing, because this book's own repository runs on them:

Location. ~/.claude/projects/<project>/memory/, where <project> is derived from the git repository, so every worktree and subdirectory of the same repo shares one memory directory. It is machine-local: not shared across machines or with teammates.
Structure. A MEMORY.md index plus optional topic files (debugging.md, api-conventions.md, and so on). The index tracks what is stored where.
What loads. Only the first 200 lines or 25KB of MEMORY.md, whichever comes first, is loaded at the start of every session. Topic files are not loaded at launch; Claude reads them on demand with its normal file tools when it needs them. This is retrieval (Chapter 9) applied to the agent's own notes: a small index always present, the detail fetched only when relevant.
Controls. /memory lists every loaded CLAUDE.md, CLAUDE.local.md, and rules file, toggles auto memory, and opens the memory folder. Telling Claude "remember that we use pnpm, not npm" saves to auto memory; saying "add this to CLAUDE.md" puts it in the instructions layer instead. Disable it per project with autoMemoryEnabled: false, or relocate it with autoMemoryDirectory.

Don't be confused. CLAUDE.md and auto memory are both loaded every session and both persist, but they are opposites in authorship and intent. You write CLAUDE.md as instructions ("always do X"); Claude writes auto memory as learnings ("the tests need a local Redis"). CLAUDE.md loads in full; auto memory loads only its MEMORY.md index, with topic files fetched on demand. Use CLAUDE.md to direct behavior and let auto memory accumulate what the agent discovers, and check the latter with /memory so it does not drift.

This is not abstract for this very project. The repository you are reading was built by a Claude Code agent whose project instructions live in a committed CLAUDE.md, and whose cross-session learnings live in exactly this auto-memory directory, indexed by a MEMORY.md. The instructions layer says how to build and humanize the books; the memory layer records the moving state, what is finished, what is pushed, what convention changed. The two layers doing two jobs is the whole design.

Across projects: the user layer

Now the part the question turns on: how does context engineering work across different projects? The answer is the top of each hierarchy, the user layer, which is keyed to you and your machine rather than to any one repository.

~/.claude/CLAUDE.md is loaded into every session in every project. It is where personal, project-independent preferences go: your code-style defaults, your tooling shortcuts, the way you like commits written. Write it once and every repo inherits it.
~/.claude/rules/ holds personal rules (path-scoped or not) that apply everywhere, loaded before project rules so project rules can still take priority.
~/.claude/settings.json is your user-level configuration (model, hooks, permissions, MCP servers at user scope), again applied across all projects unless a project or managed setting overrides it (Chapter 19).
Sharing across worktrees and projects. Because a gitignored CLAUDE.local.md exists only in the worktree you created it in, the documented pattern for personal instructions you want everywhere is to keep them in your home directory and import them: @~/.claude/my-instructions.md. Project .claude/rules/ can likewise symlink a shared file from home, so one canonical rule set feeds many repositories.

The specialist's setup, then, is two-tiered and deliberate. A thin, stable user layer (~/.claude/CLAUDE.md plus user rules and settings) carries who you are and how you work into every project. A focused project layer (./CLAUDE.md, .claude/rules/, project settings, and the repo's auto memory) carries what this codebase needs and what the agent has learned about it. Knowledge that belongs to you travels; knowledge that belongs to the repo stays. Getting that split right is what lets you move between a dozen projects without re-explaining yourself and without leaking one project's specifics into another.

Takeaways

Three layers persist beyond a turn: the transcript (resume with --continue / --resume), the CLAUDE.md hierarchy you write, and auto memory Claude writes per repository. They live on different timescales and in different places.
The CLAUDE.md hierarchy is managed, then user (~/.claude/CLAUDE.md), then project, then local, then per-subdirectory; files are concatenated top-down and re-read every session, with subdirectory files loaded on demand.
@path imports (four hops), .claude/rules/ with paths: globs, and claudeMdExcludes turn the hierarchy into a system you can keep lean and modular.
Auto memory lives at ~/.claude/projects/<project>/memory/; only the first 200 lines / 25KB of MEMORY.md load each session, with topic files fetched on demand. It is per git repo and machine-local. This repository runs on exactly this mechanism.
Across projects, the user layer (~/.claude/CLAUDE.md, ~/.claude/rules/, user settings) follows you everywhere; the project layer stays with the repo. A two-tiered setup is what lets a specialist move between many projects without re-explaining themselves.

👉 You now know what is in a session and how knowledge persists beyond it. The last chapter in this part is the full surface a specialist drives: every context-relevant command and flag, the settings hierarchy, hooks, MCP scopes, subagents, and the modern strategies that tie them together. Continue to The specialist's playbook.

Context Engineering in Depth