Context Engineering

A well-designed tool still fails if the window around it is unmanaged.

Six surfaces and 24 practices, each tagged by when it applies in a run and by what implements it. An eight-symptom table points each symptom to a fix. A window ledger covers three run horizons.

Updated November 2, 2026 First published August 16, 2026

38 min read

Markdown

Every tool definition, every retrieved passage and every prior turn compete for the same fixed context window. That holds for one call and for a fleet of delegated agents working a single task for hours. A bigger window does not end the competition. It only moves the ceiling. This page covers four decisions. It covers what occupies the window at each step. It covers what gets summarized or dropped as a run grows. It covers what moves to durable storage outside the window. It covers how to draw a clean boundary when one unit of work hands off to another.

Three other pages sit on adjacent ground. This page names the split once so a reader does not have to guess it. The Agent Tool Interface covers designing one tool interface well. It already carries four practices on this ground under its own context surface. This page links to stable-prefix-first, budget-the-window, compact-on-a-rule and keep-data-separable-from-instructions by anchor. It does not restate them. MCP in Production covers running an integration layer across an organisation: identity, the catalog, supply chain. The Agentic Delivery Playbook covers operating a fleet of coding agents: tasks, gates, spend. This page covers what occupies the window at every step of a long run. The run can involve any number of tools, integrations or delegated agents.

The six surfaces

Where a long-running window actually breaks.#

Each surface fails a different way. Most failures trace back to something never getting a budget in the first place.

Three of context engineering's six surfaces act within a single turn. Two act across a run, and one acts across many runs.

Budget & allocation

Covers: The window as a fixed resource. It splits across instructions, tool definitions, retrieved content, running history and the task itself. Each slice needs an owner who answers for what it costs.

Breaks when: The task is assembled last, after everything else has claimed its share. It is the first thing cut when the window runs out.

Watch: Whether every slice in a run has a named owner and a written share, rather than a shared pool nobody is actually rationing.

Selection

Covers: What gets pulled into a given step. Content is either preloaded at session start or fetched just in time. Anything retrieved needs a relevance floor. A wider retrieval set can make an answer worse, so the discipline must stop that.

Breaks when: A bigger retrieval set reads as more thorough and instead buries the one passage that mattered under nine that were merely on-topic.

Watch: The share of retrieved tokens a response actually cites or acts on, against the share it silently carried and ignored.

History & compaction

Covers: What a long-running conversation or agent loop keeps, drops or summarizes as it outgrows the window. The change should follow a stated rule. Without one, it becomes a scramble once the window is full.

Breaks when: Compaction runs for the first time under pressure. Whatever is oldest or least structured gets cut first. That is usually the goal and the constraints that a long-running task most needed to keep.

Watch: Whether the original goal, active constraints and open commitments survive the fifth compaction pass as well as they survived the first.

State outside the window

Covers: Durable state that lives outside any single context window. Examples are files, working notes and a task registry. This covers what belongs there. Anything not stored there gets carried in-window turn after turn.

Breaks when: Everything worth remembering is kept in-window by default. It falls out when the window turns over. Or it gets re-explained at real token cost on every step.

Watch: Whether a fact written once to durable storage is read back in on the step that needs it. A failing run re-derives it or asks for it again.

Isolation & delegation

Covers: A clean context windowThe context window is the maximum text, measured in tokens, a model can consider at once. handed to one unit of work at a time. It also covers the handoff contract between units. It states what may cross that boundary and what the other side must re-derive.

Breaks when: A subtask inherits the entire parent window instead of a scoped handoff, so it reasons over context nobody actually curated for its job.

Watch: How much of a delegated unit's starting window is context it actually referenced, against context it simply inherited by default.

Integrity & measurement

Covers: Instructions kept structurally apart from data at scale. The provenance of everything in the window. Ordering that survives a compaction pass. A per-turn log, so a context problem is diagnosable after the fact.

Breaks when: Retrieved content and a real instruction sit in the same undifferentiated stream, with nothing in the format telling the model which is which.

Watch: Whether a context-related incident produces a specific per-turn span to inspect, or just a shrug and an account of the model getting worse.

The practice bank

24 practices, six surfaces.#

Filter by when in a run a practice applies, or by what actually implements it, then copy the visible list as a Markdown checklist.

01 Budget & allocation

