---

name: context-optimization description: Use when optimizing agent context, reducing token costs, implementing KV-cache optimization, or asking about "context optimization", "token reduction", "context limits", "observation masking", "context budgeting", "context partitioning" version: 1.0.0

Context Optimization Techniques

Extend effective context capacity through compression, masking, caching, and partitioning. Effective optimization can 2-3x effective context capacity without larger models.

Optimization Strategies

Compaction

Summarize context when approaching limits:

Copyif context_tokens / context_limit > 0.8:
    context = compact_context(context)

Priority for compression:

1. Tool outputs → replace with summaries
2. Old turns → summarize early conversation
3. Retrieved docs → summarize if recent versions exist
4. Never compress system prompt

Summary generation by type:

• Tool outputs: Preserve findings, metrics, conclusions
• Conversational: Preserve decisions, commitments, context shifts
• Documents: Preserve key facts, remove supporting evidence

Observation Masking

Tool outputs can be 80%+ of tokens. Replace verbose outputs with references:

Copyif len(observation) > max_length:
    ref_id = store_observation(observation)
    return f"[Obs:{ref_id} elided. Key: {extract_key(observation)}]"

Masking rules:

• Never mask: Current task critical, most recent turn, active reasoning
• Consider: 3+ turns old, key points extractable, purpose served
• Always mask: Repeated outputs, boilerplate, already summarized

KV-Cache Optimization

Cache Key/Value tensors for requests with identical prefixes:

Copy# Cache-friendly ordering: stable content first
context = [
    system_prompt,      # Cacheable
    tool_definitions,   # Cacheable
    reused_templates,   # Reusable
    unique_content      # Unique
]

Design for cache stability:

• Avoid dynamic content (timestamps)
• Use consistent formatting
• Keep structure stable across sessions

Context Partitioning

Split work across sub-agents with isolated contexts:

Copy# Each sub-agent has clean, focused context
results = await gather(
    research_agent.search("topic A"),
    research_agent.search("topic B"),
    research_agent.search("topic C")
)
# Coordinator synthesizes without carrying full context
synthesized = await coordinator.synthesize(results)

Budget Management

Copycontext_budget = {
    "system_prompt": 2000,
    "tool_definitions": 3000,
    "retrieved_docs": 10000,
    "message_history": 15000,
    "reserved_buffer": 2000
}
# Monitor and trigger optimization at 70-80%

When to Optimize

Performance Targets

• Compaction: 50-70% reduction, <5% quality loss
• Masking: 60-80% reduction in masked observations
• Cache: 70%+ hit rate for stable workloads

Best Practices

1. Measure before optimizing
2. Apply compaction before masking
3. Design for cache stability
4. Partition before context becomes problematic
5. Monitor effectiveness over time
6. Balance token savings vs quality
7. Test at production scale
8. Implement graceful degradation