headroom

name headroom description SmartCrusher + CCR context compression — crunch large JSON arrays, tool outputs, and search results to save tokens. Use when context is bloated or approaching token limits. license MIT homepage https://github.com/chopratejas/headroom Headroom — Context Compression Layer SmartCrusher + CCR (Compress-Cache-Retrieve) for token-saving context compression. Portable Python module — no external dependencies beyond stdlib. When to Use Large tool output (grep results, JSON arrays, file listings) approaching context limit Before sending a long context to a model with token cap Need to preserve essential items while dropping noise Quick Start from skills.headroom import SmartCrusher, CCRStore # Compress a JSON array (keep most important items) crusher = SmartCrusher() result = crusher.crush(large_json, query= "relevant keywords" ) # result.compressed → compressed JSON string # result.items_kept / items_total → retention ratio # result.compression_ratio → e.g. 0.3 means 70% tokens saved SmartCrusher — 5-Dimensional Scoring Keeps items by: First/Last items — pagination context + latest data (30% head + 15% tail) Error items — 100% preserved Statistical outliers — > 2 std from mean Query-relevant — BM25 match against user query Change points — significant transitions in data Config overrides: crusher = SmartCrusher(config={ "max_items_after_crush" : 15 , "first_fraction" : 0.3 , "variance_threshold" : 2.0 , }) CCR Store — Compress-Cache-Retrieve store = CCRStore(max_entries= 1000 , ttl_seconds= 3600 ) # Cache original when crushing store.put(hash_key, original_text) # Retrieve if LLM needs more detail full_text = store.get(hash_key) Token Estimation from skills.headroom import estimate_tokens tokens = estimate_tokens( "some text — CJK-aware counting" ) Integration Notes This module is already imported by skills/shared/context_trimming.py (SmartCrusher layer) CCR background worker in skills/sakura/app/agent/memory_curator.py writes to Qdrant For roleplay context trimming: the context_trimming module wraps SmartCrusher with 24msg/40K char cap