教了 Agent 一百遍的规矩，换个工具它一条都不认，换个人也一条都不认——我把记忆搬回了仓库

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */
#content_views .toc,
/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */
#content_views.markdown_views > p:empty:has(+ .toc),
#content_views.markdown_views > .toc + p:empty,
/* 富文本旧版目录标记 */
#content_views.htmledit_views #main-toc,
#content_views.htmledit_views #hr-toc,
#content_views.htmledit_views p[id*=\”-toc\”] {
display: none !important;
}
/* 目录去掉后，紧跟的首个标题不再多出一块上边距 */
#content_views.markdown_views > .toc + h1,
#content_views.markdown_views > .toc + h2,
#content_views.markdown_views > .toc + h3,
#content_views.markdown_views > .toc + h4,
#content_views.markdown_views > .toc + p:empty + h1,
#content_views.markdown_views > .toc + p:empty + h2,
#content_views.markdown_views > .toc + p:empty + h3,
#content_views.markdown_views > .toc + p:empty + h4 {
margin-top: 0 !important;
}

教了 Agent 一百遍的规矩，换个工具它一条都不认——我把记忆搬回了仓库

30 篇连载 · RSI-BOOT：把「工程记忆」还给仓库。一个开源（MIT）的本地 MCP 记忆服务，只记这个仓库的工程约定与禁止项。
主链路零 API Key、可离线。同一套关于本仓库的问题，开记忆比不开少耗 74.1% 的 token。

一、先说一个你大概也遇到过的场景

你在 Cursor 里带了 Agent 两周，它学会了这个仓库的三条规矩：函数名用蛇形、支付日志里不能打印卡号、空指针要先判空再取字段。

晚上换了个工具，用 Claude Code 打开同一个仓库。

它一条都不认。你写在 Cursor 里的规矩，只存在于 Cursor 里——你以为换的是编辑器，其实把两周的教学成果留在了上一个工具里。

不是模型变笨了。是那些规矩从来没被存在一个「工具无关」的地方。

二、规矩为什么会丢：三种失败方式

这不是哪一个工具的毛病。把一个仓库的规矩交给现在这几种方案保管，会以三种不同的方式丢，代价和修法都不一样。

第一种，宿主把它删了。 Cursor 在 2.1 版本砍掉了 Memories 功能，用户存在里面的项目知识随之蒸发。AI 编程宿主的"记忆"长期处于实验态，今天有明天无，产品策略一调，你教过的东西说没就没。把工程规矩押在别人的产品路线图上，是这一种。更隐蔽的是，很多宿主的记忆无结构、无审批，混着闲聊和正经约束，你自己都分不清哪些是规矩、哪些是噪音。

第二种，本机锁死，不进 git。 Claude Code 这类工具会在本地磁盘写"自动记忆"，但它们默认只活在当前机器、当前账号。换一台电脑，或者同事拉下同一个仓库，这些记忆不会出现。结果是同一个仓库三个人三套记忆，谁都对齐不上；而且因为不进版本库，既没法 code review，也没法在团队里传承——它们成了只属于某台电脑的幽灵知识。

第三种，云上跟账号走。 把记忆放云端能解决"换机器"，但引入新代价：要 API Key、要联网、记忆归某个云账号而不是某个仓库。仓库拷给客户、开源出去、或者你哪天注销那个账号，记忆就留在服务商那里。对金融、医疗这类对数据驻留有硬性要求的团队，"把本仓库的禁止项托管给第三方"本身就是合规红线。

三种病根相同：项目规矩被绑在了"某次聊天 / 某台机器 / 某个云账号"上，而没绑在它真正该待的地方——仓库本身。 仓库是唯一跟着代码走、能进 git、能被团队共享的载体，所以记忆也该住在那儿。

三、它该住在仓库里

rsi-boot 是一个开源（MIT）的本地 MCP 记忆服务，只记一件事：这个仓库的工程约定与禁止项。

记忆就是仓库里 .rsi/ 下的纯文件——YAML 存条目、JSONL 存事件。没有远端服务，没有账号，主链路不调模型、不调 embedding，断网也能跑。

把这件事放进现有的几种"规矩载体"里一比，位置就清楚了：

前三行各有一种丢法，第四行也不是白拿的——它要求你在每条新规矩落库前点一次确认。这笔账值不值，看完第九节你自己就能算。

