headroom：为AI Agent装上上下文压缩层，Token省95%

来源：互联网 2026-07-20 06:27:10

Headroom是AIAgent的上下文压缩层，包含了用于压缩JSON的SmartCrusher、压缩代码的CodeCompressor和压缩文本的Kompress-base三款引擎，并采用CCR可逆压缩技术保留原文。支持Library、Proxy、AgentWrap、MCPServer这四种集成模式，最高可节省高达95%的Token，实测在代码搜索中节省9

引言

现实是，随着 Agent 越来越复杂，上下文被填充得越来越满。工具返回的 JSON 动辄几千行，RAG 检索出的文档大量冗余，搜索结果里充斥着无关内容，日志中更是噪声不断。最终的后果很有代表性：Token 消耗飞涨，成本失控，有时甚至直接超出窗口限制。

长期稳定更新的攒劲资源： >>>点此立即查看<<<

但压缩这件事，headroom 有自己的理解。它的方案是在内容进入 LLM 之前先做一道工序：不是简单截断，也不是做一遍摘要——后者会丢失信息。它要做的是保留关键信息、去掉冗余，同时还支持按需取回原文。听起来很实用。

围绕这个核心思路，接下来会拆解几个关键点：Agent 上下文为什么会“膨胀”，膨胀的代价到底有多大；headroom 的四种集成模式（Library / Proxy / Agent Wrap / MCP Server）各自适用什么场景；三种压缩引擎 SmartCrusher、CodeCompressor、Kompress-base 到底怎么工作的；CCR 可逆压缩如何做到压缩后还能取回原文；以及真实的基准测试数据——不同工作负载下的压缩率与精度保持情况。

前置条件也不高：有基础的 Python 使用经验，了解 LLM API 的基本用法（Token 计费概念），如果用过至少一种 AI Agent 框架会更好。

项目背景

项目简介

headroom 自称是“AI Agent 的上下文压缩层”，它的位置正好卡在用户输入与 LLM 之间。核心逻辑很直接：工具输出、日志、代码片段、RAG 检索结果里，往往有大量与当前问题无关的内容。把这些冗余去掉，LLM 反而能看得更清楚、答得更准——同时还能省下大量 Token。

与简单截断或摘要不同，headroom 的压缩是可逆的。原始内容会保留在本地，LLM 通过 headroom_retrieve 工具可以按需取回，不会因为压缩而丢失任何信息。

作者/团队介绍

作者: Tejas Chopra（chopratejas）
语言组成: Python 76.9% + Rust 18.3% + TypeScript 2.7%
License: Apache 2.0

项目数据

GitHub Stars: 12,800+
Forks: 823
版本: v0.23.0（最新）
License: Apache 2.0
支持: Python 3.10+，Node.js，Docker

主要功能

核心作用

headroom 在 Agent 的工具输出到达 LLM 之前拦截并压缩内容，目的是降低噪声、节省 Token、避免上下文窗口超限。整体定位是一个透明的压缩中间件——不改变 Agent 的逻辑，只改变内容的密度。

使用场景

代码搜索与分析
- 搜索 100 个文件返回 17,765 个 token，压缩后仅 1,408 个（节省 92%），Agent 只看到与问题相关的代码片段
SRE 事故调试
- 系统日志、堆栈跟踪、指标数据混合输入，65,694 token 压缩至 5,118（节省 92%），关键异常信息反而更突出
GitHub Issue 分流
- 批量处理 Issue，54,174 token 压缩至 14,761（节省 73%），分类准确率不降
RAG 检索增强生成
- 检索出的文档块去冗余后，LLM 不再被不相关内容干扰，回答精度反而提升
多 Agent 协作
- 跨 Agent 共享压缩后的记忆，自动去重，避免同一信息被重复消耗多次

快速开始

# 安装完整版（含所有扩展）pip install "headroom-ai[all]"# 或按需安装扩展：[proxy] [mcp] [ml] [code] [memory] [langchain] 等pip install "headroom-ai[proxy,mcp]"

方式一：Library 模式（代码内嵌）

from headroom import Headroomhr = Headroom()# 压缩消息列表，传给 LLM 前调用compressed = hr.compress(messages)# 正常调用 LLMresponse = client.messages.create(model="claude-opus-4-5",messages=compressed.messages,)# 查看节省了多少 Tokenprint(f"压缩率: {compressed.compression_ratio:.1%}")print(f"节省 Token: {compressed.tokens_sa ved}")

方式二：Proxy 模式（零代码改动）

# 启动透明袋里headroom proxy --port 8787# 只需把 base_url 指向袋里，其余代码不变

import anthropic# 只改一行：把 API 请求打到 headroom proxyclient = anthropic.Anthropic(base_url="http://localhost:8787")# 之后的代码完全不变response = client.messages.create(...)

方式三：Agent Wrap（一行命令包装现有 Agent）

headroom wrap claude# 包装 Claude Codeheadroom wrap aider # 包装 Aiderheadroom wrap cursor# 包装 Cursorheadroom wrap codex # 包装 Codex CLI

查看压缩统计

headroom perf# 输出: 今日节省 Token: 48,392 | 累计节省: $12.40

核心特性

