skip to content

Memory & Context

What Claude Code loads and pays for: CLAUDE.md and auto memory, the context window and compaction, model and effort, and cost with prompt caching. Asked because context is the agent's working budget.

part ofClaude Coderead it →
on this pageshow

explore

questions

22

What belongs in a Claude Code project CLAUDE.md, and why can't it guarantee Claude follows an instruction?

level: juniorimportance: must knowfreq 38%

answer

  1. what you would otherwise re-explain
  2. commands, conventions, layout, always-do rules
  3. concrete enough to verify
  4. user message after the system prompt
  5. context, not enforced configuration

basics

~20 s

A project CLAUDE.md holds facts Claude needs every session: build and test commands, conventions, layout and team rules. Claude reads it as context, not enforced configuration, so a rule that must hold belongs in permissions or a hook.

solid answer

~40 s

`./CLAUDE.md` (or `./.claude/CLAUDE.md`) is where you write down what you would otherwise re-explain each session: build and test commands, style and naming conventions, where code lives, and "always do X" rules. `/init` drafts one from the codebase, and suggests improvements rather than overwriting when one exists. Keep it concrete ("run `npm test` before committing", not "test your changes") and short, under about 200 lines; move procedures into skills and area-specific conventions into path-scoped rules. The limit is mechanical: Claude Code delivers CLAUDE.md as a user message after the system prompt, so the model reads it and tries to follow it, with no guarantee, especially for vague or conflicting lines. Anything that must hold whatever the model decides, such as never touching `.env`, belongs in a `permissions.deny` rule or a `PreToolUse` hook.

go deeper

for a junior

Know what goes in a project CLAUDE.md, where it sits, that /init drafts one, and that it is read every session.

for a middle

Explain why concrete, short instructions are followed more reliably, and how /context shows whether a file loaded.

for a senior

Show you know CLAUDE.md is delivered as context the model may not follow, and name the layers that enforce: permission rules, hooks, managed settings.

for a principal

Frame the team trade-off: what is worth a line every session against what belongs in skills, rules or enforced settings, and who reviews the file.