A context window isn't elastic just because a provider raised the advertised limit. Every token spent on a tool definition, retrieved text or an old transcript is a token the instructions and the task cannot use. A bigger window does not change that arithmetic. It only moves the ceiling. /tool-design/ already covers writing down a per-slice token budget and alarming when one crosses it (see stable-prefix-first and budget-the-window). This surface is the layer above that. It decides who owns the allocation decision across an entire run. It also reserves room for the response itself before the rest of the window claims it. A window with no output reserve produces a response cut off mid-sentence. To a user, that reads like a stalled system. The real cause is the budget.

Reserve a fixed share of the window for the model's own output before anything else claims it

Per turn Prompt

What it is: An explicit, protected token allowance for the response itself. Set it before instructions, tool definitions, retrieved content or history are assembled. Do not use whatever happens to be left over.
How to build it: Compute the output reserve first, subtract it from the total window, and only then allocate the remaining space across every other slice.
Produces: A response that finishes instead of one truncated mid-sentence because the rest of the window filled up first.
Tradeoff: A generous output reserve shrinks how much instruction, retrieval or history the same window can carry, which matters on a genuinely input-heavy step.
Prove it: A step run at every other slice's full allowance still completes its response without truncation, checked directly rather than assumed from headroom.

Give every context slice a named owner and a written share

Per run Orchestration

What it is: A per-slice owner (instructions, tool defs, retrieved content, history, task) accountable for what that slice costs. A shared pool leaves everyone assuming someone else is rationing it.
How to build it: Assign the owner at design time alongside a numeric or proportional share, and revisit the assignment whenever a new slice type joins the run.
Produces: A run where a slice that starts growing has a specific owner to flag it, instead of a shared budget nobody is actually watching.
Tradeoff: Named ownership adds a real coordination step whenever a new context source joins the run, friction worth having against a budget nobody owns.
Prove it: Every slice in the current run maps to a named owner in the design record, checked against the actual assembled context rather than assumed.

The Agent Tool Interface: Budget the window

Treat the window as a fixed, competed-for resource, not a bucket that expands to fit whatever gets assembled

Per run Prompt

What it is: A standing design assumption that every context source competes for the same finite space. Adding one shrinks the room left for the others.
How to build it: Model context assembly as an allocation decision with a fixed total. A budget review applies the same discipline to headcount. Do not append sources until something breaks.
Produces: A design conversation that asks what a new context source displaces, instead of only whether the new source is useful on its own.
Tradeoff: Treating the window as fixed means saying no to a genuinely useful addition until something else is cut to make room for it.
Prove it: The last context source added to a live run has a recorded answer for what it displaced, alongside what it added.

Alarm the moment any slice crosses its written budget, not once the whole window overflows

Per turn Instrumentation

What it is: A per-slice measurement on a live run. It fires the instant one slice exceeds its stated share. A single check for total window overflow fires too late.
How to build it: Instrument token counts per slice at assembly time. Compare each against its written allocation. Raise the alarm on the specific slice that broke budget. Do not alarm on the aggregate.
Produces: A fix that targets the slice that grew, such as a retrieval set or an unbounded history. A blanket truncation applied wherever the window runs out does not do this.
Tradeoff: Per-slice instrumentation costs real engineering time to build and keep current as new slice types join a run.
Prove it: A deliberately oversized test input on one slice trips that slice's specific alarm, checked directly rather than assumed from the aggregate limit.

02 Selection

Retrieval quality gets measured constantly on this site; how much of what's retrieved actually belongs in the window at all gets measured far less. A wider retrieval set looks like due diligence, and it is often the opposite. Picture a model reasoning over ten passages, nine of them merely topical. It finds the one relevant passage harder to weigh. Selection is the discipline of deciding what a given step needs before it is fetched. It ignores what the step might conceivably use. It also sets a real relevance floor. A fixed count pads itself out on a thin result set. The failure this surface exists to catch is quiet. A retrieval set grew because growing it felt safer. Nobody checked whether the growth helped.

Default to fetching content just-in-time, not preloading everything a task might need

Per turn Retrieval

What it is: A retrieval design that fetches content at the step that needs it. It does not load everything a task could touch into the window up front.
How to build it: Scope retrieval calls to the question of the current step. Reach for a broader preload only when a specific, named latency or availability constraint requires it.
Produces: A window where the content at any step is content that step is likely to use. No standing library rides along the whole run on the chance it helps.
Tradeoff: Just-in-time fetching adds a real retrieval call, and the latency it costs, at the exact moment the answer is needed.
Prove it: A sampled step's context is checked against what that step actually referenced, and the share of unused preloaded content is measured directly.

