mcpField
C
context-compactor

context-compactor

github.com/adaptationioAgent workflows40 installs
Repository

About context-compactor

context-compactor is a Python component for reducing conversation context as token limits approach. It prioritizes architectural decisions, unresolved issues, and current state while removing stale outputs and redundant messages.

Key features

  1. 01Check whether context needs compaction
  2. 02Score message importance
  3. 03Preserve key decisions, bugs, and state
  4. 04Summarize content and discard stale material
  5. 05Estimate token usage

Use cases

  1. 01Reduce context near a token limit
  2. 02Prepare compact state for session handoffs
  3. 03Retain essential project details across long sessions

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/adaptationio/skrillz --skill context-compactor

After installing, type/context-compactorin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

references/
COMPACTION-STRATEGY.md
scripts/
compactor.py
importance_scorer.py
summarizer.py
token_estimator.py

Details

From the project README

Context Compactor

Automatically summarizes and compacts context when approaching token limits while preserving critical information.

Quick Start

Check if Compaction Needed
from scripts.compactor import ContextCompactor

compactor = ContextCompactor()
if compactor.should_compact(context, limit=100000):
    compacted = compactor.compact(context)
Compact Context
compacted = compactor.compact(context)
# Preserves: architectural decisions, bugs, current state
# Discards: stale tool outputs, redundant messages

Preservation Strategy

┌─────────────────────────────────────────────────────────────┐
│                  PRESERVATION PRIORITY                       │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  MUST PRESERVE (Never remove)                               │
│  ├─ Architectural decisions                                 │
│  ├─ Unresolved bugs and blockers                           │
│  ├─ Current feature state                                   │
│  ├─ Recent file changes (last 5)                           │
│  └─ Error patterns and solutions                           │
│                                                              │
│  CAN SUMMARIZE (Compress to summary)                        │
│  ├─ Completed features (list of IDs)                       │
│  ├─ Resolved errors (brief mention)                        │
│  └─ Historical decisions (key points)                      │
│                                                              │
│  CAN DISCARD (Remove entirely)                              │
│  ├─ Redundant tool outputs                                 │
│  ├─ Stale search results                                   │
│  ├─ Superseded messages                                    │
│  └─ Verbose logging                                         │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Compaction Process

  1. Score Importance: Assign score to each message/content
  2. Identify Critical: Mark must-preserve content
  3. Summarize Middle: Compress can-summarize content
  4. Discard Stale: Remove can-discard content
  5. Validate: Ensure compacted context is coherent

Token Budgets

Context TypeLimitAction
< 50%NormalNo action
50-75%WarningPrepare for compaction
75-90%CompactTrigger compaction
> 90%CriticalAggressive compaction

Integration Points

  • autonomous-session-manager: Triggers compaction check
  • memory-manager: Stores compacted summaries
  • handoff-coordinator: Uses compacted state for handoffs

References

  • references/COMPACTION-STRATEGY.md - Detailed strategy
  • references/TOKEN-BUDGETS.md - Budget management

Scripts

  • scripts/compactor.py - Core ContextCompactor
  • scripts/importance_scorer.py - Message scoring
  • scripts/summarizer.py - Content summarization
  • scripts/token_estimator.py - Token counting

Comments

Markdown supported