Context Window

Concept of the skill

A context window is finite working memory shared by instructions, tools, skills, conversation history, tool results, reasoning/output budget, and files.

Coverage

The quantitative discipline behind an agent's working memory. Allocates the context-window budget across three zones: System (system prompt, rules, tool schemas), Skill Injection (the SKILL.md files auto-loaded for the current task), and Working (conversation, tool results, file contents, agent output). Names the three context health states — ok (< 60% used), compact (60–80%), exhausted (> 80%) — and the 80% compaction rule that compaction must always trigger before the budget is fully consumed, leaving 20% as the safety margin for finishing the current operation, writing the checkpoint, running the closeout protocol, and emitting the continuation signal. Specifies the pre-compact protocol (commit uncommitted changes, write the continuation signal, update the checkpoint, save state that cannot be re-derived from git or disk) and the post-compact recovery flow (re-injection of git status, active-task reference, recent commits, critical findings). Catalogs typical token consumption per operation type (full file read 20–40K, large tool-result JSON 10–30K, single SKILL injection 3–8K, fixed system overhead) and the five token-reduction techniques: deterministic-CLI over heavy MCP / tool-result paths, targeted file reads with offset + limit instead of full-file reads, search-before-read (grep first, read the match), progressive skill disclosure (small SKILL.md kept always loaded; large reference files loaded on demand), and count-mode for exploration (count matches, then read the few that matter). Specifies the cross-session persistence hierarchy — git history > files on disk > durable memory > live context — and uses it to decide _what to checkpoint_ before compaction. Lists per-model-class context strategies for 1M, 200K, and 128K windows.

Philosophy of the skill

The context window is the agent's _working memory_. Unlike human memory, it has a hard ceiling — when it fills, information is permanently lost from the live session unless it has been checkpointed somewhere durable. Managing the window is not optional. It is the difference between completing a long task and crashing mid-work with the most recent reasoning gone.

The trap of large windows is the assumption that they are _effectively_ unlimited. A 1M-token window feels infinite until a single 2000-line file read consumes 30K, three of those plus a long tool-result chain pushes past 200K, and the agent is at 60% before any real implementation has happened. The ceiling is real, and it is closer than the headline number suggests. Discipline at 200K is identical to discipline at 1M; only the absolute numbers move.

The 80% rule exists because compaction is _itself_ an operation that needs budget. Hitting 100% mid-operation loses the operation. Compacting at 80% preserves it — the remaining 20% pays for the act of preserving.

Source Notes

Current vendor docs agree on the central budget shape: the context window is a finite store for prior conversation and current-turn input, and output or thinking/tool-use behavior also competes for capacity in provider-specific ways. Anthropic's context-window docs describe conversation history accumulating across turns, 200K and 1M Claude classes, context awareness, tool-result and extended-thinking nuances, and server-side compaction / context editing options. Google's Gemini long-context guide frames long context as short-term memory, notes 1M+ token Gemini windows, and still recommends optimization techniques such as context caching for high-input workloads. OpenAI's model comparison docs expose model-specific context-window and max-output-token values, which is the operational reminder that planning must use the actual model selected at runtime, not a generic "frontier model" assumption.

Zone Model

A useful per-session mental partition of the available budget:

The exact share varies by model, harness, and task type. The zones are useful because budget breaches show up in different places: a System overrun is a rules / tool-schema problem, a Skill overrun is a routing / over-injection problem, a Working overrun is a context-management / file-read problem. Each has a different remediation.

Practical budget by model class

Replace these illustrative figures with the actual figures of your runtime — they shift over time and across vendors.

Do not copy these classes into a capacity claim. Check the provider's model page for the exact model, then subtract: system prompt, tool schemas, always-loaded rules, injected skills, conversation history that must remain visible, and a realistic max_tokens / output reserve. A request that fits the input window can still fail the task if it leaves no room to answer.

Context Health States

The 80% rule

Always compact at 80% of the working budget — never at 100%. The remaining 20% is the safety margin for:

• Completing the operation currently in flight
• Writing the checkpoint state
• Running whatever session-closeout / wrap protocol the runtime ships
• Emitting the continuation signal so the next session can resume

Hitting 100% mid-operation loses work. Compacting at 80% preserves it.

Compaction Protocol

When to compact

1. Context health reaches compact or exhausted
2. After completing a logical unit of work (one task, one file, one audit item)
3. Before starting a large new operation that will read many files
4. When tool results begin to truncate (a leading indicator of context pressure)

Pre-compact checklist

Before triggering compaction:

1. Durably checkpoint intended changes — commit, stage, or write a patch/notes file for work you own; do not blanket-commit an unrelated dirty tree.
2. Write the continuation signal — the next-session contract: active task, current question, remaining work.
3. Update any loop or task checkpoint — advance the recorded phase to the actual phase.
4. Save critical state — anything that cannot be re-derived from git history or files on disk goes into a durable artefact now.

