5.1 - Context Window Management

Build exercise: Build a Persistent Case Facts Context Manager

Intermediate · 45 minutes

You'll practice:

• Implement the persistent case facts block pattern to protect transactional data from summarisation
• Trim verbose tool results to relevant fields before they accumulate in context
• Recognise and mitigate the progressive summarisation trap for numerical values, dates, and identifiers
• Apply the lost-in-the-middle mitigation by placing key findings at the beginning of aggregated inputs
• Understand that the Claude API is stateless and each request must include complete conversation history

1. Create a case facts extractor that identifies transactional data (amounts, dates, order numbers, statuses) from tool results

   The persistent case facts block is the single most important pattern in context window management. Extracting transactional facts into a structured block that is never summarised prevents the progressive summarisation trap from destroying critical numerical values and identifiers.

   You should see: A function that takes raw tool output and returns a structured object containing only the transactional facts: customer ID, order numbers, amounts, dates, and statuses. Non-transactional narrative content should be excluded.

   Hints

   1. Focus on data types that summarisation destroys: numbers, dates, identifiers, and statuses. These are the fields a support agent needs to process a refund.

   2. Define a fixed set of transactional field types to extract: monetary amounts, dates, order/reference numbers, status values, and customer identifiers.

   3. function extractCaseFacts(toolResult) {
        return {
          customerId: toolResult.customer_id,
          issues: [{
            orderId: toolResult.order_id,
            orderDate: toolResult.order_date,
            refundAmount: toolResult.total_amount,
            status: toolResult.status,
            itemDescription: toolResult.item_description
          }]
        };
      }
      
      // Usage: extract facts from every tool result
      const caseFacts = extractCaseFacts(orderLookupResult);

2. Implement a persistent case facts block that is prepended to every prompt, outside summarised history

   The case facts block must persist across every turn regardless of what happens to the conversation history. It sits outside the summarised portion of the context, ensuring amounts, dates, and order numbers survive even when earlier conversation turns are compressed.

   You should see: A prompt construction function that always includes the case facts block at the top of every message, followed by any summarised history, followed by the current turn. The case facts block should be clearly delimited with a section header.

   Hints

   1. Use a clear delimiter like a section header to separate the case facts block from the conversation history so the model treats them differently.

   2. The case facts block should be formatted as structured data (JSON or a clear key-value list) prepended to the system prompt or first user message of every API call.

   3. function buildPrompt(caseFacts, summarisedHistory, currentMessage) {
        const caseFactsBlock = `## Active Case Facts (DO NOT SUMMARISE)\n` +
          `${JSON.stringify(caseFacts, null, 2)}\n\n`;
        
        return [
          { role: "user", content: caseFactsBlock + summarisedHistory },
          { role: "assistant", content: "I have the case facts and history." },
          { role: "user", content: currentMessage }
        ];
      }

3. Build a tool result trimmer that filters order lookup responses from 40+ fields to only the 5 relevant return-related fields

   Untrimmed tool results are a silent context budget killer. An order lookup returning 40+ fields consumes tokens in every subsequent turn as conversation history grows. Trimming to relevant fields before results enter context is essential, not optional.

   You should see: A trimming function that takes a raw tool result object and returns only the fields needed for the current task. The trimmed result should be 80-90% smaller than the original.

   Hints

   1. Implement this as a PostToolUse hook or within the tool implementation itself, before the result enters conversation history.

   2. Define the relevant fields based on the task context. For a refund workflow: order_id, order_date, total_amount, return_eligible, and item_description.

   3. function trimToolResult(rawResult, relevantFields = null) {
        if (!relevantFields) {
          relevantFields = [
            "order_id", "order_date", "total_amount",
            "return_eligible", "item_description"
          ];
        }
        return Object.fromEntries(
          Object.entries(rawResult).filter(([k]) => relevantFields.includes(k))
        );
      }
      
      // Before: 40+ fields, ~2000 tokens
      // After: 5 fields, ~200 tokens
      const trimmed = trimToolResult(orderLookupResult);

4. Test with a multi-turn conversation where summarisation occurs and verify that transactional facts survive intact across all turns

   This validates that the persistent case facts pattern actually works. The exam tests whether you understand that progressive summarisation destroys specific amounts and dates, and the case facts block is the fix. You need to verify this empirically.

   You should see: A 6-8 turn conversation where summarisation occurs after turn 4. After summarisation, the agent should still reference the exact refund amount ($247.83), order number (#8891), and date (March 3rd) from the case facts block. Without the block, these values would be lost to summarisation.

   Hints

   1. Run two versions: one with the case facts block and one without. After summarisation, ask the agent to confirm the refund amount and order number. The version without the block will lose specifics.

   2. Simulate summarisation by replacing turns 1-4 with a compressed summary after turn 4, keeping the case facts block intact in both versions.

   3. // Simulate multi-turn conversation with summarisation
      const caseFacts = { orderId: "#8891", refundAmount: "$247.83", orderDate: "2024-03-03" };
      
      // Turn 5: after summarisation
      const withCaseFacts = buildPrompt(caseFacts, "Customer wants a refund for a recent order", "Please confirm the refund details.");
      // Agent should reference: $247.83, #8891, March 3rd
      
      const withoutCaseFacts = buildPrompt(null, "Customer wants a refund for a recent order", "Please confirm the refund details.");
      // Agent will say: your recent refund request (no specifics)

5. Add key findings placement logic that positions summaries at the beginning of aggregated inputs to mitigate the lost-in-the-middle effect

   Models process information at the beginning and end of long inputs reliably, but findings buried in the middle may be missed. Placing key findings summaries at the start of aggregated inputs is a structural fix for this well-documented phenomenon.

   You should see: An aggregation function that places a Key Findings Summary section at the top of combined inputs, followed by detailed results with explicit section headers. The key findings should be concise bullet points drawn from the detailed content.

   Hints

   1. The fix is structural, not prompt-based. Do not tell the model to pay attention to everything. Instead, reorganise the input so critical information is at the beginning.

   2. Extract one-line summaries from each source and place them in a Key Findings Summary section at the top. Follow with detailed results using clear section headers.

   3. function aggregateWithKeyFindings(sources) {
        const keyFindings = sources.map(s => `- ${s.name}: ${s.keyClaim}`);
        
        return `## Key Findings Summary\n${keyFindings.join("\n")}\n\n` +
          `## Detailed Findings\n\n` +
          sources.map(s => `### ${s.name}\n${s.fullContent}`).join("\n\n");
      }
      
      // Key findings at top, detailed content with headers below
      // Mitigates lost-in-the-middle effect structurally