Codex CLI 中的记忆工作原理

Codex CLI 在 ~/.codex/memories/ 目录下提供了一个由异步汇总生成的记忆存储。这是一项第一方功能：

• 在 developers.openai.com/codex 有文档说明
• 并在 github.com/openai/codex 完全开源

在本期 In Context 文章中，我们将深入探讨 Codex CLI 如何处理记忆。Codex 是 OpenAI 的编程智能体，提供三种变体：CLI、IDE 扩展以及 ChatGPT 中的云端工作区。其中 CLI 是文档最丰富的界面，其记忆内部实现也已开源，因此我们将以此为例进行分析。下文中的大部分内容同样适用于 IDE 扩展，因为它们共享相同的 ~/.codex/ 配置和记忆布局。

记忆架构

Codex 的记忆存储在一个目录中：~/.codex/memories/。该目录包含一组固定的 markdown 文件。没有 SQLite，没有嵌入索引或混淆的二进制数据块。

重要的文件包括：

• memory_summary.md：下一个会话启动时首先读取的合并视图
• MEMORY.md：长格式的合并记忆文件，可按需进行 grep 搜索
• raw_memories.md：合并前的原始提取结果
• skills/SKILL.md：特定于技能的记忆
• rollout_summaries/*.md：每个会话的摘要，用于后续的合并过程

这就是整个记忆层。 其余部分只是填充记忆的流水线以及从中读取的读取路径。

记忆的写入方式

写入路径分为两个阶段。

阶段 1 是按 rollout 进行的。 当一个会话空闲时间足够长（默认六小时）后，Codex 会认领一个后台任务，对对话进行采样（使用严格模式的提取提示），然后将每个输出通过秘密内容审查器处理，并将结果存储在本地状态数据库中。此时，记忆文件尚未被修改。

阶段 2 是全局的。 它会获取一个全局锁（保存在状态数据库中），以确保不会有两次合并同时运行。然后加载最近的阶段 1 输出，将它们同步到磁盘，检查生成的工作区是否与现有内容不同，如果确实有差异，才启动一个独立的合并子智能体。该子智能体会读取候选内容，决定合并、修补或丢弃哪些内容，并将差异写回 ~/.codex/memories/。

两个阶段都使用可配置的模型（阶段 1 使用 extract_model，阶段 2 使用 consolidation_model），并且合并过程作为一个独立的子智能体运行，不与用户聊天内联执行。

记忆的加载方式

在会话启动时，Codex 会完整读取 memory_summary.md，将其截断以适配一个固定的 5,000 个 token 预算（该常量定义在读路径的 crate 中，未在公开文档中说明），然后将结果注入到开发者指令中。这个截断后的摘要就是智能体预先加载的全部内容。

对于摘要中没有包含的信息，智能体会被指示直接对 MEMORY.md 进行 grep 搜索。读取路径模板会指导智能体：从摘要中提取关键词，搜索 MEMORY.md，如果找到指向的摘要文件则打开，如果没有匹配则停止。整个搜索预算控制在少量步骤内。

没有嵌入存储，没有相似性搜索，没有重排序步骤。它只是纯文本和子串匹配——这是有意为之的设计。这种权衡保证了可预测性和零检索时间成本，但代价是无法找到查询语句与存储表述不共享关键词的事实。

控制记忆的机制

上面的所有行为都由少数几个配置旋钮控制。在依赖该系统之前，有必要了解这些配置。

• 默认关闭。 必须启用主开关 features.memories。开启后，两个子开关控制运行时：generate_memories（写入）和 use_memories（读取）。在启用该功能后，两者默认都为 true。
• 空闲阈值。 min_rollout_idle_hours（默认 6）设定了会话在进入阶段 1 之前所需的最小空闲时间。活动中的会话永远不会触发该流程。
• 合并上限。 max_raw_memories_for_consolidation（默认 256，上限 4,096）限制了每次合并过程考虑的最近 rollout 数量。
• 老化。 max_rollout_age_days（默认 30）超过了这个时间的线程将不再被考虑用于记忆生成。max_unused_days（默认 30）使得在该窗口内未被召回的记忆在下次合并过程中变得不可用。
• 限速感知。 min_rate_limit_remaining_percent（默认 25）当用户的 API 配额较低时，会推迟合并过程，以确保后台工作不会抢占前台请求。
• 秘密内容审查。 内置的内容擦除功能，在任何记忆写入磁盘之前会删除凭证。
• 地理限制。 在发布时，记忆功能在欧洲经济区（EEA）、英国和瑞士不可用。这些地区的用户根本无权访问。

局限性在哪里

最简单地说：这套记忆系统并不健壮。它只是单个用户的 markdown 文件，受限于固定的 token 预算，并且大多数失败模式都源于此。

• 加载时的硬 token 上限。 memory_summary.md 在每次会话启动时会被截断到 5,000 个 token。超过上限的内容会被静默丢弃。没有警告，没有日志。智能体根本看不到这些内容。
• 仅依赖关键词的回退搜索。 任何未包含在摘要中的内容，都必须通过在 MEMORY.md 中进行字面子串匹配才能找到。复述的事实是不可见的。例如，“我们的部署命令是什么？”将无法找到“生产部署通过 make ship-prod 进行”，除非这些确切术语被存储。
• grep 成本随文件增大而增加。 MEMORY.md 是线性搜索的。对于长期使用积累了数月记忆的用户，每次未命中后的 grep 代价会越来越高。
• 仅限生成状态，不可编辑。 文档将 ~/.codex/memories/ 定义为由 Codex 管理。手动编辑记忆并不是支持的路径。用户真正希望智能体始终知道的内容应放在 AGENTS.md 中。
• 空闲门控脆弱。 会话需要空闲六小时才能进入合并阶段。如果开发者连续进行高强度的编码工作，可能永远无法触发该过程。
• 本地状态限制。 ~/.codex/memories/ 是每用户、每台机器的文件系统状态。没有跨机器同步，没有团队共享，没有远程存储后端。
• 地理限制。 发布时，记忆功能在欧洲经济区、英国和瑞士被屏蔽。

触及这些限制的生产场景

结构性限制在真实团队中遇到的具体情况下最为关键。

Mem0 如何补充

Mem0 是一个位于智能体和持久存储之间的记忆层。对于 Codex，有一个 MCP 集成，文档位于 docs.mem0.ai/integrations/codex。Codex CLI 原生支持 MCP 服务器。它们可以在 ~/.codex/config.toml 的 [mcp_servers.] 部分进行配置（配置参考）。最简单的 Mem0 设置只需一个代码块：

[mcp_servers.mem0]
type = "stdio"
command = "mem0-mcp"

这个简单的代码块为 Codex 暴露了九个 MCP 工具：add_memory、search_memories、get_memories、get_memory、update_memory、delete_memory、delete_all_memories、delete_entities、list_entities。Codex 的智能体会像处理任何其他 MCP 工具表面一样处理这些工具。

底层的变化包括：

• 持久化、跨机器的记忆。 本地 ~/.codex/memories/ 的上限消失。同一个 Mem0 存储可以跟随用户跨越笔记本电脑、服务器和 CI 环境。在新机器上无需从头重新生成。
• 跨工具的记忆。 一个用户在终端中使用 Codex CLI，在编辑器中同时使用 Cursor，可以指向同一个 Mem0 后端。在 Codex CLI 会话中捕获的事实（例如，“staging 部署脚本会静默吞掉错误，对于相同的诊断，倾向于使用生产风格的输出”）会在下一次 Cursor Agent 对同一项目运行时浮现出来。用户无需在两个工具之间复制任何内容。
• 语义召回。 Mem0 通过基于嵌入的搜索按意义进行检索。Codex 的原生召回是完整读取 memory_summary.md 并在必要时对 MEMORY.md 进行 grep：快速且可预测，但无法找到措辞与查询不同的存储事实。使用 Mem0 后，询问“我们的部署命令是什么？”可以找到“生产部署通过 make ship-prod 进行”，即使词语不重叠。
• 每用户隔离。 每个用户的 userId 限定了其记忆范围。三位团队成员使用同一个 Mem0 后端，但各自拥有独立的存储。
• 没有 5,000 token 摘要上限。 检索是对实际存储进行排名的语义搜索，而不是一次性加载整个摘要文件。即使记忆基数很大，也能保持可用，而不会被截断以适应开发者指令的预算。
• 实时更新。 Mem0 在对话进行时写入记忆，而不是依赖于六小时的空闲门控。下一个会话会立即看到上一个会话教给它的内容。
• 在记忆功能不可用的地区也能使用。 欧洲经济区、英国和瑞士的用户可以获得一个不依赖 Codex 区域部署的记忆层。

Codex CLI 的记忆层在当下的智能体编程领域经过精心设计：两阶段后台合并、秘密内容审查、基于 grep 且 token 成本可预测的读取路径，以及端到端开源的流水线。如果你现在正在使用 Codex CLI，并且对上述任何一个限制感到似曾相识，那么 Mem0 集成只需要大约一分钟 [docs.mem0.ai/integrations/codex]

In Context #9

这篇博文属于 In Context 系列，是 @mem0ai 关于 AI 智能体记忆和上下文工程的博客系列。@mem0ai 是一个智能、开源的内存层，专为 LLM 和 AI 智能体设计，提供跨会话的长期、个性化且上下文感知的交互。

• 在这里获取免费 API 密钥：app.mem0.ai
• 或者从我们的开源 GitHub 仓库自行托管 mem0。