首页 / 文章

确保智能体记忆真实性的四条编码规则

存储更多笔记并不能解决编码代理的内存问题。有四条规则能确保其正常运行:可见的过时提示、失败时的自动屏蔽、明显的截断显示以及持续的约束限制。

发布者:REACTAPP.TOP阅读约 9 分钟2130 词

来源: Your Coding Agent Has a Memory Problem. Storing More Won’t Fix It.

打开第二个聊天窗口后,你的编程助手将一无所知。它不会比之前知道得更多,反而什么都不会知道。四十分钟前关于为何拒绝队列式处理方法的决策已经消失,客户端安全团队绝不会批准新数据库的约束也不存在了,你之前已经探索过的那三个死胡同也同样消失了,这样就没人需要再重复那些尝试了。上下文在窗口切换后会丢失。

因此只能遵循常规流程:粘贴旧聊天记录,把能想到的内容重新输入,对于想不起来的事情则再次解释。每次切换窗口至少需要十到十五分钟,而那些基于你已经得出的结论的优质请求也会白白浪费。

这些平台中没有任何功能能够填补这一缺口,因为每个记忆功能都仅限于你试图离开的那个特定场景。有位开发者的解决方案是自行构建一个记忆层:大约2,600行Node代码,没有运行时依赖,可为GitHub Copilot、Claude Code和Codex提供服务。几乎立刻,它就遇到了没人提及的问题。

存储更多只会让情况更糟

记忆系统的真正缺陷并非遗忘,而是错误地、且满怀信心地记住事物。

想象这样一张便条,上面写着“认证使用JWT”,这是在该机制确实适用时写的,而在代码库改为使用服务器端会话四个月后仍被取出使用。这种信息并不会逐渐变得不确定,反而会被再次调用、被信任并作为基础继续发展,最终导致出现一个明确且自信地给出错误结论的智能体,甚至还能给出所谓“来源”。这显然比那个说“我不知道这里的认证机制是如何工作的”的智能体更糟糕,因为后者至少会向你询问,而前者则会直接输出错误结论。

因此,存储并非体现巧妙工程设计的所在,因为它只不过是一个文件夹和一套架构而已。真正的难点在于,在底层代码不断变化的情况下,仍要确保保存下来的知识始终准确无误。最终的设计采用了四项保障措施,每项措施都只需要很少的代码,但需要极大的自我约束力。

谁来撰写这些便条

该作者是一个语言模型,几乎所有的设计决策都源于此。其输入内容不可信赖,但并非因为有人故意为之:这些输入可能来自包含 API 密钥、连接字符串或他人电子邮件地址的对话。其输出格式也不能想当然地接受,而且每次修正都需要发起一次真实的请求。

最后一个问题出现在意想不到的地方:验证器会一次性报告所有问题,而不会在遇到第一个问题时就停止。

export function validateNode(input) {
  const e = [];
  // ...every check pushes onto e instead of throwing...
  if (e.length) throw new ValidationError(e);
  return n;
}

迅速出错是一种本能反应,但在这里这是不对的。能够修正自身输出的模型可以一次性修复所有问题,而无需逐一查找故障,每查找一个故障都需要额外发起请求。虽然只是一个小改动,却能让一次重试变为五次。

备注共有四种类型,稍后会用到:system、decision、convention和constraint。

规则1:在使用备注时显示其时效性

你无法避免JWT与会话机制之间的问题。无论设计如何,一条备注在周一可能是准确的,到三月就可能出错。唯一可行的是在有人准备依赖该备注的瞬间显示其时效,因为只有这时人们才能采取行动。

每条备注都会记录其被捕获时的仓库HEAD版本:

id: auth-service
type: system
title: Auth uses server sessions
scope: repo
confidence: observed
captured_sha: a1b2c3d      # repo HEAD at capture
repos: [orders-api]
edges:
  - rel: depends-on
    dst: postgres-primary

在检索时会转换为提交次数:

captured 47 commits ago — verify before trusting

无需任何模型、定时任务或后台扫描器来判断新鲜度。只需执行一条 git rev-list --count ..HEAD 命令即可完成,该方式具有确定性,且成本低廉,可直接内嵌使用。

有三个小细节的重要性甚至超过了核心理念。