所以它的定位只有一句，我建议把它当成整站的锚：

Agent 的工程记忆，不是对话记忆：约定和禁止项落在仓库里，换一个宿主读到的还是这一份。

这句话里有两个刻意的限定，值得拆开看。第一，工程记忆——它存的是"函数名怎么写"“支付日志里不能打卡号”“上次那个空指针是怎么修的”，不是你的聊天画像，也不是通用知识库。第二，不是对话记忆——它不保存你和模型的闲聊，也不替模型答题。把这条边界记牢，后面看基准数字时才不会拿错尺子。

公开基准上，它的冷启动检索命中率是 LoCoMo Hit@5 56.5%、LongMemEval-S Hit@5 96.6%。这两个数字都有边界，怎么读才不会被误导，第六节专门交代。

由此长出三个能力：记忆随仓库走（.rsi/）、跨工具且多人共用一份、以及 Harness-RSI 自改进闭环。

四、一条记忆长这样

不是数据库里的一行，也不是向量库里的一段 embedding，就是仓库里一个 YAML 文件：

id: aba52c7981c44692b0ea52b0b1a18437
type: convention
title: 项目配置与规范摘要
content: |
– 主语言: python
– 框架: pydantic
– 测试框架: pytest
status: active
domain: bootstrap
tags:
– signal:config
created_at: '2026-09-10T11:46:29.820750+00:00'
updated_at: '2026-09-15T01:50:58Z'

（字段取自仓库里一条真实条目，content 的折行做了简化。）

全部机关在 status: active 这一行：只有 active 的条目才进召回池。草稿躺在 pending/，被否的进归档，谁批的、什么时候批的，顺着文件都能查回去。

看起来太简单了对吧？一个 YAML 文件而已。但决定它有没有用的从来不是文件格式，而是三件事：这份文件在不在 git 里、换个工具还认不认、写进去的东西有没有人把过关。后面三十篇拆的就是这三件事。

五、三分钟速览：只要记住这四件事

如果整个专栏你只打算记住四件事，我建议是这四件。

第一，记忆落在 .rsi/，跟仓库走。 记忆是纯文件（YAML / JSONL），不是远端服务里的一行记录。仓库拷走、换机器、换目录，.rsi/ 一起走；打开另一个仓库就是另一份，不串味。它默认进 .gitignore，团队把核准记忆放行、运行产物忽略，就实现了"新人 clone 即继承"。存储布局与原子写见第 20 篇。

第二，检索有两套独立子系统，不能混为一谈。 这是整套系统头号易错点：召回链 rsi_recall 是纯内存 BM25 倒排索引，零 Key、离线、不碰向量也不调 LLM；知识检索 knowledge_search 才是 BM25 加向量的 RRF 融合（k=60，原始分门槛 cosine ≥ 0.6 或 BM25 归一化 ≥ 0.6），它服务于知识条目与规则注入。看到「检索」二字，先分清它说的是哪一套。机制分别在第 5 篇与第 10 篇。

第三，审批治理是硬纪律，不是可选项。 环是固定的：召回 → 干活 → 蒸馏成待审条目 → 人批准后才留下 → 下一轮召回读到留下的条目。召回只认 active 状态，所以一条记忆没经过批准，永远不会进下一轮。这条纪律换来了记忆的归属权与可审计性，代价是你要花几次点击。我认为这个代价值得，理由在第 8 篇完整展开。

第四，Harness-RSI 是自改进闭环，而且它只改自己那一小块。 负反馈 → 失败桶 → 提案 → 静态门禁 → 7 天观察 → 采纳率掉了就自动回滚。它只改可写槽位（提示词 / 技能 / 召回策略 / 意图规则 / 知识），绝不碰业务代码。第 13 到 16 篇逐段拆这条环。

六、关键数据，以及三条"别读错"的提醒

先把数字摆出来。

另有一项 token 实测：同一套关于本仓库的问题，关记忆与开记忆各答一遍，六组合计省下 1,214,004 token，比例 74.1%（单组从 10.5% 到 89.7% 不等，引用必须说合计）。

然后是我认为比数字本身更重要的三条提醒，漏掉任何一条都会读错。

