domains / agent-tooling / context-compression / context-compression

context-compression

Skill card

combined

The two copies share the same core philosophy (tokens-per-task, structured summaries, artifact trail) and the same example summary block, but they are not simple reproductions of one another. The muratcankoylan copy adds explicit routing boundaries to other skills (context-optimization, context-degradation, filesystem-context, memory-systems, self-managed-context) and a specific warning against opaque compression when debugging/artifact tracking is critical. The sickn33 copy adds a concrete compression trigger strategy table (fixed threshold, sliding window, importance-based, task-boundary) and a detailed probe-based evaluation framework with specific probe types and a six-dimension evaluation rubric. Because each copy contains material steps and constraints the other lacks, crowning one would hide a real alternative.

Repositories

Other copies

Combined skill

---
name: context-compression
description: "Use when long-running agent sessions need context compression, structured summarization, or durable handoff summaries that preserve decisions, files, risks, and next actions."
---

# Context Compression Strategies

When agent sessions generate millions of tokens of conversation history, compression becomes mandatory. The correct optimization target is **tokens per task**: total tokens consumed to complete a task, including re-fetching costs when compression loses critical information.

## When to Activate

Activate this skill when:
- Agent sessions exceed context window limits.
- Codebases exceed context windows (5M+ token systems).
- Designing conversation summarization strategies.
- Debugging cases where agents "forget" what files they modified.
- Building evaluation frameworks for compression quality.

**Do not activate** for:
- General token-efficiency tactics (masking, prefix caching): use `context-optimization`.
- Diagnosing why a long context is failing: use `context-degradation`.
- Writing raw outputs to files without summarizing: use `filesystem-context`.
- Designing long-term semantic memory: use `memory-systems`.

## Core Concepts

Context compression trades token savings against information loss. Select from three production-ready approaches:

1. **Anchored Iterative Summarization**: Best for long-running sessions where file tracking matters. Maintain structured, persistent summaries. When compression triggers, summarize only the newly-truncated span and merge with the existing summary. This prevents drift that accumulates when summaries are regenerated wholesale.
2. **Opaque Compression**: Reserve for short sessions where re-fetching costs are low and maximum token savings are required. Achieves 99%+ compression ratios but sacrifices interpretability. **Never use this when debugging or artifact tracking is critical.**
3. **Regenerative Full Summary**: Use when summary readability is critical and sessions have clear phase boundaries. Generates detailed structured summaries on each trigger. Weakness: cumulative detail loss across repeated cycles.

## Detailed Topics

### Optimize for Tokens-Per-Task

Measure total tokens consumed from task start to completion. If the agent repeatedly asks to re-read files it already processed, compression is too aggressive. Track re-fetching frequency as the primary quality signal.

### Solve the Artifact Trail Problem First

Artifact trail integrity is often the weakest dimension in compression evaluations. Address this proactively by preserving these categories explicitly in every compression cycle:
- Which files were created (full paths).
- Which files were modified and what changed (include function names).
- Which files were read but not changed.
- Specific identifiers: function names, variable names, error messages, error codes.

Implement a separate artifact index or explicit file-state tracking in agent scaffolding rather than relying solely on the summarizer.

### Structure Summaries with Mandatory Sections

Build structured summaries with explicit sections that act as checklists. Adapt sections to the agent's domain (e.g., "Root Cause" for debugging, "Source Schema" for migration).

```markdown
## Session Intent
[What the user is trying to accomplish]

## Files Modified
- auth.controller.ts: Fixed JWT token generation
- config/redis.ts: Updated connection pooling

## Decisions Made
- Using Redis connection pool instead of per-request connections

## Current State
- 14 tests passing, 2 failing

## Next Steps
1. Fix remaining test failures
2. Run full test suite
```

### Choose Compression Triggers Strategically

When to trigger compression matters as much as how to compress:

| Strategy | Trigger Point | Trade-off |
|----------|---------------|-----------|
| Fixed threshold | 70-80% context utilization | Simple but may compress too early |
| Sliding window | Keep last N turns + summary | Predictable context size |
| Importance-based | Compress low-relevance sections first | Complex but preserves signal |
| Task-boundary | Compress at logical task completions | Clean summaries but unpredictable timing |

The sliding window approach with structured summaries provides the best balance of predictability and quality for most coding agent use cases.

### Probe-Based Evaluation

Traditional metrics like ROUGE fail to capture functional compression quality. Use probe-based evaluation to measure functional quality by asking questions after compression:

| Probe Type | What It Tests | Example Question |
|------------|---------------|------------------|
| Recall | Factual retention | "What was the original error message?" |
| Artifact | File tracking | "Which files have we modified?" |
| Continuation | Task planning | "What should we do next?" |
| Decision | Reasoning chain | "What did we decide about the Redis issue?" |

Evaluate compression quality across six dimensions:
1. **Accuracy**: Are technical details correct?
2. **Context Awareness**: Does the response reflect current conversation state?
3. **Artifact Trail**: Does the agent know which files were read or modified?
4. **Completeness**: Does the response address all parts of the question?
5. **Continuity**: Can work continue without re-fetching information?
6. **Instruction Adherence**: Does the agent follow the original user intent?