headroomlabs-ai/headroom

What it solves

AI agents read a lot of context — tool outputs, logs, RAG chunks, files, and conversation history — and every token costs money and latency. Long agent sessions with heavy tool output often send far more tokens than the model actually needs, while still paying for the full prompt. Headroom shrinks that context before it reaches the LLM, preserving the important parts (like error lines) while cutting token usage significantly. Compression runs locally, so no prompt or file content leaves your machine.

How it works

Headroom sits between your agent/app and the LLM provider. It inspects each chunk of content, detects its type (JSON, source code, prose, images), and applies the best compressor:

• ContentRouter picks the compressor.
• SmartCrusher handles JSON arrays and nested objects, keeping outliers, error items, and boundaries based on field variance.
• CodeCompressor is AST-aware for many programming languages.
• Kompress-v2-base is a HuggingFace model trained on agentic traces for prose.
• CacheAligner flags volatile content that would break a provider's KV-cache prefix without rewriting prompts.
• CCR (Cache-and-Compress-Reversible) stores originals locally so the model can retrieve full text on demand via headroom_retrieve.

After compression, the smaller prompt plus a retrieval tool go to the LLM. You can integrate Headroom as a library (compress() in Python/TypeScript), as a proxy on a port (zero code changes), as an agent wrapper (headroom wrap any of 20+ agents), or as an MCP server. There's also headroom learn that reads past sessions to adjust verbosity, and output token reduction that appends a terseness note to the system prompt to reduce what the model writes back.

Who it's for

Developers and teams who run coding agents daily and want to cut token costs without changing their code. It's a good fit if you use multiple agents (Claude Code, Codex, Cursor, etc.) and want one shared memory store, or if you need reversible compression so originals remain retrievable for a TTL. It's less useful for short conversational exchanges, prose-heavy tasks, or environments where you can't run local processes.

Highlights

• Local compression: no data sent anywhere for compression.
• Multiple integration modes: library, proxy, agent wrapper, MCP, and cross-agent memory.
• Proven savings: 30–57% on real scenarios (e.g., 55,957 → 24,340 tokens in an incident-debugging case), with much higher savings on repetitive JSON/logs.
• Sub-millisecond latency (0.21 ms p50 on 10K-token JSON, 1.4 ms at 100K) so it doesn't affect agent responsiveness.
• Accuracy preserved: benchmarks show no significant degradation (e.g., GSM8K, TruthfulQA, SQuAD v2, BFCL).
• Reversible compression via CCR: model can retrieve full context when needed.
• Output token reduction: trims model-written text, with measurable or estimated savings reporting.