D3 · Claude Code › Cluster 1 · Memory & CLAUDE.md

1.1 · What CLAUDE.md Is & When It Loads

Auto-loaded project memory

CONCEPT Persistent memory that survives the fresh context window

Every Claude Code session starts with a fresh context window — Claude remembers nothing from your last conversation. CLAUDE.md is the mechanism that carries knowledge across that boundary: a plain-Markdown file you write with the standing instructions Claude should hold in every session — build commands, coding conventions, project layout, "always do X" rules. You write it; Claude reads it automatically at the start of each session.

The key word is auto-loaded. You don't attach it, reference it, or paste it in. When a session launches, Claude Code discovers the relevant CLAUDE.md files and injects their full contents into the context window before your first message. That's why it's called memory — it's the durable layer beneath each ephemeral conversation.

🔑 CLAUDE.md is delivered as a user message after the system prompt, not as part of the system prompt itself. Claude reads it and tries to follow it, but there is no guarantee of strict compliance — it is context, not enforced configuration.

CONCEPT Context, not enforcement — and how it loads

This is the single most tested distinction in the cluster. CLAUDE.md shapes behavior; it does not enforce it. If you need a rule that runs no matter what Claude decides — block a command, run a linter before every commit — that belongs in a hook (a PreToolUse hook executes as a shell command regardless of the model's choices), not in CLAUDE.md.

PropertyCLAUDE.md
Who writes itYou (and your team)
What it holdsInstructions, conventions, workflows, architecture
When it loadsAutomatically, at the start of every session
How much loadsThe full file, regardless of length (shorter = better adherence)
Delivered asA user message after the system prompt
Enforced?No — it is context. Use hooks for hard enforcement
Ancestor CLAUDE.md files (in your cwd and directories above it) load in full at launch. Nested CLAUDE.md files in subdirectories load on demand — only when Claude reads a file in that subdirectory (covered in 1.6).
⚠️ Files over ~200 lines consume more context and reduce adherence. CLAUDE.md loads in full no matter how long it is, so length costs you tokens on every single turn — keep it tight.

DIAGRAM Fresh window → CLAUDE.md bridges the gap

flowchart TD S["New session starts
(fresh context window)"] --> D{"Discover CLAUDE.md
up the dir tree"} D -->|"found"| L["🟢 Inject full contents
as a user message"] D -->|"none"| E["No memory loaded"] L --> C["Claude reads it as context
(not enforced config)"] C --> U["Your first prompt runs
with project memory present"] C -.->|"need a hard rule?"| H["🟠 Use a PreToolUse hook
— enforced regardless"] classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef gate fill:#ffe8cc,stroke:#ff9f40,color:#9a4a0a; classDef bad fill:#f8d7da,stroke:#dc3545,color:#721c24; class L ok; class H gate; class E bad;

CODE A minimal project CLAUDE.md

Plain Markdown at your repo root. Create it by hand, or run /init to have Claude analyze the codebase and generate a starting file.

# CLAUDE.md — loaded automatically at the start of every session

## Build & test
- Install deps with `npm ci`
- Run `npm test` before committing
- Use 2-space indentation (never tabs)

## Project layout
- API handlers live in `src/api/handlers/`
- Shared types live in `src/types/`

<!-- Maintainer note: HTML comments are stripped before injection,
     so they cost zero context tokens. -->
Run /init to auto-generate a starter CLAUDE.md. If one already exists, /init suggests improvements rather than overwriting it.

TRADE-OFFS CLAUDE.md vs. a hook for a rule

✅ CLAUDE.md (context)

  • Flexible, natural-language guidance
  • Zero-config: just write Markdown
  • Great for conventions, layout, "prefer X"
  • Loaded every session automatically

⚠️ Hook (enforcement)

  • Runs as a shell command at a fixed event
  • Applies regardless of what Claude decides
  • Needed when a rule must run (block/lint/gate)
  • More setup; not natural language
Rule of thumb: guidance → CLAUDE.md; guarantee → hook.

EXAM TRAPS

Trap: "CLAUDE.md is part of the system prompt." → It is delivered as a user message after the system prompt. That's why adherence isn't guaranteed. For system-prompt-level text use --append-system-prompt.
Trap: "CLAUDE.md enforces rules." → It is context, not enforcement. To block or force an action regardless of Claude's choice, use a hook (e.g. PreToolUse).
Trap: "Only the first N lines of CLAUDE.md load." → CLAUDE.md loads in full regardless of length. The 200-line / 25KB truncation applies to auto memory's MEMORY.md, not CLAUDE.md.
Trap: "You must attach or reference CLAUDE.md to use it." → It is auto-loaded at session start by walking the directory tree — no manual attach needed.

PRACTICE

Q1 · When exactly is a project's CLAUDE.md loaded into context?

Automatically at the start of every session, before your first prompt. Ancestor files (cwd and above) load in full at launch; nested subdirectory files load on demand when Claude reads files there.

Q2 · You need "run the linter before every commit" to always happen. CLAUDE.md or a hook?

A hook. CLAUDE.md is context and adherence isn't guaranteed. A hook runs as a shell command at a fixed lifecycle event regardless of what Claude decides.

Q3 · Where does CLAUDE.md sit relative to the system prompt, and why does it matter?

It's injected as a user message after the system prompt. Because it's context rather than system-level instruction, Claude may not comply strictly — especially with vague or conflicting rules.