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.

Verification

• [ ] I can state the active question in one sentence
• [ ] I can fill the active-context contract (task / question / hypothesis / evidence / rejected / next step / handoff location) without hand-waving
• [ ] I know — and could explain — why each currently loaded source is in context
• [ ] I am carrying handles for useful-soon sources instead of payloads I do not yet need
• [ ] I have reduced raw inputs — including subagent reports and my own reasoning traces — into smaller written evidence capsules or checkpoints with provenance and re-open conditions
• [ ] I have replaced large tool outputs and exposed reasoning traces with masked observations or decision capsules before clearing them
• [ ] Stable reusable context is ordered before volatile per-turn context when prompt caching / prefix reuse matters
• [ ] I have removed or ignored disproven hypotheses from the active thread while preserving one-line rejected-path markers
• [ ] I have folded completed branches into result capsules instead of leaving trial-and-error active
• [ ] The handoff is just my live contract frozen — kept continuously fresh against automatic compaction, not deferred to a moment I might not control — with all required fields
• [ ] I am loading new context because _evidence demands it_, not because I feel uncertain
• [ ] One active hypothesis, one primary question, one verification target — no exceptions
• [ ] A successor agent could resume from my checkpoint in under thirty seconds
• [ ] Any outbound URL or external source carried into the active context has provenance and a reason for inclusion

Do NOT Use When

Skill Graph context

<!-- skill-graph-context:start (generated — do not edit by hand) -->

Classification

• Subject: agent-ops
• Public: true
• Domain: agent/context
• Scope: Deciding what to load into an active agent session, recovering from context drift, preparing compaction or restart, distilling raw inputs into a working summary, and writing a resumable handoff — intake triage, the active-context contract, the six-step context-management loop, working-set shaping, evidence capsules, observation masking, just-in-time handle-before-payload loading, prompt-caching alignment, context-rot defenses, drift signals, anti-drift reset rules, the runtime-primitives boundary, compaction-ready handoffs, and selective rebuild after context loss. Portable across any agent session; principle-grounded, not repo-bound. Excludes token math (context-window), prompt wording (prompt-craft), persistent memory curation, and multi-graph context architecture (context-graph).

When to use

• the session feels noisy and I'm re-reading the same files — what discipline pulls it back?
• the agent keeps citing assumptions that were already disproven — how do I clear them out?
• I'm about to compact — what do I need to preserve so the next session resumes correctly?
• the thread is lost; what's the recipe for rebuilding only what's needed instead of warming up everything?
• I have a 300-line error log and a 600-line component file in context — how do I distill them?
• the active question changed three times this session — how do I prevent the old context from steering the new one?
• this conversation has 40K tokens of evidence; what should the working set actually contain?

Not for

• calculate the per-zone token budget for the 200K context window
• improve this prompt template for the grader
• curate the persistent memory index file
• design the multi-graph architecture for skills + docs + memory
• review this AI-generated PR for correctness
• why is this skill not routing — fix the keyword config

Related skills

• Verify with: context-engineering
• Related: prompt-craft, tool-call-strategy, context-engineering, context-graph, summarization

Keywords

• context management, working set discipline, intake triage four buckets, context drift recovery, context management loop, compaction-ready handoff, distill raw inputs, one active hypothesis, selective context rebuild, lost-thread recovery

<!-- skill-graph-context:end -->