Set a relevance floor for what gets included, not a fixed top-K

Per turn Retrieval

What it is: A minimum relevance score a retrieved item must clear before it enters the window, checked in addition to any fixed count like top-5 or top-10.
How to build it: Score every retrieved candidate. Drop anything under a stated floor, whatever its rank. Let the count of included results vary from step to step. Do not fix it at a round number.
Produces: A window that never pads itself with a merely topical eighth result to fill a fixed slot count. A floor decides what enters.
Tradeoff: A strict floor sometimes returns fewer results than a fixed top-K would. A genuinely thin result set has to show as thin. Do not pad it out.
Prove it: A retrieval run against a query with few genuinely relevant matches returns fewer than the nominal top-K, rather than padding out to it.

Measure whether a wider retrieval set is actually helping before assuming it is

Across runs Instrumentation

What it is: A standing check that a larger retrieved set correlates with a better answer on the eval set. The check replaces the assumption that more context is always safer.
How to build it: Run the same eval cases at two or three retrieval widths. Compare pass rate directly. Do not widen the set on intuition whenever an answer looks incomplete.
Produces: Evidence for the width that actually helps a given task, which is very often narrower than the width that felt safer to configure.
Tradeoff: Running the comparison costs real eval time against every retrieval-width change, instead of trusting a single plausible-looking setting.
Prove it: The current retrieval width has a recorded eval comparison against at least one narrower setting, checked, not assumed from why wider felt safer.

Failure mode: Similarity is not relevance

Carry the source alongside every retrieved item, alongside its text

Per turn Retrieval

What it is: A structural provenance field on every retrieved chunk: which document, which system, how current. It travels with the content into the window, alongside the passage itself.
How to build it: Attach source metadata at retrieval time. Preserve it through to whatever renders the context. The model and a human reviewer can then both tell where a claim came from.
Produces: An answer traceable back to a specific source instead of one where retrieved text and the model's own reasoning are indistinguishable after the fact.
Tradeoff: Provenance metadata is itself tokens in the window. It costs real budget (see the budget surface above). The benefit pays off only when something needs checking.
Prove it: A claim in a sampled answer is traced back to the specific source record it came from, using only the metadata carried in context.

03 History & compaction

History is the slice that grows most predictably and gets managed least deliberately. A run that is going fine never seems like the moment to build the compaction path. The fix is treating compaction as a scheduled routine exercised while the window still has headroom, not an emergency response improvised the day it fills. What a compaction pass may drop matters as much as when it runs. A summarizer with no instruction to preserve the goal, the active constraints and any open commitment will compress those along with everything else. An agent that forgot what it was asked to do is a harder failure to spot than one that ran out of room.

Compact history on a rule written down in advance, never as an emergency response

Per run Orchestration

What it is: A stated compaction trigger, such as turns older than N or a slice crossing a named share. Define it before the run starts. Do not improvise a summarization once the window is already full.
How to build it: Publish the trigger condition alongside the design of the run. Execute compaction on that schedule even while the window has headroom. The mechanism then gets exercised before it is ever load-bearing.
Produces: A compaction pass that runs under normal conditions, with time to check what it kept. Do not improvise one under pressure that cuts whatever is oldest first.
Tradeoff: Compacting on a fixed schedule sometimes runs before it's strictly needed, spending the summarization cost earlier than a just-in-time trigger would.
Prove it: A run forced past its compaction trigger executes the pass on schedule. Check it against the published rule. Do not check it against whether the window happened to be full.

The Agent Tool Interface: Compact on a rule

Name the three things a compaction pass must never drop: the goal, active constraints, and open commitments

Across runs Orchestration

What it is: A fixed, explicit checklist a summarization step is required to preserve, regardless of how aggressively it compresses everything else in a long run's history.
How to build it: Write the checklist into the compaction routine itself. Validate its presence in the compacted output before accepting it. Do not trust a general-purpose summarizer to keep what matters.
Produces: An agent still knows what it was asked to do after the tenth compaction pass. It also still knows what it promised. It knows both as well as it did after the first pass.
Tradeoff: A protected checklist gives the summarizer less room to compress the sections it's actually free to shrink, so overall compaction is less aggressive.
Prove it: A long run is forced through several compaction cycles. It is then quizzed on its original goal and any open commitment. It answers correctly from the compacted state alone.

