How Claude Code memory works, and when to clear it

Claude Code has two kinds of memory, and people conflate them constantly. There are the rules you write, loaded in full at the start of every session. And there is auto memory, the notes Claude writes for itself, indexed and loaded on demand. Knowing which is which, and knowing when to reset the conversation versus compress it, is the difference between a session that stays sharp and one that drifts.

This guide maps the whole stack, then covers the lifecycle: when to /clear, when to /compact, and how to keep the whole thing lean. You can verify any specific detail at code.claude.com/docs/en/memory.md.

Two memories, one easy mix-up

Hold this distinction first, because everything else hangs off it.

• CLAUDE.md is memory you write. Rules, conventions, commands. It loads in full on every session and applies to every turn.
• Auto memory is memory Claude writes. Things it learned while working: a build quirk, a debugging insight, a preference you stated. An index loads at session start; the detailed notes load only when relevant.

One is standing instructions. The other is accumulated learnings. They live in different files, load differently, and you manage them differently. Keep them separate in your head and the rest of this is straightforward.

The memory stack

When a session starts, Claude Code assembles its standing context from several sources, in a fixed precedence order. Higher entries are more general and load first; lower entries are more specific and, where they conflict, win.

Here is what each layer is, who owns it, and where it lives.

A few things worth calling out:

• The managed policy file is set by an administrator and cannot be excluded. If you are in a managed environment and wondering where a rule came from, this is the first place to look.
• Project CLAUDE.md loads in full, every session. This is the file your whole team shares, so it is the one most worth keeping tight.
• CLAUDE.local.md is gitignored by design. It is for things you want on your machine but not in the shared repo, like a local database path or a preferred output style.

How do Claude Code memory conflicts resolve?

These layers are additive, not exclusive. They all load, and Claude reads them together. Precedence only matters when two of them disagree, and the rule is simple: the more specific layer wins. A user-level preference for terse output yields to a project rule that asks for detailed commit messages, because the project file is closer to the work at hand. A path-scoped rule for src/api/ overrides a general project convention when Claude is editing an API file.

In practice you rarely write deliberate overrides. Precedence matters most as a debugging tool: when Claude does something you did not ask for, walk the stack from the top and find the layer that told it to. A surprising behaviour almost always traces back to a managed policy or a global user file you forgot was there.

Path-scoped rules

A normal CLAUDE.md loads on every turn whether or not it is relevant. Path-scoped rules fix that. A file under .claude/rules/ with a frontmatterthe small block of YAML at the top of a markdown file, between two --- lines, that carries metadata paths: field loads only when Claude reads a file matching one of its globsa pattern like src/api/**/*.ts that matches a set of file paths. The API rules below cost nothing on a CSS task. They enter context only when Claude touches a .ts file under src/api/.

---
paths:
  - "src/api/**/*.ts"
---
 
# API rules
 
- Every endpoint validates its input before use.
- Return errors in the shared error-response shape.
- Never log request bodies; they may contain secrets.

This is the main tool for keeping context lean as a project grows. Specialised rules that only matter in one corner of the codebase belong here, not in the always-loaded project file.

Imported memory with @path

Inside any CLAUDE.md you can reference another file with @path, and Claude Code expands it inline at session start. It is a way to keep one short entry point that pulls in larger pieces.

# Project conventions
 
See @docs/style-guide.md for formatting.
See @docs/testing.md for how we write tests.

Imports are recursive a few hops deep, so an imported file can import others. The catch is that every imported line still counts as loaded context. Importing a thousand-line doc costs the same as pasting it; the import only saves you from duplicating the text, not from paying for it.Common gotchaDo not reach for @path to keep context lean: an @import loads in full every session, exactly like inlining the file.For load-only-when-relevant detail, use a path-scoped rule under .claude/rules/ instead.

Auto memory: the notes Claude writes

Auto memory (officially "Auto memory", available in Claude Code v2.1.59 and later) is the second kind of memory, and it works the other way around. Instead of you writing rules for Claude, Claude writes notes for itself as it works.

The notes live in a per-project memory directory under ~/.claude/projects/<project>/memory/. The mechanics:

• It is keyed per git repo, and shared across worktrees of that repo.
• An entry-point MEMORY.md index loads at session start. Roughly the first 200 lines, around 25KB, is what gets read in automatically.
• Detailed topic files are written by Claude and read on demand when a topic becomes relevant, not loaded up front.
• It is plain markdown you can read, edit, or delete. Manage it with the /memory command.

This is how Claude carries a hard-won insight from one session into the next without you re-explaining it. It debugs a flaky test, learns the cause, writes a note, and next week it reads that note instead of rediscovering the problem.

CLAUDE.md vs auto memory

This table is the one to internalise.

Use the file you write for what you already know. Let auto memory capture what neither of you knew until the work surfaced it.

How do I turn auto memory off?

If you do not want it, disable it with autoMemoryEnabled: false in settings:

{
  "autoMemoryEnabled": false
}

Or set the environment variable for a single run or shell:

export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

The context lifecycle: clear, compact, context

The memory stack above is your standing context. On top of it sits the live conversation, which grows every turn. Managing that growth is a separate skill, and it comes down to three commands.

What does /clear do?

/clear begins a brand-new conversation. It drops the chat history but keeps your CLAUDE.md and your auto memory, since those are standing context, not conversation. The previous session is not gone; you can reach it again with /resume.

Use /clear between unrelated tasks. When you finish a bug fix and move to an unrelated layout change, clear first. Dragging the auth-debugging history into a CSS task is pure noise: it costs tokens and dilutes the model's focus on the new job.

