每天一个开源项目#1 Headroom — AI Agent 上下文压缩层，Token 消耗直降 95%

dong_junshuai
2 阅读5分钟

Headroom — AI Agent 上下文压缩层，Token 消耗直降 95%

GitHub Trending #1 · 2026-06-03 · ⭐ 7,509 · Fork 508

📌 项目概览

Headroom 是一个 AI Agent 上下文压缩中间层，位于你的 Agent（Claude Code、Cursor、Codex 等）和 LLM Provider 之间，对 Agent 读取的所有内容 — 工具输出、日志、RAG 结果、文件、对话历史 — 进行智能压缩，再送入 LLM。

核心价值：相同的回答质量，Token 消耗减少 60%-95%。对于高频使用 AI 编程 Agent 的开发者来说，这意味着显著的成本节省和更少的上下文窗口溢出问题。

项目地址：github.com/chopratejas…

🚀 核心特性

  1. Library 模式 — compress(messages) 一行代码集成到任何 Python/TypeScript 应用中
  2. Proxy 模式 — headroom proxy --port 8787，零代码修改，任何语言都能用
  3. Agent Wrap — headroom wrap claude|codex|cursor|aider|copilot 一条命令包装主流 Agent
  4. MCP Server — 提供 headroom_compress、headroom_retrieve、headroom_stats 三个 MCP 工具，任何 MCP 客户端可调用
  5. 跨 Agent 记忆 — Claude、Codex、Gemini 之间共享压缩记忆，自动去重
  6. headroom learn — 从失败的 Agent 会话中挖掘经验，自动写入 CLAUDE.md / AGENTS.md
  7. 可逆压缩（CCR） — 原始内容永不删除，LLM 按需通过 headroom_retrieve 取回原文
  8. 6 种压缩算法 — SmartCrusher（JSON）、CodeCompressor（AST）、Kompress-base（文本，HuggingFace 模型）等

🏗️ 技术架构

Your Agent / App
  (Claude Code, Cursor, Codex, LangChain, your own code...)
       │   prompts · tool outputs · logs · RAG results · files
       ▼
   ┌─────────────────────────────────────────────────────┐
   │  Headroom   (runs locally — your data stays here)   │
   │  ─────────────────────────────────────────────────  │
   │  CacheAligner  →  ContentRouter  →  CCR             │
   │                    ├─ SmartCrusher   (JSON)          │
   │                    ├─ CodeCompressor (AST)           │
   │                    └─ Kompress-base  (text, HF)      │
   │                                                     │
   │  Cross-agent memory  ·  headroom learn  ·  MCP      │
   └─────────────────────────────────────────────────────┘
       │   compressed prompt  +  retrieval tool
       ▼
  LLM Provider  (Anthropic · OpenAI · Bedrock · …)

关键组件：

  • ContentRouter — 自动检测内容类型，路由到最合适的压缩器
  • SmartCrusher — 专门压缩 JSON 结构（工具输出的主力）
  • CodeCompressor — 基于 AST 的代码压缩，保留语义
  • Kompress-base — 基于 HuggingFace 模型的通用文本压缩
  • CacheAligner — 稳定前缀，让 Provider 的 KV Cache 命中率提升
  • CCR（Cross-agent Context Retrieval） — 本地存储原始内容，LLM 需要时可按需取回

本地优先：所有数据处理在本地完成，不经过第三方服务器。

📊 代码结构与技术栈

语言分布：

语言占比
Python76.7%
Rust18.4%
TypeScript2.7%
HTML0.9%
PowerShell0.5%
Shell0.4%
其他（C, Dockerfile, PLpgSQL 等）< 1%

技术栈：

  • 核心逻辑：Python（FastAPI）
  • 高性能压缩引擎：Rust（性能敏感路径）
  • TypeScript SDK：前端/Node 生态支持
  • MCP 协议：原生 MCP Server 支持
  • Docker 部署：提供 Dockerfile
  • CI/CD：GitHub Actions + Codecov

设计亮点：Python 负责易用性和生态集成，Rust 负责压缩算法的性能，TypeScript 覆盖前端场景。这种多语言架构在开源工具中越来越常见。

📈 基准测试

真实 Agent 工作负载节省：

工作负载压缩前压缩后节省
代码搜索（100 结果）17,7651,40892%
SRE 事件调试65,6945,11892%
GitHub Issue 分诊54,17414,76173%
代码库探索78,50241,25447%

精度保持：

基准类别基线Headroom变化
GSM8K数学0.8700.870±0.000
TruthfulQA事实0.5300.560+0.030
SQuAD v2QA—97%19% 压缩
BFCL工具—97%32% 压缩

🔧 快速上手

# 安装
pip install "headroom-ai[all]"          # Python
npm install headroom-ai                 # Node / TypeScript

# 使用方式一：包装 Agent
headroom wrap claude                    # 包装 Claude Code
headroom wrap codex                     # 包装 Codex
headroom wrap cursor                    # 包装 Cursor

# 使用方式二：代理模式（零代码修改）
headroom proxy --port 8787

# 使用方式三：代码集成
from headroom import compress
result = compress(messages, model="claude-sonnet-4")

# 查看统计
headroom stats

支持的 Agent：Claude Code、Codex、Cursor、Aider、Copilot CLI、OpenClaw。

环境要求：Python 3.10+

🎯 适用场景

强烈推荐：

  • 每天高频使用 AI 编程 Agent 的开发者（Claude Code、Cursor 等）
  • 跨多个 Agent 工作，需要共享上下文记忆的团队
  • 需要可逆压缩，确保原始内容随时可取回的场景
  • LLM API 成本敏感的团队和个人

可能不需要：

  • 只使用单一 Provider 的原生压缩功能，且不需要跨 Agent 记忆
  • 在沙盒环境中无法运行本地进程的场景

🌟 社区热度分析

指标数据
⭐ Star7,509
🍴 Fork508
📋 Open Issues130
📜 LicenseApache-2.0
🗓️ 创建时间2026-01-07
🔄 最近更新2026-06-03（今日）

活跃度：项目创建不到 5 个月就达到 7500+ Star，今日仍在 Trending 第一名，说明社区关注度极高。130 个 Open Issues 表明用户活跃参与，但也意味着项目仍在快速迭代中，API 可能有变动。

Tags：agent ai claude-code compression context-engineering context-window cursor llm mcp openai rag token-optimization

💡 总结评价

亮点：

  • 切中痛点：AI Agent 的 Token 消耗是实实在在的成本问题，92% 的压缩率非常吸引人
  • 架构优雅：ContentRouter 自动路由、CCR 可逆压缩、CacheAligner 缓存优化，设计考虑周全
  • 生态覆盖广：支持 6+ 主流 Agent，提供 Library/Proxy/MCP/Wrap 四种集成方式
  • 多语言实现：Python 易用 + Rust 性能 + TypeScript 覆盖，各取所长
  • 本地优先：数据不出本机，隐私安全有保障

不足：

  • 项目较新（5 个月），API 稳定性有待观察
  • 130 个 Open Issues 说明还在快速迭代，生产环境使用需谨慎
  • Kompress-base 模型需要从 HuggingFace 下载，首次使用有一定门槛
  • 压缩可能在某些极端场景下丢失细微语义，需要根据实际场景评估

一句话总结：如果你是 AI Agent 的重度用户，Headroom 值得一试 — 它可能是目前最实用的上下文压缩方案。

avatar
文章
阅读
粉丝