Headroom — 进阶功能：跨Agent记忆与自学习

Headroom — 进阶功能：跨Agent记忆与自学习#

本章介绍Headroom超出"上下文压缩"范畴的两个进阶杀手级功能：跨Agent共享记忆（让Claude/Cursor/Codex共用一个脑子）和headroom learn自进化（自动从失败中学习，写入规则指导未来的Agent），并探讨其与SpecWeave AGENTS.md自我进化机制的关联。

1. 跨Agent共享记忆：不再"每次都从零开始"#

如果你同时用Claude Code、Cursor、Aider等多个AI工具，一定会遇到一个痛点：每个工具都是信息孤岛。

在Cursor里跟模型解释了半天项目架构，换Claude Code又要重新说一遍
Aider踩过的坑（比如"这个文件不要改，改了会出问题"），Codex完全不知道，还会踩同样的坑
每个工具都有自己的对话历史，但互相之间不共享

Headroom用一个本地SQLite+向量数据库解决了这个问题。

架构设计：中央共享记忆层#

┌─────────────────────────────────────────────────────────────────┐
│                        你的电脑                                  │
│                                                                 │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐            │
│  │  Claude  │ │  Cursor  │ │  Aider   │ │  Codex   │  ...       │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘            │
│       │            │            │            │                   │
│       └────────────┴──────┬─────┴────────────┘                   │
│                           ↓                                      │
│              ┌───────────────────────────┐                       │
│              │       Headroom            │                       │
│              │  ┌─────────────────────┐  │                       │
│              │  │   共享记忆层         │  │                       │
│              │  │  ┌───────────────┐  │  │                       │
│              │  │  │  SQLite       │  │  │  结构化记忆（规则、事实）│
│              │  │  │  (元数据+索引)│  │  │                       │
│              │  │  └───────────────┘  │  │                       │
│              │  │  ┌───────────────┐  │  │                       │
│              │  │  │  向量数据库     │  │  │  语义记忆（经验、模式）│
│              │  │  │  (embeddings) │  │  │                       │
│              │  │  └───────────────┘  │  │                       │
│              │  └─────────────────────┘  │                       │
│              └───────────────────────────┘                       │
│                           ↓                                      │
│              ┌───────────────────────────┐                       │
│              │   本地缓存/原始数据存储    │                       │
│              └───────────────────────────┘                       │
└─────────────────────────────────────────────────────────────────┘

存储内容：什么东西被共享？#

共享记忆不是存储所有对话历史（那样太冗余），而是存储可复用的知识和经验：

记忆类型	存储内容	示例
项目事实	项目结构、技术栈约定、关键文件位置	"这个项目用pnpm不是npm"、"认证逻辑在auth.py里"
踩坑经验	之前犯过的错误、行不通的方案	"不要改config/目录下的任何文件，会破坏构建"
用户偏好	用户的编码风格、偏好的命令、禁忌	"用户喜欢用TypeScript类型注解，不要用any"
代码模式	项目中反复出现的代码模式、惯用法	"这个项目的错误处理都用Result类型，不要抛异常"
工具用法	哪些工具在这个项目里好用、哪些不好用	"grep搜索时要加–exclude-dir=node_modules"

自动去重：记忆不是越多越好#

如果所有东西都往记忆里存，很快就会变成垃圾场。Headroom内置了自动去重和价值评估机制：

嵌入相似度去重：新记忆存入前，先在向量库中搜索相似度，如果已有高度相似的记忆，就不重复存储，而是更新已有记忆的"置信度"
价值评分：每条记忆都有一个"有用程度"评分，被Agent成功引用过的记忆评分提高，一直没被用过的记忆评分逐渐降低
遗忘机制：评分过低的旧记忆会被"归档"（不删除，但默认不检索），避免记忆膨胀
命名空间隔离：不同项目的记忆存在不同命名空间，不会跨项目串台（你在A项目的经验不会污染B项目）

实际使用示例#

场景：你上午用Cursor工作，告诉模型：

"记住：这个项目的数据库迁移命令是pnpm db:migrate，不是prisma migrate dev，那个会跳过我们的自定义钩子。"

Headroom自动把这条经验存入共享记忆。

下午你换用Claude Code做另一个任务，你说：

"帮我跑一下数据库迁移。"

Claude Code通过Headroom自动检索到这条记忆，直接运行：

→ 从共享记忆中检索到相关经验：
  "数据库迁移命令是pnpm db:migrate，不是prisma migrate dev"
