Headroom：让 AI 智能体少花 90% Token 的上下文压缩层

项目简介

Headroom 是一个为 AI 智能体（AI Agent）打造的上下文压缩层。它在提示词、工具输出、日志、RAG 检索片段、文件和对话历史到达大模型之前进行压缩，让你在获得相同答案的同时， Token 成本大幅下降。官方实测：JSON 类数据可减少 60–95% 的 Token，编码类智能体可减少 15–20%。

核心功能

• 多种部署形态：Python/TypeScript 内联库、headroom proxy 零代码代理、headroom wrap 一键包装 Claude/Codex/Cursor/Aider/Cline 等主流 Agent，以及原生 MCP Server。
• 内容感知压缩：SmartCrusher 专攻 JSON，CodeCompressor 基于 AST 压缩代码，Kompress-v2-base 用自研 HuggingFace 模型处理自然语言。
• 可逆压缩（CCR）：原始内容本地缓存，LLM 可通过 headroom_retrieve 按需取回，绝不丢失信息。
• 跨 Agent 记忆：同一台机器上 Claude、Codex、Grok、Gemini 等工具可共享记忆库并自动去重。
• 输出 Token 优化：通过 Verbosity steering 和 Effort routing，自动削减模型废话、重复代码和过度思考，进一步降低输出侧成本。
• headroom learn：自动挖掘失败会话，把纠偏规则写入 CLAUDE.local.md、AGENTS.md 或 GEMINI.md，让 Agent 越用越聪明。

安装要求和过程

环境要求：Python 3.10+。推荐用 uv 或 pip 安装；TypeScript 开发者也可用 npm 安装 SDK（仅库，无 CLI）。

# 推荐：uv 全局工具安装（隔离环境）
uv tool install --python 3.13 "headroom-ai[all]"

# 或者 pip
pip install "headroom-ai[all]"

# TypeScript SDK（仅库）
npm install headroom-ai

启动方式三选一：

# 一键部署 + 自动配置 Agent
headroom deploy

# 包装 Claude Code（自动启动本地代理并注入配置）
headroom wrap claude

# 零代码 drop-in 代理
headroom proxy --port 8787

验证：

headroom doctor    # 健康检查
headroom perf      # 性能报告
headroom dashboard # 实时节省看板

典型使用场景

场景 1：AI 编码助手降本增效
你每天用 Claude Code、Cursor 或 Codex 处理大型代码库。代码搜索结果、RAG 片段、测试日志动辄几万 Token。Headroom 自动压缩输入内容，代码搜索场景可减少 92% Token，而答案质量不变。配合 headroom learn，它还能把常见误操作自动写入项目本地规则文件。

场景 2：SRE 事故排查
排查线上事故时，需要把大量日志、监控输出、GitHub Issue、运行时报错塞进上下文。Headroom 对日志和结构化数据压缩率极高，65k Token 的排查材料可压缩到 5k 左右，让智能体在上下文窗口内“看完全部证据”，而不是被截断。

场景 3：多 Agent 共享记忆
你在同一项目里混用 Claude Code、Codex、Grok CLI 和 Aider。Headroom 提供跨 Agent 的共享记忆存储，避免每个工具重复读取文件、重复建立上下文，真正实现“一次理解，处处可用”。

推荐理由

Headroom 最让我喜欢的一点是“不绑架你的工作流”。它既可以是库，也可以是代理，还可以一键 wrap 你已有的 Agent，不需要重写 prompt 或迁移模型。而且它是本地优先的，原始内容不会离开你的机器，企业敏感代码也能放心使用。

更难得的是，它在省钱的同时还做了“可逆压缩”和“失败学习”：前者保证信息不丢，后者让 Agent 越用越准。对于已经在用 Claude Code、Cursor、Codex 等工具的开发者来说，Headroom 几乎是“装完就能省钱”的基础设施。

下载地址

• GitHub 仓库：https://github.com/headroomlabs-ai/headroom
• 官方文档：https://docs.headroomlabs.ai/docs
• PyPI：https://pypi.org/project/headroom-ai/
• HuggingFace 模型：Kompress-v2-base

Headroom 采用 Apache 2.0 协议开源，当前 Stars 约 63.2K，主要语言为 Python。