提醒一：这些是"找不找得回"，不是"答得对不对"。 rsi-boot 的主链路根本不调模型，没有"答题"这个环节，所以它报的是冷启动检索命中率（Hit@5 / Recall@5 / MRR）。Mem0 主页上那两个百分数（LoCoMo 92.5、LongMemEval 94.4）是另一套做法：先让模型借助记忆答题，再由裁判给答案打分，而且用的是 top 50、top 200 这种很宽的输出窗口。两套测量链路不同，不能放在同一列比较——连放在一起参照都比错了。这条口径我们在第 23 篇专门交代过。

提醒二：74.1% 是毛收益，不是净收益。 它省的是推理期的 token，不包含记忆自身的建设成本——学习扫描、人工核准、反馈回流、健康扫描都要消耗算力和 token，而这部分没有从"开记忆"一侧扣除。把它当成端到端净收益去理解，就会高估。第 25 篇专门拦了这个推论。

提醒三：平均数会掩盖偏科。 LoCoMo 那个 56.5% 拆开看是：多跳 +27.8、开放域 +29.6，而单跳 −29.3、时间 −38.9，长板短板相抵才凑出总平均。这些差值对照的是学术论文的检索数字（LoCoMo 原论文与 ECHO），不是 Mem0 的答题分。偏科不可怕，可怕的是用平均数把偏科藏起来——第 24 篇逐项拆给你看。

七、和商业化竞品比：一张路线表，不是分数表

下面这张表比的是产品路线与成本结构，不是分数。再次声明：不把两边的百分数摆进同一张对照表。

关于 Mem0，我只讲两件能站住的事：一是路线差异（事实记忆 + 模型答题 vs 程序性记忆 + 行为约束），二是成本结构相反（它的主链路要调 embedding 接口，rsi-boot 主链路零 Key）。这两点都不涉及把分数摆在一起。完整的选型决策表在第 26 篇。

八、商业化可行性：我的判断

下面这一段不是仓库里写着的结论，是我作为使用者的判断——你完全可以不同意。我只拿前面那些摆得出来的产品事实做依据，不引用任何市场规模、融资或客户数量的数字，因为那些数字我拿不出来。

有利的部分，有硬事实支撑。 其一，它用的是 MIT 许可，商用与二次分发没有法律障碍，这对想把它内嵌进自家工具链的公司很关键。其二，主链路零 Key、不联网、本地优先，直接对应"数据不能出境、不能出本地"的合规场景——金融、医疗这类对数据驻留有硬性要求的行业，云端记忆方案往往第一步就被合规拦下，而 rsi-boot 不会。其三，记忆跟仓库走、带审批与版本快照，正好命中企业"记忆也得能 review、能追责、能回滚"的诉求，这比"记忆更准"更容易被工程组织接受。其四，成本结构上它不付向量化税，规模越大这个差异越明显。

不利的部分，我也如实说。 它不是通用事实记忆库：不存对话、不替模型答题，想拿它做"用户画像"或"通用问答增强"会失望。它偏科，LoCoMo 单跳 −29.3、时间 −38.9 是真实短板，纯 BM25 在需要软推理的题上就是弱。它要求人工审批，有持续的交互成本，讨厌点确认的人会觉得啰嗦。它依赖 MCP 宿主生态，宿主不支持 MCP 时只能退到 AGENTS.md 托管块。多人协作还有 git 的隐性成本——共享核准记忆意味着要处理冲突与合并。

我的形态判断。 它更可能以"被集成的工程记忆层"的形态成立——IDE 或平台内嵌的一层能力、企业内源工具链里的一个组件，而不是直接下场和通用记忆 SaaS 比答题分。理由很简单：它该赢的那一格是"记忆归谁、能不能审计、换工具丢不丢、合规过不过"，不是"答题分"那一格。拿自己的短板去撞别人的主场，既违背它自己的诚实口径，也赢不了。

九、什么时候该用，什么时候不该用（详见第 26 篇）

该用：项目规矩要跟着仓库走；团队要让新人 clone 即继承；合规不允许记忆出本地；同一个人换着多个 AI 工具写同一个仓库，不想每次重学。

不该用：想要对话个性化画像；想要通用事实问答；完全不接受审批这一步的交互成本；期待"喂一堆数据就自动长出规范"的全自动体验。

十、装上、接上、跑第一次

pip install rsi-boot # 需要 Python 3.10+
rsi init # 只写用户级配置 ~/.rsi/config.yaml

