headroomlabs-ai/headroom

项目概览

提供本地运行的可逆上下文压缩（CCR），LLM 可在需要时按需检索被压缩的原始数据，避免了传统压缩方式导致的信息丢失。

项目类型

AI Agent · RAG 与知识库 · 提示词工程

应用场景

编程开发

部署方式

查看项目说明

License

Apache-2.0

适合谁

• 需要降低复杂代理长对话或大量 RAG 数据交互过程中的 Token 消耗，且希望数据仅在本地处理的开发者和 AI 工程师。
• 希望跨多种代理和编码工具（如 Cursor、Claude Code 等）统一管理和压缩上下文环境的用户。

核心能力

• 作为 MCP 服务器运行，为任何 MCP 客户端提供 headroom_compress、headroom_retrieve 和 headroom_stats 三项工具，用于执行压缩、检索和统计操作。
• 在本地缓存被压缩的原始数据，使得 LLM 能够在对话过程中按需检索这些被压缩的内容，从而在减少 Token 占用的同时保留原始信息。

限制与风险

• 如果你只使用单一提供商原生的上下文压缩功能，且不需要跨代理共享记忆，则该项目对你价值有限。
• 如果你在无法运行本地进程的沙盒环境中工作，将无法使用该工具。
• 基于 ONNX 的功能在 x86/x86_64 架构上需要 CPU 支持 AVX2 指令集；如果缺失，将回退到非 ONNX 路径执行，可能会影响部分功能的运行表现。

如何开始

• 支持通过单行命令安装（如 pip install）并使用简单命令启动代理服务（如 headroom proxy），过程无需编写复杂代码。

核验依据

• GitHub 项目简介: 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…

内容核验时间：