从记住到可运行：Coding Agent 记忆系统正在变成运行时可靠性问题

来源说明

本文基于 2026-05-13 的每日研究发布流程写成。今天没有发现一篇 2026-05-13 当天发布、足以单独支撑原创研究文章的新论文；但工程侧出现了一个足够清晰的新材料簇：OpenAI Agents SDK 的 sandbox memory 文档把 agent memory 定义为 sandbox workspace 中可保留、可隔离、可渐进读取的文件化产物；AgentMemory 在 2026-05-09 到 2026-05-12 的连续 changelog 则暴露出真实运行时故障，包括 saved memory 召回为空、MCP shim 工具面不完整、hook 阻塞启动、Docker volume 权限导致状态假持久化、反向代理下 viewer 空面板、以及上下文预算选择被 oversized block 饿死。

这些材料共同支撑一个比“记忆能不能召回”更具体的技术问题：coding agent 的长期记忆正在从算法组件变成运行时可靠性层。它既要服务下一次任务的上下文复用，也要承受文件系统、沙盒生命周期、MCP 客户端、Docker、反向代理、token budget、权限隔离和可观测性的工程压力。

稳定 slug：2026-05-13-agent-memory-runtime-reliability。

参考来源：

• OpenAI Agents SDK: Agent memory
• OpenAI: The next evolution of the Agents SDK
• GitHub: rohitg00/agentmemory changelog
• AgentMemory: Persistent memory for AI coding agents
• Agenr: Local-first memory for AI agents
• Engram: Persistent cognitive memory for AI agents

先给结论

AI 记忆系统的叙事正在变窄，也变得更工程化。过去几周的主线是 benchmark 分数、安全边界和数据库原生 memory；今天更值得关注的是另一个层面：coding agent memory 必须像运行时系统一样被设计、部署和调试。

OpenAI Agents SDK 的 sandbox memory 文档有一个重要信号：它没有把 memory 描述成一个神秘的向量库能力，而是把先前运行中的经验提炼成 sandbox workspace 里的文件。读取时先注入小摘要，再按需搜索 MEMORY.md 和 rollout summaries；生成时分成 conversation extraction 和 layout consolidation 两阶段；隔离时不是按 agent 名称，而是按 memory layout 分离目录。

AgentMemory 的近期修复则说明，真正困难的地方经常不在“有没有 embedding”。一个 saved memory 已经写入 KV，但检索 enrichment 仍去 observation 表查，就会出现索引命中但结果为空；Docker volume owner 错了，API 仍可能返回 success，但重启后状态消失；一个 oversized pinned context block 让 budget loop break，就会把后面本来放得下的小块全部饿死。

我的判断是：下一阶段 agent memory 的质量差异不会只体现在 LoCoMo、LongMemEval 或 R@5 上，而会体现在四个运行时问题上：

• 记忆是否有可审计的物理形态。
• 读取是否遵守渐进披露和作用域隔离。
• 写入、压缩、遗忘是否能在失败时被复盘。
• 部署、客户端和上下文预算是否会让“已经记住”的东西在运行时消失。

换句话说，memory 不只是 save() 和 search()。它正在成为 coding agent 的状态管理层。

技术问题：为什么 coding agent memory 比聊天记忆更难

聊天助手的长期记忆通常围绕用户偏好、个人事实、历史对话和个性化回答展开。coding agent 的记忆更麻烦，因为它记住的不只是人说过什么，还包括工作区状态、工具输出、失败尝试、测试命令、部署环境、项目约定、子 agent 分工和历史修复路径。

这会带来五个差异。

第一，记忆和文件系统纠缠。coding agent 的有效经验往往来自真实文件、命令结果和构建日志。如果 memory 只存在云端用户画像里，它很难可靠地指向当前仓库证据；如果 memory 存在 workspace 里，它又必须跟随 sandbox 快照、目录布局和持久化策略。