Summarize history that no longer fits, and reach for truncation only as a last resort

Per run Orchestration

What it is: A preference for lossy but structured summarization over blind truncation when history has to shrink. Reserve a hard cutoff for the case where summarization has no time or budget left to run.
How to build it: Build the summarization path first. Treat truncation as a documented fallback with its own trigger. Do not make it the default mechanism whenever the window fills.
Produces: A history that degrades to a shorter, still-coherent account of what happened, instead of one that stops mid-turn with no signal anything was cut.
Tradeoff: Summarization costs a model call and real latency that a blind truncation, being nearly free, doesn't.
Prove it: A run that hits its history limit produces a coherent summary of the dropped turns, checked against the fallback truncation path never having triggered instead.

Failure mode: Context overflow drops the task

Detect a repeated failed approach sitting in history before it gets read as fresh information

Per run Orchestration

What it is: A check that flags when the last several turns show the same failed action retried with no new information. It tells that apart from genuine progress that looks similar.
How to build it: Compare a candidate next action against recent history for a near-repeat of an action that already failed. Surface that comparison to whatever decides the next step. Do not trust the model to notice the pattern in its own transcript.
Produces: A loop that gets interrupted and redirected instead of one that reads its own failed attempt as informative context and tries the same thing again.
Tradeoff: A repeat detector can misfire on a legitimate retry with a genuinely new parameter, so it needs a real similarity threshold, not an exact match.
Prove it: A test run seeded with a repeated failing action gets flagged and redirected before a stated retry ceiling, checked directly against a live loop.

Failure mode: Unbounded agent loop

04 State outside the window

Not every fact worth keeping belongs in the window at all. A file, a working note or a task-registry entry can hold state far longer and far more cheaply than a context window can. This surface asks one question at the point something is produced. Does it need to survive past the current step? If so, write it out immediately. Do not carry it forward in the history of every turn. The re-entry side costs as much as the write side. A durable record that is expensive to read back in only moves the overflow problem from now to whenever it is needed again. Price that re-entry cost in the same decision as writing the record.

Write durable facts to storage outside the window, then read them back in on demand

Across runs Orchestration

What it is: A discipline where anything worth keeping past the current step is written to a file, a note or a registry entry. It is pulled back into context only on the step that needs it. It is not carried forward through the history of every later turn.
How to build it: Identify what needs to survive past this step at the point it is produced. Write it out immediately. Treat the in-window copy as disposable once it is persisted.
Produces: A window that does not pay the ongoing cost of restating something already stored. A fact that survives a compaction pass that would otherwise have dropped it.
Tradeoff: Writing state out costs a real step. Reading it back in costs a real retrieval. Both are paid against a task that could have kept the fact in the window a little longer.
Prove it: A fact written to durable storage early in a run is still correctly recalled several steps later, after the in-window copy has been compacted away.

Separate a disposable scratchpad from a durable note, and mark which is which

Across runs Orchestration

What it is: Two distinct classes of outside-window storage. A scratchpad is expected to be discarded at the end of the run. A durable note is expected to outlive it. State the distinction explicitly. Do not imply it by the folder a file happens to sit in.
How to build it: Name the class at the point of writing, scratch or durable. Give each its own retention rule and its own reader. A downstream step then never has to guess which kind of note it found.
Produces: A durable note survives a routine cleanup pass. A scratchpad does not become load-bearing unnoticed, because everyone knows it is temporary.
Tradeoff: Maintaining two classes with different retention rules is more moving parts than a single undifferentiated notes folder.
Prove it: A cleanup pass runs against the storage of a completed task. It removes every scratchpad entry and leaves every durable note intact. Check this against the stated class on each.

Price the token cost of reading a piece of outside-window state back in before deciding to persist it

Across runs Instrumentation

What it is: An explicit check, at the point something is written to durable storage, for how expensive it will be to read back into context later. A large persisted record only moves the budget problem from now to whenever it is re-entered.
How to build it: Estimate the re-entry token cost when the record is created. For anything read back often, prefer a compact, structured format over a full transcript dump.
Produces: Durable state that is cheap to re-enter on the step that needs it. The record is not so large that reading it back recreates the overflow problem it was written out to avoid.
Tradeoff: A compact persisted format loses some detail that a full dump would have kept. That is a real cost if the detail matters later.
Prove it: The token cost of reading the largest durable record in use back into a fresh window is measured. Nobody assumes it is negligible because it lives outside the window.

