Manage conversation context to preserve critical information across long interactions

The Claude Messages API is stateless: every request must carry the full messages array, and the model has no server-side memory of prior turns. To maintain conversational coherence across a long interaction you resend the complete conversation history on each request, so the model can reason over everything the customer said and everything the tools returned. In the Agent SDK and the raw API you own that transcript, unlike a consumer chat product that appears to "remember" for you.

Because you own the transcript, you also own its cost. Every token of history is re-billed and re-processed on every turn, and the context window is finite. That creates a real tension: dropping older turns to save tokens breaks coherence (the agent forgets what the customer already told it), but keeping everything raw blows the budget and dilutes the model's attention.

The rest of this lesson resolves that tension. Keep the full history the model needs for coherence, but compress the parts that are expensive and low-value (verbose tool results), and protect the parts that are cheap but fragile (exact numbers, dates, IDs) in a dedicated structure that summarization can never touch.

As history grows, a common tactic is progressive summarization: periodically replace older turns with a condensed summary to reclaim tokens. Summarization is excellent for narrative and intent, for example "the customer is disputing a duplicate charge and is frustrated after two failed calls." It is dangerous for precision.

Prose summaries reliably lose exact numerical values, percentages, dates, order numbers, statuses, and customer-stated expectations, which are the very facts a support or extraction workflow depends on. A summary that reads "the customer wants a refund for a recent order" has silently dropped that it was order #A-4471, that the amount was $650, and that the customer was promised a 3-day turnaround. Two turns later the agent quotes the wrong figure, re-asks a question the customer already answered, or refunds the wrong amount.

The rule is simple: summarize the narrative, never the load-bearing facts. Anything the agent must reproduce exactly should be pulled out and stored verbatim before summarization runs, not entrusted to a paraphrase.

The fix for lossy summarization is to extract transactional facts into a persistent "case facts" block that lives outside the summarized history and is re-injected verbatim into every prompt. Store it as structured data so it stays unambiguous and cheap to carry:

{
  "case_facts": {
    "customer_id": "C-88213",
    "order_id": "A-4471",
    "refund_amount_usd": 650.00,
    "order_date": "2026-06-14",
    "status": "delivered_damaged",
    "promised_resolution": "3-day replacement"
  }
}

Because this block sits outside the region that gets summarized or compacted, no summarization pass can overwrite it. For multi-issue sessions (a single customer with three separate disputes) keep a separate context layer keyed per issue, each carrying its own order IDs, amounts, and statuses, so facts from one issue do not bleed into another. Think of it as a small typed scratchpad that rides along with the conversation and always reflects ground truth.

Tool results accumulate in context and consume tokens disproportionately to their relevance. A single order lookup might return 40+ fields (billing address, carrier metadata, internal flags, tax breakdowns) when the return workflow only needs about 5: order ID, item, amount, status, and order date. If you append the raw payload every turn, it stays in the transcript forever, gets re-billed on every iteration, and dilutes the model's attention across noise.

Trim tool outputs to only the relevant fields before they enter the transcript. The cleanest place to do this is a PostToolUse hook or the tool wrapper itself, so the trimming is deterministic rather than something you ask the model to do:

// PostToolUse: keep only return-relevant fields
const { order_id, item, amount, status, order_date } = raw;
return { order_id, item, amount, status, order_date };

This is usually the single highest-leverage token saving in an agent, because tool results dominate context growth. Note the difference from a prompt instruction: you physically shrink the payload, you do not merely ask the model to ignore fields, which it may not reliably do.

Models reliably process information at the beginning and the end of a long input but may omit content buried in the middle. This "lost in the middle" effect is a property of long-context attention, not something you can fully prompt away, and it gets worse as the input grows.

Two layout tactics mitigate it. First, place a key-findings summary at the very beginning of an aggregated input, so the most important conclusions sit in a high-attention region rather than being discovered (or missed) deep inside. Second, organize detailed results with explicit section headers, so each section has a salient anchor and the model can navigate the structure instead of skimming an undifferentiated wall of text. The recent turns and the current question naturally fall at the end, which is also high-attention.

What you must never do is drop a critical figure, or an entire subtopic, into the middle of a 40k-token block and assume it will be used. In a research synthesis, that is exactly how a report ends up covering the first and last sources well while quietly omitting everything in between.

In multi-agent systems, every downstream agent has its own limited context budget, so what upstream agents return is decisive. If a web-search subagent hands the synthesis agent verbose page content plus its full reasoning chain, the synthesizer's window fills with low-value text and the actual facts get crowded out or lost in the middle.

Instead, modify upstream agents to return structured data: key facts, citations, and relevance scores rather than raw content and reasoning chains. Require subagents to include the metadata downstream synthesis needs to stay accurate, including publication or data-collection dates, source URLs, document names, page numbers, and methodological context. Dates in particular prevent temporal differences from being misread as contradictions, and source mappings preserve attribution through the synthesis step.

{
  "claim": "Adoption rose 34% in 2025",
  "source": "gartner.com/ai-2025",
  "published": "2026-01-12",
  "relevance": 0.91
}

This is the multi-agent expression of the same principle used in the case-facts block: pass the distilled, metadata-rich signal, not the raw transcript, so each agent spends its budget on reasoning rather than on re-reading noise.