第二，记忆和工具权限纠缠。读取 memory 可能需要 shell 搜索文件，更新 memory 可能需要 filesystem 写入。OpenAI 文档里 memory() 在启用读取时要求 shell()，live update 默认开启时还要求 filesystem()，这不是偶然实现细节，而是说明 memory 已经进入 agent 的工具权限模型。

第三，记忆和运行时生命周期纠缠。一个多轮任务到底应该被合并成一段 memory conversation，还是拆成多个 run？OpenAI 文档用 conversation id、SDK session id、group id 和 per-run id 的优先级来回答这个问题。这个设计背后的工程事实是：没有稳定身份，后处理就不知道哪些执行属于同一段经验。

第四，记忆和上下文预算纠缠。coding agent 的上下文通常已经很拥挤：系统指令、仓库规则、当前文件、diff、测试输出、工具结果、用户请求都会抢预算。长期记忆如果以错误顺序或错误大小注入，可能不是帮助，而是直接挤掉当前任务证据。

第五，记忆和部署形态纠缠。AgentMemory 0.9.10 的 Docker volume 权限修复很典型：状态写入失败时如果 API 仍返回 success，系统表面上“记住了”，实际只是 RAM 中短暂存在。对用户而言，这比没有 memory 更糟，因为它制造了可靠性的错觉。

所以，coding agent memory 的核心问题不是“怎么让模型记得更多”。更准确的问题是：如何让跨 run 的经验成为一个有边界、有证据、有生命周期、有故障可见性的运行时状态。

机制拆解：两条路线正在收敛

1. 文件化 memory：把长期状态放回 workspace

OpenAI Agents SDK 的 sandbox memory 方案值得注意，因为它把 memory artifacts 放在 sandbox workspace 的 memories/ 目录下，默认布局包括 memory_summary.md、MEMORY.md、raw_memories.md、raw_memories/ 和 rollout_summaries/。

这种设计不是最炫的 memory 架构，但它很适合 coding agent。原因有三点。

第一，文件是 agent 和人都能检查的状态。一个长期记忆如果只是数据库记录或 embedding 向量，开发者很难在失败时快速判断它到底写了什么。Markdown 索引、原始 memory extract 和 rollout summary 至少给了审计入口。

第二，文件天然跟 sandbox 生命周期绑定。OpenAI 文档说，复用 memory 需要保留整个 memories directory，可以通过同一个 live sandbox session、持久化 session state 或 snapshot 实现；一个全新的空 sandbox 则从空 memory 开始。这把“记忆是否存在”变成了可部署条件，而不是隐藏的全局服务。

第三，文件适合渐进披露。文档中的读取路径不是把所有历史经验塞进 prompt，而是先注入小摘要；当当前任务看起来相关时，再搜索 MEMORY.md，最后只在需要时打开对应 rollout summaries。这是一个重要工程原则：memory 的默认形态应该是索引和摘要，不是完整历史回放。

这条路线的代价也很明显。文件化 memory 并不自动解决冲突、过期、权限和删除。它只是把问题变得可见。系统仍然需要定义哪些 raw memories 能进入 MEMORY.md，哪些用户输入或工具输出属于敏感数据，哪些旧经验在当前仓库版本下已经失效。

2. Runtime memory：把捕获、召回、压缩和观测做成服务面

AgentMemory 走的是另一条更完整 runtime 的路线。它把自己定义为 complete memory runtime，不只是 library 或 vector store；站点描述了 hooks、BM25/vector/graph 三路召回、自动 consolidation、REST/MCP 双入口、viewer、OpenTelemetry traces、session replay 和跨工具集成。

这类系统的价值在于覆盖 coding agent 的真实接入点。每个 PreToolUse、PostToolUse、SessionStart、Stop 都可能成为 memory signal；MCP 客户端需要看到完整工具面；viewer 要能看到 session、memory、graph、health；observability 要能告诉开发者一次 memory 操作的延迟和失败路径。

但最近 changelog 暴露出的故障也说明，runtime memory 的可靠性要求比普通库高得多。