Keep durable state in a shared, queryable registry, not a private file only one run knows to check

Across runs Orchestration

What it is: A standing, shared location for state meant to outlive a single run, such as a task registry or a shared notes store. Any run that needs the state can query it. A file path known only to the run that wrote it does not count.
How to build it: Route anything meant to persist across runs through the shared registry. Do not use a working directory scoped to one session. Make the registry the first thing a new run checks.
Produces: State that a second, unrelated run can actually find and use, instead of a fact trapped in the first run's own private storage.
Tradeoff: A shared registry needs real access and naming conventions to stay usable as more runs write to it. A private per-run file never had to enforce that discipline.
Prove it: A fact written by one run is found and correctly used by an unrelated second run querying the shared registry. The second run does not inherit the files of the first.

CodeHerder

05 Isolation & delegation

This is where the delivery model of the studio earns its place on the page. A fleet of coding agents run through CodeHerder gets one clean context per stage. A handoff comment is the contract between stages. Nobody forwards a transcript. That shape generalises past coding agents. A subtask that starts from the full parent window carries every tool definition, every piece of retrieved content and every prior turn the parent accumulated. Much of it has no bearing on the narrower job the subtask received. A scoped handoff comes from a stated contract. It keeps the window of a delegated unit small enough to reason over cleanly. It also stops the context of a parent from ballooning with the needs of every subtask at once.

Start each unit of delegated work from a clean window scoped to its own job

Per run Orchestration

What it is: A fresh context window for a subtask or subagent. It holds only what that specific unit of work needs. It does not inherit the full parent window wholesale.
How to build it: Define the minimum context a delegated unit requires before it starts. Assemble only that. Resist the shortcut of forwarding the entire window of the parent because it is already there.
Produces: A subtask that reasons over context actually curated for its job, and a parent window that isn't bloated by carrying every subtask's needs at once.
Tradeoff: Scoping a clean window per unit of work costs a real design step at every delegation point. The zero-effort default is to pass everything along.
Prove it: A delegated unit's starting context is audited against what it actually referenced during its run, and the share of unused inherited context is measured.

The Agentic Delivery Playbook

Define a handoff contract between units of work, not a raw transcript dump

Per run Orchestration

What it is: A structured handoff passes between one unit of work and the next. It states what was asked, what was decided and what is still open. The entire raw transcript that produced it stays behind.
How to build it: Specify the fields a handoff must carry before the boundary is built. Require the sending unit to fill them explicitly. The receiving unit then never pages back through a full transcript to reconstruct what it needs.
Produces: A receiving unit that starts with exactly what it needs, stated plainly. It does not re-derive that from a transcript that was never written for the purpose.
Tradeoff: A structured handoff can drop nuance that only lived in the raw transcript's phrasing, a real loss if the receiving unit needed that nuance.
Prove it: A receiving unit given only the structured handoff, with the raw transcript withheld, completes its job correctly. Check this directly. Do not assume it from how thorough the handoff looks.

The Delivery Record

Decide explicitly what's allowed to cross a delegation boundary, and block the rest

Per run Orchestration

What it is: An enforced allowlist for what the context of a parent unit can pass to a delegated one. A second allowlist covers what the result of a delegated unit can pass back. An open channel that lets anything cross by default does not count.
How to build it: Name the specific fields permitted to cross each boundary at design time. Reject or strip anything else at the boundary itself. Do not trust each side to send only what is appropriate.
Produces: A delegation boundary that can't leak an unrelated credential, an unrelated user's data, or simply more tokens than the receiving unit's own budget allows.
Tradeoff: An enforced allowlist means a genuinely new field needed by a delegated unit requires a deliberate boundary update. Nobody adds it to whatever gets passed along.
Prove it: A field deliberately excluded from the boundary's allowlist is confirmed absent on the receiving side, tested directly rather than assumed from the design document.

Require a delegated unit to re-derive anything it needs to trust, rather than assume the parent's state still holds

Per run Orchestration

What it is: A rule that a delegated unit re-checks any fact it depends on for a correctness-relevant or safety-relevant decision. It does not trust a value the parent handed off as still current.
How to build it: Mark handoff fields that are safe to trust as-is separately from fields that need re-verification. Examples are the current state of a file, a permission grant and a price. Re-derive the latter inside the boundary of the delegated unit before acting on it.
Produces: A delegated unit that does not act on a stale assumption. The assumption came from a parent whose own state may have moved on since the handoff was written.
Tradeoff: Re-deriving anything genuinely re-checkable costs a real call the delegated unit could have skipped by trusting the handoff outright.
Prove it: A test changes the parent state after handoff and before the delegated unit acts. The delegated unit catches the change. It does not act on the stale value.

