AgentSkillsCN

Context Compressor

上下文压缩器

SKILL.md

Context Compressor Skill

Automated context management for long-running Clawdbot sessions. Detects when context limits approach, compresses old conversation history, and seamlessly transfers to a fresh session.

When to Use

  • •Long coding sessions with extensive context accumulation
  • •Projects with many iterations and refinements
  • •When noticing Claude repeating itself or losing track of details
  • •Proactively before hitting hard context limits
  • •During heartbeats or idle moments when user isn't actively waiting

How It Works

  1. •Monitoring: Continuously tracks context usage via session metadata
  2. •Compression: When threshold reached (configurable, default 80%), summarizes old messages
  3. •Preservation: Extracts key decisions, code changes, file states, and action items
  4. •Handoff: Initiates new session with compressed context as foundation
  5. •Continuity: User experiences seamless transition with all important context preserved

Key Features

  • •Smart Summarization: Preserves decisions, code, file states, not just raw text
  • •Configurable Thresholds: Set when compression triggers (70-90% of context limit)
  • •Background Operation: Works during heartbeats or low-activity periods
  • •Selective Retention: Keeps important files, decisions, TODOs; compresses chaff
  • •Session State Transfer: New session inherits all critical context automatically

Core Concepts

Context Degradation Patterns

As sessions grow long, watch for these signs:

  • •Repetitive responses ("As I mentioned earlier...")
  • •Missing references to earlier decisions
  • •Forgetting file modifications
  • •Asking to repeat information
  • •General coherence degradation

Compression Strategy

  1. •

    Extract Core Intelligence:

    • •All decisions made and their rationale
    • •File paths and their current state
    • •Pending tasks and their status
    • •Important code snippets or configurations
    • •User preferences and patterns
  2. •

    Condense History:

    • •Remove filler, backtracking, dead ends
    • •Keep only high-signal turns
    • •Merge related iterations into summaries
    • •Preserve critical code snippets inline
  3. •

    Format for Efficiency:

    • •Use compact representations
    • •Reference files rather than dump contents
    • •List decisions as bullet points
    • •Include only relevant code context

Usage

Automatic Mode (Recommended)

The skill runs automatically during heartbeats and idle periods. Configure threshold:

bash
# Set compression to trigger at 75% context usage
context-compressor set-threshold 75

# Check current status
context-compressor status

Manual Trigger

bash
# Force compression and session reset
context-compressor compress --force

Configuration

bash
# View all settings
context-compressor config

# Adjust summarization depth
context-compressor set-depth brief|detailed|comprehensive

# Set quiet hours (compression won't run)
context-compressor set-quiet-hours 23:00-07:00

Output

When compression occurs, the skill produces:

  1. •

    Summary File: memory/compressed-{session-id}.md

    • •Executive summary of session
    • •Key decisions made
    • •Files modified and their states
    • •Pending tasks
    • •Code snippets worth preserving
  2. •

    Session Handoff: Automatic new session with:

    • •User context (USER.md)
    • •Project memory (MEMORY.md)
    • •Compressed session summary
    • •Current working state

Best Practices

  1. •Regular Compression: Don't wait for limits. Compress proactively every few hours
  2. •Preserve Code: Always keep actual code snippets, not just references
  3. •Track Decisions: Explicitly note WHY decisions were made, not just WHAT
  4. •Keep TODOs: Mark incomplete work clearly for continuity
  5. •Reference Files: Point to files rather than embedding full contents

Integration Points

  • •Heartbeats: Runs compression checks during heartbeat cycles
  • •Memory System: Writes compressed summaries to memory files
  • •Session Management: Coordinates with session spawn for handoff
  • •File Tracking: References current file states accurately

Technical Details

Compression Algorithm

  1. •Parse session transcript into atomic turns
  2. •Score each turn for importance (decisions = high, chat = low)
  3. •Keep top N% of turns by importance score
  4. •Summarize remaining turns into executive summary
  5. •Extract and preserve code blocks separately
  6. •Generate session transfer package

Thresholds

  • •Conservative (70%): Trigger early, preserve more context
  • •Balanced (80%): Default, good for most workflows
  • •Aggressive (90%): Push limits, maximum session length
  • •Manual Only: Disable auto-trigger, compress on demand

File References

The compressor tracks:

  • •Modified files and their paths
  • •Configuration changes
  • •New files created
  • •Deleted files
  • •Directory structure changes

Troubleshooting

Compression Too Frequent

bash
# Increase threshold
context-compressor set-threshold 85

Context Lost After Handoff

Check that:

  1. •Compressed summary was generated (memory/compressed-*.md)
  2. •New session loaded memory files
  3. •Critical files weren't in the "chaff" that got dropped

Performance Impact

Compression runs in background and should complete in <30s for typical sessions. If slower:

  • •Reduce summarization depth
  • •Increase threshold to compress less frequently
  • •Exclude large files from compression scope

Examples

Typical Workflow

code
User: Working on notes app sidebar
[Session runs 2 hours, many iterations]

Heartbeat triggers → Context at 78% → Auto-compress → New session
User: (no interruption, seamless continuation)
New session has: executive summary, key decisions, file states, TODOs

Manual Recovery

code
User notices Claude repeating itself
User: "context-compressor compress --force"
Compressor summarizes → New session starts → User continues seamlessly

Related Skills

  • •memory-system: Underlying memory infrastructure
  • •self-improving-agent: Learns from session patterns
  • •sessions-spawn: Handles new session creation

See Also