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

Monitoring: Continuously tracks context usage via session metadata
Compression: When threshold reached (configurable, default 80%), summarizes old messages
Preservation: Extracts key decisions, code changes, file states, and action items
Handoff: Initiates new session with compressed context as foundation
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

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
Condense History:
- Remove filler, backtracking, dead ends
- Keep only high-signal turns
- Merge related iterations into summaries
- Preserve critical code snippets inline
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:

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

# Check current status
context-compressor status

Manual Trigger

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

Configuration

# 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:

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
Session Handoff: Automatic new session with:
- User context (USER.md)
- Project memory (MEMORY.md)
- Compressed session summary
- Current working state

Best Practices

Regular Compression: Don't wait for limits. Compress proactively every few hours
Preserve Code: Always keep actual code snippets, not just references
Track Decisions: Explicitly note WHY decisions were made, not just WHAT
Keep TODOs: Mark incomplete work clearly for continuity
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

Parse session transcript into atomic turns
Score each turn for importance (decisions = high, chat = low)
Keep top N% of turns by importance score
Summarize remaining turns into executive summary
Extract and preserve code blocks separately
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

# Increase threshold
context-compressor set-threshold 85

Context Lost After Handoff

Check that:

Compressed summary was generated (memory/compressed-*.md)
New session loaded memory files
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

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

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

/context-compressor