headroomlabs-ai/headroom — 精读笔记

来源：GitHub (★72715)

URL: https://github.com/headroomlabs-ai/headroom

精读日期：2026-09-18

模型：DeepSeek V4 Flash（AI 生成，人工未审校）

正文获取：全文

一、核心论点/事实

Headroom 在内容到达 LLM 前压缩工具输出、日志、RAG 片段、文件与对话历史，宣称编码 Agent 减少 20% token，JSON 减少 60-95% token，且答案质量不变。
压缩完全在本地运行，提示词与文件内容不外发；原始内容本地缓存，按需检索。
提供三种形态：Python/TypeScript 库、代理（proxy）、MCP 服务器；CLI 仅随 PyPI 包发布，npm 包是 TypeScript SDK。
支持 headroom wrap 一键包裹 claude、codex、grok、copilot、cursor、aider、opencode、cline、continue、goose、openhands 等十余种 Agent。
跨 Agent 共享存储（Claude、Codex、Gemini、Grok）并自动去重；headroom learn 挖掘失败会话并写入修正。
基准测试用真实 MCP 服务器输出格式构建四个场景，命令为 uv run python benchmarks/index_proof_table.py --seed 20260902。
压缩延迟极低：100K token 时约 1.4 ms，不影响 Agent 延迟。

流水线：CacheAligner → ContentRouter → CCR；ContentRouter 识别内容类型并选择压缩器。
三个专用压缩器：SmartCrusher（JSON）、CodeCompressor（AST，源码）、Kompress-v2-base（文本/散文，HuggingFace 模型）。
CacheAligner 标记会破坏 provider KV-cache 前缀的易变内容，且从不改写提示词。
输出侧优化：在系统提示词末尾追加"简洁、不复述上下文"的短指令以保持 prompt cache 命中；当某轮只是工具结果后的恢复（如读文件、测试通过）时降低 thinking effort，新问题与错误保持全量思考。
配置热更新：每次请求实时读取开关，通过 loopback 将当前设置热同步到运行中的代理，无需重启、不丢请求；共享代理上覆盖是全局的，最后一次显式设置生效。
附带 Serena 语义代码导航，以 user scope 注册（Claude Code 中），在其他项目持续可用。

作者承认：节省程度取决于载荷的重复度，重复 JSON 数组与日志收益最大；TruthfulQA 在 N=100 时 ±0.03 落在置信区间内，属"无可检测差异"而非提升；输出侧节省是反事实的，无法观测模型本会输出什么；共享代理上的配置覆盖是全局的，最后设置者生效；包裹会话需每次启动才能生效。
AI 判断：60-95% 的 JSON 压缩率高度依赖特定数据形态，泛化到非重复性内容时可能显著缩水；"答案不变"的验证仅提及 TruthfulQA 一项基准，覆盖任务类型有限；跨 Agent 共享存储与失败会话挖掘涉及本地敏感数据聚合，虽称本地运行，但存储安全边界未在文中说明。

Harness 工程：CacheAligner 的"只标记不改写"与系统提示词尾部追加指令的设计，是保持 KV-cache 命中的可借鉴模式；配置热同步机制对长驻 Harness 服务有直接参考价值。
多模型协同：跨 Agent 共享存储 + 自动去重 + 失败会话学习，可作为多模型协同中记忆层与经验回流的实现范式。
模型评测：其"节省是反事实的"这一自认局限，提示评测 Agent 压缩类组件时需设计可对照的基线；TruthfulQA 置信区间处理方式可作为评测严谨性案例。
Agent 落地：按内容类型路由到 JSON/AST/文本三类压缩器的架构，适合作为 Agent 上下文治理的工程模板；输出侧"仪式性内容"裁剪与动态 thinking effort 调节，是降低推理成本的可落地手段。
AI 原生产品：本地压缩 + 原始内容按需检索的隐私优先设计，可作为面向企业客户的 Agent 产品差异化卖点。

本笔记由 DeepSeek V4 Flash 自动生成，未经人工审校。原文链接：https://github.com/headroomlabs-ai/headroom