AgentMemory 0.9.5 修复了 memory_save 写入后 BM25 没有索引的问题。更微妙的是，0.9.6 又修复了 search recall 的 result enrichment 路径：搜索已经能排到 saved memories，但 enrichment 仍去 observation 存储里找，导致客户端看到空结果。这个故障很有代表性：memory 系统可以在不同层都“部分正确”，最终行为仍然错误。

0.9.6 还修复了 standalone MCP shim 只暴露少量工具的问题。对 memory runtime 来说，MCP 工具面就是产品 API。如果 Claude Code 以外的客户端只能看到 4 到 7 个工具，而服务端实际上支持 51 个工具，那么同一个 memory store 在不同 agent 里的能力边界就不一致。长期看，这会让用户误以为是模型忘了，实际是客户端没有拿到工具。

hook 延迟修复也很关键。session-start 和 subagent-start 如果等待一个慢或不可达的 REST server，会把每次 agent 启动拖慢几秒，在多 agent fan-out 下甚至可能形成资源压力。记忆捕获不应该阻塞 agent 启动路径，除非当前任务明确需要同步注入上下文。

0.9.10 的三个修复更像生产故障复盘：Docker volume owner 导致状态重启后消失；viewer 在 80/443 反向代理下硬编码端口导致空面板；context budget loop 遇到第一个 oversized block 就 break，使后续小块无法进入上下文。这些都不是 memory algorithm 论文里常见的问题，但它们决定了系统在真实部署里是否可信。

工程判断：memory layer 要有四个可靠性边界

1. 持久化边界：写入成功必须可证明

一个 memory 系统最危险的失败不是报错，而是假成功。Docker volume 权限错误导致状态只留在 RAM，API 仍报告 success，这类故障会破坏用户对长期记忆的基本信任。

生产系统应该把写入成功拆成至少三层：

• logical write：memory item 通过 schema 校验并进入写入队列。
• durable write：底层文件、数据库、KV 或对象存储确认持久化。
• searchable write：索引、摘要、图谱或缓存能够在读路径看到它。

只有第一层成功不能叫“记住了”。至少要在 trace 或 health check 中暴露 durable lag 和 index lag。对 coding agent 来说，还应该允许 agent 或用户运行一个轻量验证：刚保存的 memory 是否能按关键词、ID 或来源 session 被召回。

2. 读取边界：默认摘要，按需展开

OpenAI 的 progressive disclosure 是正确方向。长期记忆不能默认全量注入，否则它会和当前任务证据竞争，还会放大过期和越权风险。

一个更完整的读取策略应该分四层：

• summary：少量高置信、通用、近期验证过的规则或偏好。
• index：可搜索的 memory map，包含标题、来源、时间、作用域和标签。
• evidence：对应 rollout summary、工具输出摘要或文件引用。
• raw trace：必要时才打开的原始 session、命令输出或消息片段。

这套分层的关键不是节省 token，而是保留控制权。agent 应该先知道“可能有相关记忆”，再决定是否展开证据；用户或开发者也应该能看到是哪一层 memory 影响了输出。

3. 隔离边界：按 layout 和作用域，而不是按 agent 名称

OpenAI 文档强调 memory isolation 基于 MemoryLayoutConfig，不是 agent name。这个细节很重要。agent 名称只是调用方身份，不能等价于数据边界。

同一个 sandbox 里可能有工程 agent、财务 agent、安全审计 agent 和文档 agent。如果它们共享 layout，就可能共享 rollout files、raw memories、MEMORY.md 和 memory_summary.md。如果它们不应该共享，就必须有不同 memories directory 和 sessions directory。

生产系统里还要再加几层作用域：

• user scope：个人偏好、沟通习惯、长期目标。
• project scope：仓库约定、设计决策、客户限制。
• task scope：当前修复、失败尝试、临时选择。
• agent scope：某个 agent 自己的工具经验和 prompt 习惯。
• audit scope：只用于复盘，不默认进入 prompt 的运行日志。

如果作用域只靠 prompt 文字约束，而存储、索引和目录没有隔离，迟早会发生串线。

4. 预算边界：memory selection 是调度问题

