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

See Also

• [Context Engineering Skills Collection]()
• Research on "lost-in-the-middle" phenomenon in LLM context windows