An agent can only reason about what is in front of it. Context engineering is the discipline of deciding what that is — and what it is not.

What is in the window

A typical agent context contains:

The window is shared. Adding a large file means removing something else, or paying more per call, or exceeding the limit. There is no free context.

The quality problem, not just the size problem

A bigger window does not automatically mean better reasoning. Models attend unevenly across long contexts. Information in the middle can be missed. Irrelevant text can distract. A 100K-token context full of noise can perform worse than a 10K-token context with the right evidence.

Practical consequences:

• Put the task and constraints near the top and repeat the critical ones at the point of use.
• Prefer a focused retrieval set over a dump of everything.
• Label sources and sections clearly.
• Remove stale tool output that no longer matters.
• Keep a short “current state” block that summarizes what is known, what was tried and what remains.

This is sometimes called avoiding “context rot.” The model is not a database; it is a reasoning engine with a limited working memory.

Retrieval is not free

Retrieval-augmented generation (RAG) fetches relevant external text into context. It scales memory beyond the window, but it introduces its own failure modes:

• Recall failure — the relevant document was not retrieved.
• Ranking failure — it was retrieved but ranked below less useful chunks.
• Chunking failure — the relevant passage was split across chunks.
• Freshness failure — the index is stale.
• Trust failure — the retrieved text contains instructions (prompt injection).
• Context bloat — too many chunks crowd out the task.

A good retrieval pipeline logs what was retrieved, why, and which chunks the model actually used. Without that, a wrong answer is indistinguishable from a missing document.

Compaction strategies

When the context approaches its limit, the harness must reduce it. Options:

1. Truncate oldest messages. Simple, but may drop the original task or a critical constraint.
2. Summarize history. Replace older turns with a model-generated summary. Cheap, but lossy.
3. Summarize + pin. Keep a structured “facts and decisions” block that is never summarized away.
4. Retrieve on demand. Replace history with a searchable store and fetch relevant pieces.
5. Subagent isolation. Move a subtask into a separate context, return only the result.
6. Structured state. Keep the task state in a database or file, and include only the current view in the prompt.

The best systems combine several. The key distinction:

• Decisions and constraints — must survive. “Use 422, not 400.” “The staging database is read-only.” “Do not touch the generated files.”
• Evidence — keep a pointer and a short excerpt. Raw logs live in durable state.
• Exploration — compress aggressively. The agent does not need every failed search result.
• Unresolved errors — keep verbatim until resolved. A paraphrased stack trace is often useless.

A compaction policy

A practical policy:

if context_tokens > 80% of window:
  1. Drop duplicate tool outputs.
  2. Replace old file reads with path + line range + a one-line note.
  3. Summarize completed subtasks into decisions and outcomes.
  4. Move raw logs to the event store, keep a reference.
  5. Never summarize: user constraints, acceptance criteria,
     unresolved failures, pending approvals.
  6. If still over budget, ask the model for a structured summary
     and validate that pinned facts are present.

Step 6 is important: after summarizing, check that the pinned facts actually survived. A summary that omits the acceptance criteria is a correctness bug, not a token optimization.

Context caching

Inference engines can cache the KV state for a shared prefix, reducing prefill cost and TTFT. For agents, this is powerful:

• The system prompt and tool schemas are identical across calls.
• A long repository map or retrieved document may be reused.
• A subagent’s context is separate and can be cached independently.

But caching interacts with context management:

• Changing the system prompt invalidates the cache.
• Reordering messages can break prefix matching.
• Per-tenant caches need isolation.
• A cache hit is not a guarantee that the content is still correct.

Design prompts with a stable prefix: system instructions first, then tools, then stable reference material, then the changing conversation. This is good for both caching and human readability.

Context for subagents

A subagent gets its own context window. This is useful for isolation and parallelism, but it creates a handoff problem: the parent must pass enough context for the subagent to succeed, and the subagent must return a result the parent can use.

A good handoff includes:

• the task and acceptance criteria,
• relevant files or references,
• constraints and permissions,
• what has already been tried,
• the expected output format.

A bad handoff is “figure it out” plus a vague goal. The subagent then re-explores everything, wastes tokens and returns a summary that may not match the parent’s state.

Measuring context health

Track:

• Context utilization per call (tokens used / window).
• Compaction frequency and how much was removed.
• Pinned-fact survival rate after compaction.
• Retrieval hit rate and which chunks were cited.
• Task success rate by context strategy.
• Cost per task — context tokens are paid on every call.

If compaction is frequent, the task may be too large for one context. Split it, use a subagent, or move state to durable storage.

Next: tools and MCP — how to design the interface between a model and the world, including the error messages that determine whether it recovers or loops.