Nine Context Sources

## Full reference: the 9 context sources

### 1. Anchor statistic and the critical design choice

The VILA-Lab Dive-into-Claude-Code paper (arXiv 2604.14228) concluded that Claude Code is ~1.6% AI decision logic and ~98.4% deterministic infrastructure. The context-construction subsystem is an instance of that split: the 9 sources are deterministic (merged in a fixed order, by a fixed algorithm), but the model's compliance with the instructions inside them is probabilistic.

The paper's §Context Construction explicitly names this as the **Critical design choice**: "CLAUDE.md is user context (probabilistic compliance), NOT system prompt (deterministic). Permission rules provide the deterministic enforcement layer."

This is, in our reading, the single most-misunderstood Claude Code design decision. Teams adopt CLAUDE.md, put a "never delete the database" line in it, and are surprised when the model occasionally does exactly that. The model was never going to enforce that rule deterministically. The enforcement belongs in permission rules, PreToolUse hooks, or the tool allow-list.

The paper also names three recurring design commitments across the codebase: graduated layering over monolithic mechanisms; append-only designs favoring auditability over query power; and model judgment within a deterministic harness. The context system instantiates all three — especially the append-only commitment, visible in the file-based memory model.

### 2. The 9 ordered context sources (architecture.md §9 Ordered Context Sources)

Before every model call, the harness assembles context from these 9 sources in order:

1. **System prompt** — CLI-bundled, immutable. Safety and tone rules live here. Users cannot override.
2. **Environment info** — cwd, OS, wall-clock time, version string. Small, always present.
3. **CLAUDE.md hierarchy** — 4 levels merged in precedence order (see §4).
4. **Path-scoped rules** — files under `.claude/rules/**/*.md` that apply only when the agent is working in the matching directory subtree.
5. **Auto-memory** — memory files discovered on demand; see §5 (file-based memory).
6. **Tool metadata** — the schema of every tool in the current permission scope. Layer 1 of the safety layers (pre-filtering) strips denied tools from this list.
7. **Conversation history** — prior user and assistant messages, subject to the 5 shapers (see turn-execution-pipeline pack).
8. **Tool results** — outputs of tools called earlier in the session. Treat as untrusted content (see injection-surface-audit).
9. **Compact summaries** — if Auto-Compact fired, the model-generated summary of compressed history.

Ordering rationale:

- System prompt first so the model sees safety rules before anything else.
- Environment, hierarchy, rules, and memory are the "stable" context — they change at most per-session.
- Tool metadata comes before history so the model knows its affordances before seeing what has happened.
- History and tool results are the dynamic part of the turn.
- Compact summaries are last because they are the lossiest representation; the model should prefer raw history when available.

Re-ordering these in a clone is an anti-pattern — the order encodes trust (safety rules first, untrusted tool results after).

### 3. CLAUDE.md as user context — the full argument

CLAUDE.md is injected as part of the user-visible context, not into the immutable system prompt. Practical consequences:

- **Probabilistic compliance** — the model treats CLAUDE.md as guidance, not constraint. Adherence is statistical.
- **Overridable by later messages** — a user can ask the model to ignore a CLAUDE.md instruction, and the model may comply. In the system prompt, that wouldn't be possible.
- **Visible in every turn** — CLAUDE.md content enters every model call. Anything sensitive leaks every turn.
- **Probabilistic behavior is fine for style, bad for safety** — "prefer Edit over Write" is fine; "never drop the production DB" is not.

The deterministic layer is permission rules (see seven-safety-layers pack). Rules can `deny` a tool call; CLAUDE.md cannot.

Concretely, if you need the agent to NEVER do X:

- Add a deny rule that matches X at the tool-argument level.
- Add a PreToolUse hook that returns `permissionDecision: deny` for X.
- Remove the capability from the tool allow-list entirely.

If you merely prefer the agent to usually do Y:

- Write it in CLAUDE.md as a convention.
- Add a short rationale so the model can explain a deviation.

### 4. The 4-level CLAUDE.md hierarchy (architecture.md §CLAUDE.md Hierarchy)