然后在要用记忆的那个项目里放一份 MCP 配置。Cursor 的写法是这样，放进项目根的 .cursor/mcp.json：

{
"mcpServers": {
"rsi-boot": {
"command": "rsi",
"args": ["serve"],
"env": {
"RSI_PROJECT_ROOT": "${workspaceFolder}"
}
}
}
}

其余四家各有一条命令，不用手写 JSON：

有一个坑必须提前说：这段不要配进用户级 mcp.json。用户级配置里的 ${workspaceFolder} 经常不展开，rsi serve 只能退回按 cwd 猜项目根——猜错的结果就是记忆串到别的仓库，而且你不会收到任何报错。要记哪个项目，就写在那个项目里。Qoder 和 Claude Code 同理，都从项目目录启动。

两个常被问到的点：rsi init 不会在项目里建 .rsi/，项目记忆目录是第一次 rsi serve 或 rsi bootstrap 时创建的，别对着 rsi init 等一个不会出现的目录。另外机器上没装 rsi 命令也能跑，把 "command": "rsi" 换成 "command": "uvx"、"args" 换成 ["–from", "rsi-boot", "rsi", "serve"] 即可。

接上之后，在宿主里说一句「第一次学这个项目」，或者直接跑 rsi bootstrap，它就开始扫这个仓库的信号源。五个宿主的完整配置（含 Codex 的 TOML 写法、DeepSeek Harness 的工具名前缀）第 4 篇逐家给了。

十一、30 篇导航

这一篇不是 30 篇正文之一，它是整站的入口：讲这个专栏的范围、那些数字该怎么读、以及它站在什么位置。想直接开读，从第 1 篇开始。

• 基础与上手：第 1 篇 开篇 ｜ 第 2 篇 RSI 概念 ｜ 第 3 篇 装上跑通 ｜ 第 4 篇 接进五大宿主
• 原理与检索：第 5 篇 召回链路 ｜ 第 6 篇 冲突检测 ｜ 第 7 篇 环全景 ｜ 第 8 篇 蒸馏审批 ｜ 第 9 篇 负反馈 ｜ 第 10 篇 知识检索 ｜ 第 11 篇 意图与召回臂 ｜ 第 12 篇 置顶与记忆健康
• Harness 自改进：第 13 篇 失败桶挖掘 ｜ 第 14 篇 提案与静态门禁 ｜ 第 15 篇 7 天观察与自动回滚 ｜ 第 16 篇 晋升槽位版本
• 写链路与架构：第 17 篇 写链路与注入 ｜ 第 18 篇 MCP 工具面 ｜ 第 19 篇 分层 ｜ 第 20 篇 存储 ｜ 第 21 篇 观测 ｜ 第 22 篇 DAG（关系图与函数管道，不是任务调度器）
• 基准公信力：第 23 篇 方法学与诚实口径 ｜ 第 24 篇 分项拆解 ｜ 第 25 篇 token 实测
• 落地与收口：第 26 篇 选型 ｜ 第 27 篇 多人共享 ｜ 第 28 篇 跨工具迁移 ｜ 第 29 篇 安全隐私 ｜ 第 30 篇 贡献与收口

十二、这些数字为什么值得你采信

你大概会想：这些数字凭什么信。我的回答是四条口径，你可以拿它们逐条去核：

第一，只讲已经落地的能力。仓库里还在施工的部分，不会被当成卖点摆出来。
第二，不知道就说不知道。有两处目前确实没有答案：有一版指标因为定义依赖测试集调整而被撤下，具体是哪一天撤的已经查不到（第 24 篇讲了这件事）；记忆自身的维护成本也还没有公开数字，所以那个 74.1% 只能算毛收益（第 25 篇说明了为什么不算进去）。这两处我们选择写"不知道"，而不是填一个好看的数。
第三，所有数字都出自仓库 benchmark/results/ 下的原始 SUMMARY，不引用二手转述，也不挑好看的那一次。
第四，该承认的短板照写：LoCoMo 上单跳和时间类题是明显弱项，74.1% 是毛收益不是净收益。这些不会因为难看而被藏起来。

一个项目敢把自己"撤过版"“偏科”"毛收益不等于净收益"都写出来，反而比永远一次成功更可信——因为前者证明它有一套不会被漂亮数字带偏的校验机制。这三十篇想交给你的，不只是一个能用的工具，还有这套校验机制本身。