headroomlabs-ai/headroom

Project overview

This project reduces LLM token consumption from agent contexts through local-first, reversible context compression. It caches compressed originals locally so the LLM can retrieve them on demand, lowering costs without losing accuracy.

Project type

AI Agent · RAG

Use cases

Coding & Development

Deployment

Refer to project documentation

License

Apache-2.0

Best for

• Developers and AI engineers looking to reduce LLM token costs across multi-agent or multi-provider workflows without relying on a single native compaction feature.

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

• Not needed if you only use a single provider's native compaction and do not need cross-agent memory.
• Not applicable if you work in a sandboxed environment where local processes cannot run.
• ONNX-backed features require AVX2 on x86/x86_64 architectures; the system falls back to non-ONNX paths if missing.

Getting started

• Supports simple one-line installs and proxy startup commands. The first success path is running pip install "headroom-ai[all]" followed by headroom proxy --port 8787. Note that platform-independent sdist fallback installations require a local Rust toolchain.

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: 60–95% fewer tokens (for JSON data), 15-20% fewer tokens (for coding agents) · library · proxy · MCP · content-aware compressors · local-first · reversible
• 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…

Reviewed at: 2026-07-17T06:50:31Z