context-compression

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Context Compression

上下文压缩

Reduce context size while preserving information critical to task completion.
在保留任务完成所需关键信息的同时减小上下文规模。

Overview

概述

Context compression is essential for long-running agent sessions. The goal is NOT maximum compression—it's preserving enough information to complete tasks without re-fetching.
Key Metric: Tokens-per-task (total tokens to complete a task), NOT tokens-per-request.
上下文压缩对于长时间运行的Agent会话至关重要。我们的目标不是最大化压缩率,而是保留足够完成任务的信息,无需重新获取数据。
核心指标: Tokens-per-task(完成一项任务所需的总Token数),而非每请求Token数。

When to Use

使用场景

  • Long-running conversations approaching context limits
  • Multi-step agent workflows with accumulating history
  • Sessions with large tool outputs
  • Memory management in persistent agents

  • 接近上下文限制的长时间对话
  • 历史记录不断累积的多步骤Agent工作流
  • 包含大量工具输出的会话
  • 持久化Agent中的内存管理

Strategy Quick Reference

策略速查

StrategyCompressionInterpretableVerifiableBest For
Anchored Iterative60-80%YesYesLong sessions
Opaque95-99%NoNoStorage-critical
Regenerative Full70-85%YesPartialSimple tasks
Sliding Window50-70%YesYesReal-time chat
Recommended: Anchored Iterative Summarization with probe-based evaluation.

StrategyCompressionInterpretableVerifiableBest For
Anchored Iterative60-80%YesYesLong sessions
Opaque95-99%NoNoStorage-critical
Regenerative Full70-85%YesPartialSimple tasks
Sliding Window50-70%YesYesReal-time chat
推荐方案: 结合基于探针评估的Anchored Iterative Summarization。

Anchored Summarization (RECOMMENDED)

Anchored Summarization(推荐)

Maintains structured, persistent summaries with forced sections:
undefined
通过强制划分的板块来维护结构化、持久化的摘要:
undefined

Session Intent

Session Intent

