| name | common-context-optimization |
| description | Maximize context window efficiency, reduce latency, and prevent lost-in-middle issues through strategic masking and compaction. Use when token budgets are tight, tool outputs overflow the context, conversations drift from intent, or latency spikes from cache misses. |
| metadata | {"triggers":{"files":["*.log","chat-history.json"],"keywords":["reduce tokens","optimize context","summarize history","clear output"]}} |
Priority: P1 (HIGH)
1. Observation Masking (Noise Reduction)
Problem: Large tool outputs (logs, JSON lists) overwhelm context and degrade reasoning.
Solution: Replace raw output with semantic summaries after consumption.
- Identify outputs exceeding 50 lines or 1 KB.
- Extract critical data points immediately.
- Mask by rewriting history to replace raw data with summary placeholder.
- See
references/masking.md for patterns.
See implementation examples for masking patterns.
2. Context Compaction (State Preservation)
Problem: Long conversations drift from original intent.
Solution: Recursive summarization that preserves State over Dialogue.
- Trigger compaction every 10 turns or 8k tokens.
- Compact:
- Keep: User Goal, Active Task, Current Errors, Key Decisions.
- Drop: Chat chit-chat, intermediate tool calls, corrected assumptions.
- Format: Update System Prompt or Memory File with compacted state.
- See
references/compaction.md for algorithms.
See implementation examples for compacted state format.
3. KV-Cache Awareness (Latency)
Goal: Maximize pre-fill cache hits.
- Static Prefix: Enforce strict ordering — System -> Tools -> RAG -> User.
- Append-Only: Never insert into middle of history; append new turns only.
References
Anti-Patterns
- No raw tool dumps: Mask large outputs immediately after extracting data.
- No unbounded growth: Compact every 10 turns to preserve intent over dialogue.
- No middle insertions: Append-only history maximizes KV cache hits.