## What a project CLAUDE.md is Every Claude Code session starts with a fresh context window: nothing from yesterday's conversation carries over on its own. A **CLAUDE.md** file is the way you carry knowledge across that gap. It is a plain Markdown file that Claude Code reads at the start of every session and places in the model's context, so each conversation starts already knowing the facts you wrote down. The **project** CLAUDE.md lives at `./CLAUDE.md` or `./.claude/CLAUDE.md` in the repository and is committed, so the whole team shares it. Other scopes exist (an organization-managed file, your personal `~/.claude/CLAUDE.md`, an uncommitted `CLAUDE.local.md`), but the project file is where most teams start. ## What belongs in it The docs' rule of thumb is to write down **what you would otherwise re-explain**. Add a line when Claude makes the same mistake a second time, when code review catches something Claude should have known about the codebase, or when you type the same correction you typed last session. Good content: - **Build, test and lint commands**: the exact invocations, such as `npm test` or `make lint`. - **Conventions that differ from defaults**: naming, indentation, error-handling patterns. - **Project layout**: where API handlers, migrations or fixtures live. - **"Always do X" rules**: run the tests before committing, use the shared logger. - **Architectural decisions** a new teammate would need in order to be productive. What does *not* belong: multi-step procedures (a **skill** loads those on demand), conventions that matter for only one part of the tree (a **path-scoped rule** under `.claude/rules/` loads only when Claude works with matching files), and anything Claude can derive by reading the code, such as a directory listing. Instructions work best when they are **concrete enough to verify**: | Vague | Concrete | | --- | --- | | "Format code properly" | "Use 2-space indentation" | | "Test your changes" | "Run `npm test` before committing" | | "Keep files organized" | "API handlers live in `src/api/handlers/`" | Keep each file short (the docs target **under 200 lines**), grouped under headings and bullets, and free of contradictions: if two instructions conflict, Claude may pick either one. ## Getting a first version: /init and /memory `/init` analyzes the codebase and generates a starter CLAUDE.md with the build commands, test instructions and conventions it discovers. If a CLAUDE.md already exists, `/init` **suggests improvements instead of overwriting it**. Setting the environment variable `CLAUDE_CODE_NEW_INIT=1` switches `/init` to an interactive flow that asks which artifacts to set up and presents a proposal before writing anything. After that, `/memory` lists the CLAUDE.md files for your user and project scopes and opens any of them in your editor, so you can refine the draft with what Claude could not discover on its own. ## Why it is guidance, not enforcement The docs say it plainly: Claude **treats CLAUDE.md as context, not enforced configuration**. Mechanically, Claude Code delivers the content as a **user message after the system prompt**, not as part of the system prompt. The model reads it and tries to follow it, but strict compliance is not guaranteed, least of all for vague or conflicting instructions, a bloated file, or a line that competes with guidance Claude Code adds on its own. So a line like "never edit `.env`" or "never push to main" is a request, not a control. For something that must hold regardless of what the model decides, use the layers the client enforces: - a **`permissions.deny`** rule in a settings file, which refuses the tool call; - a **`PreToolUse` hook**, a script that runs before a tool call and can block it; - for an organization, those same controls delivered through **managed settings**. A managed CLAUDE.md deployed by IT is still guidance; the docs pair it with managed settings precisely because only the settings enforce. If an instruction must run at a fixed point, before every commit or after each edit, write it as a hook rather than a sentence. ## Checking that it loaded When Claude seems to ignore a CLAUDE.md, work through this: 1. Run `/context` and look under **Memory files**. A file that is not listed is a file Claude cannot see. 2. Confirm the file sits somewhere that loads for this session, such as the working directory or a directory above it. 3. Make the instruction more specific, and remove contradicting lines in other instruction files. 4. If it must always hold, move it out of CLAUDE.md into a permission rule or a hook.

  • Where should a multi-step release procedure go instead of the project CLAUDE.md, and why?
    Into a skill. CLAUDE.md loads into every session, so a long procedure costs context even when nobody is releasing and dilutes the always-relevant rules. A skill's body loads only when it is invoked or Claude judges it relevant, which keeps CLAUDE.md to short facts that apply to every task.
  • How do you confirm that a CLAUDE.md file actually loaded into a Claude Code session?
    Run `/context` and check the list under **Memory files**; if the file is missing there, Claude cannot see it. Then check that it sits in a location that loads for the session, such as the working directory or a directory above it, and use `/memory` to open and edit the file.

CLAUDE.md is the briefing note you hand a contractor on day one: it shapes how they work, but it opens and locks no doors. The building's key cards, which here are permission rules and hooks, decide which rooms they can actually enter.

  • CLAUDE.md rules are enforced like permission rules
  • CLAUDE.md is part of the system prompt, so Claude always obeys it
  • A longer, exhaustive CLAUDE.md makes Claude follow it more reliably
  • Vague guidance like 'write clean code' is specific enough
  • Running /init overwrites the existing CLAUDE.md
open as a page

In Claude Code, what does /usage (alias /cost) report, and what does its dollar figure mean on a Pro plan versus an API key?

level: juniorimportance: must knowfreq 22%

basics

~20 s

Claude Code's /usage shows session token counts, a locally estimated dollar cost and, on Pro, Max, Team or Enterprise, plan usage bars. API-key users pay per token; subscribers draw on plan limits, so that dollar figure is not their bill.

open as a page

In Claude Code, how do you switch the model mid-session or at launch, and which method changes the default for new sessions?

level: juniorimportance: must knowfreq 30%

basics

~20 s

Use /model inside a session or claude --model at launch. A typed /model name, or Enter in the picker, switches now and saves the model key in ~/.claude/settings.json; s in the picker, --model and ANTHROPIC_MODEL affect only that session.

open as a page

In Claude Code, when do you run /clear instead of /compact, and what does each command keep from the session?

