Headroom: Context Compression as LLM Middleware with Self-Learning from Failed Agent Sessions
A Counterintuitive Number
10,144 → 1,260 tokens.
The same FATAL error was found, the same fix proposed—but the LLM only read 12% of the original context. This isn't a benchmark scenario; it's everyday output from headroomlabs-ai/headroom in real coding agent sessions.
Over the past two years, LLM optimization has focused almost entirely on the model side: longer context windows, faster inference, cheaper tokens. Headroom asks: if 80% of what the model reads is redundant, why make the model read it at all?
Compression Isn't Preprocessing—It's Middleware
Most token compression tools work as "preprocessing"—truncating, summarizing, or stripping lines before sending. Headroom instead acts as a middleware layer sitting between your agent and the LLM provider, doing three things traditional compressors don't.
First, content routing. Headroom's ContentRouter detects the input type—JSON, source code, or natural language—then selects a matching compressor. JSON goes through SmartCrusher (60-95% compression), code through CodeCompressor (AST-based structural compression), text through Kompress-v2-base (a compression model on HuggingFace). This is far more precise than one-size-fits-all summarization, because JSON redundancy lives in structure (repeated keys, nesting), code redundancy in patterns (imports, boilerplate), and text redundancy in semantics (repeated phrasing).
Second, cache alignment. CacheAligner does something subtler—it marks "volatile content." LLM providers' KV-caches are prefix-based: if your prompt prefix is unchanged, the cache hits and inference is fast and cheap; change the prefix and the cache invalidates. Traditional compressors don't know this and may compress a stable prefix into a completely different string, invalidating the cache. CacheAligner identifies frequently changing content (timestamps, counters) and keeps its relative position stable during compression, preserving the KV-cache prefix.
Third, reversible compression (CCR). Original content is cached locally, and the model can retrieve full text on demand via the headroom_retrieve tool. Compression is therefore not lossy—if the model judges the compressed information insufficient, it can actively request the original. It's a "compress first, expand on demand" architecture rather than a one-way operation.
headroom learn: Turning Failed Sessions into Self-Teaching Material
This is Headroom's most interesting feature, and one rarely discussed elsewhere.
Every coding agent fails. Claude Code runs 20 rounds and errors out. Codex edits 15 times and tests still fail. These failed sessions are usually discarded—tokens spent, no result produced, seemingly worthless.
headroom learn mines failed sessions to find where the model went wrong, then writes corrections into project-level instruction files—CLAUDE.local.md (default, gitignored), CLAUDE.md, AGENTS.md, GEMINI.md, or GROK.md.
This is essentially experience-driven prompt engineering. Traditional prompt engineering is hand-written: "don't use var, use const," "tests must cover edge cases." headroom learn extracts automatically from failures: "In this module of this project, your last attempt with method X failed; the correct approach is Y."
The key distinction: these corrections are project-specific. Generic coding instructions ("write clean code") help little in concrete projects, because failures occur in project-specific contexts—an API's calling convention, a config file's format, a test framework's quirk. That's exactly the knowledge headroom learn captures.
Cross-Agent Memory: What Claude Learned, Gemini Can Use
Another underrated feature is cross-agent shared memory. When you wrap multiple coding agents (Claude Code, Codex, Gemini, Grok) with headroom wrap, they share the same local compressed storage with automatic deduplication.
What does this mean? If Claude Code works on a project for 2 hours, reading 50 files, its compressed context accumulates substantial project knowledge. When you switch to Codex, it doesn't need to re-read those files—Headroom's shared store already holds compressed versions ready to use.
This solves a real problem: context migration between agents. Traditionally, you'd copy-paste context manually or export/import session logs. Headroom automates this and drastically shrinks the amount of data transferred through compression.
The Numbers
Headroom's README cites compression figures by scenario:
- Coding agents: 20% token reduction (text is already code; redundancy is lower)
- JSON processing: 60-95% reduction (JSON's structural redundancy is very high)
- RAG chunks: content-dependent, typically 40-70%
pip install "headroom-ai[all]", it runs locally, and no data is sent to third parties.Architectural Implications
Headroom's architecture points to a deeper insight: the LLM input layer is becoming an independent engineering domain.
Previously, "what to feed the LLM" was decided at the application layer—RAG systems chose what to retrieve, agent frameworks chose which files to read, tools chose return formats. Headroom inserts a "content optimization layer" between these and the application layer, dedicated to making the same information fit in fewer tokens.
Its three components—ContentRouter (classification), CacheAligner (cache awareness), and CCR (reversible compression)—form a complete middleware architecture. It doesn't modify your prompts, doesn't change your agent logic, doesn't replace your LLM provider. It does one thing: make every token the model reads more information-dense.
As context windows grew from 4K to 200K and now 1M, "can it fit" stopped being the problem. "How much of what fits is noise" became the new problem. Headroom's answer: solve it with middleware thinking, not bigger windows.
---
*Project: headroomlabs-ai/headroom* *Documentation: headroomlabs.ai*