AgentMemory 0.9.10 的 mem::context 修复说明，context budget 不是简单 top-k。一个 oversized pinned block 如果让选择循环直接停止，后续更小、更相关的 blocks 就完全没有机会进入上下文。

这类问题在长期记忆里很常见。系统可能按 recency、importance、pin、semantic score 或 graph distance 排序，但真正注入时还要满足 token budget。只排序不装箱，会出现三种失败：

• 大块记忆垄断预算。
• 高优先级但低相关记忆挤掉当前证据。
• 某条记忆被 pin 后长期污染上下文。

更稳的策略是把 memory selection 当作 constrained scheduling：先按作用域过滤，再按任务意图分组，再在每组内做 token-aware packing。oversized block 应该被压缩、跳过或拆分，而不是让整个选择流程停掉。

适用场景

这种运行时视角最适合三类 agent。

第一类是 coding agent。它们需要跨 session 记住仓库结构、测试命令、失败补丁、用户偏好和部署状态，但每次任务又必须以当前文件和当前指令为准。文件化 memory、session replay、MCP 工具面和预算调度都直接影响任务成功率。

第二类是研究和数据分析 agent。它们经常跨多天阅读论文、清洗数据、运行 notebook、积累假设和修正口径。这里的 memory 需要保存证据链，而不是只保存结论。rollout summaries 和 raw memory extracts 比纯向量库更容易审计。

第三类是企业工作流 agent。销售、客服、财务、合规和运维任务都有强作用域和权限边界。memory 的关键指标不是“个性化更自然”，而是是否能证明某条客户事实、审批状态或故障经验只在正确范围内影响输出。

不适合的场景也要说清楚。如果 agent 只是一次性问答、短会话工具调用或高敏感数据处理且没有保留策略，那么长期 memory 可能只是新风险。先做好明确的 session state、日志脱敏和删除机制，再考虑跨 run 学习。

失败模式

第一，索引和存储不同步。memory item 已经写入 durable store，但 BM25、向量、图谱或 enrichment 路径没有覆盖它。用户看到的是“明明保存了却搜不到”。AgentMemory 0.9.5 和 0.9.6 的连续修复就是这个类别。

第二，假持久化。API 返回 success，但底层存储权限、volume、快照或目录配置有问题，重启后状态消失。这类错误必须通过持久化探针和重启后验证发现，不能只靠写入接口返回值。

第三，客户端工具面不一致。一个 MCP shim、IDE 插件或子 agent 只暴露部分 memory tools，导致某些客户端能写不能查、能查不能治理。用户会把它感知成模型能力差异，但实际是协议面不完整。

第四，记忆捕获阻塞关键路径。hook 为了记录 session start 或 tool output 等待远端 memory server，agent 启动被拖慢，多 agent 并发下放大成系统压力。记忆写入应尽量异步，只有当前输出依赖 memory 注入时才同步等待。

第五，作用域泄漏。工程项目的经验进入财务 agent，临时任务偏好进入用户全局记忆，审计日志被当作生成上下文。解决办法必须落到 layout、目录、索引和权限，而不能只写在 prompt 里。

第六，上下文预算饥饿。长 memory、pinned memory 或过宽 summary 抢占 token，导致当前文件、错误日志或用户最新指令被挤掉。长期 memory 如果降低当前任务证据密度，就是负收益。

第七，遗忘机制只按 recency。OpenAI 文档里的 raw memory consolidation 上限会保留较新的 raw memories，这是一种必要的 bounded policy，但生产系统不能只靠新旧。被证伪、越权、低价值、高成本或重复的 memory 都应该有不同的降权和删除路径。

可验证指标

如果要评估一套 coding agent memory runtime，我会从下面这些指标开始，而不是只看 R@5。

