Headroom

Headroom 是 AI 智能体的上下文压缩层，在工具输出、日志、RAG 分块、文件和对话历史到达 LLM 之前对其进行智能压缩。通过自动检测内容类型并选择专用压缩器，在保持答案质量不变的前提下大幅减少 token 消耗。

核心功能

• 智能内容压缩：ContentRouter 自动检测内容类型，SmartCrusher 处理 JSON（减少60-95%）、CodeCompressor 基于 AST 压缩代码、Kompress-v2-base 压缩文本
• 多种集成模式：Python/TypeScript 库内联调用、零代码代理模式、一键 wrap 主流编码智能体、独立 MCP 服务器
• 可逆压缩（CCR）：原始内容本地缓存，LLM 可通过 headroom_retrieve 按需取回完整内容
• 跨智能体记忆：在 Claude、Codex、Gemini、Grok 之间共享存储，自动去重
• 输出 Token 缩减：裁剪模型回复中的冗余内容（客套话、重复代码、过度思考）
• 失败学习：headroom learn 自动从失败会话中学习并写入纠正规则

适用场景

• 降低编码智能体（Claude Code、Cursor、Codex、Aider、Cline等）的 token 消耗
• 压缩 SRE 事故调试日志（可达92% token节省）
• GitHub Issue 分类和代码搜索结果压缩
• 大规模代码库探索时的上下文窗口管理
• RAG 管线中减少检索分块的 token 数量
• 多智能体协作中的上下文共享与记忆管理

安装方式

前置要求：Python 3.10+

# 推荐：uv 全局安装 CLI 工具
uv tool install --python 3.13 "headroom-ai[all]"

# 或 pip 安装
pip install "headroom-ai[all]"

# 一键本地部署+智能体配置
headroom deploy

# 包装编码智能体
headroom wrap claude

# 启动 MCP 服务器
headroom mcp serve

许可证：Apache-2.0
GitHub Stars：64k+