系列：《AI 共享记忆：RSI-BOOT 让跨工具、多人协同实现共用一份记忆库》第 1 篇 配套系列深潜：RSI 到底是什么见第 2 篇、装上跑通见第 3 篇、接进五大宿主见第 4 篇、召回链路机制见第 5 篇、基准公信力见第 23/24/25 篇、与 Mem0 选型对比见第 26 篇。
你在这个项目里教过 Agent 三件事：函数名用蛇形、支付日志里不能打卡号、上次那个空指针是先判空再取字段。这三件是这个仓库的规矩，不是某一次聊天的废话。
它们现在常常不跟着仓库走：宿主的记忆功能可能哪天就被删掉，本机记忆不进 git，云记忆跟的是账号而不是仓库。
三种丢法，代价各不相同，正好下一节逐个说。
RSI-BOOT 把约定、禁止项和修过的教训放进仓库自己的 .rsi/。目录跟着仓库走，打开另一个仓库就是另一份，不会串。Cursor、Claude Code、Codex、Qoder、DeepSeek Harness 接的是同一份。主链路不调用模型，也不要 API Key。
一、三类痛点：规矩为什么总在丢
把"项目规矩记不住"这件事拆开看，其实是三种不同的丢失方式，每一种对应的代价都不一样，解决办法也完全不同。
第一类：宿主把它删了。 Cursor 2.1 直接砍掉了 Memories 功能，用户存在里面的项目知识随之蒸发。这不是个例------AI 编程宿主的"记忆"功能长期处于实验态，今天有明天无，产品策略一调，你教过的东西说没就没。依赖宿主自身的记忆存储，等于把工程规矩押在别人的产品路线图上。更隐蔽的是，很多宿主的"记忆"是无结构、无审批的，混着闲聊和正经约束，连你自己都分不清哪些是规矩、哪些是噪音。
第二类：本机锁死，不进 git。 Claude Code 这类工具会在本地磁盘写一些"自动记忆"，但它们默认只活在当前机器、当前账号。你换一台电脑，或者同事拉下同一个仓库，这些记忆不会出现。结果是同一个仓库，三个人三套记忆，而且谁都对齐不上。更糟的是，因为不进版本库，这些记忆既没法 code review，也没法在团队里传承------它们成了"只属于你这台电脑的幽灵知识"。
第三类：云上跟账号走。 把记忆放到云端（Mem0 一类）能解决"换机器"的问题，但引入了新代价：要 API Key、要联网、记忆归属某个云账号而不是某个仓库。仓库拷给客户、开源出去、或者你注销那个云账号时，记忆留在服务商那里。对很多团队来说，把"这个仓库的禁止项"托管给第三方账号，本身就是合规红线------尤其是金融、医疗这类对数据驻留有硬性要求的行业。
三类痛点的共同根因只有一个：项目规矩被绑在了"某个聊天 / 某台机器 / 某个云账号"上，而不是绑在它真正该待的地方------仓库本身。 RSI-BOOT 的第一性原理，就是把记忆的归属从"会话/账号"挪回"仓库"。仓库是唯一跟着代码走、能进 git、能被团队共享的载体，所以记忆也该住在那儿。
二、一句话定位，和一个必须点破的身份
RSI-BOOT 的定位可以用一句话说完：让项目记忆跟着仓库走、跨工具一份、零 API Key。
- 跟着仓库走 ：记忆落在仓库根的
.rsi/，随git流动。换目录、换机器、换同事，只要仓库在，记忆就跟着在。打开另一个仓库，就是另一份，互不串味。 - 跨工具一份 ：Cursor、Claude Code、Codex、Qoder、DeepSeek Harness 接的是同一个
rsi serve暴露的 MCP 服务，读的是同一份.rsi/。上午在 Cursor 里记下的禁止项，晚上换 Codex 打开，读到的是同一条。 - 零 API Key：主链路（召回、注入、审批）不调用任何大模型、不调 embedding、不联网。你不需要为了"记住项目规矩"去申请任何密钥。
但这里必须开宗明义点破一件事------RSI 到底是什么身份。它不是又一个"知识库"，也不是"聊天记录管理器"。在仓库的设计文档里，它的定位写得很硬：
RSI 是宿主模型的程序性记忆层（procedural memory layer），不是仓库理解器。它只沉淀"怎么做"（约定 / 禁止项 / 修 bug 经验 / 技能），不解析仓库语义、不替宿主模型生成答案。
这句话值得钉在每一篇的开头。后面我们会用一整篇（第 2 篇）展开它为什么是"程序性"而不是"事实性"，但你要先记住这个结论：RSI 改变的是 Agent 的行为方式，而不是给 Agent 多塞一份参考资料。 这也是它和大多数"AI 记忆"方案最本质的分野------别人往"多知道点什么"上使劲，它往"下次别再犯"上使劲。
为了让你立刻建立直觉，这里先给一张"它是什么 / 不是什么"的速查表，细节后面逐篇展开：
| 它是什么 | 它不是什么 |
|---|---|
| 宿主模型的程序性记忆层 | 仓库理解器（不解析语义、不答题） |
| 只沉淀"怎么做"（约定/禁止项/教训） | 事实性知识库（那走另一套子系统） |
工程记忆，存于 .rsi/ |
对话记忆（不存聊天记录） |
| 跟仓库走、随 git 流动 | 跟云账号走的云端记忆 |
| 主链路零 Key、纯本地文件 | 需要 API Key 才能用的托管服务 |
三、用起来是一个环
光说定位太抽象。RSI-BOOT 真正用起来的时候，是一条闭环。对当前项目窗口里的 Agent 说"第一次学这个项目"，它扫描这个仓库，把发现写成待审条目。你批准之后，下一次召回才读得到；没批准的不会混进下次的上下文。
之后日常就是这几句简单的交互：
| 你说 | 发生的事 |
|---|---|
| 开工前先看这个仓库的规矩 | 召回。禁止项放在最前，后面是约定和修过的教训 |
| 把刚才的修法记下来 | 先进入待审，你批准后才留下 |
| 这两条是不是矛盾 | 查冲突，等你裁决 |
你点过头（批准）的约定，会写进仓库根 AGENTS.md 的托管块，也会写进 .cursor/rules。没接 MCP 的工具打开这个仓库，也能读到这段。接了 MCP 的，召回读的是同一份 .rsi/：上午在 Cursor 里记下的禁止项，晚上换一个工具、或者同事换 Codex 打开，读到的是同一条。
把这条环画出来会更清楚：
这就是"环"的完整叙事版：召回 → 干活 → 蒸馏成待审条目 → 人批准后才留下 → 下一轮召回读到留下的条目。注意中间的闸门------"人批准"是记忆留下的唯一开关，模型不能自己把东西落库。这是后面所有信任设计的支点。
举个具体的迷你例子。你修了一个空指针：某函数直接取 user.profile.name，当 profile 为 null 时整个接口 500。你让 Agent 记下这条教训，宿主蒸馏出一条 teaching_case（教学案例）：
wrong_action：直接取嵌套字段，未判空。correct_fix：先判profile是否存在，缺失时走默认值或显式报错。error_signature：凡是"取对象深层字段前未判空"的实现。
这条教训落库后，下次你（或同事）再写类似取字段的代码，召回会把这条教训带回来，排在禁止项之后、作为"建议规避"。它不是一句"小心空指针"的废话，而是带结构、可定位、能直接指导改代码的约束。这就是"程序性记忆"落在环里的样子。
另外还有一条独立的旁路：Agent 照规矩干砸了，这条规矩不会被偷偷改掉，而是作为负反馈进失败桶。失败桶只喂给自改进闭环，闭环也只改那几个可写槽位（提示词 / 技能 / 召回策略 / 意图规则 / 知识），绝不碰你的业务代码。提案要过静态门禁、还要你确认，观察 7 天，采纳率掉了就自动回滚。这条环已经写在软件里（第 13--16 篇会展开）。
这里记的是这个仓库的写法、禁止项和修 bug 的经验。聊天记录不在里面------这是一条铁律，系列里会反复出现："Agent 的工程记忆，不是对话记忆"。
四、诚实预告：基准数字只回答"找不找得回"
铺垫到这儿，你大概想知道：它到底管不管用？我先给一组数字，但必须说清口径------这组数字只是预告钩子，完整方法论和分项偏差留到第 23/24/25 篇。
召回是 RSI-BOOT 的公开主榜。题是别人的（LoCoMo 1536 道、LongMemEval-S 500 道），召回是 RSI-BOOT 自己的冷启动，按词去对记忆，默认交 5 条，另外测了 10 条。没有再接一个模型去写答案。所以下面报的是检索命中，不是模型答题分：
| 数据集 | 有据可查的题 | Hit@5 | Recall@5 | MRR |
|---|---|---|---|---|
| LoCoMo | 1536 | 56.5% | 51.0% | 0.427 |
| LongMemEval-S | 500 | 96.6% | 90.1% | 0.907 |
还有一项 token 收益：同一套关于本仓库的问题，关记忆答一遍、开记忆再答一遍，Cursor 报的 token 合计省了 74.1%（六组明细后述）。
为什么我要强调"只回答找不找得回"？ 因为很容易拿错尺子。Mem0 主页上的 92.5（LoCoMo）、94.4（LongMemEval）是另一套做法：先让模型答题，再用裁判打分，看的是前 50 或前 200 条。那个百分数衡量的是"模型带记忆后答题有多准"，而 RSI-BOOT 的百分数衡量的是"该找的那条记忆，冷启动能不能找回来"。两套口径不可放在同一列比较，这是公信力底线，第 23 篇会展开讲。
RSI-BOOT 自己也很克制：公开结果至今没有和别人的"答题分"放在同一列。它只说自己能多准地把规矩召回给你，不替你声称"模型因此更聪明了"。这种克制，恰恰是它值得信的地方。
五、本系列怎么读：从痛点到行动
这一篇是开头，后面二十九篇大致按这条弧线走：先讲清概念（本篇 + 第 2 篇），再带你装上、接好宿主（第 3、4 篇），然后逐层拆原理------召回链路、冲突、主循环、知识检索、意图与召回臂、置顶健康（第 5--12 篇），接着是写进软件的自改进闭环（第 13--16 篇）、写入与注入边界（第 17 篇）、架构全景（第 18--22 篇，其中第 22 篇是 DAG 关系图与函数管道），再到基准公信力（第 23--25 篇）、选型对比（第 26 篇）、团队与迁移（第 27、28 篇）、安全隐私（第 29 篇），最后以贡献与路线图收口（第 30 篇）。
你不必从头读到尾。如果你只想"赶紧用起来"，第 3、4 篇足够；如果你是被"AI 记忆到底能不能信"吸引来的，直接跳第 23--25 篇看基准；如果你是技术 Lead 在选型，第 26 篇的对比表能帮你下决定。但无论哪条路径，"环"这个概念会反复出现------它是理解 RSI-BOOT 一切设计的钥匙。
六、常见反驳与我的取舍
讲到这里，预期会有三类反驳。我先把它们摆出来，也说说我的判断，免得你心里嘀咕。
第一类："Claude Code 自己能记，Cursor 的 Rules 也能写，为什么还要 RSI-BOOT？" 能记不等于能跨工具、能审计、能自改进。Claude Code 的自动记忆锁在本机、不进 git，换同事对不上；Cursor Rules 是人肉维护的静态文件，覆盖不了"上次那个空指针怎么修的"这种经验，也不会从负反馈里长出更好的行为约束。RSI-BOOT 的价值不在"记一条"这个点，而在"同一份记忆能被五个宿主共用、且每条都要你批准才留下、且会随采纳率自我修正"。把记忆从"某个工具的便利功能"升格成"仓库的资产"，这才是它的主张。
第二类："直接上向量库加 Embedding 不是更准吗？语义检索听起来更高级。" 我的判断是，项目规矩里绝大多数是字面约定------"函数名用 snake_case""支付日志不打卡号"------这些词面一碰就中，BM25 足够，且零 Key、离线、不花钱。RSI-BOOT 的设计第一性原理就是"主链路零 API Key、不联网、只写仓库自己的 .rsi/"，所以把召回和知识库混合检索拆成两套独立子系统（第 5、10 篇展开）。语义召回那 10% 才交给可插拔的向量通道去补，不配 Key 就退化回纯 BM25。先解决 90% 的零成本场景，再谈增强，这个取舍我认同，也建议你别一上来就追向量化。
第三类："多一层记忆系统，Agent 上下文不就被撑爆了？" 恰恰相反。本篇引用的那个 74.1% 的 token 实验反直觉地说明：开着记忆反而更省 token。原因是记忆把"项目规矩"从每次都要从文件或对话里重新捞一遍，变成一次精准召回的几行约束；注入还有单文件 4000 字符、项目总量 32KB 的硬上限（src/rsi_boot/injector/targets.py 的 MAX_FILE_CHARS / MAX_TOTAL_CHARS）。记忆不是往上下文里灌水，是把正确的约束精准放进该在的位置。撑爆上下文的从来不是"有记忆"，而是"把整本代码或整段聊天塞进去"------RSI-BOOT 的蒸馏纪律恰恰禁止这种事。
说完反驳，也交个底：RSI-BOOT 不是万灵药。如果你的项目是单人、单工具、且约定写得清清楚楚放在 README 里，那手写 AGENTS.md 就够了，不必引入它。它真正划算的拐点出现在"跨工具 / 多人 / 长期维护 / 想从失败里自我改进"这几条里至少命中两条的时候。这篇先把定位讲透，值不值得上手，读到第 3、4 篇你自己会有答案。
七、把记忆当成仓库资产，而不是工具功能
我反复强调"跟仓库走"，不是修辞，是一个具体的工程判断：记忆的归属权该回到仓库和团队，而不是某个工具的云端账号。
举一个真实会发生的场景。你在一个支付仓库里教会 Agent"日志里不能打明文卡号"。如果这条记在 Claude Code 的本地记忆里，换一台机器、或者同事接手，这条就丢了，下一个 Agent 可能再把卡号打进日志。如果记在某个云端记忆服务里，它跟着你的账号，仓库拷给客户或开源出去，记忆留在别人的服务里，归属说不清。记在 .rsi/ 里，它随仓库进 git（核准部分）、随 fork、随交接一起走------这条规矩的寿命和仓库一样长，谁打开这个仓库谁读到。
这也是为什么第二节那张速查表里，"跟仓库走、随 git 流动"和"跟云账号走的云端记忆"是并排的两格。记忆绑在账号上，本质是把项目的资产外包给了工具商；记忆绑在仓库上，项目才真正拥有自己的"行规"。RSI-BOOT 的 .rsi/identity.json 里 project_id 恒为 local，就是把这个判断写死在代码里：隔离靠目录，不靠账号、不靠命名空间。顺着这个判断再走一步------当记忆随 git 流动时，它还能被 code review：一次记忆变更就是一次 git diff，你能看见"这条禁止项是谁、什么时候批准加进来的"。这是云端记忆方案的黑盒账号永远给不了的透明度。
八、我实测那个 74.1% 的方法，以及诚实偏差
本篇引用的 token 数字不是拍脑袋。方法是：拿 rsi-boot 这个仓库自己的问题，关记忆答一遍、开记忆再答一遍，看 Cursor CLI 报出的 token。关键是"关记忆"怎么定义------它去掉的是仓库根的 AGENTS.md 托管块和 .rsi/ 检出，让 Agent 看不到任何项目规矩；"开记忆"就是这份仓库，召回与注入都在。环境是 2026-10-29、Cursor CLI 2026.10.22、ask 模式、模型 Auto，token 把输入、输出、缓存读、缓存写四项加在一起。
六组加总：关记忆 1637977、开记忆 423973、省 1214004，比例 74.1%。但我想强调一个诚实偏差：同一套题我跑了四次（第一组再跑三轮），分别是 89.7%、76.0%、74.7%、79.5%。单组从 10.5% 到 89.7% 波动极大------有的组（项目根、basetemp、工作区边界）关记忆时要反复捞文件、token 暴涨，开记忆后几行约束就压住了；有的组（依赖、密钥、健康扫描）关记忆时也不怎么吃 token，开记忆的收益就小。所以本篇只引用合计 74.1%，绝不拿某一次当总成绩。这种"把波动摆出来而不是只报均值"的做法，是 rsi-boot 基准的公信力底色。
还有一个更刺眼的诚实点：LoCoMo 那 450 道"答案根本不在对话里"的题，rsi-boot 冷启动前 5 条一次都没有交空------对话里根本没有答案时，它仍然返回了几条看起来相关的话。这不是 bug，是 BM25 召回的固有行为：它只判断"词面像不像"，不判断"该不该有答案"。rsi-boot 选择把"该空时空了"这一列（0/450）明摆出来，而不是藏起来。因为一旦你开始粉饰召回的失败模式，后面所有数字都不可信。
为什么我坚持把基准只报"找不找得回"，不报"答对没答对"。 因为 rsi-boot 的主链路根本不调模型，没有"答题"这个环节。让它去和 Mem0 那种"先答题再打分"的方案比百分数，是拿苹果比橘子。它能诚实地告诉你"该找的那条规矩，冷启动能不能找回来"------Hit@5 56.5%（LoCoMo）/ 96.6%（LongMemEval-S），MRR 0.427 / 0.907------这就够了。模型带着这些规矩最终答得怎么样，是宿主模型的能力，不是 rsi-boot 的功劳，也不该算在它的账上。第 23--25 篇会给分项、给方法协议、给"该空时空了"这类失败模式的完整拆解，但本篇只立住一句话：我们只对"找回记忆"这件事负责，不对"模型有多聪明"负责。
这种克制不是营销话术，是我愿意推荐 rsi-boot 进生产的根因。一个工具如果一边说"我的记忆多准"，一边把"模型答题分"和"检索命中率"混在一张表里，我第一反应是它自己都不信自己的检索。rsi-boot 反过来：它把波动、把"该空时空了"、把"只测找回不测答对"全部摊开，反而让我觉得"这东西知道自己边界在哪"。信任工程工具，先看它怎么报坏消息，不是看它怎么报好消息。
小结
- 项目规矩属于仓库，不该属于某次聊天、某台机器或某个云账号------这是 RSI-BOOT 的全部出发点。
- 它的身份是宿主模型的程序性记忆层：只沉淀"怎么做"，不解析仓库语义、不替模型答题。
- 用起来是一条环：召回 → 干活 → 蒸馏成待审 → 你批准 → 下一轮召回。负反馈走失败桶旁路，只改可写槽位。
- 基准只报"冷启动检索命中"，与 Mem0 的"模型答题分"不可同列------这是它的诚实口径，也是后面公信力的根基。
- 系列按"痛点 → 概念 → 上手 → 原理 → 自改进 → 架构 → 基准 → 选型 → 团队 → 安全 → 收口"展开，可按需跳读，但"环"是贯穿全篇的钥匙。
下一篇预告
这一篇把"环"讲完了，但 RSI 到底为什么是"程序性记忆层"而不是"知识库"，我们还没说透。下一篇（第 2 篇）专门拆这个概念：程序性记忆和事实性记忆差在哪、为什么 RSI 既不是仓库理解器、也不是对话记忆、更不是云端账号记忆，以及------"程序性"这三个字到底改了 Agent 的什么。那是理解后面所有机制的地基。