| Level | Path | Scope | Typical use |
|---|---|---|---|
| Managed | /etc/claude-code/CLAUDE.md | System-wide (enterprise) | Org policies; not writable by the user |
| User | ~/.claude/CLAUDE.md | Per-user | Personal style preferences across all projects |
| Project | CLAUDE.md, .claude/CLAUDE.md, .claude/rules/*.md | Per-project | Project conventions, run commands, directory map |
| Local | CLAUDE.local.md | Personal (gitignored) | Local overrides; not committed |

Precedence rule: later layers specialize. They do not silently override. If two layers contradict, the model has to reconcile, and the outcome is probabilistic — not the determinism you wanted. If you actually need a deterministic override, use permission rules at the level that should win.

Path-scoped rules live under `.claude/rules/**/*.md`; they apply only when the agent is working in the matching directory subtree. A file at `.claude/rules/server/api.md` applies when the agent edits `server/api/**`; it does not apply when the agent edits `client/**`. Path-scoped rules silently shadowing global rules is a common source of confusion — log which scoped rules fired in the transcript header.

### 5. File-based memory (architecture.md §File-Based Memory)

Claude Code's memory subsystem is deliberately anti-RAG: **no embeddings, no vector DB.** Instead, an LLM-based scan inspects up to 5 memory-file headers on demand and decides which to load fully into context.

Why this works:

- **Inspectable** — memory is just files. Open in your editor; grep by name.
- **Editable** — fix a bad memory by editing a file. No re-indexing step.
- **Version-controllable** — commit memories that belong to the repo; gitignore those that don't.
- **Auditable** — the paper's append-only commitment applied: you can diff memory across sessions.
- **Good enough at Claude Code's scale** — the paper notes that 5 relevant files on demand covers the common case; embeddings pay for the long tail, and the long tail is not where the value is.

Anti-pattern: bolting a vector DB onto a clone "because CLAUDE.md doesn't scale." Measure first. Most teams who reach for a vector DB never hit the limit of the file-based approach; they inherit latency, a new failure mode, and an opaque retrieval step in exchange for a scale they don't need.

When you might legitimately want a vector DB:

- Memory count exceeds ~500 files per project.
- You have explicit latency SLOs that the LLM-scan can't meet.
- You need cross-project retrieval beyond the ~/.claude user layer.

Even then, the vector DB should sit beside the file-based memory, not replace it. File-based is the source of truth; the vector DB is a derived index that can be rebuilt.

### 6. Path-scoped rules and precedence (architecture.md §CLAUDE.md Hierarchy)

`.claude/rules/**/*.md` files are scoped to a path subtree. They are loaded only when the agent's current working context matches the scope. This is useful for:

- Language-specific conventions in monorepos (`.claude/rules/python/` vs `.claude/rules/typescript/`).
- Module-level landmines (`.claude/rules/server/billing.md` — "never change the charge flow without a security review").
- Per-surface style (`.claude/rules/ui/` vs `.claude/rules/server/`).

Known pitfall: a path-scoped rule can silently contradict a global rule. The model has to reconcile; the outcome is probabilistic. Prevention:

- Log which scoped rules fired per turn; include in the transcript header.
- Treat path-scoped rules as a linter's lens, not a hard override.
- For hard overrides, use permission rules scoped by tool argument, not content-level conventions.

### 7. Cross-references

- **turn-execution-pipeline** — step 3 of the 9-step pipeline is "context assembly." This pack expands that step.
- **seven-safety-layers** — permission rules are the deterministic layer that CLAUDE.md deliberately is not.
- **claude-code-guide** — the operator's view of AGENTS.md / CLAUDE.md; this pack is the architectural view of why the files behave as they do.
- **injection-surface-audit** — tool results (source 8) are untrusted; the audit documents the envelope pattern.

### 8. Clone checklist

If you are porting Claude Code's context system to another harness:

1. Assemble 9 sources in the documented order; do not reorder.
2. Implement the 4-level CLAUDE.md precedence; merge, do not silently override.
3. Make memory file-based first; add vector DB only if you measure a limit.
4. Path-scoped rules log which scope fired; transcript header records it.
5. CLAUDE.md content is treated as user context — any test that asserts the model "must never do X because CLAUDE.md says so" is a test design bug; rewrite with a deterministic enforcement path.

### 9. Honest limitations

- **Probabilistic compliance is genuinely probabilistic** — the model will, on some tasks and some seeds, ignore a CLAUDE.md rule. This is not a bug; it is the design. If that is unacceptable for your rule, it is not a CLAUDE.md rule.
- **File-based memory has a scale ceiling** — 5 files scanned on demand does not cover every workload. Measure before you jump to a vector DB.
- **Precedence is merge-with-specialization, not strict override** — two contradictory rules at different levels do not resolve deterministically.
- **CLAUDE.md in the context window is a token tax** — every turn pays it. Keep CLAUDE.md terse; offload long content to skills or path-scoped rules.

### 10. License + attribution

This pack paraphrases and cites architecture content from VILA-Lab/Dive-into-Claude-Code (arXiv 2604.14228, CC-BY-NC-SA-4.0). Attribution to VILA-Lab is required; non-commercial + share-alike terms inherited on any verbatim excerpts. Paraphrased summaries are original and credited per the license. Do not remove the attribution entry from `sources[]`.