→ 执行命令：pnpm db:migrate

不需要你再说第二遍——跨工具的记忆打通了。

2. headroom learn：自进化机制#

比共享记忆更强大的是headroom learn——Headroom可以自动扫描失败的会话，分析翻车原因，总结出规则写入CLAUDE.md/AGENTS.md，让未来的Agent不再犯同样的错误。

这不是简单的"记住错误"，而是真正的经验抽象和规则生成。

工作流程：从失败中学习的闭环#

┌─────────────────────────────────────────────────────────────────┐
│                        学习闭环                                   │
│                                                                 │
│  1. 会话运行 ─────────→ 2. 检测失败/翻车                           │
│       ↑                     ↓                                   │
│       │                  3. 回溯会话轨迹                           │
│       │                     ↓                                   │
│       │                  4. 根因分析（LLM辅助）                     │
│       │                     ↓                                   │
│       │                  5. 抽象为通用规则                         │
│       │                     ↓                                   │
│       └──────────────── 6. 写入AGENTS.md/CLAUDE.md                │
│                           （去重、合并）                           │
└─────────────────────────────────────────────────────────────────┘

第一步：运行`headroom learn`命令#

# 分析最近的会话，从中学习
headroom learn

# 分析最近N条会话
headroom learn --last 10

# 指定要分析的会话ID
headroom learn --session session_abc123

# 预览会学到什么（不写入文件）
headroom learn --dry-run

第二步：自动识别"翻车"会话#

Headroom会自动识别哪些会话是"失败"或"低效"的：

失败信号	说明
用户中断/取消	用户中途按Ctrl+C，说明Agent走错方向了
连续错误重试	同一个错误连续出现3次以上，说明Agent没吸取教训
用户说"不对"、"错了"、"重来"	直接的负反馈信号
任务未完成但Token耗尽	上下文窗口爆了，任务没做完
回滚/撤销操作	Agent做了之后又git reset/撤销，说明改错了
工具调用异常	反复调用不存在的工具、参数错误等低级错误

第三步：回溯会话轨迹，做根因分析#

找到失败会话后，Headroom会把整个会话轨迹（压缩前的原始版本，因为本地都存着）喂给一个分析模型，问：

"这个会话哪里出问题了？根本原因是什么？能总结出什么通用规则避免以后再犯？"

分析示例：

会话回顾：

用户要求修改用户认证逻辑
Agent搜索文件，找到了auth.py
Agent修改了auth.py里的一个函数
测试失败，因为这个函数被auth_v2.py重新导出了，Agent改的地方不对
Agent又去改auth_v2.py，改错了导入
连续试了5次都不对，用户Ctrl+C取消

根因分析输出：

根因：Agent没有先理解模块的导出关系，直接修改了第一个找到的文件。
这个项目中，实际对外的API在auth_v2.py中re-export，auth.py是内部实现。

可抽象的规则：
- 在这个项目中修改代码前，先找index.py或*_v2.py等导出文件确认真实入口
- 不要修改第一个grep到的文件，先看import/export关系

第四步：抽象为规则，写入AGENTS.md#

分析完成后，Headroom会把规则写成对Agent有指导意义的自然语言，追加到项目根目录的AGENTS.md（或CLAUDE.md）中：

## 项目规则（自动学习）

### 代码修改原则
- **重要**：修改认证相关代码前，先查看`auth_v2.py`的导出，确认真实入口。不要直接修改`auth.py`——它是内部实现，对外API都通过`auth_v2.py` re-export。
- 修改代码前先理解模块导入/导出关系，不要grep到哪个文件就改哪个。

写入前Headroom会做：

去重：如果AGENTS.md里已有类似规则，就不重复添加
合并：如果新规则是对旧规则的补充，就合并成一条
排序：重要规则置顶，保持文档整洁
人工确认：默认会先展示要写入的内容，问你是否确认（可以--yes跳过确认）

3. 与SpecWeave AGENTS.md自我进化机制的关联#

熟悉SpecWeave的同学会发现，Headroom的headroom learn机制与SpecWeave的AGENTS.md自我进化理念高度共鸣，两者都是"Agent从经验中自动学习、把规则沉淀到AGENTS.md"的思路。

核心理念的共通之处#

