Headroom headroomlabs-ai/headroom

能干什么

一个跑在本地的上下文压缩中间件，专门治「Agent 烧 token」：它压的是模型要读的东西——工具输出、日志、RAG 检索片段、文件、对话历史，按内容类型路由到不同压缩器（JSON 用 SmartCrusher、代码用 AST 感知的 CodeCompressor、文本用自训的 Kompress 小模型）。项目自述的四个真实 Agent 场景基准：代码搜索省 21%、SRE 排障省 57%、代码库探索省 42%、issue 分诊省 30%；重复性强的 JSON/日志能省 90%+，纯散文几乎不省。接入方式四种：Python/TS 库一行 compress()、零代码改动的本地代理（headroom proxy）、一条命令包现有编码 Agent（headroom wrap claude/codex/cursor/copilot/aider/cline 等十几款）、MCP server。压缩可逆——原文缓存在本地（CCR），模型要全文时自己调 headroom_retrieve 取回；跨 Agent 共享一份记忆；headroom learn 能从失败会话里挖教训写回 CLAUDE.md 这类指令文件。压缩全程本地跑、数据不出机器，延迟开销亚毫秒级（项目自述 10K token 输入 p50 0.21ms）。

怎么干

• uv tool install --python 3.13 "headroom-ai[all]"（或 pip install；TS 只用 npm 库）
• 选一种接法：headroom proxy --port 8787 起代理（零改动）/ headroom wrap claude 包一个编码 Agent / 自己代码里 from headroom import compress 内联用
• headroom doctor 体检，headroom dashboard 看实时省了多少 token

本站怎么用

它把本站反复回答的「上下文吃显存」问题在输入侧做了一道减法：上下文窗口有限、长工具输出挤占上下文，压缩后同样窗口装得下更多有效信息——对本地小模型尤其有意义（窗口小、每一 token 都贵）。读者用 Cline/aider/OpenClaw 这类编码 Agent 时，这是「不改代码、加一层就省 token」的选项。注意它省的是输入 token，模型本身还是你配的那个（本地或在线）。

显存口径

自身几乎不占显存：基础压缩进程内跑、无需下大模型；[ml] 特性会带 PyTorch（Kompress 模型较小），纯 CPU 也够。它不跑主模型，显存账全在你配的那个 LLM 上（本地模型按 /capacity/ 档位）。