Pre-compact hook

A pre-compact hook, closeout script, or manual checklist is the deterministic enforcer of the checklist. It captures, at minimum:

• The active task identifier and the current question
• The agent mode / phase
• The current git branch and the most recent commit hashes
• The current context-health state
• A small bag of custom state (whatever the runtime needs to resume)

Any runtime that supports compaction without a checkpoint mechanism is _one accidental compaction away from losing the decision trail_. The mechanism can be a hook, a closeout command, or a human-run checklist, but it must be repeatable and fast.

Post-compact recovery

After compaction, the session-start brief should re-inject:

• Git status (branch, recent commits, dirty files)
• The active task pulled from the continuation signal
• A short summary of the in-progress board state
• Any critical findings recorded in the pre-compact checkpoint

The agent does not re-load the lost conversation. It rebuilds _selectively_ from the durable artefacts.

Token Consumption Patterns

What consumes the most context

Five token-reduction techniques

#### 1. Deterministic CLI over heavy tool-result paths

Where the runtime offers both a heavy tool-result path (e.g., a large MCP-style JSON dump) and a deterministic CLI / scripted path that returns the same data shaped tighter, prefer the CLI. The savings can easily be 50–100× per call. The principle: ship structured output through tools the model can read efficiently, not through whatever path the runtime happens to expose by default.

#### 2. Targeted file reads (offset + limit)

BAD:  read the whole 2000-line file
      → 30K tokens
GOOD: read 30 lines starting at the function you actually need
      → 500 tokens

If a code-search step has already located the relevant lines, _use_ those line numbers. A "read everything because I might need it" pattern is the single biggest avoidable burn.

#### 3. Search before read

BAD:  read 5 candidate files looking for a function
      → 100K tokens
GOOD: grep for the function name first, then read 30 lines from the one match
      → 2K tokens

The search step costs ~1K tokens and replaces 50–100K of speculative reading.

#### 4. Progressive skill disclosure

Skills should follow a two-tier structure:

• `SKILL.md` — the core patterns, the routing-contract description, the verification checklist. Always loaded when the skill is selected. Should fit comfortably in 3–8K tokens.
• *`references/.md`** — detailed reference material, long examples, deep specifications. Loaded _only_ when explicitly needed.

Only SKILL.md is auto-injected. References are loaded by the agent when the task demands the depth.

#### 5. Count mode for exploration

BAD:  list every TODO comment in the repo, full match content
      → 50K tokens
GOOD: count first, then read selectively
      grep --count "TODO"                                  → 200 tokens
      grep "TODO" path: src/lib/ --head 10                 → 2K tokens

Exploration should be a _count → narrow → read_ sequence, not a single exhaustive read.

Cross-Session Persistence Hierarchy

What survives a compaction or session restart, ranked from most to least durable:

1. Git — code, commits, branches. Permanent.
2. Files on disk — checkpoints, continuation signals, structured logs (JSONL is ideal). Persistent until manually deleted.
3. Durable memory — index files and topic files in a memory directory consumed by the next session. Persistent and indexed.
4. Live context — conversation history, in-flight reasoning, tool results. Lost on compaction.

The hierarchy drives the pre-compact checklist: anything that lives only at level 4 needs to be promoted to levels 1–3 _before_ compaction, or it is gone.

Planning for compaction

When starting a complex multi-step task:

1. Break it into subtasks each of which can complete inside one context window
2. After each subtask: checkpoint intended changes + update state + write continuation signal
3. If a subtask risks exceeding the budget mid-flight, split further or read fewer files

The rhythm is: small unit → durable checkpoint → state update → next unit. Compaction becomes a routine boundary instead of a crisis.

Per-Model-Class Strategies

A 1M window is not a license to ignore the rules — it just shifts the breaking point further out. Apply the same discipline; the budget math just lets you run longer between compactions.

Anti-Patterns

Verification

• [ ] The current context-health state has been correctly classified as ok, compact, or exhausted based on actual usage estimates
• [ ] The pre-compact checklist has been followed before any compaction (durable checkpoint, continuation signal, state update, custom state)
• [ ] A pre-compact hook, closeout script, or manual checklist runs deterministically enough that compaction never happens without a checkpoint
• [ ] File reads use offset + limit targeting for any file beyond ~200 lines
• [ ] The session prefers deterministic CLI / scripted tool paths over heavy MCP-style result dumps where both exist
• [ ] No compaction has been triggered at 100% — the 80% rule has been respected
• [ ] What needs to survive the session has been promoted from live context to git / files / durable memory before any compaction
• [ ] The active model's actual context budget (not assumed budget) is the planning baseline
• [ ] Output / reasoning headroom is reserved before declaring the working set safe

Do NOT Use When