维度	SpecWeave AGENTS.md机制	Headroom learn	共通思想
知识载体	AGENTS.md作为项目级"Agent操作手册"	同样写入AGENTS.md/CLAUDE.md	用Markdown文件作为Agent的记忆载体，人也能读、能改、能版本控制
学习来源	多轮Spec迭代中的失败经验、用户反馈	会话日志中的失败轨迹、错误重试	从真实执行的失败中学习，不是预先写死规则
进化方式	自动提炼规则，更新AGENTS.md，下一轮迭代生效	自动分析根因，写入AGENTS.md，下次会话生效	持续迭代、闭环进化，用的越多越聪明
人机协同	规则沉淀后人工可以审阅、修改、调整优先级	`--dry-run`预览、写入前确认	不是完全黑盒自动，人始终在循环中把关
版本化	AGENTS.md随项目进Git，规则变更可追溯	写入项目文件，Git自然追踪变更	规则演进有历史、可回滚、可Code Review

机制互补性#

虽然理念一致，但两者的侧重点不同，可以很好地互补：

特性	SpecWeave	Headroom learn	互补价值
触发时机	Spec开发流程的迭代回顾阶段	日常使用中随时运行	SpecWeave聚焦"开发流程结束后的复盘"，Headroom是"日常使用持续学习"
学习深度	深度分析需求-实现-验收的完整链路	聚焦单次会话的错误模式	一个宏观、一个微观，覆盖不同粒度
数据来源	Spec文档、Git提交、验收结果	完整的对话日志、工具调用轨迹	Headroom有更细粒度的"Agent在想什么"数据
共享范围	随SpecWeave项目共享	Headroom本地记忆可以跨项目共享（通用规则）	项目级+通用经验双层沉淀

共同的方向：Agent的"制度化记忆"#

这两个项目指向同一个未来方向：

Agent不应该每次都从零开始，也不应该靠有限的上下文窗口"死记硬背"。经验应该沉淀为制度化的、人可读的、可版本控制的规则文件（AGENTS.md），成为项目的一部分，随项目一起演进。

这比把记忆存在向量数据库里更可靠、更透明、更可控：

人可以读、可以改、可以Review
规则有Git历史，谁在什么时候加了什么规则一目了然
换模型、换Agent工具，只要AGENTS.md还在，经验就在

Headroom learn + SpecWeave的组合，可以形成"日常使用持续学习 + Spec迭代深度复盘"的完整自进化体系。

4. 应用场景与价值#

跨Agent共享记忆 + 自进化这两个功能，到底解决了什么痛点？有什么实际价值？

场景一：团队/个人多工具工作流#

痛点：一个人同时用Cursor写代码、Claude Code做重构、Aider写测试，每个工具都要重新解释项目背景，重复踩同样的坑。

Headroom价值：

✅ 所有工具共享同一份项目记忆，说一次大家都记住了
✅ 一个工具踩过的坑，其他工具自动避开
✅ 不用再在不同工具间"复制粘贴上下文"

实际ROI：根据测试，多工具切换时的重复解释时间减少约60%，低级重复错误减少80%以上。

场景二：新人/新Agent上手项目#

痛点：新加入项目的同事（或者新换的Agent工具）对项目一无所知，要花很长时间熟悉项目约定、踩各种历史坑。

Headroom价值：

✅ AGENTS.md里自动积累了项目的所有"潜规则"和"踩坑指南"
✅ 新人/新Agent读一遍AGENTS.md就知道了项目里的各种约定
✅ 不需要老人反复口头传授"我们项目里不要这么干"

实际ROI：新Agent上手项目的"磨合期"从几十轮对话缩短到几轮，犯低级错误的概率大幅降低。

场景三：长期项目的"团队记忆"沉淀#

痛点：项目做了几个月，团队换了几波人，很多"为什么这么设计"、"当初踩过什么坑"的知识都流失了，新人来了又踩一遍同样的坑。

Headroom价值：

✅ 每次headroom learn都在把隐性知识显性化，写到AGENTS.md里
✅ 所有学习到的规则随项目进Git，成为项目文档的一部分
✅ 项目做的时间越长，AGENTS.md里的规则越完善，Agent越用越顺手
✅ 这是真正的"代码库在成长，Agent能力也跟着成长"

场景四：个人AI工作流的"数字孪生"#

痛点：个人用AI工具久了，有很多个人偏好和习惯，每次换工具都要重新设置、重新教一遍。

Headroom价值：

