headroomlabs-ai/headroom

这是什么？

核心功能

• 01按内容类型路由，JSON、代码和自然语言分别使用不同的压缩器。
• 02可逆压缩，原始内容缓存在本地，可按需取回。
• 03提供无需改代码的代理，以及对主流编程智能体的一键接入命令。
• 04提供 Python 和 TypeScript 库，可通过 compress() 内联调用。
• 05提供 MCP 服务器，包含压缩、取回和统计工具。
• 06在本地运行压缩，提示词和文件内容无需发送到外部服务进行压缩。

适用场景

• 长时间运行、工具输出很多的编程智能体（如 Claude Code、Cursor），降低 token 成本。
• 在把日志或大型 JSON 搜索结果交给模型排查问题前先行压缩。
• 在已有的 LangChain 或 LiteLLM 流程中压缩检索到的 RAG 片段。
• 让多个智能体通过同一个代理和共享记忆层协同工作。

快速上手

1. 1

   使用 uv 安装命令行工具

   uv tool install --python 3.13 "headroom-ai[all]"
2. 2

   或使用 pip 安装 Python 包

   pip install "headroom-ai[all]"
3. 3

   在 8787 端口启动即插即用代理

   headroom proxy --port 8787
4. 4

   运行健康检查确认安装正常

   headroom doctor

使用前须知

• !节省效果差异很大，普通文本和已经很紧凑的输出压缩效果很小。
• !README 中的压缩基准数据由项目方自行报告，基于特定的固定随机种子场景。

标签

常见问题

headroom 是什么？

在内容发送给大模型前压缩工具输出、日志、文件和 RAG 片段的上下文压缩层。 Headroom 是面向 AI 智能体和大模型应用的上下文压缩层。它在工具输出、日志、RAG 片段、文件和对话历史发送给模型之前进行压缩，压缩过程在用户本机运行。内容路由会识别每段内容的类型：JSON 交给 SmartCrusher 处理，源代码交给基于 AST 的 CodeCompressor，自然语言文本则由 Kompress-v2-base 模型处理。

headroom 可以免费使用吗？用的什么许可证？

headroom 以 Apache-2.0 许可证开源。用于商业产品前，请先确认许可证条款。

headroom 还在维护吗？

活跃维护中。headroom 最近一次提交是在 2026年10月17日。

headroom 适合用来做什么？

长时间运行、工具输出很多的编程智能体（如 Claude Code、Cursor），降低 token 成本。 在把日志或大型 JSON 搜索结果交给模型排查问题前先行压缩。 在已有的 LangChain 或 LiteLLM 流程中压缩检索到的 RAG 片段。 让多个智能体通过同一个代理和共享记忆层协同工作。

headroom 怎么安装和运行？

使用 uv 安装命令行工具: uv tool install --python 3.13 "headroom-ai[all]" 或使用 pip 安装 Python 包: pip install "headroom-ai[all]" 在 8787 端口启动即插即用代理: headroom proxy --port 8787 运行健康检查确认安装正常: headroom doctor

在哪里获取 headroom？

源代码和安装说明在 GitHub 上：https://github.com/headroomlabs-ai/headroom