level: juniorimportance: must knowfreq 30%

basics

~10 s

/clear starts a new conversation with empty history, so use it between unrelated tasks. /compact keeps the same conversation but replaces its history with a structured summary, freeing room to continue the current task.

open as a page

Where can Claude Code's CLAUDE.md files live, at managed, user, project and local scope, and who shares each one?

level: middleimportance: must knowfreq 24%

basics

~10 s

Managed policy CLAUDE.md applies to every user on the machine, ~/.claude/CLAUDE.md to you in every project, ./CLAUDE.md or ./.claude/CLAUDE.md to the team through git, and a gitignored ./CLAUDE.local.md to you in one project.

open as a page

How do Claude Code's /effort levels work, what is the default on Opus 5.5, and what does the ultrathink keyword change?

level: middleimportance: must knowfreq 18%

basics

~20 s

Effort (low, medium, high, xhigh, max) sets how much Claude reasons per step; Opus 5.5 and Sonnet 5.5 default to medium. ultrathink in a prompt adds a one-turn instruction to reason harder without changing the effort level sent to the API.

open as a page

In a four-hour Claude Code session, Claude ignores a path-scoped rule and an early decision after auto-compaction — what survived, and what do you change?

level: seniorimportance: must knowfreq 15%

basics

~20 s

Content loaded from disk comes back after compaction: project-root CLAUDE.md, unscoped rules, auto memory and the plan are re-injected. Path-scoped rules, nested CLAUDE.md and chat-only decisions are summarized away, so move what must persist into project-root CLAUDE.md.

open as a page

What does Claude Code's auto memory save, where is it stored, how much loads each session, and how do you turn it off?

level: middleimportance: should knowfreq 16%

basics

~20 s

Auto memory is notes Claude writes about your preferences, corrections and project context, kept per repository in ~/.claude/projects/<project>/memory/. Each session loads the first 200 lines or 25KB of MEMORY.md; switch it off with /memory or autoMemoryEnabled.

open as a page

How does a Claude Code .claude/rules file with paths: frontmatter differ from an unscoped rule, and when does it load?

level: middleimportance: should knowfreq 13%

basics

~20 s

A rule without paths loads every session like .claude/CLAUDE.md; one with a paths glob loads only when Claude works on a matching file, at 2.1.286 by reading it. paths is the only field read, and bad YAML makes the rule unscoped.

open as a page

What does the 'Prompt cache (main)' line in Claude Code's /usage report, and how do you act on its misses?

level: middleimportance: should knowfreq 8%

basics

~20 s

Claude Code's /usage adds a Prompt cache (main) line from v2.1.251: requests, the share of input tokens served from cache, misses with tokens re-cached, expected rebuilds from compaction, and whether the cache is warm. It covers the main conversation only.

open as a page

What do Claude Code's model aliases such as opus, sonnet, fable, best and opusplan resolve to, and why is default not one of them?

level: middleimportance: should knowfreq 14%

basics

~20 s

Aliases name a family that moves forward: at Claude Code 2.1.286 on the Anthropic API, opus is Opus 5.5 and sonnet is Sonnet 5.5, while other providers can lag. opusplan uses opus in plan mode and sonnet otherwise; default only clears an override.

open as a page

When does Claude Code auto-compact a session, and how do you make it compact earlier with /autocompact or its overrides?

level: middleimportance: should knowfreq 9%

basics

~10 s

By default Claude Code auto-compacts when the conversation reaches the model's context limit, or about 967K tokens on native 1M-window models. /autocompact 500k, --autocompact, autoCompactWindow or CLAUDE_CODE_AUTO_COMPACT_WINDOW sets an earlier window.

open as a page

In Claude Code, what already fills the context window before your first prompt, and how does /context show it?

level: middleimportance: should knowfreq 14%

basics

~20 s

Before the first prompt Claude Code loads the system prompt, environment details, every applicable CLAUDE.md, the start of auto memory, skill descriptions and MCP tool names. /context shows usage by category, the files that loaded and suggestions to cut it.

