Headroom Skill 技能

Headroom — AI Agent 上下文压缩层，token 减半不影响答案质量

Headroom 是由 Headroom Labs 开发的 AI Agent 上下文压缩层，在 LLM 接收到 prompt 之前压缩工具输出、日志、RAG 检索结果、文件内容与会话历史。官方实测：编码 Agent 场景减少 20% tokens，JSON 类内容减少 60%~95%，答案完全一致。压缩在本地运行，原始 prompt 与文件内容不会被发送到任何外部服务。

核心能力

• 多形态部署：支持 Python / TypeScript 库（compress(messages)）、本地代理（headroom proxy --port 8787）、MCP 服务器三种集成方式，覆盖任何语言栈。
• 零代码 Agent 包装器：一条命令 headroom wrap claude|codex|grok|copilot|cursor|aider|opencode|cline|continue|goose|openhands|openclaw|vibe|omp|zcode 即可给主流 Agent 套上压缩层，headroom unwrap 一键卸载。
• MCP 协议工具：暴露 headroom_compress、headroom_retrieve、headroom_stats 三个 MCP 工具给任意 MCP 客户端（Claude Code、Cursor、Codex 等）。
• 跨 Agent 共享记忆：在同一台机器上 Claude、Codex、Gemini、Grok 可共享一个去重记忆池。
• 输出 Token 优化：不仅压缩输入，还会修剪模型回写内容，进一步降低总体 token 消耗。
• 可逆压缩（CCR）：原始内容缓存在本地，按需取回，避免因压缩丢失关键上下文。
• 失败会话自学习：headroom learn 挖掘失败会话并把修正写到 CLAUDE.local.md / AGENTS.md / GEMINI.md 等项目记忆文件。
• 开放模型：在 HuggingFace 发布 kompress-v2-base 模型，开发者可自托管压缩引擎。

安装配置

• PyPI 安装：pip install headroom-ai 获取库与 CLI。
• NPM 安装：npm install headroom-ai 集成到 Node.js / TypeScript 项目。
• 本地代理启动：headroom proxy --port 8787 启动 HTTP 代理，把 Anthropic / OpenAI base URL 指向 http://localhost:8787 即可透明接入。
• MCP 服务器配置：在 Claude Code / Cursor 的 MCP 配置中加入 headroom mcp stdio 命令。

使用步骤

1. 通过 PyPI / NPM 安装 headroom-ai 客户端与 CLI。
2. 选择部署形态：库内调用、本地代理、MCP 服务器三选一。
3. 用 headroom wrap 给目标 Agent 套上压缩层。
4. 让 Agent 正常工作，观察 token 消耗（推荐用 headroom stats 命令查看）。
5. 在多 Agent 场景下开启共享记忆池实现跨工具上下文复用。
6. 用 headroom learn 自动积累失败会话教训到项目 CLAUDE.md。

适用场景

• 编码 Agent 在长会话中日积月累的 token 成本过高。
• RAG 应用检索结果文档过长、占满上下文窗口。
• 多 Agent 工具栈并存（Claude + Codex + Cursor），需要统一压缩与共享记忆。
• 关注数据隐私的企业，不希望 prompt 与文件上传第三方压缩服务。
• 想用 LLM 处理 JSON 日志、长 CSV、代码文件却苦于 token 限制的团队。

适用人群

• 高频使用 Claude Code / Codex / Cursor 等 Agent 的开发者与 AI 工程师。
• 关心 AI 成本控制、希望压缩 token 的 CTO / 技术 Lead。
• 在本地或私有云部署 LLM、注重数据合规的企业架构师。

工作原理

Headroom 在客户端与 LLM 之间插入透明压缩层：基于本地训练的小模型（kompress-v2-base）结合规则式压缩，对工具输出与 RAG 结果做语义保留式摘要；关键信息（如错误关键字 FATAL）以"锚点"形式保留以便检索；CCR（Compression-Retrieval）机制把原文存到本地缓存，Agent 按需取回完整内容。整个链路完全本地运行，不依赖外部 API。

官方链接

• GitHub：https://github.com/headroomlabs-ai/headroom
• 文档：https://docs.headroomlabs.ai/docs
• PyPI：https://pypi.org/project/headroom-ai/
• 模型：https://huggingface.co/chopratejas/kompress-v2-base
• 协议：Apache-2.0