[What we're trying to accomplish - NEVER lose this]
[What we're trying to accomplish - NEVER lose this]

Files Modified

Files Modified

  • path/to/file.ts: Added function X, modified class Y
  • path/to/file.ts: Added function X, modified class Y

Decisions Made

Decisions Made

  • Decision 1: Chose X over Y because [rationale]
  • Decision 1: Chose X over Y because [rationale]

Current State

Current State

[Where we are in the task - progress indicator]
[Where we are in the task - progress indicator]

Blockers / Open Questions

Blockers / Open Questions

  • Question 1: Awaiting user input on...
  • Question 1: Awaiting user input on...

Next Steps

Next Steps

  1. Complete X
  2. Test Y

**Why it works:**
- Structure FORCES preservation of critical categories
- Each section must be explicitly populated (can't silently drop info)
- Incremental merge (new compressions extend, don't replace)

---
  1. Complete X
  2. Test Y

**优势:**
- 结构化设计强制保留关键类别信息
- 每个板块都必须明确填充内容(不会静默丢失信息)
- 增量合并(新的压缩结果是扩展而非替换原有内容)

---

Implementation

实现方案

python
from dataclasses import dataclass, field
from typing import Optional

@dataclass
class AnchoredSummary:
    """Structured summary with forced sections."""

    session_intent: str
    files_modified: dict[str, list[str]] = field(default_factory=dict)
    decisions_made: list[dict] = field(default_factory=list)
    current_state: str = ""
    blockers: list[str] = field(default_factory=list)
    next_steps: list[str] = field(default_factory=list)
    compression_count: int = 0

    def merge(self, new_content: "AnchoredSummary") -> "AnchoredSummary":
        """Incrementally merge new summary into existing."""
        return AnchoredSummary(
            session_intent=new_content.session_intent or self.session_intent,
            files_modified={**self.files_modified, **new_content.files_modified},
            decisions_made=self.decisions_made + new_content.decisions_made,
            current_state=new_content.current_state,
            blockers=new_content.blockers,
            next_steps=new_content.next_steps,
            compression_count=self.compression_count + 1,
        )

    def to_markdown(self) -> str:
        """Render as markdown for context injection."""
        sections = [
            f"## Session Intent\n{self.session_intent}",
            f"## Files Modified\n" + "\n".join(
                f"- `{path}`: {', '.join(changes)}"
                for path, changes in self.files_modified.items()
            ),
            f"## Decisions Made\n" + "\n".join(
                f"- **{d['decision']}**: {d['rationale']}"
                for d in self.decisions_made
            ),
            f"## Current State\n{self.current_state}",
        ]
        if self.blockers:
            sections.append(f"## Blockers\n" + "\n".join(f"- {b}" for b in self.blockers))
        sections.append(f"## Next Steps\n" + "\n".join(
            f"{i+1}. {step}" for i, step in enumerate(self.next_steps)
        ))
        return "\n\n".join(sections)

python
from dataclasses import dataclass, field
from typing import Optional

@dataclass
class AnchoredSummary:
    """Structured summary with forced sections."""

    session_intent: str
    files_modified: dict[str, list[str]] = field(default_factory=dict)
    decisions_made: list[dict] = field(default_factory=list)
    current_state: str = ""
    blockers: list[str] = field(default_factory=list)
    next_steps: list[str] = field(default_factory=list)
    compression_count: int = 0

    def merge(self, new_content: "AnchoredSummary") -> "AnchoredSummary":
        """Incrementally merge new summary into existing."""
        return AnchoredSummary(
            session_intent=new_content.session_intent or self.session_intent,
            files_modified={**self.files_modified, **new_content.files_modified},
            decisions_made=self.decisions_made + new_content.decisions_made,
            current_state=new_content.current_state,
            blockers=new_content.blockers,
            next_steps=new_content.next_steps,
            compression_count=self.compression_count + 1,
        )

    def to_markdown(self) -> str:
        """Render as markdown for context injection."""
        sections = [
            f"## Session Intent\n{self.session_intent}",
            f"## Files Modified\n" + "\n".join(
                f"- `{path}`: {', '.join(changes)}"
                for path, changes in self.files_modified.items()
            ),
            f"## Decisions Made\n" + "\n".join(
                f"- **{d['decision']}**: {d['rationale']}"
                for d in self.decisions_made
            ),
            f"## Current State\n{self.current_state}",
        ]
        if self.blockers:
            sections.append(f"## Blockers\n" + "\n".join(f"- {b}" for b in self.blockers))
        sections.append(f"## Next Steps\n" + "\n".join(
            f"{i+1}. {step}" for i, step in enumerate(self.next_steps)
        ))
        return "\n\n".join(sections)

Compression Triggers

压缩触发条件

ThresholdAction
70% capacityTrigger compression
50% capacityTarget after compression
10 messages minimumRequired before compressing
Last 5 messagesAlways preserve uncompressed
ThresholdAction
70% capacityTrigger compression
50% capacityTarget after compression
10 messages minimumRequired before compressing
Last 5 messagesAlways preserve uncompressed

CC 2.1.7: Effective Context Window

CC 2.1.7:有效上下文窗口

Calculate against effective context (after system overhead):
TriggerStatic (CC 2.1.6)Effective (CC 2.1.7)
Warning60% of static60% of effective
Compress70% of static70% of effective
Critical90% of static90% of effective

基于有效上下文(扣除系统开销后)进行计算:
TriggerStatic (CC 2.1.6)Effective (CC 2.1.7)
Warning60% of static60% of effective
Compress70% of static70% of effective
Critical90% of static90% of effective

Best Practices

最佳实践

DO

建议

  • Use anchored summarization with forced sections
  • Preserve recent messages uncompressed (context continuity)
  • Test compression with probes, not similarity metrics
  • Merge incrementally (don't regenerate from scratch)
  • Track compression count and quality scores
  • 使用带强制板块的Anchored Summarization
  • 保留最近的消息不压缩(保证上下文连续性)
  • 使用探针而非相似度指标测试压缩效果
  • 增量合并(不要从头重新生成)
  • 跟踪压缩次数和质量评分

DON'T

不建议

  • Compress system prompts (keep at START)
  • Use opaque compression for critical workflows
  • Compress below the point of task completion
  • Trigger compression opportunistically (use fixed thresholds)
  • Optimize for compression ratio over task success

  • 压缩系统提示词(应始终放在开头)
  • 对关键工作流使用不透明压缩
  • 压缩到影响任务完成的程度
  • 随机触发压缩(应使用固定阈值)
  • 为了压缩率而牺牲任务成功率

Target Metrics

目标指标

MetricTargetRed Flag
Probe pass rate>90%<70%
Compression ratio60-80%>95% (too aggressive)
Task completionSame as uncompressedDegraded
Latency overhead<2s>5s

MetricTargetRed Flag
Probe pass rate>90%<70%
Compression ratio60-80%>95% (too aggressive)
Task completionSame as uncompressedDegraded
Latency overhead<2s>5s

References

参考资料

For detailed implementation and patterns, see:
  • Compression Strategies: Detailed comparison of all strategies (anchored, opaque, regenerative, sliding window), implementation patterns, and decision flowcharts
  • Priority Management: Compression triggers, CC 2.1.7 effective context, probe-based evaluation, OrchestKit integration
如需详细的实现方案和模式,请参考:
  • 压缩策略:所有策略(Anchored、Opaque、Regenerative Full、Sliding Window)的详细对比、实现模式和决策流程图
  • 优先级管理:压缩触发条件、CC 2.1.7有效上下文、基于探针的评估、OrchestKit集成

Bundled Resources

配套资源

  • assets/anchored-summary-template.md
    - Template for structured compression summaries with forced sections
  • assets/compression-probes-template.md
    - Probe templates for validating compression quality
  • references/compression-strategies.md
    - Detailed strategy comparisons
  • references/priority-management.md
    - Compression triggers and evaluation

  • assets/anchored-summary-template.md
    - 带强制板块的结构化压缩摘要模板
  • assets/compression-probes-template.md
    - 用于验证压缩质量的探针模板
  • references/compression-strategies.md
    - 详细的策略对比文档
  • references/priority-management.md
    - 压缩触发条件与评估文档

Related Skills

相关技能

  • context-engineering
    - Attention mechanics and positioning
  • memory-systems
    - Persistent storage patterns
  • multi-agent-orchestration
    - Context isolation across agents
  • observability-monitoring
    - Tracking compression metrics

Version: 1.0.0 (January ) Key Principle: Optimize for tokens-per-task, not tokens-per-request Recommended Strategy: Anchored Iterative Summarization with probe-based evaluation

  • context-engineering
    - 注意力机制与定位
  • memory-systems
    - 持久化存储模式
  • multi-agent-orchestration
    - Agent间上下文隔离
  • observability-monitoring
    - 压缩指标跟踪

版本: 1.0.0(1月) 核心原则: 优化每任务Token数,而非每请求Token数 推荐策略: 结合基于探针评估的Anchored Iterative Summarization

Capability Details

能力详情

anchored-summarization

anchored-summarization

Keywords: compress, summarize history, context too long, anchored summary Solves:
  • Reduce context size while preserving critical information
  • Implement structured compression with required sections
  • Maintain session intent and decisions through compression
关键词: compress, summarize history, context too long, anchored summary 解决问题:
  • 在保留关键信息的同时减小上下文规模
  • 实现带必填板块的结构化压缩
  • 在压缩过程中保留会话意图与决策记录

compression-triggers

compression-triggers

Keywords: token limit, running out of context, when to compress Solves:
  • Determine when to trigger compression (70% utilization)
  • Set compression targets (50% utilization)
  • Preserve last 5 messages uncompressed
关键词: token limit, running out of context, when to compress 解决问题:
  • 确定何时触发压缩(使用率达70%时)
  • 设置压缩目标(使用率降至50%)
  • 保留最后5条消息不压缩

probe-evaluation

probe-evaluation

Keywords: evaluate compression, test compression, probe Solves:
  • Validate compression quality with functional probes
  • Test information preservation after compression
  • Achieve >90% probe pass rate
关键词: evaluate compression, test compression, probe 解决问题:
  • 使用功能性探针验证压缩质量
  • 测试压缩后的信息保留情况
  • 实现>90%的探针通过率