open as a page

In a monorepo, Claude Code launched at the root ignores the conventions in packages/billing/CLAUDE.md — how do CLAUDE.md files load, and what do you change?

level: seniorimportance: should knowfreq 14%

basics

~20 s

Claude Code loads CLAUDE.md from the launch directory and its ancestors at startup, but a subdirectory's file only when Claude reads a file there; all are concatenated root-down, never overriding. Launch from the package or use a path-scoped rule.

open as a page

After running /model mid-session, a Claude Code turn is slow and costly; which mid-session actions invalidate its prompt cache, and which do not?

level: seniorimportance: should knowfreq 14%

basics

~20 s

Each model has its own cache, so /model makes the next request reprocess the whole history. Turning on fast mode, compaction and changed tool definitions also invalidate it; editing files or CLAUDE.md, switching permission mode, invoking skills and spawning subagents keep it.

open as a page

A developer's Claude Code sessions keep starting on Sonnet at low effort despite /model opus and /effort high; their shell exports ANTHROPIC_MODEL and CLAUDE_CODE_EFFORT_LEVEL. What is happening?

level: seniorimportance: should knowfreq 7%

basics

~10 s

Exported variables outrank the saved choices. ANTHROPIC_MODEL beats the model key /model saved, so each launch returns to Sonnet; CLAUDE_CODE_EFFORT_LEVEL outranks even /effort and --effort, so high never takes. Remove both from the profile.

open as a page

What does Claude Code's /fast mode change about an Opus session, how is it billed, and when is lowering effort the better lever?

level: middleimportance: nice to knowfreq 6%

basics

~20 s

Fast mode, a research preview, runs Opus with an API configuration tuned for speed, up to 2.5x faster at the same quality but a higher per-token price; subscribers pay from usage credits. Lowering effort instead buys speed by thinking less.

open as a page

A repository's AGENTS.md stopped reaching Claude Code after a developer added a CLAUDE.local.md — why, and how do you fix it?

level: seniorimportance: nice to knowfreq 7%

basics

~10 s

Since 2.1.277 Claude Code reads AGENTS.md only when no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md exists in the working directory or above, and CLAUDE.local.md counts. Set Project instructions to claude-md-and-agents-md, or import @AGENTS.md.

open as a page

Which prompt-cache TTL does Claude Code use by default on a subscription versus an API key, and when would you set promptCacheTtl to 1h?

level: seniorimportance: nice to knowfreq 6%

basics

~20 s

Claude Code requests a one-hour TTL for the main conversation only on a subscription within plan usage; on usage credits, an API key or a cloud provider it is five minutes, as are subagents. promptCacheTtl "1h" (v2.1.242+) buys the hour for idle-prone sessions.

open as a page

What does Claude Code's --fallback-model flag do, which failures trigger it, and how long does a switch last?

level: seniorimportance: nice to knowfreq 4%

basics

~20 s

--fallback-model names backup models Claude Code tries in order when the primary is overloaded or unavailable. Rate-limit, authentication and billing errors never trigger it, and a switch lasts one turn before the primary is tried again.

open as a page

Why does a Claude Code session stop with 'Autocompact is thrashing' after reading a huge log file, and how do you recover?

level: seniorimportance: nice to knowfreq 5%

basics

~20 s

Auto-compaction succeeded, but an oversized file or tool output refilled the window after each summary, so Claude Code stopped retrying. Read in smaller chunks, run /compact with focus that drops the output, or use a subagent.

open as a page

A team lead finds one developer's Claude Code spend tripled in a week; how would you set up per-user cost visibility and caps for the whole team?

level: principalimportance: nice to knowfreq 7%

basics

~20 s

Match caps to how the team pays: seat allowances plus usage-credit spend limits on Teams or Enterprise, workspace spend limits on the Console, cloud budgets on Bedrock, Agent Platform or Foundry. For per-user visibility everywhere, push OpenTelemetry export through managed settings.

open as a page