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

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 — this guide covers the machinery around it.)

The memory layers

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

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:

---
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.

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 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).
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 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.