文章标题:在代码变更时保持 AI 编码智能体记忆的相关性
正文: 编码智能体可以在会话之间保留信息。它们可以保存调查结果、记住架构决策,并检索那些在会话结束时本会消失的知识。
但它们所了解到的代码一直在变化。
设想一个智能体在调查指针移动处理器中的一个 bug。它定位了相关实现并记录了结论。一个月后,另一个智能体调查一个相关问题,并检索到这些笔记。
该函数可能已经移动、被重命名或发生了实质性变化。甚至只是在文件其他地方添加几行,也可能让旧的代码行引用指向不相关的代码。
还有另一个问题:下一个智能体可能永远检索不到这次调查,因为它用不同的术语描述了同一段代码。或者它可能检索到对同名但不相关函数的调查。
我们想了解这些问题在真实代码仓库中出现的频率、编码智能体处理它们的效果如何,以及将持久知识与源代码结构关联起来是否能改善检索和复用。
为什么 AI 编码智能体记忆需要源代码引用
智能体可以将知识保存在 Markdown 文件、会话摘要或 Cognee 这类专用记忆系统中。
这些方法让以往的调查可供未来会话使用。记忆系统还可以根据智能体正在执行的任务来组织和检索知识。
考虑一条已保存的观察记录:
指针移动处理器包含 crop-move 逻辑。调查裁剪拖拽时请检查此函数。
下一个智能体如何确定前一个智能体检查的确切函数?
文件路径和行号提供了一个起点,但行号描述的是文件某一特定版本中的位置,而不是对函数的持久引用。函数名更有用,但它们不一定唯一,而且可能变化。Git commit 可以让原始源代码可恢复,尽管智能体仍需要将那个历史实现与当前代码关联起来。
这些限制也会影响检索。依赖文本或语义相似度的记忆系统可能会漏掉那些用不同描述指代同一函数的以往调查,或者检索到关于名称相似但不相关实现的观察记录。
我们使用 Enola 来建立这种关联。
Enola 通过从源代码中提取符号及其关系,构建代码库的结构化表示。它的 locate 功能将源代码位置解析为一个符号:
enola locate src/app.ts:120
结果包含该符号的标识符、名称以及 body_hash,即其代码的指纹。
智能体可以将这些信息与调查结果一起保存。当之后检索该调查时,Enola 可以识别出对应的符号,并检查其实现是否已发生变化。
该引用也可以支撑检索本身。如果多条调查指向同一个符号,记忆系统就可以将它们关联到同一个实现,而无论智能体是如何描述它的。
这提供了补充语义检索的结构化信息,而不是取代语义检索。
实验方法:测试智能体记忆面对代码库变更的表现
我们使用了两个开源 TypeScript 项目 Excalidraw 和 Vite,考察已保存的智能体知识在代码仓库演进过程中会发生什么。
实验分为三部分:从历史代码仓库版本中收集智能体调查,检查其源代码引用在后续版本中的情况,并测试智能体能否仅凭书面描述识别出相关调查。
选取历史修复并记录智能体调查
我们从每个仓库中选取了二十个历史修复,总计四十个修复。
对于每个修复,我们检出该修复之前的一个修订版本,并使用 Opus 5.5 启动一个新的 Claude Code 会话。
该 agent 被要求调查早期状态下的代码,并记录其观察结果。每次调查都保存在本地的 MEMORY.md 文件中,并附有对相关源代码位置的引用。
每次调查都使用全新会话,防止 agent 依赖先前调查中积累的知识。保存的观察结果代表了可以带入后续会话的内容。
在某些情况下,这些调查产生了多个源代码引用。在两个项目中,我们评估了 Excalidraw 中的 45 个记录位置和 Vite 中的 51 个记录位置,总共 96 个位置。
这些位置,而非历史修复的次数,是源代码位置实验的测量单位。
跨仓库修订版本评估源代码引用
我们在较晚的修订版本中检查了这些仓库,包括原始调查之后三十天的时点以及每个项目较晚的修订版本。
对于每个保存的位置,我们检查原始行引用是否仍然指向该 agent 调查过的函数。
当记录的位置指向不同的函数时,即使原始函数仍然存在于仓库的其他位置,该引用也被计为不正确。
然后我们使用 Enola 将原始源代码位置解析为符号标识和代码指纹。通过保留符号标识符、名称和 body_hash,我们可以在不单纯依赖原始行号的情况下,对照后续的仓库修订版本检查这些引用。
这使我们能够区分源代码位置变得过时与底层实现实际消失或发生变化这两种情况。
将实现变更与行移动分开测量
我们还跟踪了 Excalidraw 中一个单独的指针移动函数,跨越 188 个每日仓库修订版本。
对于每个修订版本,我们检查了该函数的行号是否发生变化,以及其实现是否发生变化。
该比较将文件中其他位置的编辑所引起的变更与函数自身代码的变更区分开来。
然后我们进行了一项单独的审查,使用十八条保存的观察结果,涉及实现已发生变化的函数。一个全新的 Claude Code 会话检查了较晚的代码,并评估先前的观察结果是否仍然适用。
这测试了基于指纹的检查的一个重要局限性:检测到代码变更并不能确定先前的解释是否已经变得不正确。
使用书面观察结果测试检索
最后,我们调查了是否可以在没有结构化引用的情况下识别出关于同一实现的先前观察结果。
我们检查了以下情况:不同的 agent 调查到达了同一个函数但对其描述不同,以及不相关的函数共享相同的名称。
在纯文本比较中,该 agent 收到了书面观察结果,但没有 Enola 的符号引用,并被要求识别重复出现的函数。
我们将其结果与通过 Enola 解析原始源代码位置所获得的标识进行了比较。
在 Excalidraw 案例中,我们将纯文本排名重复了五次。我们还检查了 Vite 中共享函数名称或对相关代码的不同描述影响了 agent 分组的情况。
这些测试评估了自然语言观察结果是否足以识别常见的源代码符号。它们不是完整记忆检索系统的基准测试,也没有衡量 Cognee 的检索性能。
结果:代码变更如何影响 Agent 记忆
为什么文件路径和行号会变得过时
三十天后,45 个记录的 Excalidraw 位置中有 13 个、51 个 Vite 位置中有 8 个指向了不同的函数。
在我们检查的较晚仓库修订版本中,这些数字分别增加到 25 和 18。
| Project | Locations examined | Incorrect after 30 days | Incorrect at later revision |
|---|---|---|---|
| Excalidraw | 45 | 13 (29%) | 25 (56%) |
| Vite | 51 | 8 (16%) | 18 (35%) |
原来的函数仍然存在。它们的位置发生了变化,通常是因为文件中其他地方的修改。
因此,按照旧引用行事的代理可能会找到有效的源代码,却找不到其前身所调查的实现。引用仍然能打开一个文件,而该位置的代码可能看起来完全合理。
使用 Enola,我们把原始位置解析为符号,并记录它们的标识和指纹。这样我们就可以对照后续的仓库修订版本来检查这些引用,而不必完全依赖行号。
跨代码版本跟踪函数变化
我们跨 188 个每日仓库修订版本跟踪了 Excalidraw 中的一个 pointer-movement 函数。
它的行号变化了 93 次,而函数内部的代码只变化了 25 次。在其余 68 次中,文件其他地方的编辑改变了它的位置,却没有改变它的实现。
Enola 的指纹让我们能够区分一个函数是移动了,还是其实现发生了变化。
我们还让一个新的 Claude Code 会话审查了十八条已保存的观察记录,这些记录涉及实现已发生变化的函数。该代理判断,尽管外层函数在其他地方发生了修改,其中一些记录仍然准确。
因此,指纹变化是检查早期观察记录的理由,而不是自动将其丢弃。同样,函数体未变化也并不保证该观察记录仍然有效:依赖项、调用方或周围行为可能已经改变。
对于记忆系统来说,这些信号有助于确定哪些检索到的观察记录需要进一步验证。
用符号引用改进代理记忆检索
第三个实验关注的是检索,而不是代码移动。
在 Excalidraw 中,五项独立调查到达了同一个函数,但对其描述各不相同。这些代理提到了 pointer movement、crop movement、一个内部闭包,以及同一文件中的其他相关代码。
将它们保存的源代码位置解析到原始仓库修订版本后,五项调查全部关联到:
App.onPointerMoveFromPointerDownHandler
随后我们让一个代理仅使用书面观察记录来识别反复出现的函数,而不使用 Enola 的结构化引用。
在五次尝试中,它从未将该函数列入其前五个反复出现的函数。
在四条记录中,文本中记录的函数名与包含所引用源代码位置的函数不一致。
Vite 暴露了相反的问题。多个插件包含名为 renderChunk 的函数,而该代理将关于不同实现的观察记录归到了这个共享名称之下。它也未能关联七项涉及 cssPostPlugin 的调查,而该插件包含多个相关函数。
这说明仅靠文本检索存在局限。相似的描述不一定指代同一段代码,而不同的描述可能指代完全相同的实现。
有了源自源代码的符号引用,记忆系统可以检索与特定实现相关的调查,而不受其措辞影响。
例如,调查 App.onPointerMoveFromPointerDownHandler 的代理可以检索与该符号相关的早期观察记录,包括那些最初被描述为 crop-movement 调查的记录。
像 Cognee 这样的系统有可能将这些引用纳入其现有的检索机制,在语义关系之外使用符号标识。
我们的实验展示了仅靠文本识别的局限,以及结构化引用如何解决这些问题。实验并未衡量 Cognee 检索性能的端到端改进。
如何用 Enola Locate 跟踪源代码引用
我们的实验使用 MEMORY.md,因为我们的工作基于 Claude Code。该方法并不绑定于特定的记忆格式。
当 agent 记录一条观察结果时,它可以用 Enola 解析出相关的源代码位置:
enola locate src/app.ts:120
返回的 id、name 和 body_hash 可以与这条观察结果一并保存。Enola 把保存下来的符号引用称为 stamp。
对于历史追溯,locate 还支持 --at 选项,用于针对特定的仓库修订版本解析位置。这能确保该引用标识的是调查发生时该代码的实际状态。
Stamps 可以保存为 JSONL 记录,供日后检查:
enola locate --stamps findings.jsonl
Enola 会报告每个引用的状态:
| 状态 | 含义 |
|---|---|
| current | 该符号的代码未发生变化。 |
| moved | 相同的代码在另一个位置被找到。 |
| rewritten | 该符号仍然存在,但其代码已改变。 |
| gone | 未找到匹配的符号。 |
| ambiguous | Enola 无法建立唯一匹配。 |
这为 agent 提供了两次使用 Enola 的机会:在保存观察结果时,记录它所描述的源代码符号;在检索该结果时,对照当前仓库检查该引用。
记忆系统还可以按观察结果关联的符号为其建立索引。如果 agent 正在调查某个特定函数,那么关于该函数的早先观察结果就能被检索出来,而不必完全依赖语义相似度。
Enola 通过其 CLI 和 MCP 接口提供 locate 功能,使这一工作流能够与编码 agent 和持久化记忆系统集成。
记忆系统仍然负责存储、检索和排序。Enola 提供符号引用及其实现变更的相关信息。
在代码库演进过程中保持 Agent 记忆的相关性
我们的实验暴露了在 agent 会话之间传递源代码知识时存在的若干问题。
随着仓库演进,行号引用变得不可靠。函数经常在不改变其实现的情况下发生移动。调查同一段代码的 agent 会生成各自不同的描述,导致它们的观察结果难以相互关联;而共享的函数名又会让互不相关的调查被归为一组。
诸如 Cognee 这样的持久化记忆系统负责处理 agent 知识的存储、组织和检索。Enola 提供源自源代码的信息,供这些系统将保存的观察结果与它们所描述的实现关联起来。
这种关联可以改善记忆的组织方式以及检索时的选取方式。它还能让 agent 在依赖某条检索到的观察结果之前,检查其背后的代码是否已经改变。
这里存在局限。一个有效的符号引用并不能证明早先的解释是正确的,而且系统中其他位置的变化也可能在未改动被引用函数的情况下使某条观察结果失效。
但 agent 不再需要仅凭自然语言描述去重建其早先观察结果与当前仓库之间的每一处关联。它可以用 Enola 确定这些观察结果所指向的是哪段代码,以及自记录以来那段代码经历了什么。
解释仍然是 agent 自己的责任。
延伸阅读
- Enola — Flows 与 locate 文档
- Enola — GitHub 仓库
- Veljko Kovač — 关于 agent 记忆的文章(X)
- 每个编码 agent 都需要的四层记忆
- coding agents
继续阅读
更多来自博客的内容
Nov 7, 202612 min read
AST 到底有多真实?解析器库真正能给你什么
代码工具把抽象语法树当作基准真相。升级 Enola 背后的解析器表明,这一真相在多大程度上取决于语法、版本和运行时。
Oct 27, 20267 min read
Enola for VS Code:在你的 agent 会话旁做架构检查
文章标题:在代码变更时保持 AI 编码代理记忆的相关性
正文: Enola for VS Code 在编辑器内展示架构发现、规则检查,以及来自 Claude Code、OpenCode、Codex 和 pi 的已记录编码代理会话。
Oct 23, 202614 min read
Claude Code 基准测试:Enola 在模型从未见过的代码上的表现
一项横跨五个私有仓库的 Claude Code A/B 基准测试,衡量 Enola 对答案准确性、成本、时间和一致性的影响。