This project reduces LLM token consumption by compressing agent context such as tool outputs, logs, and retrieved chunks. It operates as a local-first, reversible context compression layer to lower costs while maintaining answer accuracy.
Project overview
It caches compressed originals locally for on-demand retrieval via a context compression registry, operating as a local process rather than a hosted API.
Project type
AI Agent · RAG · Prompt Engineering
Use cases
Knowledge Q&A · Coding & Development
Deployment
Refer to project documentation
License
Apache-2.0
Best for
Developers and AI engineers who need to reduce token costs across multi-agent or RAG workflows using a local data boundary.
Key capabilities
Provides headroom_compress, headroom_retrieve, and headroom_stats tools for any MCP client.
Caches compressed originals locally so the LLM can retrieve them on demand.
Limitations and risks
It is not needed if you only use a single provider's native compaction and do not need cross-agent memory.
It cannot be used in sandboxed environments where local processes cannot run.
ONNX-backed features require the AVX2 instruction set on x86/x86_64 architectures. If AVX2 is missing, the system falls back to non-ONNX paths.
Getting started
You can install the system with a simple one-line command: pip install "headroom-ai[all]", and start it using: headroom proxy --port 8787.
Evidence and sources
GitHub project description: Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP s…
README: - **Library** — `compress(messages)` in Python or TypeScript, inline in any app - **Proxy** — `headroom proxy --port 8787`, zero code changes, any language - **Agent wrap** — `hea…
README: Headroom (runs locally — your data stays here)
README: uv tool install --python 3.13 "headroom-ai[all]" # CLI as a global tool in a self-contained virtual env pip install "headroom-ai[all]" # Python — ships the `headroom` CLI npm inst…