06 Integrity & measurement

A model reads one stream of tokens. No privileged channel marks an instruction apart from a retrieved passage or a tool return value. The trust-boundary and context surfaces of /tool-design/ cover why that matters for a single call. At the scale of a whole run, the same fact compounds. Content entered the window three compaction passes ago. A call nobody can trace retrieved it. It now sits next to instructions that survived unchanged. Nobody can audit that window. Carry provenance with the content. Keep ordering stable across a rewrite. Log what was assembled on every turn. Together these turn a context problem from a vague complaint into a specific span someone can open and inspect.

Mark retrieved content and tool output as data in the format itself, not by convention alone

Per turn Prompt

What it is: A structural distinction between an instruction and anything retrieved or returned. It can be a dedicated field, or a wrapping delimiter that the system prompt names explicitly as untrusted. Do not rely on everyone remembering to phrase retrieved text carefully.
How to build it: Wrap retrieved content and tool output in a format that the assembly code enforces. A prompt author should not have to apply it by hand on every call site.
Produces: A model that has an actual structural signal to weigh against an embedded instruction hiding inside retrieved text, instead of one undifferentiated stream of tokens.
Tradeoff: Structural marking adds real assembly-code discipline at every place context gets built, a cost worth paying once rather than skipped per call site.
Prove it: A labelled injection attempt is planted inside retrieved content and run through the full path. Confirm the structural marking is present around it. Confirm it is present around the system instructions too.

The Agent Tool Interface: Keep data separable from instructions

Stamp provenance on every piece of content that enters the window, including the parts a reviewer is unlikely to check

Per turn Instrumentation

What it is: A recorded source for every context item: which retrieval call, which tool response, which prior turn. It is carried alongside the item. A reviewer should not have to correlate it with a separate system log.
How to build it: Attach the provenance stamp at the point content enters context. Keep it attached through any compaction or summarization step. Do not let it drop out the first time the content is rewritten.
Produces: A context problem that's diagnosable from the window's own contents, not one that requires reconstructing which source contributed what after the fact.
Tradeoff: Carried provenance is itself tokens against the budget surface above, a cost that only pays off when something actually needs checking.
Prove it: A claim in a sampled response is traced to its provenance stamp alone. Nobody needs to consult a separate system log to confirm the source.

Keep a stable assembly order through every compaction and retrieval change, through the last call as much as the first

Per run Prompt

What it is: The stable-prefix-first rule of /tool-design/ applies to a single call. Hold the same discipline across an entire run. Put static content first and volatile content last. Preserve that order through every compaction pass. A pass must not reset it.
How to build it: Apply the ordering rule inside the compaction and retrieval-refresh routines themselves, in addition to the initial assembly code. A mid-run rewrite then cannot reorder what a later call depends on for caching.
Produces: A cache-read share that holds steady across a long run instead of resetting every time history gets rewritten.
Tradeoff: Enforcing stable ordering through a compaction pass constrains how that pass can restructure content, a real limit on how freely it can rewrite.
Prove it: Cache-read share is measured immediately before and after a compaction pass on the same run. The two numbers are close. The pass does not reset the hit rate.

The Agent Tool Interface: Stable prefix first

Log the shape of the assembled context on every turn, alongside the final response

Per turn Instrumentation

What it is: A per-turn record of what went into the window: which slices, roughly how large each, which sources. It is captured alongside the request and response logging a system already keeps.
How to build it: Instrument context assembly to emit its own shape as a structured log line on every turn. Retain it for at least as long as the matching response is retained.
Produces: A specific, inspectable record of what the model was looking at when something went wrong. Nobody has to reconstruct it afterward from an incomplete transcript.
Tradeoff: Per-turn context logging adds real storage volume over a long-running system, and needs the same redaction discipline any other request log needs for sensitive content.
Prove it: A context-related incident picked at random has its per-turn shape log recoverable, and that log alone is enough to identify which slice caused the problem.

Show, don't just state

A practice bank entry, as one turn's assembly.#

The same turn, assembled two ways: unbudgeted history, then fixed slots with a budget each.

The same turn, two assemblies.

One assembly re-sends everything it has. The other sends fixed slots, each with its own budget and its own owner.

