Codex CLI 在 ~/.codex/memories/ 目录下提供了一个生成的、异步汇总的记忆存储。

这是一个第一方功能：

• 文档位于 developers.openai.com/codex
• 并且在 github.com/openai/codex 完全开源。
  在这篇 In Context 文章中，我们将逐步讲解 Codex CLI 中记忆是如何处理的。

Codex 是 OpenAI 的编码代理，它以三种形式发布：CLI、IDE 扩展，以及 ChatGPT 内的云工作区。

CLI 是文档最详尽的界面，其记忆内部实现也已开源，因此我们重点分析它。下面的大部分内容也会间接适用于 IDE 扩展，因为它共享相同的 ~/.codex/ 配置和记忆布局。

1、记忆架构

Codex 的记忆存在于一个目录中：~/.codex/memories/。该目录包含一组固定的 Markdown 文件。没有 SQLite，没有嵌入索引，也没有不透明的二进制 blob。

重要的文件包括：

• memory_summary.md：下一个会话首先读取的汇总视图
• MEMORY.md：长格式的合并记忆文件，按需进行 grep
• raw_memories.md：合并前的提取输出
• skills/<name>/SKILL.md：特定技能的记忆
• rollout_summaries/<slug>.md：每个会话的摘要，用于输入到合并流程
  

这就是整个记忆层。其余部分都是填充它的管道以及从中读取的路径。

2、记忆如何写入

写入路径分为两个阶段。

阶段 1 是每个 rollout（执行轮次）的。当一个会话空闲足够长时间（默认为六小时）后，Codex 会认领一个启动任务，使用严格 schema 的提取 prompt 对对话进行采样，对每个输出运行秘密红action（secret-redactor），并将结果存储在本地状态数据库中。此时还没有任何内容写入记忆目录。

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

两个阶段都使用可配置的模型（阶段 1 使用 extract_model，阶段 2 使用 consolidation_model），并且合并过程作为独立的子代理运行，而不是内联在用户的聊天中。

3、记忆如何加载

在会话开始时，Codex 完整读取 memory_summary.md，将其截断以适应固定的 5000 token 预算（这是 read-path crate 中定义的常量，未在公开文档中说明），然后将结果注入到开发者指令中。这个截断后的摘要就是代理预加载的全部内容。

对于不在摘要中的任何内容，代理会被指示直接 grep MEMORY.md。读取路径模板告诉代理：从摘要中提取关键词，在 MEMORY.md 中搜索，如果指向则打开相关的 rollout-summary 文件，如果没有匹配则停止。整个搜索预算保持在少量步骤内。

没有嵌入存储，没有相似性搜索，也没有 rerank 步骤。设计上就是纯文本和子字符串匹配。其代价是用可预测性和零检索时间成本，换取无法找到查询表述与存储表述不共享关键词的事实。

4、控制它的机制

少数配置旋钮控制了上面的一切。在依赖系统之前值得了解。

• 默认关闭。必须打开主特性开关 features.memories。开启后，两个子开关控制运行时：generate_memories（写入）和 use_memories（读取）。两者在特性启用后默认均为 true。
• 空闲阈值。min_rollout_idle_hours（默认 6）设置会话符合阶段 1 条件的最小空闲时间。活跃会话永远不会触发它。
• 合并上限。max_raw_memories_for_consolidation（默认 256，上限 4096）限制每次合并过程考虑的最近 rollout 数量。
• 老化处理。max_rollout_age_days（默认 30）停止考虑超过此天数的线程用于记忆生成。max_unused_days（默认 30）使在该窗口内未被召回的记忆在下一次合并中不合格。
• 速率限制感知。min_rate_limit_remaining_percent（默认 25）在用户 API 配额低时回退合并，以便后台工作不会饿死前台请求。
• 秘密红action。在任何记忆落盘前内置的凭证擦除功能。
• 地理限制。发布时，Memories 在 EEA、英国或瑞士不可用。这些地区的用户完全无法访问。

5、它在哪里停止

最简短的表述：这个记忆系统并不健壮。它是一个用户的 Markdown 文件，处于固定的 token 预算内，大多数失败模式都由此而来。

• 加载内容的硬 token 上限。每次会话开始时 memory_summary.md 都会被截断到 5000 token。超过上限的内容被静默丢弃。没有警告，没有日志。代理就是看不到它。
• 仅关键词回退。任何未进入摘要的内容必须能在 MEMORY.md 中通过字面子字符串匹配找到。改写后的事实不可见。“我们的部署命令是什么？”将无法找到“production deploys go through make ship-prod”，除非其中一个确切术语被存储。
• Grep 成本随文件增长。MEMORY.md 是线性搜索。对于长期用户，积累数月记忆后，每次 miss-then-grep 的成本都会更高。
• 仅生成状态，不可编辑。文档将 ~/.codex/memories/ 描述为 Codex 管理的。手动编辑记忆不是支持的路径。用户真正希望代理始终知道的内容应放入 AGENTS.md。
• 空闲门限的脆弱性。会话需要空闲六小时才能符合合并条件。连续进行编码冲刺的开发者可能永远无法触发它。
• 仅本地状态。~/.codex/memories/ 是每用户、每机器的文件系统状态。没有跨机器同步，没有团队共享，没有远程后备存储。
• 地理门限。发布时 Memories 在 EEA、英国和瑞士被屏蔽。

6、生产场景中触及这些限制的情况

结构限制在真实团队出现的具体案例中最为重要。

7、Mem0 如何适配

Mem0 是一个位于代理和持久化存储之间的记忆层。

针对 Codex 特别提供了一个 MCP 集成，文档位于 docs.mem0.ai/integrations/codex。

Codex CLI 原生支持 MCP 服务器。它们在 ~/.codex/config.toml 中的 [mcp_servers.<name>] 下配置（config-reference）。最小的 Mem0 设置是一个配置块：

[mcp_servers.mem0]
url = "https://mcp.mem0.ai/mcp"
bearer_token_env_var = "MEM0_API_KEY"

该单个配置块向 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 部署脚本会静默吞掉错误，建议对相同诊断使用 production-style 输出”）会在同一项目的下一个 Cursor Agent 运行中出现。用户无需在两个工具之间复制任何内容。
• 语义召回。Mem0 通过基于嵌入的搜索按含义检索。Codex 原生召回完整读取 memory_summary.md 并回退到 grep MEMORY.md：快速且可预测，但无法找到表述与查询不同的存储事实。使用 Mem0 后，询问“我们的部署命令是什么？”即使词语不重叠，也能找到“production deploys go through make ship-prod”。
• 每用户隔离。每个用户的 userId 划定其记忆范围。三名使用相同 Mem0 后端的队友保持独立的存储。
• 没有 5000 token 摘要上限。检索是对实际存储的排序语义搜索，而不是对单个摘要文件的整文件加载。大型记忆库保持可用，而不会被截断以适应开发者指令预算。
• 实时更新。Mem0 在对话发生时写入记忆，而不是在六小时空闲门限后。下个会话能看到上个会话教给它的内容。
• 在 Memories 不可用的地方可用。EEA、英国和瑞士的用户获得不依赖 Codex 区域发布的记忆层。
  Codex CLI 的记忆层在当今编码代理领域设计得非常精心：两阶段后台合并、秘密红action、基于 grep 的可预测 token 成本的读取路径，以及端到端开源的管道。

如果你今天正在运行 Codex CLI，并且其中任何差距看起来很熟悉，Mem0 集成只需大约一分钟 [docs.mem0.ai/integrations/codex]

---

原文链接：Codex CLI 记忆工作机制 - 汇智网