# Managing Claude Code Memory & Context: CLAUDE.md, /compact, and Auto-Memory

> How Claude Code remembers — every CLAUDE.md scope and load order, path-scoped rules, the auto-memory system, and the context commands that keep sessions sharp.

Claude Code's memory is layered: CLAUDE.md files load by scope (managed → user → project → local, plus on-demand subdirectory files), .claude/rules/ adds path-scoped instructions, and auto-memory persists learnings across sessions. In-session, /context shows what's eating the window, /compact summarizes deliberately, /clear resets — knowing what survives each is the skill.

Claude Code has two resources that get conflated: **context** — what the model can see right now, a finite per-session window — and **memory** — what persists when the session ends. Long sessions degrade when context fills with noise; new sessions start dumb when nothing was persisted. This guide is the map of both systems and the commands that move things between them. (For *what to write* in a CLAUDE.md, see [CLAUDE.md Best Practices](/guides/configuration/claude-md-best-practices) — this guide covers the machinery around it.)

## The memory layers

**CLAUDE.md, by scope.** Loaded in order at session start:

| Scope | Location | Notes |
| --- | --- | --- |
| Managed policy | OS-level admin path | Org-wide, can't be excluded |
| User | `~/.claude/CLAUDE.md` | Your defaults, every project |
| Project | `./CLAUDE.md` | Checked in — the team contract |
| Local | `./CLAUDE.local.md` | Personal, gitignored overrides |
| Subdirectory | `subdir/CLAUDE.md` | **On demand** — loads when Claude reads files there |

The on-demand behavior of subdirectory files is the underused one: a `packages/api/CLAUDE.md` costs nothing until the agent actually works in `packages/api/`. CLAUDE.md also supports **imports** — `See @docs/git-workflow.md` pulls another file in (imports can nest, with a depth cap) — so the always-loaded file can stay a thin index over deeper references.

**Path-scoped rules.** `.claude/rules/*.md` files load unconditionally — unless you give them a `paths:` frontmatter:

```markdown
---
paths:
  - "src/**/*.tsx"
---
# Frontend rules
Use the design-system components; never hand-roll buttons.
```

Now frontend rules ride along only when frontend files are touched. This is the answer to the bloated CLAUDE.md: invariants stay global, everything area-specific becomes a scoped rule. (`~/.claude/rules/` does the same across all your projects.)

**Auto-memory.** Claude keeps its own notebook per project at `~/.claude/projects/<project>/memory/`: a `MEMORY.md` index loaded at startup (capped around 200 lines so it can't bloat), plus topic files it reads on demand. Claude writes to it when it learns something durable — a build quirk, a debugging insight — and you stay in charge: it's plain Markdown, browsable and editable via `/memory`, toggleable with `autoMemoryEnabled` in settings. All worktrees of a repo share one memory, which is exactly what you want for [parallel sessions](/guides/advanced/parallel-claude-code-worktrees).

Quick capture for any layer: start a message with `#` — "`# integration tests need the docker stack up`" — and it's saved without breaking flow. `/init` bootstraps a project's CLAUDE.md in the first place (and reads an existing `AGENTS.md`, `.cursorrules`, etc. while it's at it).

## The context window, in practice

**See it: `/context`.** A visual breakdown of what's consuming the window — system prompt, CLAUDE.md, MCP tool definitions, conversation. Run it before optimizing anything; the answer is often "three MCP servers you forgot about."

**Reset it: `/clear`.** Between unrelated tasks, clearing beats carrying. The old conversation remains reachable via `/resume`, so clearing costs nothing but stale context.

**Compress it: `/compact`.** Mid-task, `/compact` summarizes the conversation and frees the window — and takes instructions: `/compact keep the failing test output and the refactor plan`. Auto-compaction fires on its own when the window fills, but a deliberate compact at a milestone beats an automatic one mid-thought. Know what survives: project CLAUDE.md is re-read from disk, rules and auto-memory persist — **conversation-only instructions are what fade**. The corollary is the core discipline: *if it must survive, put it in a file.*

**Time-travel it: `/rewind` and `/resume`.** `/rewind` rolls back to a checkpoint when a direction failed (cheaper than arguing the agent out of a bad path); `/resume` and `--continue` reattach to past sessions per directory.

## Keeping sessions lean

The habits that follow from the machinery:

1. **CLAUDE.md under ~200 lines.** It's loaded *every* session — every line taxes every task and dilutes adherence. Invariants only.
2. **Skills for procedures.** A 300-line release process belongs in a [skill](/guides/skills/writing-your-first-skill) that loads when invoked, not in standing context.
3. **Rules scoped by path**, as above.
4. **Subagents for verbose work.** A log dive or sweeping search in a subagent keeps thousands of lines in *its* context; only the conclusion returns to yours.
5. **Mind MCP tool definitions.** Every connected server ships its schemas into context — keep the per-project set tight ([details](/guides/mcp/claude-code-mcp-setup)).
6. **Big windows are budget, not license.** 1M-token modes exist on recent models, but a focused window still beats a full one — see [Context Engineering](/guides/prompting/context-engineering) for the why.

The mental model that makes all of this click: **context is RAM, files are disk.** CLAUDE.md, rules, and memory are what you've chosen to load at boot; `/compact` is swap; `#` and `/memory` are how you write things to disk before the power cycles.

---

_Source: https://agentscamp.com/guides/configuration/claude-code-memory-context — Guide on AgentsCamp._