被重写的历史记录会给出不同的结果。 当由于重新基址或清理操作导致无法再访问到某个提交时,显示零个提交会给人一种虚假的安心感。此时工具应显示“历史记录已被重写,请验证”而非其他内容。未知状态与新鲜状态属于不同的结果,必须保持区分。

注释仅在其声称所属的仓库中才会被标记。以无关历史记录为基准计算的提交次数不过是伪装成有效信号的噪音。那些限定在 orders-api 范围内的注释,即便在 billing-api 中被调用,也不会被标记为已被修改。

if (Array.isArray(node.repos) && node.repos.length &&
!node.repos.includes(here)) return null;

设有一个阈值。在10次提交之前,根本不会提及内容过时问题,因为持续触发的警告仅具装饰性,并非真正的警告。该阈值是可配置的。当提交次数达到100次时,另一个更高的阈值会被触发,从而执行doctor命令,列出需要重点审查的记录,这样你就可以主动查找,而无需逐一被告知。

规则2:内容屏蔽处理已完成

该商店的文本内容以明文形式存在于企业桌面电脑上,模型会根据可能包含各种信息的对话来生成其内容。因此,任何数据在写入磁盘之前都会经过扫描。共有十四种模式用于识别诸如 AWS 密钥、GitHub 和 Slack 令牌、私钥、JWT、承载令牌、数据库连接字符串、会话 Cookie、私有 IP 地址和内部主机名,以及电子邮件地址等信息,每次检测到此类内容时都会在写入前替换为 <redacted:kind>。

“失败即关闭”机制会执行特定的操作,其功能可在该函数的首几行中看到:

