Headroom — Token Compression Tool (Updated 2026-06-24)
Repository: https://github.com/headroomlabs-ai/headroom (formerly chopratejas/headroom)
Stars: 48,352⭐ (up from ~30K at first research)
Package: headroom-ai PyPI, v0.23.0 installed, MCP Server v1.26.0
Language: Python
License: Apache 2.0
Test Results (2026-06-24)
Headroom successfully integrated as MCP Server into Hermes (Manas profile).
MCP Tools exposed:
headroom_compress— Compress contentheadroom_retrieve— Retrieve original by hash (CCR reversible)headroom_stats— Session statistics
Compression benchmarks on our data:
| Content | Before | After | Reduction |
|---|---|---|---|
| JSON array (200 items) | 19,633 chars | 9,097 chars | 54% |
| Structured logs (600 entries) | 112,668 chars | 46,793 chars | 58% |
Format: SmartCrusher converts JSON arrays to header+CSV format, preserving anomalies.
Limitations:
- Text/prose compression needs PyTorch for Kompress-base model (not installed — WSL memory)
- Short messages (<300 tokens) skipped
- Code compression needs tree-sitter bindings
Config (manas profile):
headroom:
command: ${HOME}/.hermes/hermes-agent/venv/bin/headroom
args: '["mcp","serve"]'
timeout: 30
connect_timeout: 10
enabled: true