四种集成模式
- Library / Proxy / Agent Wrap / MCP Server，按需选择，无需改造已有架构
CCR 可逆压缩（Compressed Context Retrieval）
- 压缩后原文本地存储，LLM 可通过 headroom_retrieve 工具按需取回，压缩不等于丢弃
跨 Agent 共享记忆
- 多个 Agent 访问同一记忆存储，自动去重，避免重复消耗相同信息
headroom learn 自动学习
- 分析失败的 Agent 会话，自动将经验写入 CLAUDE.md / AGENTS.md，让下次运行更聪明
全内容类型覆盖
- JSON（SmartCrusher）、代码（AST 级别 CodeCompressor）、纯文本（Kompress-base）、图像均支持
本地优先，隐私安全
- 所有压缩计算本地完成，数据不离开本机

项目优势对比

对比维度	headroom	简单截断	LLM 摘要	手动过滤
信息保留	可逆，原文可取回	永久丢失	可能失真	依赖规则
集成成本	1行代码 / 0行代码	简单	需要额外 LLM 调用	维护成本高
压缩质量	结构感知	无感知	通用摘要	场景局限
成本	节省 API 费用	无额外成本	额外 Token 消耗	无额外成本

项目详细剖析

压缩流水线架构

headroom 的内部处理流程分为三个阶段：

用户输入 / 工具输出 ↓CacheAligner← 对齐缓存，避免重复处理相同内容 ↓ContentRouter ← 识别内容类型，路由到对应引擎├── SmartCrusher (JSON / 结构化数据)├── CodeCompressor (代码，AST 级别)└── Kompress-base(纯文本，HuggingFace 模型) ↓压缩后内容 → LLM ↓原文本地存储（CCR 索引）← 支持按需检索

CacheAligner 负责识别已经处理过的内容，跳过重复压缩，降低计算开销。ContentRouter 则分析消息内容类型——JSON 结构、代码语法、纯文本——然后路由到最适合的压缩引擎。不同类型的内容用不同策略压缩，效果自然远好于通用方案。

三种压缩引擎

① SmartCrusher（JSON / 结构化数据）

工具调用的返回值通常是 JSON，里面包含大量与当前问题无关的字段。SmartCrusher 会分析 LLM 的上一条查询，提取相关字段，丢弃无关结构。

举个例子：

# 原始工具返回：1200 token{"results": [{"id": "abc123","title": "...","content": "...", # 与查询相关"metadata": { # 无关字段"created_at": "...","updated_at": "...","author_id": 42,"tags": ["...", "..."],"internal_score": 0.87,# ... 20+ 更多无关字段}}# × 99 更多结果]}# 压缩后：约 80 token（节省 93%）# 只保留 title + content，剔除所有 metadata

② CodeCompressor（代码，AST 级别）

代码的压缩不能靠截断——截断会破坏语法，LLM 看到残缺的代码反而更困惑。CodeCompressor 解析 AST（抽象语法树），保留函数签名、类定义、关键注释，压缩掉函数体实现细节。

# 原始代码片段：800 tokendef process_payment(user_id: int,amount: float,currency: str = "USD",retry_count: int = 3) -> PaymentResult:"""处理支付请求，支持重试机制"""for attempt in range(retry_count):try:# 验证用户余额balance = get_user_balance(user_id)if balance < amount:raise InsufficientFunds(...)# ... 200 行实现细节 ...except NetworkError:if attempt == retry_count - 1:raisetime.sleep(2 ** attempt)# AST 压缩后：约 60 tokendef process_payment(user_id: int, amount: float,currency: str = "USD", retry_count: int = 3) -> PaymentResult:"""处理支付请求，支持重试机制"""...# [实现已压缩，可通过 headroom_retrieve 取回]

③ Kompress-base（纯文本）

对于文档、日志等纯文本，headroom 使用 HuggingFace 上的 Kompress-base 模型做语义压缩，保留与当前查询最相关的句子，过滤冗余。

CCR：可逆压缩的关键

普通截断是单向的——一旦截掉，信息就永久丢失了。headroom 的 CCR（Compressed Context Retrieval）机制让压缩变得可逆。

原文 ──────────── 压缩 ──────────→ LLM││└── 存入本地 CCR 索引│ (按 trace_id 索引)│ │ 需要更多细节时 ↓headroom_retrieve("trace_id", "函数实现") │ ↓从本地索引取回原文片段

在 MCP Server 模式下，LLM 可以主动调用 headroom_retrieve 工具：

# LLM 决定需要查看完整实现时，自动调用：headroom_retrieve(trace_id="abc123",query="process_payment 的重试逻辑实现")# → 返回原始代码的对应片段

MCP Server 模式

MCP 模式暴露三个工具给 LLM：

# Claude Code / Cursor / 任何支持 MCP 的客户端可以直接调用headroom_compress(content, content_type="auto")# → 压缩内容，返回压缩后文本 + trace_idheadroom_retrieve(trace_id, query)# → 按需取回原文片段headroom_stats()# → 返回当前会话的压缩统计信息

配置示例（claude_desktop_config.json）：

{"mcpServers": {"headroom": {"command": "headroom","args": ["mcp"]}}}

headroom learn：从失败中自动学习

这是 headroom 最独特的功能之一。当 Agent 会话失败（任务未完成、LLM 多次重试、上下文超限），headroom learn 会分析失败原因，自动将学到的规律写入 CLAUDE.md 或 AGENTS.md。

headroom learn --session-log ./logs/session_2026-06-05.jsonl# 输出示例：# 发现 3 个重复模式：# 1. 在搜索 GitHub API 时总是携带过多 metadata 字段 → 已添加过滤规则到 CLAUDE.md# 2. 处理大型 JSON 响应时上下文超限 3 次 → 已添加 SmartCrusher 提示到 AGENTS.md# 3. 代码分析任务中 CodeCompressor 提升了 40% 成功率 → 已记录配置