为什么需要
AI Agent 跑一段时间就崩溃的最常见原因：上下文窗口爆了。Claude Code 读了一个 5 万行日志文件、Cursor 在大型 monorepo 里 grep 整个目录、Agent 调工具拿到 10MB JSON——下一个请求直接超出 200K token 限制，对话被迫截断或者整体重来。
Headroom 是在 LLM 之前加一道压缩层。工具输出、日志、RAG chunks、文件内容、对话历史，所有进 LLM 的数据先过一遍压缩：把重复行去掉、把可逆向的信息压成摘要（需要时可以恢复）、把噪音字段删掉。实测一个真实场景：10,144 tokens 的 GitHub Action 错误日志压到 1,260 tokens，关键错误信息完全保留。
接入方式有四种，按改造成本从低到高：
- 代理模式 —
headroom proxy --port 8787，任何语言的 LLM 调用都能切到代理上，零代码改动 - 库调用 — Python/TypeScript 直接
compress(messages)，在自己的 Agent 代码里手动接入 - CLI wrap —
headroom wrap claude|codex|cursor|aider|copilot，一行命令包一层 - MCP server — 提供
headroom_compress、headroom_retrieve、headroom_stats三个工具
最有意思的是 headroom learn 子命令：它会挖掘 Agent 失败过的会话，自动把修正方案写进 CLAUDE.md / AGENTS.md，下次同类问题不再犯。
怎么用
Python 库调用：
python
from headroom import compress
compressed = compress(
messages=conversation_history,
target_ratio=0.3,
algorithm="kompress"
)
代理模式：
bash
headroom proxy --port 8787
# 把 LLM base URL 改成 http://localhost:8787/v1
CLI wrap 现有工具：
bash
headroom wrap claude
headroom wrap cursor
注意事项
- Apache 2.0 开源
- 6 种压缩算法各有侧重：kompress（自研模型）、llmlingua、recoverable、摘要型等
- 压缩/恢复完全可逆，原文存在本地，按需召回
- 复杂 RAG 场景下建议开启
headroom_retrieve配套，Agent 可以主动把压缩部分捞回来 - 自研的 Kompress-v2-base 模型在 HuggingFace 开源，可独立部署
- 跨 Agent 记忆共享：Claude、Codex、Gemini 跑的 Agent 可以共享同一个压缩记忆库