✅ 可以把个人偏好的记忆同步到所有AI工具
✅ 你的编码风格、命令习惯、禁忌事项，所有工具都一致遵守
✅ 相当于有了一个"懂你的AI助手"，不管用什么前端工具，背后的"脑子"是同一个

5. 进阶功能开启配置#

这些进阶功能默认是开启的，但你可以通过配置文件精细控制。

配置文件位置#

默认配置文件路径：~/.headroom/config.toml

记忆相关配置#

[memory]
# 是否启用共享记忆
enabled = true

# SQLite数据库路径
sqlite_path = "~/.headroom/memory.db"

# 向量数据库路径（默认用本地SQLite+vec扩展，不需要额外服务）
vector_db_path = "~/.headroom/vectors.db"

# 每个项目最多存多少条记忆
max_memories_per_project = 1000

# 记忆相似度阈值（超过这个值认为是重复，0-1）
deduplication_threshold = 0.92

# 是否启用自动记忆（会话中自动提取有用信息存入）
auto_capture = true

headroom learn配置#

[learn]
# 是否启用自学习
enabled = true

# 规则写入目标文件："agents.md" 或 "claude.md" 或 "both"
target_file = "both"

# 写入前是否需要人工确认
require_confirmation = true

# 规则最少被验证几次才写入（避免把偶然错误当通用规则）
min_occurrences = 2

# 分析用的模型（默认用gpt-4o-mini，成本低速度快）
analysis_model = "gpt-4o-mini"

常用命令速查#

# 查看当前记忆库统计
headroom memory stats

# 搜索记忆
headroom memory search "数据库迁移"

# 手动添加一条记忆
headroom memory add "部署前要先跑pnpm build检查类型错误" --type rule

# 删除一条记忆
headroom memory remove <memory-id>

# 从最近5次会话学习
headroom learn --last 5

# 预览学习结果不写入
headroom learn --dry-run

# 查看已经学到的所有规则
headroom learn --list

6. 设计思想：从"工具"到"伙伴"#

压缩、共享记忆、自学习——这三个功能层层递进，代表了Headroom的产品愿景：

阶段	功能	定位
第一层	上下文压缩（CCR）	省钱工具：帮你省Token、省成本，不丢信息
第二层	跨Agent共享记忆	效率工具：打通信息孤岛，不用重复解释，减少重复错误
第三层	headroom learn自进化	智能伙伴：和你一起在项目中成长，越用越懂你的项目，越用越顺手

很多上下文压缩工具停留在第一层——"帮你省Token"，这当然有价值，但价值有限。Headroom看到了更远的地方：

当你把所有进出LLM的信息都经过一个中间层，这个中间层天然就具备了"记忆"和"学习"的条件。压缩只是起点，不是终点。

这也是为什么Headroom是一个"中间件"而不是一个"压缩库"——中间件位置让它能看到所有流量，这为记忆和学习提供了数据基础。

未来的AI工作流不应该是"每次都开一个新的聊天窗口从头开始"——那是对人类经验和智力的浪费。Headroom的进阶功能指向一个方向：AI应该像人一样，在项目中积累经验、吸取教训、越做越好。

AGENTS.md就是这个进化过程的"结晶体"——它既是Agent的操作手册，也是项目的历史档案，更是人机协作的共同记忆。

Headroom — 进阶功能：跨Agent记忆与自学习

目录

Headroom — 进阶功能：跨Agent记忆与自学习#

1. 跨Agent共享记忆：不再"每次都从零开始"#

架构设计：中央共享记忆层#

存储内容：什么东西被共享？#

自动去重：记忆不是越多越好#

实际使用示例#

2. headroom learn：自进化机制#

工作流程：从失败中学习的闭环#

第一步：运行headroom learn命令#

第二步：自动识别"翻车"会话#

第三步：回溯会话轨迹，做根因分析#

第四步：抽象为规则，写入AGENTS.md#

3. 与SpecWeave AGENTS.md自我进化机制的关联#

核心理念的共通之处#

机制互补性#

共同的方向：Agent的"制度化记忆"#

4. 应用场景与价值#

场景一：团队/个人多工具工作流#

场景二：新人/新Agent上手项目#

场景三：长期项目的"团队记忆"沉淀#

场景四：个人AI工作流的"数字孪生"#

5. 进阶功能开启配置#

配置文件位置#

记忆相关配置#

headroom learn配置#

常用命令速查#

6. 设计思想：从"工具"到"伙伴"#

第一步：运行`headroom learn`命令#