# Context Optimization

Extend effective context capacity through strategic techniques.

## Four Core Strategies

| Strategy | Target | Reduction | When to Use |
|----------|--------|-----------|-------------|
| **Compaction** | Full context | 50-70% | Approaching limits |
| **Observation Masking** | Tool outputs | 60-80% | Verbose outputs >80% |
| **KV-Cache Optimization** | Repeated prefixes | 70%+ hit | Stable prompts |
| **Context Partitioning** | Work distribution | N/A | Parallelizable tasks |

## Compaction

Summarize context when approaching limits.

**Priority**: Tool outputs → Old turns → Retrieved docs → Never: System prompt

```python
if context_tokens / context_limit > 0.8:
    context = compact_context(context)
```

**Preserve**: Key findings, decisions, commitments (remove supporting details)

## Observation Masking

Replace verbose tool outputs with compact references.

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

**Never mask**: Current task critical, most recent turn, active reasoning
**Always mask**: Repeated outputs, boilerplate, already summarized

## KV-Cache Optimization

Reuse cached Key/Value tensors for identical prefixes.

```python
# Cache-friendly ordering (stable first)
context = [system_prompt, tool_definitions]  # Cacheable
context += [unique_content]                   # Variable last
```

**Tips**: Avoid timestamps in stable sections, consistent formatting, stable structure

## Context Partitioning

Split work across sub-agents with isolated contexts.

```python
result = await sub_agent.process(subtask, clean_context=True)
coordinator.receive(result.summary)  # Only essentials
```

## Decision Framework

| Dominant Component | Apply |
|-------------------|-------|
| Tool outputs | Observation masking |
| Retrieved docs | Summarization or partitioning |
| Message history | Compaction + summarization |
| Multiple | Combine strategies |

## Guidelines

1. Measure before optimizing
2. Apply compaction before masking
3. Design for cache stability
4. Partition before context problematic
5. Monitor effectiveness over time
6. Balance savings vs quality

## Related

- [Context Compression](./context-compression.md)
- [Memory Systems](./memory-systems.md)