What breaks turn-assembly.yaml

# One turn's context assembly
messages:
  - role: system
    content: "{{ entire_style_guide_file }}"
  - role: user
    content: "{{ full_chat_history }}"
  - role: user
    content: "{{ current_question }}"
# Re-sent in full, unbudgeted, on every single turn.

A whole style guide plus the full chat history, re-sent in full on every turn, unbudgeted.

What works turn-assembly.yaml

# One turn's context assembly, fixed slots
slots:
  - name: system_rules
    owner: platform
    budget_tokens: 400
    source: pinned_prompt
  - name: retrieved_context
    owner: retrieval
    budget_tokens: 1200
    source: vector_search(query, k=6)
  - name: recent_turns
    owner: session
    budget_tokens: 800
    source: last_n_turns(n=4)
  - name: current_turn
    owner: session
    budget_tokens: 300
    source: user_message
output_reserve_tokens: 1000

Fixed slots, each with a token budget and a named owner, plus a retrieval slice instead of a whole file.

The window is a fixed, competed-for total, so every slot gets a written share of it. Treat the window as competed
Every slot has one owner who is accountable for what sits in it. Name an owner per slice
Retrieve the slice a turn needs instead of preloading the whole document. Just-in-time over preloaded
The output gets a reserved slice of its own, not whatever the input happens to leave behind. Reserve the output slice

Failure signatures

Start from the symptom, not the taxonomy.#

Each row is something a real run does that looks like a model problem and isn't. It resolves to the surface that owns the fix and the specific practice that is the fix.

The response is cut off mid-sentence, right when it should be finishing.

Cause: Nothing reserved room for the output. Instructions, tool defs, retrieved content and history claimed the window first, and the answer ran out of space on the way out.

Budget & allocation The fix: Reserve a fixed share of the window for the model's own output before anything else claims it →

A crowded retrieval set comes back confidently, and the one document that actually answers the question isn't reflected in the response.

Cause: A fixed top-K padded the set with passages that were only on topic. No relevance floor applied. The one relevant passage competed with nine that were not.

Selection The fix: Set a relevance floor for what gets included, not a fixed top-K →

A long-running agent loses track of what it was actually asked to do partway through the task.

Cause: A compaction pass summarized the goal along with everything else. Nothing told it that the goal, the active constraints and the open commitments were content it could not compress away.

History & compaction The fix: Name the three things a compaction pass must never drop: the goal, active constraints, and open commitments →

The same failed action gets retried over and over, with no new information between attempts.

Cause: The failed attempt sits in history looking exactly like fresh information to reason from. Nothing checks recent history for a near-repeat before the next action runs.

History & compaction The fix: Detect a repeated failed approach sitting in history before it gets read as fresh information →

A fact established early in a session has to be re-explained on every turn after.

Cause: The fact was only ever kept in-window. It falls out of history the moment the window turns over or gets compacted. Nobody wrote it once to durable storage to read back on demand.

State outside the window The fix: Write durable facts to storage outside the window, then read them back in on demand →

A delegated subtask acts on information the parent had already learned was wrong.

Cause: The subtask treated a value from its handoff as current. It did not re-derive anything that affects correctness inside its own boundary before it acted.

Isolation & delegation The fix: Require a delegated unit to re-derive anything it needs to trust, rather than assume the parent's state still holds →

Prompt caching stops paying off partway through a long run, for no visible reason.

Cause: A compaction or retrieval-refresh pass rewrote content and broke the stable-prefix ordering. That reset the cache hit rate the run relied on.

Integrity & measurement The fix: Keep a stable assembly order through every compaction and retrieval change, through the last call as much as the first →

A document written in plain, unremarkable language quietly changes what the model does next.

Cause: Retrieved content sat in the same stream as real instructions. Nothing in the structure told the model which part was data.

Integrity & measurement The fix: Mark retrieved content and tool output as data in the format itself, not by convention alone →

The window ledger

What occupies the window, at three run horizons.#

No token counts or vendor window sizes here on purpose. The shape holds regardless of which model or context size a run happens to use.

Per turn

What occupies it: Everything assembled for this request: the system instructions, the tool catalog, what was retrieved for this question and the running history so far.
Typical failure: The task itself, added last, is the first thing truncated once the rest of the window has already claimed its space.
The discipline that holds: A protected output reserve and a per-slice budget, checked before anything is added rather than after the window overflows.

Per run

