从设计者的角度理解源码 -- Claude Code 的记忆系统设计
为什么记忆不是数据库
引言
多数人对 Agent 记忆的想象是:把聊天记录存下来,下次读回来。
Claude Code 不是这样。它没有数据库,没有向量库,只有一堆 Markdown 文件,外加一份索引。
更反直觉的是:存下来的东西,下一轮不一定被读到。
周一,你在会话里纠正过一次:测试别 mock 数据库,上次 mock 让迁移挂了。模型说记住了。周二,新开会话,你让它补一个测试。它又 mock 了。你去翻记忆目录:文件在,索引也在。它确实“记住”了,但这一轮没被选中。
这不是模型笨。记忆系统在五个地方做了取舍:存哪层、记什么、怎么过期、谁来整理、怎么接进提示词。
所以这篇文章不按“模块”讲,而是按一个判断展开:
记忆系统的核心不是存储,是加载与怀疑。
一、记忆不是数据库,是三级加载
记忆要同时满足三个约束。上下文窗口有限,不能全量加载;注意力会衰减,越长越容易漏;token 要钱,每轮都重算。数据库解决“存和查”,向量库解决“语义相似”,但这里真正的问题是:存哪一层、什么时候加载、加载多少。
如果只有一层,会掉进两个坑。全量加载,窗口撑爆;全量检索,每次都要扫一遍,慢且贵。于是 Claude Code 把它拆成三级。
| 级别 | 载体 | 回答什么问题 | 加载时机 | 体积 | 知道什么 | 不知道什么 |
|---|---|---|---|---|---|---|
| L1 | MEMORY.md | 有哪些记忆 | 每次会话 | 200 行 / 25KB | 有哪些笔记,每份一句话 | 笔记的具体内容 |
| L2 | 主题文件 | 这条记忆具体是什么 | 按需,≤5 个 | 无硬上限 | 结论、原因、怎么用、关键锚点 | 精确原文、完整上下文 |
| L3 | transcript | 当时到底发生了什么 | 从不自动加载 | 单文件可达 GB | 一切原文细节 | 结论、该看哪一段 |
L1 MEMORY.md 索引:一行一个指针,200 行 / 25KB,常驻
│ 指针
▼
L2 主题文件 正文:按需选中,≤5 个,带年龄
▲ 蒸馏
│
L3 transcript 原始录音:不自动加载,只能 grep
三级的关系很容易说错,先钉死:L1 到 L2 是指针,[标题](file.md),字面意义的索引;L2 是 L3 的蒸馏,把反复出现的事实固化成笔记,但不保留指向某条 transcript 的指针;L3 只能被搜,靠关键词 grep,不是顺着 L2 的索引找过去。
这也是为什么它不用向量库。记忆语料很小——每个项目最多 200 个文件进入选择;查询要精确——错误串、文件名、函数名;内容还要能被人直接编辑和 diff。向量库解决的是大语料上的语义相似,这三个条件在这里都不成立。一份 frontmatter 加一个便宜的选择器,就够了。
它不是存储问题,是加载问题。
二、三级怎么配合
先看它放在哪。默认路径是 <配置目录>/projects/<git-root 的净化路径>/memory/,按仓库根归档,不按当前目录——所以同一个仓库的多个 worktree 共享一份记忆。解析顺序是:环境变量 CLAUDE_COWORK_MEMORY_PATH_OVERRIDE → 设置里的 autoMemoryDirectory → 默认路径。关闭也有优先级:CLAUDE_CODE_DISABLE_AUTO_MEMORY、--bare、远程环境无持久存储、设置里的 autoMemoryEnabled。自动记忆目录本身也会校验路径:拒绝相对路径、根目录、UNC、空字节,避免把读写允许名单指到危险位置。
~/.claude/
└── projects/
└── <sanitized-git-root>/
├── <session-id>.jsonl L3:会话原始记录
└── memory/
├── MEMORY.md L1:索引,每次会话加载
├── testing-real-db.md L2:主题文件
├── money-in-cents.md
├── team/ 团队记忆,同仓库共享
│ └── MEMORY.md
└── logs/2026/11/2026-11-22.md 助手模式的追加日志
L1 不是记忆,是目录。一行一个指针,格式约定为 - [标题](file.md) — 一句话钩子。两个常量把它钉死:200 行、25KB;超出就截断,并追加一句警告,提示你把细节挪到主题文件。它进的是用户上下文,不是 system prompt——策略进 system prompt 的动态段,索引作为首条 user 消息里的 # claudeMd 块。
L2 的召回不是“模型自己翻目录”,而是一条流水线。扫描只读每个文件前 30 行 frontmatter,最多 200 个文件,按 mtime 倒序;拼成清单;交给一个便宜的模型选,最多 5 个;选中的正文才被读出来,截断、加 header、注入本轮。选择器只读 name + description,所以描述写得泛,它就选不中——description 是检索键,不是标题。它本身是一次 sideQuery:用 Sonnet、JSON schema 输出,失败时返回空,不阻塞对话。
用户 prompt
│
▼
扫 memory/ ── 只读每个文件前 30 行 frontmatter
│ (最多 200 个文件,mtime 倒序)
▼
manifest:- [type] filename (ISO): description
│
▼
选择器(便宜模型)── 只读 name + description,最多选 5 个
│ 排除 MEMORY.md、已浮现过的、正在用的工具文档
▼
读正文 ── 超过行/字节上限则截断,附 Read 链接
│
▼
header:Memory (saved N days ago): path:
│
▼
作为 relevant_memories 附件注入本轮
这条流水线还有几个容易被忽略的细节。第一,选择器会跳过 alreadySurfaced 的文件,避免同一份记忆每轮重复出现;也会跳过“最近正在成功使用的工具”的参考文档,因为那对当前对话是噪声。第二,选择器失败时返回空,不报错——宁可这轮不注入,也不阻塞对话。第三,召回是预取:每轮用户按下回车时启动,和主模型流式输出、工具执行并发,工具阶段结束后才收集结果;没就绪就本轮跳过,下轮再来。预取句柄用 using 绑定,生成器任何退出路径都会 abort;单词 query 会被跳过,会话累计注入字节也有上限,防止一天下来把记忆堆满上下文。注入时的单文件读取也有行数和字节数双上限,超出就截断,并给一条 Read 链接让模型自己去看全文。附件里的 header 在创建时算好并冻结——如果每次渲染都重算年龄,“3 天前”会变成“4 天前”,字节一变就击穿 prompt cache。
用户按下回车
│
├── 启动 recall 预取(不阻塞)
│ └── 扫描 → manifest → 选择 → 读正文
│
└── 主模型开始流式输出 / 执行工具
│
└── 工具阶段结束后收集预取结果
├── 已就绪 → 注入
└── 未就绪 → 本轮跳过,下轮再来
L3 是原始录音。单个 .jsonl 可以长到 GB 级,代码里裸读有 50MB 的保护阈值。模型读它只有一种方式:grep 窄词。提示词给的三类窄词,恰好是“摘要和原文之间不会发生同义改写”的东西:错误串、文件路径、函数名。L2 里没有 session id、没有行号、没有 transcript 路径;想回到 L3,只能拿 L2 里保留的锚点去搜。
所以准确说法是:L2 是 L3 的蒸馏,不是索引。 蒸馏的价值在于“反复出现的事实不用每次回原始录音里捞”;只有当需要精确原文时,才回到 L3。
把三级串起来,一次新会话里的接力是这样的:MEMORY.md 那行进 # claudeMd,模型知道“有这么一份笔记”;选择器按 description 选中正文,模型知道“测试要连真库”和“为什么”;需要精确原文时,拿 amount_cents、2026-03-09 去 transcript 里 grep。第三步不是“顺着指针找”,是拿关键词搜。
这里有个容易忽略的对称:选择器负责语义,锚点负责精确。 前者在写入时把描述写好,后者在写入时把标识符留下。两个动作都发生在“写”的时候,不是“读”的时候。
三、什么该记,什么不该记
记忆是有成本的。它占 L1 的行数、占选择器的 5 个名额、占每一轮的 token、占模型的注意力。每一条“可记可不记”的记忆,都在挤掉一条真正该记的。
所以准入有四关:
| 关 | 判据 | 反例 |
|---|---|---|
| 1 | 不能从当前项目状态推导 | 代码模式、架构、文件结构 |
| 2 | 跨会话有用 | 只在本会话用的任务状态 |
| 3 | 重推导成本 > 存储成本 | git log 能查到的变更历史 |
| 4 | 安全 | API key、凭据 |
排除清单写得很具体:代码模式、约定、架构、文件路径、项目结构——读当前项目就能得到;git 历史、最近变更、谁改了什么——git log / git blame 才是权威;调试方案、修复配方——修法在代码里,上下文在 commit message 里;CLAUDE.md 已经写过的;临时任务细节——进行中的工作、临时状态、当前对话上下文。
最狠的一条是:即使用户明确要求保存,这些排除依然生效。 用户说“记住这周的 PR 列表”,正确动作不是照单全收,而是追问一句“哪一点是意外或不显然的”。直接记,得到的是一份流水账;追问之后,得到的才是一条能改变行为的规则。样例见附录 A5、A6。
四类记忆按信息来源分,不按话题分:
| 类型 | 记什么 | 来源 | 默认作用域 | 衰减 |
|---|---|---|---|---|
user | 你是谁:角色、目标、知识背景 | 人 | 永远 private | 慢 |
feedback | 该怎么做事:纠正与确认 | 交互 | private 优先,项目级约定可 team | 中 |
project | 为什么做、谁在做、何时 | 工作 | 强烈倾向 team | 快 |
reference | 去哪找外部信息 | 外部系统 | 通常 team | 慢 |
“只记偏好”是一句有损的概括。偏好只是 user 和 feedback 的内容;project 记的是动机与时间线,reference 记的是外部系统的指针,都不是偏好。四类合起来回答四个问题:**你是谁、怎么配合、为什么做、去哪查。**还有一条冲突规则:私有 feedback 和团队 feedback 打架时,要么不存,要么显式标注覆盖——否则两套规范会互相拆台。
作用域不是装饰,它决定了文件落在哪:
<memory>/ 私有,只有本机这个项目能看
├── MEMORY.md 索引
├── user_*.md user:永远私有
├── feedback_*.md feedback:默认私有
└── team/ 团队,同仓库的人共享
├── MEMORY.md 团队索引
└── project_*.md project / reference:倾向团队
团队记忆是自动记忆的子目录,自动记忆关闭时它也不可用;它还受 feature gate 控制。它不是“把私有目录拷过去”。它按仓库(git remote 的 hash)隔离,只同步内容 hash 变了的文件;上传前会扫描密钥,命中就整份跳过;路径要过穿越检查——空字节、URL 编码的 ../、Unicode 归一化后的斜杠、反斜杠、绝对路径、符号链接逃逸,全部拒绝。这些不是洁癖,因为团队记忆一旦跨人,写错一个路径就是组织级泄露。
一条记忆文件的契约很短:frontmatter 三个字段——name、description、type;未知 type 会降级为 undefined,不阻塞读取。正文按 feedback / project 的结构写“规则 / Why / How to apply”。保存分两步:先写主题文件,再往 MEMORY.md 加一行指针。索引行控制在 150 字符以内,超过 200 字符就说明你把正文塞进索引了。MEMORY.md 是索引,不是 dump。记忆和 CLAUDE.md 也有明确分工:CLAUDE.md 是人写的项目规约,记忆是机器写的学习;记忆提示词明确要求不要重复 CLAUDE.md 里已有的内容。
还有一条反直觉的规则,专门防行为漂移:成功和失败都要记。 只记“不要做什么”,模型会越来越保守;记录“这样做被认可”,才是在维持一个行为分布。
四、记忆为什么会过期
每条记忆都带年龄。年龄来自文件的 mtime,不是“事实发生的时间”。算法很短,见附录 A1。规则是:不超过 1 天,不警告,只显示 Memory (saved today/yesterday): path:;超过 1 天,加一段警告,说明这是当时的观察,不是实时状态,涉及代码行为或 file:line 的说法可能已经过期,引用前要对照当前代码验证。不只是召回附件;模型直接 Read 一个记忆文件时,FileReadTool 也会把同样的新鲜度提示前置到结果里。
这里有一个看似矛盾的设计:既然展示用相对年龄,为什么存储时又要求绝对日期?因为这是两套时间。存储用绝对日期,可 grep、可比较、不腐烂;展示用相对年龄,因为模型不擅长日期运算,一句“47 天前”比一个 ISO 时间戳更能触发“这可能是旧的”的判断。
但年龄有三个已知局限。第一,它按文件算,不按事实算,一个文件里新旧事实共享同一个年龄。第二,mtime 会被重写洗白,dream 为了合并新信息重写文件,里面三年前的旧事实也会“变成今天”。第三,它类型无关,user 衰减很慢、project 衰减很快,用的却是同一条 1 天阈值。
所以系统真正的防线不是年龄,而是读时验证:
读到一条记忆
│
├── 年龄 ≤1 天?── 是 → 只显示 saved today/yesterday
│ 否 → 附「N days old」警告
│
├── 记忆里提到文件/函数/flag?
│ ├── 文件 → 查存在
│ └── 函数/flag → grep
│
└── 与当前观察冲突?
├── 是 → 以现状为准,更新/删除旧记忆
└── 否 → 可以作为背景使用
除此之外,还有几种机制在帮忙:提取时更新或删除过时记忆;dream 定期删掉被推翻的事实;扫描按 mtime 倒序、上限 200,旧文件会自然掉出候选池;用户说“忽略记忆”时,系统按空目录处理。但这些都只是“降低概率”,不是“保证正确”。
所以整个记忆系统的立场只有一句:记忆是证词,不是判决。 它不保证记忆为真,只保证每条记忆都带着可怀疑的线索——日期、可验证的锚点、以及一句“以现状为准”。
五、谁在写:提取与整理
增量写入只解决“新事实入库”,不解决“库是否自洽”。没有整理,会出现三个问题:索引膨胀、重复文件、旧结论和新结论互相矛盾。
提取发生在每轮结束时,条件是模型产出“不再调用工具”的最终回复。它不是主模型顺手做的事,而是一个 fork 出来的子代理:
一轮对话结束(模型不再调用工具)
│
▼
stop hook:fire-and-forget
│
├── 上一轮提取还在跑?── 是 → 暂存 context,等它结束后补跑一次
│
├── 主模型本轮已写过记忆?── 是 → 跳过,游标推进
│
└── 轮次节流通过?── 否 → 返回
│
▼
fork 子代理(共享 prompt cache)
├── 预注入记忆清单(省掉 ls 一轮)
├── 并行读要更新的文件
├── 并行写 / 编辑
└── 成功 → 游标推进到最后一条消息
失败 → 游标不动,下轮重试
这个 fork 继承父对话的上下文与 prompt cache,所以几乎不额外花钱;它拿到的任务范围也被限制——只允许用最近 N 条消息,不允许再去 grep 源码验证。maxTurns: 5,防止它陷进“验证—再验证”的兔子洞;不写 transcript,避免和主线程抢写;如果主模型这一轮已经自己写过记忆,它直接跳过。只有成功跑完,游标才推进;失败则下次重试。退出时还有一个 60 秒的 drain,保证它不会在进程关闭时被腰斩。
它的权限是整套设计里最值得看的一页:
| 能力 | 允许 | 拒绝 |
|---|---|---|
| Read / Grep / Glob | 全部 | — |
| Bash | 只读:ls、find、cat、stat、wc、head、tail | 写入型命令、rm |
| Edit / Write | 仅记忆目录内 | 记忆目录外 |
| REPL | 允许(内部仍走同一套检查) | — |
| MCP / Agent | — | 全部 |
这不是“不信任子代理”,而是“只给它完成这件事所需的最小权限”。代码见附录 A3。
整理则是另一条线:autoDream。它每轮结束都会被调用一次,但绝大多数时候在时间门就返回了——成本只有一次 stat。要真跑起来,得同时过三重门:
每轮结束
│
▼
时间门:距上次巩固 ≥24h?── 否 → 返回(一次 stat)
│ 是
▼
扫描节流:10 分钟内扫过?── 是 → 返回
│ 否
▼
会话门:新会话 ≥5 个?── 否 → 返回
│ 是
▼
锁门:.consolidate-lock 可获取?── 否 → 返回
│ 是
▼
dream 运行(四阶段)
├── 成功 → 锁 mtime 留在 now
└── 失败 / 被 kill → 回滚 mtime,下轮重试
闸门顺序是最便宜的先:时间门一次 stat,过了才做扫描;扫描还有 10 分钟节流,防止“时间门一直过、会话门一直不过”导致每轮都扫。锁文件一物两用,mtime 就是 lastConsolidatedAt,body 是持有者 PID;持有超过 1 小时视为过期,防 PID 复用。跑失败就把锁 mtime 倒回去;用户手动 kill 也会回滚。它还注册成后台任务,所以能在任务面板里看到、能被 kill。
它做四件事:Orient(ls 目录、读索引、浏览已有主题文件);Gather(按每日日志、已漂移的旧记忆、必要时窄词 grep transcript 的顺序收集信号);Consolidate(合并进已有文件而不是新建近似重复,把相对日期转绝对,删掉被推翻的事实);Prune and Index(重写索引,保持 200 行 / 25KB,因为 It's an index, not a dump)。dream 保证自洽,不保证正确。 它可以删掉一条矛盾记忆,但不能判断该删哪一条;也可能 prune 过头,把仍然需要的历史删了。
这里有一个容易混淆的权限差异:自动 dream 会在提示词里追加“Bash 只能只读”的约束;手动 /dream 跑在主循环里,权限正常,不需要这段提示。同一个整理者,两种入口,约束不同。
把三条线放在一起看,结构就清楚了:
| 写 A | 读 | 写 B | |
|---|---|---|---|
| 触发 | 每轮结束 | 每轮 | 24h + 5 会话 |
| 游标 | 消息 UUID | 无状态 | 锁文件 mtime |
| 输入 | 当前会话 | 当前 query + 清单 | 目录 + 历史 transcript |
| 输出 | 新增/更新 | 注入上下文 | 重写/删除 |
时间 →
读: 每轮 █ █ █ █ █ █
写 A: 每轮 █ █ █ █ █ █
写 B: ──────────────█──────────────█──→ (24h + 5 会话)
这不是一条“写入 → 存储 → 召回 → 整理”的生命周期,是一个共享存储 + 两个写者 + 一个读者。三个后果:一条记忆可能写完从未被召回;召回不依赖本次写入,它读的是磁盘现状;代码里没有让写 A 与写 B 互斥的锁,两者理论上可以同时改同一个目录。
还有一件更底层的事:没有 per-fact 的 id / version / status,唯一的时间信息是文件 mtime。这也解释了前面的那些局限:年龄为什么按文件算、重写为什么能洗白、为什么锁只防 dream 之间。它们不是疏漏,是“文件 + mtime”这个轻量方案的自然结果。
六、它怎么接进提示词系统
没有“一个入口”,有四个注入点:
API Request
├─ system: [静态 7 段] + [动态段 memory(策略)] ← ①
├─ messages:
│ [0] # claudeMd(MEMORY.md 索引) ← ②
│ [attachment] relevant_memories(正文 + 年龄) ← ③
└─ tools: Read / Grep / Glob / Edit / Write ← ④
| # | 入口 | 进入什么 | 内容 |
|---|---|---|---|
| ① | systemPromptSection('memory', loadMemoryPrompt) | system prompt 动态段 | 策略:四类定义、怎么存、何时读、怎么验证 |
| ② | getUserContext() → prependUserContext() | 首条 user 消息 # claudeMd | 索引:MEMORY.md 的实际内容 |
| ③ | relevant_memories 附件 | 本轮 attachment | 正文:选中的主题文件 + 年龄 |
| ④ | Read / Grep / Glob / Edit / Write | tool calls | 动作:模型自己读写文件 |
① 和 ② 不是一回事:① 是说明书,② 是目录。 ① 回答“怎么记、怎么用”,策略通用,只有记忆目录路径随项目变;② 回答“已经记了什么”,每个项目不同。这也是为什么策略要进 system prompt、索引要进用户上下文:稳定的、跨项目的放前面,易变的、项目相关的放消息流。
MEMORY.md 不是单独一条通道,它混在 CLAUDE.md 家族里,加载顺序是 managed → user → project → local → AutoMem → TeamMem。所以它天然继承了那个块的开头一句“These instructions OVERRIDE any default behavior”,也继承了它的权威问题。
这里还有一个变体值得知道:tengu_moth_copse 开关打开时,索引不再走 # claudeMd,改由附件按需下发;召回预取也受同一个开关控制。也就是说,“索引每次会话常驻”是默认行为,不是唯一实现。
关键词在这套系统里不是一张词表,而是四类字符串:description 是检索键,选择器只读它;type 是选择先验和作用域默认值;name 或文件名是标题,也是 grep 的锚点;段落标题是读文件时的结构线索。让记忆可被检索,主要不靠模型临场想词,而靠写入时把 description 写准。
刷新时机则决定了“刚记住的东西为什么这一轮看不到”。memory 系统段被缓存到 /clear 或 /compact;# claudeMd 在会话开始时就 memoize,/compact 时清缓存;relevant_memories 每轮预取、每轮重建。所以写入的即时反馈是那条系统消息——Saved N memories(dream 是 Improved N memories),而不是索引更新。索引要等到下一次 /compact 或新会话才更新;但下一轮的召回扫描是实时的,所以新写的主题文件仍可能被选中。
最后一个设计张力:MEMORY.md 只是索引,却和 CLAUDE.md 放在同一个块里;载体很权威,内容却会过期。这就是为什么需要 TRUSTING_RECALL 来给记忆“降权”:"The memory says X exists" is not the same as "X exists now."(代码见附录 A7)。
可迁移的设计原则
收拢成三句话:
① 存证词,不存事实。
② 索引常驻,正文按需。
③ 读时怀疑,而不是写时保证。
展开成三步:
- 先分层:常驻只放指针(200 行以内),正文按需选(≤5 个),不要全量注入。
- 再定准入:能从代码 / git / 文档推导的不记;只在本会话有用的用 todo / plan;写不出锚点的先别写。
- 最后定维护:增量写和批处理整理分开;每条记忆留日期和可验证的锚点;读的时候验证,而不是写的时候保证。
知识补习
几个术语。
- point-in-time observation:记忆不是“事实”,是某个时间点的观察,不是实时状态。
- anchor:能在原文里精确匹配的字符串,通常是错误串、文件路径、函数名。
- distillation:L2 不是 L3 的索引,是把反复出现的事实提炼成笔记,不保留指回原文的指针。
- relevance selector:召回时用一个便宜的模型按
description挑文件。 - cache-safe fork:写者 A 共享父对话的 prompt cache,所以几乎不额外花钱。
- scope:作用域分 private 和 team。
- freshness:新鲜度,用文件 mtime 算出的年龄提示。
几个常量。
- 索引 200 行 / 25KB;
- 扫描只读前 30 行 frontmatter、最多 200 个文件;
- 每轮最多选 5 个主题文件;
- dream 时间门 24 小时、会话门 5 个;
- 提取代理最多 5 轮;
- transcript 裸读保护 50MB;
- 大记忆文件告警阈值 40K 字符。
四个容易记反的点。
MEMORY.md不在 system prompt 里:策略进 system prompt,索引进用户上下文。- 提取代理不是“连 Bash 都不能跑”:它允许只读 Bash,比如
ls、find、cat。 - “cache 不共享会慢 10 倍”在代码里没有这个数字:准确说法是会退化为全量 prefill,成本高一个量级。
- 记忆不是“四阶段生命周期”:是三条独立调度线,共享一个目录。
不要和 SessionMemory 混淆。 会话记忆是另一套:它在会话内滚动记录当前状态,供压缩使用,有“上下文增长 + 工具调用数”的双阈值;AutoMemory 是跨会话的长期记忆。两者都叫“记忆”,但生命周期和写入者完全不同。
附录:代码与出处
A1 年龄算法(memoryAge.ts L14-24)
// src/memdir/memoryAge.ts L14-24
export function memoryAgeDays(mtimeMs: number): number {
return Math.max(0, Math.floor((Date.now() - mtimeMs) / 86_400_000))
}
export function memoryAge(mtimeMs: number): string {
const d = memoryAgeDays(mtimeMs)
if (d === 0) return 'today'
if (d === 1) return 'yesterday'
return `${d} days ago`
}
这段说明:年龄是文件 mtime 的函数,未来时间戳会被钳到 0。
A2 缓存安全参数(forkedAgent.ts L57-68)
// src/utils/forkedAgent.ts L57-68
export type CacheSafeParams = {
systemPrompt: SystemPrompt
userContext: { [k: string]: string }
systemContext: { [k: string]: string }
toolUseContext: ToolUseContext
forkContextMessages: Message[]
}
这段说明:fork 要和父对话共享缓存,这五样必须一致;少一样就退化成全量 prefill。
A3 提取代理的权限闸门(extractMemories.ts L184-220)
// src/services/extractMemories/extractMemories.ts L184-220(节选)
if (
tool.name === FILE_READ_TOOL_NAME ||
tool.name === GREP_TOOL_NAME ||
tool.name === GLOB_TOOL_NAME
) {
return { behavior: 'allow' as const, updatedInput: input }
}
if (tool.name === BASH_TOOL_NAME) {
const parsed = tool.inputSchema.safeParse(input)
if (parsed.success && tool.isReadOnly(parsed.data)) {
return { behavior: 'allow' as const, updatedInput: input }
}
return denyAutoMemTool(tool, 'Only read-only shell commands are permitted ...')
}
if (
(tool.name === FILE_EDIT_TOOL_NAME ||
tool.name === FILE_WRITE_TOOL_NAME) &&
'file_path' in input
) {
const filePath = input.file_path
if (typeof filePath === 'string' && isAutoMemPath(filePath)) {
return { behavior: 'allow' as const, updatedInput: input }
}
}
这段说明:读和搜不限制,写只允许记忆目录,Bash 只允许只读。
A4 常量(memdir.ts L35-38、memoryScan.ts L17-18)
// src/memdir/memdir.ts L35-38
export const MAX_ENTRYPOINT_LINES = 200
export const MAX_ENTRYPOINT_BYTES = 25_000
// src/memdir/memoryScan.ts L17-18
const MAX_MEMORY_FILES = 200
const FRONTMATTER_MAX_LINES = 30
这段说明:索引和扫描的上限,决定了“记忆系统的分辨率”。
A5 一条完整的记忆(memoryTypes.ts L261-270)
---
name: 集成测试必须连真库
description: 测试禁止 mock 数据库;mock 曾让 amount_cents 迁移失败在 CI 里全绿
type: feedback
---
规则:集成测试连真库,不 mock。
**Why:** 2026-03-09 事故——mock 让 CI 全绿,prod 迁移却挂了。
**How to apply:** 任何碰数据库的测试。
这段说明:description 是检索键,Why 是判断边界的依据,How to apply 是触发条件。
A6 流水账反例(memoryTypes.ts L192-194)
- #4821 fix: retry on 429
- #4830 chore: bump deps
- #4844 refactor: extract auth middleware
这段说明:PR 列表是活动日志,不是记忆;PR 号应该当锚点,洞察才是正文。
A7 读时验证(memoryTypes.ts L240-256)
// src/memdir/memoryTypes.ts L240-256(提示词原文)
// A memory that names a specific function, file, or flag is a claim
// that it existed *when the memory was written*.
// If the memory names a file path: check the file exists.
// If the memory names a function or flag: grep for it.
这段说明:记忆里的名字是“当时存在”的声明,不是“现在存在”的事实。
评论