Headroom— AI Agent 的上下文压缩层在工具输出、日志、文件和 RAG 块进入 LLM 之前压缩 token实现 60-95% 的 token 减少。目录简介系统要求安装步骤配置说明功能详解使用方法测试与监控常见问题参考链接简介什么是 HeadroomHeadroom 是一个本地优先的上下文压缩工具可以在 AI Agent 读取内容之前对所有输入进行智能压缩工具输出tool outputs日志logs文件内容filesRAG 检索块RAG chunks对话历史conversation history核心优势优势说明节省 Token 费用60-95% 的 token 减少API 费用大幅降低更快响应更少的 token 更快的推理速度兼容所有 AgentClaude Code、Cursor、Codex、Aider、Copilot CLI 等都支持完全本地运行数据不离开你的机器隐私安全可逆压缩原始内容被缓存LLM 需要时可以检索还原零代码改动Proxy 模式下无需修改任何代码跨 Agent 共享记忆不同 Agent 之间共享上下文记忆系统要求操作系统: Windows 10/11、macOS、LinuxPython: 3.8 或更高版本磁盘空间: 至少 500MB用于安装和缓存内存: 建议 4GB 以上安装步骤方式一使用 pip 安装推荐1. 创建虚拟环境# 创建虚拟环境目录mkdirD:\toolscdD:\tools# 创建 Python 虚拟环境python-mvenv headroom-venv# 激活虚拟环境# Windows:D:\tools\headroom-venv\Scripts\activate# macOS/Linux:source/d/tools/headroom-venv/bin/activate2. 安装 Headroom# 安装完整版本包含所有功能pipinstallheadroom-ai[all]# 验证安装headroom--version3. 安装包含的功能模块headroom-ai[all]包含以下模块模块功能proxy代理服务器模式memory跨 Agent 共享记忆mlML 压缩模型code代码压缩mcpMCP 服务器集成方式二使用 Docker 安装# 拉取 Docker 镜像dockerpull ghcr.io/chopratejas/headroom:latest# 运行容器dockerrun-d\--nameheadroom\-p8787:8787\-vheadroom-data:/data\ghcr.io/chopratejas/headroom:latest配置说明目录结构安装完成后会创建以下目录D:\tools\├── .headroom\# 配置和记忆数据库│ ├── memory.db# 记忆数据库│ ├── memory_graph.db# 图数据库│ └── memory_vectors.db# 向量数据库├── headroom-data\# 数据备份目录└── headroom-venv\# Python 虚拟环境├── Include\├── Lib\├── Scripts\│ └── headroom.exe# 可执行文件└── pyvenv.cfg配置文件位置Windows:C:\Users\用户名\.headroom\macOS/Linux:~/.headroom/环境变量配置在启动脚本中设置以下环境变量echo off chcp 65001 nul title Headroom Claude Code REM 配置信息 echo Configuration: echo - Proxy URL: http://127.0.0.1:8787 echo - Target API: https://api.xiaomimimo.com/anthropic echo - Mode: token optimization (60-95%% fewer tokens) echo. REM 禁用 Rust 核心可选 set HEADROOM_REQUIRE_RUST_COREfalse REM 设置目标 API URL set ANTHROPIC_TARGET_API_URLhttps://api.xiaomimimo.com/anthropic REM 启动代理 D:\tools\headroom-venv\Scripts\headroom.exe proxy --port 8787 pause功能详解1. Token 节约功能原理: 在请求发送到 LLM 之前智能压缩上下文内容减少 token 数量。压缩策略:内容路由: 根据内容类型选择压缩策略智能跳过: 短内容50 词不压缩避免压缩开销可逆压缩: 原始内容缓存需要时可还原压缩率: 通常 60-95%取决于内容类型和长度2. 记忆功能数据库文件:memory.db— 主记忆存储memory_graph.db— 知识图谱memory_vectors.db— 向量索引功能:跨 Agent 共享记忆持久化对话历史向量化检索3. Proxy 代理模式工作原理:用户 → Claude Code → Headroom Proxy(localhost:8787)→ 目标 API ↓ 压缩 token 缓存优势:零代码改动透明代理自动压缩使用方法方式一Proxy 代理模式推荐1. 启动代理服务器# 激活虚拟环境D:\tools\headroom-venv\Scripts\activate# 启动代理headroom proxy--port87872. 配置 Claude Code 使用代理在 Claude Code 配置中设置 API 端点为:http://127.0.0.1:87873. 创建启动脚本创建start-headroom-claude.bat:echo off chcp 65001 nul title Headroom Claude Code echo Configuration: echo - Proxy URL: http://127.0.0.1:8787 echo - Target API: https://api.xiaomimimo.com/anthropic echo - Mode: token optimization (60-95%% fewer tokens) echo. set HEADROOM_REQUIRE_RUST_COREfalse set ANTHROPIC_TARGET_API_URLhttps://api.xiaomimimo.com/anthropic echo Starting Headroom proxy on port 8787... echo. D:\tools\headroom-venv\Scripts\headroom.exe proxy --port 8787 pause方式二Wrap 包装模式包装 Claude Code# 一键包装 Claude Codeheadroom wrap claude# 包装 Codex与 Claude 共享记忆headroom wrap codex# 包装 Cursorheadroom wrap cursor# 包装 Aiderheadroom wrap aider# 包装 Copilot CLIheadroom wrap copilot方式三Python 库内联使用importasynciofromheadroomimportcompressasyncdefmain():messages[{role:system,content:You are a helpful assistant.},{role:user,content:Explain quantum computing...},{role:assistant,content:Quantum computing is...}]# 压缩消息compressedawaitcompress(messages,modelgpt-4)print(f压缩后 token 数:{len(str(compressed))})if__name____main__:asyncio.run(main())方式四TypeScript 库内联使用import{compress}fromheadroom-ai;asyncfunctionmain(){constmessages[{role:system,content:You are a helpful assistant.},{role:user,content:Explain quantum computing...}];constcompressedawaitcompress(messages,{model:gpt-4});console.log(压缩完成:,compressed);}main();方式五MCP 服务器集成# 安装 MCP 服务器headroom mcpinstall# 查看 MCP 状态headroom mcp status测试与监控查看压缩效果# 查看完整统计默认 7 天headroom perf# 查看最近 24 小时headroom perf--hours24# 查看最近 1 小时headroom perf--hours1# 导出 CSV 格式headroom perf--formatcsv--hours24stats.csv# 导出 JSON 格式headroom perf--formatjsonstats.json性能报告解读Headroom Performance ReportWindow: last 168h Requests:236# 总请求数Tokens:12,623,728 -12,455,827(1.3% reduction)Total saved:167,901tokens# 节省的 token 数Content Router Routing ---------------------------------------- Compressed:29(4%)# 实际被压缩的内容Excluded:21(3%)# Read/Glob 输出被排除Skipped:460(69%)# 太短 (50 词) 被跳过Unchanged:155(23%)# 压缩比率不够高重置统计# 备份旧日志cp~/.headroom/logs/proxy.log ~/.headroom/logs/proxy.log.bak# 清空日志~/.headroom/logs/proxy.log# 重新开始统计headroom perf--hours1监控脚本创建monitor-headroom.sh:#!/bin/bash# 每 5 分钟刷新一次统计watch-n300headroom perf --hours 1常见问题Q1: 压缩率很低10%怎么办原因: 大部分内容是短消息50 词会被自动跳过。解决方案:增加长内容的使用场景代码、文档、工具输出调整压缩阈值如果支持检查压缩路由统计了解哪些内容被跳过Q2: 代理服务器启动失败检查步骤:# 1. 检查端口是否被占用netstat-ano|findstr :8787# 2. 检查 Python 虚拟环境D:\tools\headroom-venv\Scripts\python--version# 3. 重新安装pipinstall--upgradeheadroom-ai[all]# 4. 查看详细日志headroom proxy--port8787--verboseQ3: 记忆功能不工作检查步骤:# 1. 检查记忆数据库是否存在ls-la~/.headroom/memory*.db# 2. 查看记忆统计headroom memory stats# 3. 列出所有记忆headroom memory listQ4: 如何更新 Headroom# 激活虚拟环境D:\tools\headroom-venv\Scripts\activate# 更新到最新版本pipinstall--upgradeheadroom-ai[all]# 或使用内置更新命令headroom updateQ5: 如何卸载 Headroom# 1. 停止代理服务器CtrlC# 2. 卸载 Python 包pip uninstall headroom-ai# 3. 删除目录rm-rfD:\tools\.headroomrm-rfD:\tools\headroom-datarm-rfD:\tools\headroom-venv参考链接GitHub 仓库: https://github.com/chopratejas/headroom官方文档: https://headroom-docs.vercel.app/docsHuggingFace 模型: https://huggingface.co/chopratejas/kompress-v2-baseDiscord 社区: https://discord.gg/yRmaUNpsPJ许可证: Apache 2.0附录完整命令参考命令说明headroom proxy --port 8787启动代理服务器headroom perf查看压缩性能统计headroom perf --hours 24查看最近 24 小时统计headroom perf --format csv导出 CSV 格式headroom memory list列出所有记忆headroom memory stats查看记忆统计headroom learn从失败会话中学习headroom mcp install安装 MCP 服务器headroom wrap claude包装 Claude Codeheadroom wrap codex包装 Codexheadroom wrap cursor包装 Cursorheadroom update更新到最新版本headroom doctor检查配置状态附录快速启动脚本Windows 批处理脚本start-headroom-claude.bat:echo off chcp 65001 nul title Headroom Claude Code echo echo Headroom Claude Code 启动脚本 echo echo. echo Configuration: echo - Proxy URL: http://127.0.0.1:8787 echo - Target API: https://api.xiaomimimo.com/anthropic echo - Mode: token optimization (60-95%% fewer tokens) echo. echo Usage: echo - 保持此窗口打开 echo - Claude Code 会自动使用代理 echo - 按 CtrlC 停止代理 echo. set HEADROOM_REQUIRE_RUST_COREfalse set ANTHROPIC_TARGET_API_URLhttps://api.xiaomimimo.com/anthropic echo Starting Headroom proxy on port 8787... echo. D:\tools\headroom-venv\Scripts\headroom.exe proxy --port 8787 pause文档版本: 1.0最后更新: 2026-06-26