What occupies it: The accumulated state of one continuous task across many turns: everything the earlier turns established, plus whatever's been delegated out to subtasks and handed back.
Typical failure: History grows past what fits and gets compacted under pressure, cutting whatever is oldest rather than whatever is least important.
The discipline that holds: Compaction on a published schedule that protects the goal, the active constraints and any open commitments before anything else.

Across runs

What occupies it: Whatever must outlive the run that produced it. Examples are a durable note, a registry entry and a file that a later run reads.
Typical failure: A fact worth keeping was never written outside the window at all, so it vanishes the moment the run that produced it ends.
The discipline that holds: A write-then-read discipline through a shared registry, with the token cost of reading a record back in priced before it is persisted.

What this is built from

Grounded in mechanics, not a vendor's benchmark.#

No percentages, no token counts, no vendor context-window sizes, no third-party prevalence statistics. The arithmetic of a fixed, competed-for window is stable; those numbers rot in weeks.

/tool-design/ covers designing one tool's interface and already carries four practices on this exact ground under its context surface. This page is the layer above a single call. It covers what occupies the window across an entire run. That is well past what one tool definition or one response costs. The Agent Tool Interface
The Agentic Delivery Playbook is the first-party case for the isolation surface. A fleet of coding agents runs through CodeHerder with one clean context per stage. A handoff comment is the contract. Nobody forwards a transcript. The Agentic Delivery Playbook
The Delivery Record checks that handoff discipline against what shipped. It shows a real defect the review stage caught. It also shows the build-time check that now fails if the defect recurs. The Delivery Record
CodeHerder is the registry the memory surface argues for. It is a shared, queryable place for state meant to outlive one run. A fact does not stay trapped in the session that produced it. CodeHerder
Context overflow that drops the task, the unbounded agent loop and injection via retrieved content are named failure modes on this site. Each is the reason a specific practice above exists. Failure mode: Context overflow drops the task

Sources

arXiv - Lost in the Middle: How Language Models Use Long Contexts
The paper measuring how a fact's position in a context window affects recall. Retrieved 2026-08-24.
arXiv - Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks
The paper that named retrieval-augmented generation as a technique. Retrieved 2026-08-24.

Designing a long-running agent

A Ship Audit checks the window ledger above against the run you are building. It happens before the budget, compaction and isolation calls get made by default.

Book a Ship Audit → See the tool interface guide →

Questions

Before the window fills up.#

What teams ask us once a run stops fitting comfortably in a single context window.

01 Isn't this just prompt engineering with a longer name?

Prompt engineering is one input to it, not the whole discipline. This page covers what occupies the window across an entire run: retrieved content, tool catalogs, history, and state that lives outside the window entirely. It also covers the order of those items. That is a design and orchestration problem as much as a wording one.

Link to this answer

02 How is this different from /tool-design/?

/tool-design/ is about designing one tool's interface well and already owns four practices on this ground under its own context surface. This page starts where a single call stops mattering. It covers what occupies the window across a whole run. The run can be one agent or a fleet of delegated ones.

Link to this answer

03 We just bought a model with a much bigger context window. Does this still matter?

Yes. A bigger window changes where the ceiling sits. The ceiling still exists. A bigger window cannot fix a retrieval set that buries the relevant passage. It cannot fix a compaction pass that drops the goal. Budgeting and selection discipline get more forgiving at a larger size, not unnecessary.

Link to this answer

04 What's the single most common mistake on this page?

Treating compaction as an emergency response instead of a scheduled routine. A summarizer improvised the day the window fills has no instruction to protect the goal or open commitments. It cuts whatever is oldest, which is rarely what matters least.

Link to this answer

05 Do we need all 24 practices before our first agent ships?

No. Scope to what the run actually does: a single-turn assistant with no delegation needs the budget and selection surfaces far more than isolation. The failure-signature table above is the fast way to find which surface a symptom you're already seeing actually maps to.

Link to this answer

06 Where does the memory surface stop and a vector database start?

They solve different problems. Retrieval (chunk, embed, retrieve) is how a system answers from a large corpus. The memory surface here covers small, specific, durable facts that a run produces itself and needs back later. Examples are a decision, a constraint and a handoff note. Searching a document collection is a different problem.

Link to this answer

Pick the shape that fits

The same failed action retried with no new information is one of eight symptoms this page traces back to a cause. The architecture picker matches your own system to a shape like grounded answering, instead of a generic pipeline.

Use the architecture picker → See grounded answering →