Context Management

Context Management

Concept of the skill

Context management is the live-session discipline for deciding what evidence enters the agent's active working set, what gets carried only as a handle, what gets distilled, what gets dropped, and what must be preserved so a compacted, restarted, or successor session can continue without re-deriving the decision trail. It treats the context window as finite reasoning attention — not free storage — that degrades through context rot (attention dilution and recall loss as the window fills) and context pollution (irrelevant tool traces, stale logs, and disproven assumptions left active) even while well within the technical token limit.

Coverage

The working discipline that controls what enters, stays in, and exits an active agent session. Intake triage that sorts every candidate context source into four buckets (must-have / useful soon / durable background / noise) before any large file, transcript, tool result, or external page is read. The active-context contract: task, active question, hypothesis, loaded evidence, rejected paths, next verification, and handoff location. The six-step context-management loop: state the active question in one sentence, name the minimum evidence needed to prove or disprove it, load the cheapest source first (index → search → narrow slice), collapse confirmed facts and completed branches into a checkpoint and re-cite it near the recency end when the window has grown long, drop stale or disproven assumptions from the active thread while preserving rejected-path markers, and re-check whether the question changed before reading more.

Working-set shaping rules: what to keep active, what to carry only as an identifier, what to summarize, and what to push out (including raw tool results, subagent reports, and the model's own exposed reasoning traces). The "carry handles until you need payloads" rule for just-in-time loading. The L1–L4 memory-hierarchy analogy for attention cost versus retrieval cost. Stable-prefix ordering for prompt caching: keep durable system / tool / skill / reference material ahead of volatile per-turn conversation, fresh tool results, timestamps, and user-specific payloads when the runtime exposes prompt assembly order. Evidence capsules that preserve source, claim, status, implication, and re-open condition after raw material is dropped, and observation masking for large tool outputs. Distillation patterns for logs, whole files, tool results, exposed reasoning traces, subagent reports, completed debugging branches, long conversations, and multi-page docs. Drift detection signals (re-reading the same source, fix ideas changing every turn, unbounded search, forgotten proofs, repeated paraphrases, contradicted plans, superseded tool results), the four live-window pathologies (poisoning / distraction / confusion / clash), the reset rule for changing active questions, and the reset-threshold signal for when a clean restart beats more distillation. Runtime primitives that support the discipline — compaction, prompt caching / prefix reuse, tool-result or reasoning-block clearing / context editing, session trimming or summarization, memory or progress files, subagents, programmatic tool filtering — with the boundary that none of them replaces agent judgment. The compaction-ready handoff format with its required fields (task / question / hypothesis / proven facts / rejected paths / next step), high-recall-first then precision-tightened writing, durable checkpoint placement, and the under-thirty-seconds resume test. The selective-rebuild recipe for recovery after the thread is lost. A vocabulary bridge that maps this skill's home-grown terms to the industry-standard names (compaction, structured note-taking / agentic memory, just-in-time / progressive-disclosure retrieval, prompt caching, tool-result clearing, observation masking, context isolation) so the discipline travels across vendor docs and runtimes, with an outbound source trail recording the provenance of every web-derived concept carried in.

Philosophy of the skill

Context management is the practical layer between having the right information available somewhere in the workspace and having it active in the agent at the right moment. The goal is not to load more context — it is to keep the smallest working set (the minimal effective context) that still lets the agent act correctly. Without this discipline, agents speculate from stale assumptions, re-read sources they already processed, and lose the decision trail at the moment of compaction. Every context slot occupied by noise is a slot unavailable for the evidence that would actually resolve the current question.

The small-working-set rule is empirical, not aesthetic — it is grounded in how the models behave. Long-context research and current vendor guidance converge on the same operational fact: a larger context window increases what can fit, but it does not make every fitted token equally useful. As input grows, recall and accuracy tend to degrade — non-uniformly, position-dependent, and worse when distractors are present — rather than as a clean monotonic "every fact gets harder" rule. This is now named context rot, observed across the current generation of frontier models, not as a quirk of one vendor. It has three compounding mechanisms: the lost-in-the-middle effect (models attend well to the start and end of context but poorly to the middle), attention dilution (every added token competes for a fixed attention budget), and distractor interference (content semantically similar to the question but irrelevant actively misleads). The practical consequence: a large, mostly-noise window can reason worse than a much smaller window that is all signal. A million-token window is capacity, not permission to flood the session; you cannot reliably prompt your way out of it and a bigger window does not fix it. The smallest high-signal working set is the most durable lever, and it is the lever this skill operates. Treat context as scarce attention, not storage.

The hardest part is not what to load. It is what to drop. Disproven hypotheses, raw logs after the key pattern is extracted, full files after the needed lines are identified, old plans after the question changed, tool outputs after their conclusions are captured, and exposed scratch reasoning after its decisions are captured all continue to steer reasoning until they are deliberately removed or demoted. The working set is what the agent is actively reasoning over, not everything it has ever seen.

Automatic compaction, session memory, context editing, tool-result clearing, prompt caching, and subagents do not obsolete this skill. They automate mechanics: trimming, summarizing, clearing, ordering, isolating, or storing. They do not decide which fact is load-bearing, which assumption is falsified, which source should be reopened, which context is stable enough for a reusable prefix, or which handoff detail lets a cold successor resume. This skill owns that judgment — ensuring the core meaning is preserved before automation blindly truncates it.

1. Outcomes

2. The Active Context Contract

At any point in a serious task, the active working set should be explainable in this compact contract. Make it an explicit, structured object you maintain live — not a vague mental model. These are the same fields the handoff (Section 8) freezes at compaction time: the handoff is just this contract written down at the moment the session ends, so there is nothing to assemble under pressure when compaction fires.

Task: <ticket, file, user request, or short label>
Active question: <one sentence>
Current hypothesis: <one claim being tested, with its supporting evidence>
Loaded evidence: <source -> why it is active now> (as capsules, §5)
Rejected paths: <falsified assumptions and why they are out>
Next verification: <one concrete check>
Handoff location: <where the durable checkpoint lives, if any>

If any line is hard to fill, do not load more context yet — first clarify the missing line. The contract is not ceremony; it lets the agent distinguish useful uncertainty from context panic, and it prevents the agent from "guessing" what it is doing based on the last few turns of history.

3. The Context-Management Loop

Use this loop whenever a task starts, sprawls, changes direction, or feels noisy:

1. Define the active question in one sentence.
2. Name the minimum evidence that would answer it — both the prove set and the disprove set.
3. Load the cheapest source that can answer the question: index, search result, symbol list, line slice, small doc section, then only if necessary the full file, full transcript, or complete tool result. (This is just-in-time / progressive-disclosure loading — pull data in by reference at the moment it is needed, rather than front-loading everything.)
4. Collapse confirmed facts and completed branches into a short checkpoint the agent can re-read later. A finished subtask or trial-and-error branch should become one result line plus source handles, not remain as raw intermediate turns. Once the window has grown long, re-state that checkpoint near the end of the active context rather than leaving it only where it was first written: because models attend most strongly to the most recent tokens (the recency end of the lost-in-the-middle curve), the live plan and proven facts steer most reliably while they sit near the bottom of the window. Treat this as an occasional attention repair — done when the checkpoint has drifted up out of recent context — not as a mandate to repeat it every turn.
5. Drop stale or disproven assumptions from the active thread — disprove ≠ delete-from-history, but delete-from-active-context. When you drop a disproven hypothesis, leave a one-line rejected-path marker in the checkpoint (tried X — ruled out because Y) so the freed context is not re-spent re-exploring the same dead end on a later turn. Drop the raw evidence; keep the one-line verdict.
6. Re-check whether the active question changed before reading more. If yes, restart the loop and re-triage remaining sources. Do not drag old context along.

The loop is recursive — every "load more" decision restarts it. The goal is not to never read; it is to read only when evidence demands it.

4. Intake Triage — Four Buckets

Before reading anything large, sort every candidate context source into one of four buckets:

Intake rules

• Start from the user's concrete artefact: the named file, pasted error, failing test, ticket, or requested source — before loading background.
• Prefer an owning doc or source file over a broad repo-wide reference.
• Prefer a search result over a full-file read.
• Prefer one decisive slice over three speculative reads.
• Prefer a path, symbol, URL, command, or query as the temporary carrier when the content itself is not needed yet.
• If you cannot explain — out loud, in one sentence — why a source is being loaded, do not load it.

Just-in-time loading

Modern agent platforms increasingly support just-in-time context: skills load on demand, tools fetch data only when called, subagents isolate exploration, sessions can trim history, and compaction summarizes older turns. Use those features to support the same discipline: keep lightweight identifiers in the main window until the current question requires the full content.

The portable rule is: carry handles until you need payloads. A file path, line range, issue ID, URL, grep query, tool-call ID, or memory filename is often enough to preserve discoverability without paying the attention cost of the full source. Load the payload only when the handle is insufficient for the next verification.

Agent memory hierarchy analogy

Use this as an access-cost mental model, not as a runtime contract. The four buckets decide whether a source is relevant; the hierarchy decides where relevant information should live until the active question needs it.

Promote information upward only when the next verification needs it. Demote it as soon as its claim, provenance, and re-open condition have been captured. This is the cache analogy behind the four buckets: do not pay L1 attention for L4 discoverability.

Stable-prefix ordering for prompt caching

Prompt caching is a runtime optimization, but the context-management decision is ordering. When a runtime reuses exact prompt prefixes and you can influence prompt assembly, keep low-churn material before high-churn material so the cacheable prefix stays stable:

Do not fight the runtime's required instruction order. Within the regions you control, keep the reusable prefix stable and place the changing payload after it. A tool output or scratch note that changes every turn should usually become a handle, capsule, or masked observation in the active working set rather than being inserted into the stable prefix. Note the corollary: clearing or editing content the cache had already warmed invalidates that prefix downstream, so eviction is not free (see §7). Token thresholds, cache duration, cache keys, pricing, and billing math belong to context-window or runtime documentation; this skill owns only the context-ordering judgment.

5. Working-Set Shaping

The working set is what the agent is actively reasoning over — not everything it has ever seen.

Keep these active

• The current problem statement
• The current hypothesis
• The smallest evidence set that can prove or disprove it
• The facts already verified and still relevant to the current question
• The rejected-path markers that prevent repeated dead ends
• The next verification step

Push these out

• Raw logs after the repeating pattern and trigger are extracted (keep the capsule)
• Raw tool results (search output, command dumps, file reads) once the extracted fact is recorded — clearing stale tool output is the lightest-touch, lowest-risk form of compaction in an agentic loop, because the agent rarely needs to re-read a raw result after it has acted on it
• Full files after the needed symbols, lines, and invariants are identified
• Alternative hypotheses that have already been disproven, after their one-line rejected-path marker is written (not deleted blind)
• Background docs once their actionable rule has been distilled
• Subagent / sub-task reports once their conclusion is captured — a delegated agent's full transcript is bulk; keep its verdict capsule, drop the transcript
• Exposed reasoning traces, thinking-block summaries, or scratch plans after their decisions, surviving assumptions, rejected paths, and next checks are captured — on reasoning models the model's own extended-thinking blocks bloat the window as fast as raw tool output, so summarize the conclusion into a capsule and let the trace fall away rather than carrying every deliberation forward
• Prior plans after the active question has changed
• Intermediate subtask branches after their conclusion, evidence handle, and residual risk are captured

Evidence capsules

Use an evidence capsule when a source is too large to keep active — so a fact survives the drop of its raw source without losing the trail back:

Source: <path:line, URL, tool result, or command>
Claim: <what this source proves or disproves>
Status: <proven | assumed | likely | contradicted | needs recheck>
Implication: <what this changes about / lets you decide about the active question>
Re-open if: <condition under which the raw source must be read again>

The capsule is not a prose summary for its own sake — it is an auditable substitute for raw context, and it is what lets you push the raw evidence out while keeping everything reasoning depends on. If the capsule does not say when to re-open the source, it is probably too lossy.

Observation masking

When the raw observation is large but the fact that the observation happened still matters, replace it with a compact masked observation that doubles as an evidence capsule — preserving the result, key fields, source handle, and re-open condition:

[Output masked: tool-call-17 GET /items -> HTTP 200; 50 items; item #42 status=error; re-open if the item #42 remediation fails or another field becomes relevant]

Masking is only safe after the extracted fact is written somewhere auditable. A masked line that says only "output omitted" is not a capsule; it hides evidence without preserving the decision trail.

Distillation pattern

The distillation is the artefact — write it into the active conversation or checkpoint, then drop the raw input. A conversation-only distillation is durable enough for the live session, but it is not durable across compaction, restart, or handoff. Anything a successor must rely on belongs in a durable artefact: progress file, memory file, task comment, commit message, patch note, or other explicit checkpoint the session can re-read. (Writing the working summary to a re-readable file is structured note-taking, sometimes called agentic memory — the same move as the in-conversation checkpoint, just persisted outside the window so it survives a compaction or restart.)

6. Drift Detection and Reset

Context drift means the session is no longer solving the same problem it started with, or is still reasoning from assumptions that have already been falsified.

Live-window pathologies

These are failure modes of the active window itself. Recognising the named mode tells you which corrective move applies. They complement context-engineering's system-level missing / stale / wrong / overwhelming taxonomy; they do not replace it.

Designing the system that prevents these at the library level — injector quality, retrieval architecture, failure metrics — is context-engineering's job, upstream of this skill.

Anti-drift rules

• One active hypothesis at a time.
• One primary question at a time.
• One verification target at a time.
• When evidence contradicts the plan, update the checkpoint before moving on. Do not silently abandon the contradicted hypothesis — record it as a rejected path so the contradiction is not forgotten and re-litigated.
• When a branch completes, fold it into a result capsule and drop the branch's raw trial-and-error.
• When the question changes, carry forward only facts that directly support the new question.

Reset rule and reset threshold

When drift is detected, do not keep pushing. Reset the active contract:

1. Freeze the old checkpoint in one short paragraph.
2. Name the new active question.
3. Carry forward only facts that directly support the new question.
4. Move contradicted plans and old assumptions to rejected paths.
5. Reclassify every remaining source into the four intake buckets before reading more.

There is a point past which distillation stops paying off and a clean restart is cheaper. Reset threshold: when the window is so polluted that the agent repeatedly ignores the live checkpoint, contradicts facts it just captured, or each distillation pass is immediately re-bloated — stop distilling in place. Write a durable checkpoint, then trigger a deliberate restart / compaction and rebuild selectively (§9) from that checkpoint rather than attempting yet another in-place trim.

7. Runtime Primitives That Support Context Management

These primitives are now common across agent runtimes and major libraries. They support context management; they do not replace it.

Three properties that change how you use these primitives

Knowing the cost is agent-side discipline; configuring the policy is context-window's job.

• A cleared tool result usually leaves a placeholder — the model keeps awareness that a result existed, without its content. Clearing is not amnesia: the agent can re-fetch by reference if the capsule's "Re-open if" fires.
• Eviction is not free — dropping content the prompt cache had warmed invalidates that cache prefix, so reflexively clearing on every turn trades a token saving for a recompute cost. Clear only after a capsule has replaced the raw content and enough tokens are freed to justify breaking the prefix — not on a timer.
• Persisted memory is durable; the live window is not — a fact written only into the window dies at compaction, while a fact written to a re-readable file survives. Persist anything the next session must not re-derive.

Upstream-displacement check: no current runtime fully supersedes this skill. Anthropic, OpenAI, OpenCode, and LangChain now expose stronger prompt caching, compaction, clearing, trimming, memory, and isolation mechanisms. Those are mechanical supports. The unsolved part is still selection judgment: what is load-bearing, what is stable enough for a reusable prefix, what is stale, what is falsified, what should be reopened, and what a successor needs.

8. Compaction-Ready Handoffs

This skill does not own token math or compaction triggers. It owns handoff quality — the artefact a successor agent reads when the current session compacts, restarts, or hands over.

The handoff is the Active Context Contract (Section 2) frozen at the moment the session ends — same fields, written down. So the work is not a separate ritual: if you have kept the contract live, the handoff already exists.

Modern runtimes increasingly compact automatically — summarizing and re-initiating the window when it nears its limit, trimming session history, and clearing stale tool results without a manual "write the handoff now" moment — so you often do not choose when compaction fires. The defensive consequence: keep the checkpoint continuously fresh as a living artefact. A handoff you only intend to write "before compacting" is a handoff you can lose to an automatic compaction you did not see coming.

Before any compaction, restart, or handover — and in the living contract you maintain throughout — preserve these fields:

1. The active task (identifier, link, or short description)
2. The current question (one sentence)
3. The strongest supported hypothesis (and the evidence supporting it — may ride with proven facts)
4. The evidence already verified (proven facts the next session should not re-prove, as evidence handles/capsules)
5. The rejected paths (one-line tried X — ruled out because Y markers, so the successor does not re-explore a dead end you already closed)
6. The next concrete step (the action a successor would take if they had no other context)

Rejected paths are not optional padding: omitting them is the single most common way a resumed session burns its first hour re-walking a path the prior session had already falsified.

Write the first pass high-recall: err toward keeping every fact that might be needed to resume. Then tighten for precision by cutting the genuinely superfluous detail. It is cheaper to trim an over-complete handoff than to reconstruct a fact a terse one dropped.

Good handoff format

If the handoff cannot tell another agent where to start in under thirty seconds of reading, it is incomplete. Optimise for the cold start, not for the agent that already has full context.

9. Recovery After Lost Context

When the thread is lost — after compaction, after a session restart, after a long context-switching gap — rebuild selectively, in this order:

1. Re-read the user request (the canonical task statement, not your own paraphrase).
2. Re-read the last checkpoint (the durable contract, continuation artefact, or most recent agent-written summary).
3. Re-open only the files that directly support the current question — not "everything that might be relevant." Omit any raw source already distilled into an evidence capsule.
4. Reconstruct the current hypothesis from evidence (and the current file state), not from memory of what you used to think.
5. Resume from the next unverified step.

Do not "warm up" by re-reading everything. Recovery is a selective rebuild, not a context flood. Loading 30 files to "get back into the task" recreates the original drift on a fresh canvas.

10. Vocabulary and Source Trail

This skill uses task-level operational names so an agent can act without first learning one vendor's vocabulary. The table maps those names to terms used in current agent-engineering docs — for recognition and transfer, not scope expansion. The mechanisms those terms name as runtime features (configuring a context-editing policy, wiring a persistent memory store, sizing per-zone token budgets) belong to the runtime and to context-window / a persistent-memory skill, not here. This skill owns the agent-side discipline that uses them well.

This bridge prevents the skill from silently re-inventing terms the field has already settled.

Outbound source provenance

Provenance for the web-derived concepts this skill carries (each entry: source + why it is cited). These are recognition pointers, not required reading, and they are deliberately not registered as drift-tracked truth_sources — the skill stays principle-grounded and portable rather than citation-bound.

…(truncated)