What does /compact do?

/compact summarises the conversation so far to free up room, without ending it. It replaces the raw turn-by-turn history with a dense summary while preserving your CLAUDE.md and the key snippets the task still needs.

/compact

Use /compact mid-task, when the same job has run long and the window is filling with old tool output. You keep the thread of what you are doing; you shed the token weight of every intermediate step.

The one-line rule: /compact keeps the current work, /clear wipes the slate. Compact when the task continues. Clear when the task is done.

What does /context do?

/context visualises current token usage so you can see what is filling the window before you decide what to do about it. It is the diagnostic that tells you whether you need to compact, clear, or carry on.

Auto-compaction

You do not have to watch the gauge constantly. As the conversation approaches the context limit, Claude Code compacts automatically. It clears older tool outputs first, since those are the bulkiest and least reusable, then summarises the conversation if it needs more room. Manual /compact is for when you want to reclaim space before you hit that point, usually so a long task does not lose detail to an auto-compaction at an awkward moment.

A worked example CLAUDE.md

A good project file is short, specific, and made of rules you enforce. Every line loads on every turn, so each one should earn its place. Here is a generic example for a fictional service.

# Conventions
 
Build: `npm run build` · Test: `npm test` · Lint: `npm run lint`
 
## Code
- TypeScript only. No `any`. Use async/await, not promise chains.
- One component per file under `src/components/`.
- API handlers live in `src/api/handlers/`.
 
## Tests
- Co-locate tests beside the file they cover.
- The suite needs a local database running first.
 
## Do not
- Commit `.env` files.
- Add logging to `src/api/` request paths.
 
See @docs/style-guide.md for formatting details.

Notice the shape: commands on one line, a few firm conventions, a short do-not list, and a pointer to a deeper doc instead of pasting it. That last @docs/style-guide.md import keeps the entry point readable while still loading the detail when needed.

For the cross-tool view of these files (how Codex, Gemini, and Cursor name and load their equivalents), see rules and memory files.

Hygiene: keep the whole thing lean

Memory rots if you let it. A few habits keep it useful.

Keep CLAUDE.md short and specific. Every line is paid on every turn. A vague rule ("write good code") adds tokens and changes nothing. The model weights sections roughly evenly, so burying three real rules in three hundred lines of preamble makes the real ones weaker, not stronger. Aim for concrete rules a teammate could follow.

Delete stale auto-memory notes. Auto memory accumulates, and a note that was true three months ago can quietly mislead. Review it now and then with /memory and prune anything that no longer holds. It is plain markdown, so editing or deleting a file is safe and instant.

Do not hoard one-off task details in permanent memory. The pattern that bites people is treating memory as a junk drawer. A note like "the fix for ticket 412 was to bump the timeout" is a task detail, not a standing fact. It loads forever, ages badly, and crowds out the conventions that matter. Keep permanent memory for permanent things.Common gotchaThe trap is pasting a one-off fix into CLAUDE.md so Claude "remembers" it, since that file is full-loaded on every turn and now taxes every future session forever.If a detail is worth keeping at all, let auto memory capture it as an on-demand note, and reserve CLAUDE.md for rules that are true on every task.

Scope what you can. If a rule only matters in one folder, make it a path-scoped rule under .claude/rules/ so it loads only when relevant. The always-loaded project file should hold only what is always true.

Clear between tasks; compact within them. The single cheapest context hygiene move is /clear at the boundary between unrelated jobs. It is free, and it stops yesterday's context from quietly taxing today's work.

A day in the lifecycle

To make the three commands concrete, here is how they fall out across a normal working session.

You open Claude Code in a project. The memory stack loads: org policy if any, your global file, the project CLAUDE.md in full, and the auto-memory index. You start a feature. As the work goes, Claude reads files in src/api/, which pulls in the path-scoped API rules, and it picks up a quirk it notes to auto memory.

An hour in, the window is heavy with old tool output from files you have long since moved past. You run /context, see that stale reads dominate, and run /compact. The conversation collapses to a summary; the feature continues with room to breathe.

The feature ships. You now need to fix an unrelated bug in the styling layer. Rather than carry the API context into it, you run /clear. The conversation resets, but the project CLAUDE.md and auto memory are still there, so Claude still knows your conventions and the quirk it learned earlier. You start the bug fix from clean signal.

The next morning you reopen the project. You want to revisit yesterday's feature thread, so you run /resume and pick it from the list. Nothing was lost; clearing only ended that conversation's role in the live window, not its record.

That cycle, with CLAUDE.md and auto memory persisting underneath the conversation churn, is the whole model in motion.

Where this connects

Memory is one part of a bigger picture.

• For shaping what goes into the window each turn, and the order it goes in, see context engineering.
• For what /clear, /compact, and /resume do to the live session and how state carries across runs, see Claude Code session state.
• For the cross-tool rules-file landscape, see rules and memory files.
• For carrying knowledge forward when you are building your own agents, see give your agent memory across steps.

The short version

CLAUDE.md is the memory you write, loaded in full, for rules you can state up front. Auto memory is the memory Claude writes, indexed and loaded on demand, for things learned while working. The stack runs from a locked org policy down through your personal, project, and path-scoped files. On top sits the live conversation: /clear between tasks, /compact within a long one, /context to see where the tokens went. Keep both memories short and current, and a fresh session always starts from signal, not clutter.

You can confirm any detail in this guide against the official reference at code.claude.com/docs/en/memory.md.