export function redact(text, opts = {}) {
  if (typeof text !== 'string') {
    throw new TypeError('redact() requires a string; refusing to write unscanned content');
  }

给它一些它无法扫描的内容,它就不会跳过扫描继续执行,而是会中止写入操作。删除处理必须确保“没有任何内容被写入”,绝不能出现“有内容漏过”的情况。这里也没有旁路标志,因为旁路标志这种东西最终只会在周五晚上下班前才用到。

其中的两个选项是值得坚持的。

连接字符串会整体替换。像 postgres://user:hunter2@db.internal:5432/orders 这样的 URI 会将凭证直接包含在内,因此是整个 URI 被替换,而不仅仅是其中的密码。经过部分删除处理的 URI 仍然会向读取者暴露主机地址、端口、数据库名称和用户名。

作业表单中的保密内容必须经过验证。对于 password: <something> 这种简单的规则,类似“密码更换周期为90天”这样的句子也会被误判,因此该规则要求必须使用引号,或者使用一段不带引号但长度足够的文本:

{
  kind: 'assigned-secret',
  re: /\b(?:api[_-]?key|secret|password|token|client[_-]?secret|
access[_-]?key)\b\s*[:=]\s*(?:"[^"\n]{6,}"|'[^'\n]{6,}'|[^\s"'`,;)]{12,})/gi,
}

那种会破坏普通文本结构的删改功能已被关闭,这样一来它就无法再起到任何保护作用。整个模块只有一个例外:你自己的 Git 身份信息依然保留,因为它早已存在于你推送的每一个提交记录中,而隐藏这些信息只会让笔记更难阅读。

规则 3:截断操作绝不会悄无声息

在连接良好的节点上发起深度为 2 的请求可能会返回五十条笔记,从而超出设计所保护的上下文窗口范围。因此设置了默认为 8 KB 的字节限制,一旦超出就会进行截断处理。这些都不足为奇。重要的是截断之后会发生什么:

3 nodes omitted for budget: legacy-batch-job, vendor-sftp-quirk,
old-retry-policy

Every omitted id gets printed, with no exceptions. This rule carries the most conviction, because silent truncation is the failure that looks like success. Given eight of eleven notes and no sign that three are missing, an agent assumes it sees everything and replies as confidently as that implies. The missing three are probably the ones it needed: they were dropped as peripheral to the query, and a surprising constraint often sits at the edge.

Pruning goes deepest-first, then least-connected:

.sort((a, b) => b.depth - a.depth || a.degree - b.degree || ...)

深度指的是与实际查询内容的偏离程度,数值较低说明该节点并非任何人所需的枢纽。通过ID断开最终关联会导致每次对同一查询都生成相同的字节序列,因此重新索引的确定性测试能够检验实际效果。

规则4:约束条件绝不可被舍弃

无论在何种限制下、何种层级中,均不得有例外。

const removable = nodes.filter((n) => n.depth > 0 && n.type !== 'constraint');

有两类内容不会被裁剪:你要求的根节点以及所有的约束条件。这一决策基于成本考量,而非个人偏好。约束条件可能包括客户不会批准新建数据库、服务无法接入公共互联网,或是平台团队已经否决了Kafka方案等。正是这些约束让开发人员不必在从一开始就注定失败的方法上浪费大量请求。为节省400字节而删减一个元素,其实是用低成本的字节损失换取了高成本的失败构建:字节成本很低,但行不通的方案代价却很高。

这种情况需要代码提前明确处理。如果根节点加上所有约束条件已经超出预算,就必须调整预算:

Note: 9,412 bytes returned, over the 8,192 budget, because constraints
are never dropped.

已有相关报告,但问题仍未解决,因为解决方式意味着要舍弃那些值得保留的内容。

该商店使用 Markdown 格式,索引可被丢弃

有一种架构设计能够满足全部四项规则:笔记为带有 YAML 前置数据的普通 Markdown 文件,而 index.db 则是可随时删除的缓存文件。

~/.agents/memory/
  notes/<type>/<id>.md     the source of truth
  notes/archive/           superseded and decayed notes; never deleted
  index.db                 disposable SQLite cache
  ROUTING.md               generated map of everything known

单个 index 命令会逐字节地从笔记中重新生成数据库。之所以需要数据库,是因为在 SQL 中遍历图结构速度很快,而遍历文件目录则很慢。该引擎采用带深度限制的递归 CTE,并使用 UNION 代替 UNION ALL,因此 contradicts 循环无法继续递归,直到 SQLite 退出为止。SQLite 上并不存在独立的图层结构,这项工作由 CTE 完成。

没有有价值的信息会仅保存在索引中。如果 SQLite 出现损坏,缓存也会随之丢失。即便移除该工具,仍会留下可读的 markdown 文件夹,即便未安装任何其他程序也能使用。知识应当比其索引更持久,而专有的二进制存储方式从第一天起就无法满足这一要求。

这正是它能够在受限环境中安装的原因,也是最初的设想。从 22.5 版本开始,Node 就在核心版本中内置了 node:sqlite,因此该索引无需任何包、服务或网络支持。在托管桌面环境中,提出使用 Node 脚本与提议创建新数据库会引发截然不同的讨论与结果。

刻意省略的内容

没有任何内容会自动被捕获:必须由你主动触发,或者由相应的处理机制来执行。这是有意设置的限制。那种在后台监控会话并自动决定保留哪些内容的功能虽然是大家所期望的,但也最容易让系统充斥大量无用的信息。随着低质量笔记的不断积累,上述的所有规则效力都会减弱。一周内十条优质的笔记远比模型自行生成的四百条笔记更有价值。

团队共享、多机器同步以及MCP服务器的功能也均被推迟。MCP服务器会读取同一个数据存储,因此属于功能扩展而非重写。

还有一个说法尚未得到验证。关键的测试是“冷读取”:在一个月未被修改的代码库中创建一个新的聊天记录,仅通过路由摘要就能正确回复。这需要真实的运行时间,无法在测试套件中模拟。在Node 22和24版本的Linux、macOS及Windows系统上,有71项测试通过,但没有任何一项能体现真正需要了解的情况。

值得借鉴的部分

任何正在为代理工作流添加内存功能的人,无论是自己开发的还是要发布的版本,都可以将这四条规则应用到其他项目中:

  1. 在知识被使用的位置之前标注其时效性,而非放在没人会查看的仪表板上。
  2. 让净化机制通过什么都不写的方式失败,且不要添加绕过标志。
  3. 把需要处理的事项全部列出来,因为若不显示截断信息,就会让人误以为已全部处理完毕。
  4. 在预算紧张之前解决那些绝不能搁置的问题,因为压力之下做出的决策只会更糟糕。

这些措施其实都不难实施。但人们很容易忽略它们,而且当它们起作用时又难以察觉,正因如此才值得记录下来。