• Durable write verification：保存后经过进程重启或 sandbox 恢复，memory 仍可通过 ID 和关键词读取的比例。
• Searchability lag：logical write 到可被 BM25/vector/graph/search API 召回之间的延迟。
• Recall-enrichment consistency：搜索命中 ID 后，enrichment 阶段成功返回可用内容的比例。
• Layout isolation leakage：不同 memory layout、项目、agent 或用户之间错误互相影响的比例。
• Context packing efficiency：给定 token budget 下，注入 memory 的有效证据 token 占比，以及 oversized block 被正确跳过或压缩的比例。
• Current evidence retention：开启 memory 后，当前任务关键文件、错误输出和用户最新指令是否仍进入上下文。
• Hook overhead p95/p99：memory hooks 对 session start、tool call、subagent start 的额外延迟。
• Restart survival rate：Docker、sandbox snapshot、local process crash 或 remote runtime 迁移后，memory store 和索引仍一致的比例。
• Stale memory correction rate：agent 发现旧 memory 与当前环境冲突时，能否更新、降权或标记失效。
• User-visible audit coverage：受 memory 影响的输出中，能追溯到具体 memory、来源 run 和证据摘要的比例。

这些指标可以和 LongMemEval、LoCoMo、AMA-Bench 并行使用。公共 benchmark 仍然有用，但它们不能替代运行时可靠性测试。

和前几篇文章的区别

本站前面已经分析过几个相邻主题：记忆作用域合约、数据库原生 agent memory、agent memory 安全边界、benchmark hygiene、MemAgents bottleneck diagnostics。本文不重复这些主题。

它的重点更低一层：memory 作为 coding agent runtime 时，哪些非算法问题会让记忆失效。OpenAI 的 sandbox memory 文档给出一种文件化、渐进披露、layout 隔离的官方工程形态；AgentMemory changelog 提供了真实运行时故障样本；Agenr 和 Engram 代表本地优先、typed memory、decay、confidence、REST/MCP 这类 runtime 化趋势。

因此本文的核心判断不是“哪种 memory 架构最好”，而是：任何长期 agent memory 一旦进入 coding 工作流，就必须接受运行时系统的标准。写入要可证明，读取要可分层，隔离要落到目录和 layout，预算要可调度，失败要可观测。

局限

本文主要基于公开文档、官网和 changelog，而不是复现实验。AgentMemory 的 benchmark 数字和性能指标来自项目自述，本文只把它们作为产品声明，不作为独立验证结论。Agenr 和 Engram 的材料也主要是官网层面的能力说明，没有在本文中做源码级验证。

另一个限制是，OpenAI Agents SDK sandbox memory 仍处于 beta。API、默认行为和能力边界可能变化，不能把今天的文档当作长期稳定标准。更稳妥的做法是抽取其中的工程原则：文件化 artifacts、渐进披露、layout 隔离、显式 retention policy 和当前环境优先。

最后，运行时可靠性不能替代语义质量。一个 memory store 即使持久化、隔离和观测都做对，仍可能写入错误摘要、过度泛化用户偏好、召回低价值经验或在冲突时选择错误版本。可靠运行只是基础，记忆质量仍然需要独立评测。

发布前自审

• 事实可靠性：核心事实来自 OpenAI 官方文档、OpenAI 官方 blog、AgentMemory GitHub changelog 和项目官网；第三方项目声明已标注为项目自述或能力说明。
• 来源完整性：来源覆盖官方 SDK 文档、运行时项目 changelog、项目能力页和本地优先 memory runtime 线索。
• 原创性：文章主线是“coding agent memory 作为运行时可靠性层”，重点分析持久化、渐进披露、layout 隔离、上下文预算和 hook 延迟，不复述文档或 README。
• 标题党检查：标题没有宣称突破或最佳实践，只指出记忆系统工程重心变化。
• 薄内容检查：包含技术问题、机制拆解、工程判断、适用场景、失败模式、可验证指标和局限。
• 猜测边界：对 AgentMemory benchmark、Agenr、Engram 只作为公开声明处理；对 OpenAI sandbox memory 明确说明 beta 状态。
• 站内重复：区别于 2026-05-12 benchmark hygiene、2026-05-10 security boundary、2026-05-09 database-native memory 和 2026-05-02 scope contract；本文聚焦运行时可靠性。