> ## Content Index > Fetch the complete content index at: https://www.hubwiz.com/blog/llms.txt > Use this file to discover other available public pages before exploring further. # Codex CLI 记忆工作机制 - URL: https://www.hubwiz.com/blog/how-memory-works-in-codex-cli/ - Published: 2026-05-14T14:22:39.000Z - Updated: 2026-10-13T14:45:20.000Z - Description: Codex 的记忆存在于一个目录中：~/.codex/memories/。该目录包含一组固定的 Markdown 文件。没有 SQLite，没有嵌入索引，也没有不透明的二进制 blob。 - Author: admin - Tags: AGENT, OPENAI CODEX, #Import 2026-10-14 14:41 Codex CLI 在 `~/.codex/memories/` 目录下提供了一个生成的、异步汇总的记忆存储。 这是一个第一方功能： - 文档位于 [developers.openai.com/codex](https://developers.openai.com/codex?ref=hubwiz.com) - 并且在[ github.com/openai/codex](https://github.com/openai/codex?ref=hubwiz.com) 完全开源。 在这篇 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//SKILL.md`：特定技能的记忆 - `rollout_summaries/.md`：每个会话的摘要，用于输入到合并流程 ![](https://www.hubwiz.com/blog/content/images/2026/05/image-203.png) 这就是整个记忆层。其余部分都是填充它的管道以及从中读取的路径。 ## 2、记忆如何写入 写入路径分为两个阶段。 阶段 1 是每个 rollout（执行轮次）的。当一个会话空闲足够长时间（默认为六小时）后，Codex 会认领一个启动任务，使用严格 schema 的提取 prompt 对对话进行采样，对每个输出运行秘密红action（secret-redactor），并将结果存储在本地状态数据库中。此时还没有任何内容写入记忆目录。 阶段 2 是全局的。它会获取一个全局锁（保存在状态数据库中），以确保两个合并流程不会并行运行。它加载最近的阶段 1 输出，将它们同步到磁盘，检查生成的工作区是否与现有内容实际不同，然后才会生成一个单独的合并子代理。该子代理读取候选内容，决定哪些合并、哪些修补、哪些丢弃，并将 diff 写回 `~/.codex/memories/`。 ![](https://www.hubwiz.com/blog/content/images/2026/05/image-204.png) 两个阶段都使用可配置的模型（阶段 1 使用 `extract_model`，阶段 2 使用 `consolidation_model`），并且合并过程作为独立的子代理运行，而不是内联在用户的聊天中。 ## 3、记忆如何加载 在会话开始时，Codex 完整读取 `memory_summary.md`，将其截断以适应固定的 5000 token 预算（这是 read-path crate 中定义的常量，未在公开文档中说明），然后将结果注入到开发者指令中。这个截断后的摘要就是代理预加载的全部内容。 对于不在摘要中的任何内容，代理会被指示直接 grep `MEMORY.md`。读取路径模板告诉代理：从摘要中提取关键词，在 `MEMORY.md` 中搜索，如果指向则打开相关的 rollout-summary 文件，如果没有匹配则停止。整个搜索预算保持在少量步骤内。 ![](https://www.hubwiz.com/blog/content/images/2026/05/image-205.png) 没有嵌入存储，没有相似性搜索，也没有 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、生产场景中触及这些限制的情况 结构限制在真实团队出现的具体案例中最为重要。 ![](https://www.hubwiz.com/blog/content/images/2026/05/image-206.png) ## 7、Mem0 如何适配 Mem0 是一个位于代理和持久化存储之间的记忆层。 针对 Codex 特别提供了一个 MCP 集成，文档位于 [docs.mem0.ai/integrations/codex](https://docs.mem0.ai/integrations/codex?ref=hubwiz.com)。 Codex CLI 原生支持 MCP 服务器。它们在 `~/.codex/config.toml` 中的 `[mcp_servers.]` 下配置（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 工具相同的方式拾取它们。 ![](https://www.hubwiz.com/blog/content/images/2026/05/image-207.png) 底层发生的变化： - 持久化、跨机器记忆。本地 `~/.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\] --- 原文链接：[How Memory Works in Codex CLI](https://x.com/mem0ai/status/2054580022049198513?ref=hubwiz.com) 汇智网翻译整理，转载请标明出处 > **这是「Agent / MCP」专题的一部分。**完整地图见：[Agent / MCP / 自动化完全指南](https://www.hubwiz.com/blog/agent-stack/)