learnNote

主题

深度解析 Codex 的 Memory 策略与演进路径 ​

关注对象：OpenAI Codex（含 Codex CLI、Codex IDE 扩展、Codex Cloud Agent 三种形态）。 时间窗口：自 2025 年 4 月 Codex CLI 首次开源 → 2026 年 Q1 当前可获取的公开信息。 凡涉及未公开实现细节，统一以 [推测] 或 [未公开] 标注，不编造 API 名称或版本号。

1. 概览：什么是 Codex 的 Memory ​

一句话定义：Codex 的 Memory 是一组显式、文本化、分层加载的"指令与事实集合"，它在每次对话开始前被拼接进系统提示中，用来跨任务、跨会话、跨设备地稳定 Agent 行为，而不是模型权重之外的"持久知识库"。

1.1 与相邻概念的边界 ​

概念是否属于 Codex Memory说明
Context Window否（是承载 Memory 的容器）模型一次推理能看到的 token 总量。Memory 必须挤进它，但不是它本身。
Session State部分属于当前对话的消息历史、TodoWrite、工具结果属于"临时记忆"，会话结束后默认丢弃。
RAG / 向量检索否（Codex 当前未默认内置）Codex 走"全文注入 + 工具按需读文件"路线，而非语义检索。[推测] 长期可能引入。
Persistent Memory（如 ChatGPT 的 Memory）不直接复用ChatGPT 的用户级记忆是托管在云端的结构化键值；Codex 走的是本地纯文本 + Git 友好路线。
Fine-tuning / 模型权重否Memory 永远是"上下文层面"的，不修改模型本体。

1.2 分层架构（Mermaid） ​

核心信号：所有持久 Memory 最终都走"文本拼接进 System Prompt"这一条窄路；会话级状态则在用户消息流里循环；Cloud Agent 只是把"加载磁盘文件"换成了"加载云端仓库快照"。

2. 当前 Memory 体系的完整拆解 ​

下表给出 Codex 当前公开可见的 6 类 Memory；后续逐项展开。

维度载体作用域写入方加载时机
项目级<repo>/AGENTS.md单仓库人 / Agent 提交会话启动 + cwd 切换时
用户级~/.codex/AGENTS.md全用户、所有项目人手工会话启动
子目录级<sub>/AGENTS.md子树内人 / Agent进入子目录上下文时（合并）
配置级~/.codex/config.toml全局人 / codex 子命令进程启动
会话级内存消息流 + ~/.codex/sessions/*.jsonl [推测路径]单次会话模型 / 工具推理每一轮
Prompt 片段<repo>/.codex/prompts/*.md项目人/<name> 调用时

2.1 项目级记忆：AGENTS.md ​

  • 作用：告诉 Codex "这个仓库怎么跑、怎么测、有什么禁忌、风格是什么"。它是项目知识的契约文件，等价于给 Agent 看的 README。
  • 存储位置：仓库根目录 AGENTS.md，与 Git 同源，可被 Code Review。
  • 生命周期：与文件本身同寿；删除即失忆。
  • 加载时机：Codex 进程启动且 cwd 解析到该 repo 时，一次性读入并放入系统提示。
  • 写入方式：① 人手写 ② Agent 在征得用户同意后用文件编辑工具追加 ③ codex init（或等价子命令）生成模板 [部分版本支持]。
  • 典型示例：构建命令、单测命令、目录约定、严禁修改的文件、PR 标题格式、提交信息模板。

Why this design：OpenAI 在推出 AGENTS.md 时就明确把它定位为跨 Agent 的"通用约定"——不只是 Codex 用，Cursor、Aider、Claude Code 等都被鼓励读同一份文件（事实上 Claude Code 也支持 AGENTS.md 兼容）。这降低了多 Agent 共存时的"记忆方言"成本。

2.2 用户级记忆：~/.codex/AGENTS.md ​

  • 作用：跨项目的"我个人的偏好"——例如"回答用中文"、"始终用 pnpm 而不是 npm"、"提交信息禁止 emoji"。
  • 生命周期：与本机用户账号同寿。
  • 加载时机：每次启动 Codex 都会优先读取，位置上排在项目级之前。
  • 写入方式：手工编辑为主；/memory 之类的交互命令在不同版本里行为有差异 [部分版本支持]。
  • 冲突解决：当用户级与项目级冲突，项目级覆盖（more-specific-wins，详见 §2.3 合并规则）。

2.3 子目录 / 模块级记忆 ​

  • 作用：在 monorepo / 多语言子工程中，让"前端目录"与"后端目录"各持有不同的指令（例如不同的 lint 规则、不同的禁止词）。
  • 合并规则[推测但与社区观察一致]：
    1. 自顶向下扫描从 cwd 到 repo root 的所有 AGENTS.md；
    2. 不是"子级覆盖父级"，而是"父级先注入、子级后追加"——即子级被视为对父级的"补充与覆写"，但父级内容仍出现在 prompt 中；
    3. 用户级永远在最外层。
  • 取舍：好处是"局部知识不污染全局"；代价是 Token 消耗会随子目录数量线性涨，深仓库容易吃掉上下文预算。

2.4 配置级：~/.codex/config.toml ​

  • 作用：严格说不算"记忆"，但它直接决定 Memory 的加载行为——例如默认模型、是否允许 Agent 写文件、MCP 服务清单、审批策略（auto/ask/never）。
  • 存储位置：~/.codex/config.toml（开源 CLI 已确认）。
  • 写入方式：手动编辑 + codex 的子命令 [部分版本提供]。
  • 与 Memory 的耦合：审批策略会影响"Agent 能否自动追加 AGENTS.md"——这是把"记忆写入权"纳入了权限模型，体现"显式优于隐式"。

2.5 会话级记忆 ​

包含三个子层：

子层内容寿命
消息历史user/assistant/tool 的完整消息流默认整个会话
Plan / Todo模型显式维护的步骤清单（部分版本以工具形式存在）单会话
工具结果文件读、shell、MCP 返回单会话，但可能被压缩
  • 持久化：Codex CLI 会把会话以 JSONL 形式落盘（社区已观察到 ~/.codex/sessions/ 类似路径 [推测]），用于 codex resume 这类续接操作。
  • 关键工程点：会话日志与 AGENTS.md 完全分离——前者是"做过什么"，后者是"应该怎么做"。这种事实 / 指令二分比 Cline 的"全部塞进一个 .clinerules"更结构化。

2.6 工具级记忆：MCP / Skills / Hooks 与记忆的协同 ​

  • MCP（Model Context Protocol）：Codex 把 MCP 服务器列在 config.toml 里，MCP 工具描述本身就是一种 Memory——它在每次推理前作为可用工具清单注入。
  • Skills[Codex 不一定使用此命名；与 Claude Code 的 Skills 形成对照]：Codex 提供 ~/.codex/prompts/（或 <repo>/.codex/prompts/）作为"按需调用的 Prompt 片段"，用 /<name> 触发。它解决了"AGENTS.md 越写越长"的问题——把不常用的指令延迟加载。
  • Hooks[在 Codex CLI 路线图中已出现，但落地形式因版本而异]：Hooks 主要影响事件流而非记忆本身，但可以在 pre-tool / post-tool 时机里读写本地文件，从而间接更新 Memory（例如执行完测试后自动把失败用例追加到 AGENTS.md 的"已知问题"段）。

2.7 长期记忆与外部知识 ​

  • /compact（或自动压缩）：见 §3.6。它把"超长会话"压成"摘要 + 最近若干轮原文"，本质是会话级记忆的有损压缩。
  • # 快捷写入：在某些前端（IDE 扩展）中输入 #xxx 可以一键追加到当前 AGENTS.md [推测，与 Claude Code 的 # 习惯对齐]。Codex CLI 是否原生支持视版本而定。
  • Codex Cloud Agent：云端任务跑的是"无状态容器 + 仓库克隆"，每次任务重新加载 AGENTS.md；任务之间不共享会话记忆，但共享仓库本身（包括被 Agent 提交回去的 AGENTS.md 更新）。

3. 演进时间线（核心章节） ​

下面把 Codex 的 Memory 演进切成 7 个阶段。每段保留四要素结构。

【阶段 1】纯 Prompt 注入（2025 Q2，Codex CLI v0 时期） ​

  • 痛点：模型本身没有"项目知识"，每次都要用户在第一条消息里粘贴"这是个 Next.js 项目，用 pnpm 跑测试…"。
  • 方案：Codex CLI 启动时把 cwd、Git 远程、package.json/pyproject.toml 等少量元信息自动塞进 system prompt，加上一段固定的工作守则（"先读再写"、"破坏性操作要确认"）。
  • 取舍：① 无持久化，跨会话不能记住偏好；② 元信息抽取规则硬编码，扩展性差；③ 上下文里塞了一堆"猜来的"文件清单，token 浪费。
  • 遗留问题：用户开始在每个项目里手写 INSTRUCTIONS.md / .cursorrules / .aider.conf 之类的"私货"，社区方言爆炸。

【阶段 2】单文件 AGENTS.md：把方言变成标准 ​

  • 痛点：每个 Agent 各搞各的项目说明文件，跨工具协作不可能。
  • 方案：OpenAI 牵头明确推出 AGENTS.md 作为跨 Agent 通用项目记忆载体，并在 Codex CLI 中默认加载仓库根目录的该文件。
  • 关键决策：
    • 选择 Markdown 而非 YAML/JSON——人类可读 + LLM 易解析；
    • 放在仓库根、与代码同 PR——天然受 Code Review 监督；
    • 不规定章节结构——降低用户上手成本。
  • 取舍：① 不规定结构 → 内容质量参差，长项目里 AGENTS.md 容易变成"流水账"；② 单一文件 → monorepo 不友好。
  • 遗留问题：① 全局偏好（"我永远用中文回复"）应该写在哪？② 子模块怎么办？

【阶段 3】分层记忆：用户级 + 项目级 + 子目录级 ​

  • 痛点：阶段 2 留下的两个空白。
  • 方案：
    • 引入 ~/.codex/AGENTS.md 作为用户级全局指令；
    • 允许 <sub>/AGENTS.md 在子目录生效，按"父级 → 子级"顺序合并；
    • 加载顺序：用户级 → 仓库根 → 子目录（越具体的越靠后追加）。
  • 取舍：
    • 优点：方言被分层吸收，monorepo 也能局部声明；
    • 代价：Token 预算开始紧张；用户心智成本上升（"为什么这条规则没生效？"——因为被子级覆盖了）；冲突调试变难。
  • 遗留问题：① 没有"看一眼现在到底加载了哪些 Memory"的可视化；② 编辑 AGENTS.md 还得离开会话。

【阶段 4】交互式写入与 /-命令体系 ​

  • 痛点：用户常常在对话里临时蹦出"以后都帮我用 ruff 而不是 black"，但要他自己记得切去编辑 AGENTS.md 不现实。
  • 方案：
    • 提供 /init（生成项目模板）、/compact（压缩）、/<custom>（调用自定义 prompt）等命令；
    • 在 IDE 形态中提供 # 快捷写入（按下 # + 一句话即追加到 AGENTS.md）[推测，与同类工具对齐]；
    • Agent 可以主动建议："要不要把这条规则写进 AGENTS.md？" 然后用文件编辑工具落盘。
  • 取舍：
    • 写入便利性 ↑↑；
    • 但记忆污染风险也 ↑↑——Agent 可能把一次性偏好误判为永久规则。Codex 的对策是"写入即 diff，需要用户确认"，这与配置里的审批策略联动。
  • 遗留问题：跨项目的"用户技能复用"——例如"我有一套 React 代码评审清单"——AGENTS.md 太重，每次粘贴又烦。

【阶段 5】Prompt 片段 / Skills 化：按需加载的"延迟记忆" ​

  • 痛点：① AGENTS.md 越写越长，会吃掉上下文预算；② 有些指令只在特定任务里需要（写 PR、生成 release note、做 code review）。
  • 方案：
    • 在 ~/.codex/prompts/ 与 <repo>/.codex/prompts/ 引入 Prompt 片段，用 /name 显式触发；
    • [推测] 部分版本进一步把"片段 + 工具集合"打包成类 Skills 的概念（与 Claude Code 的 Skills、Cursor 的 Modes 是同一种应对策略）。
  • 取舍：
    • 优点：把 Memory 从"全部常驻"降级为"按需加载"，上下文预算大幅释放；
    • 代价：用户必须知道"该调用哪个片段"，发现性变差；命名空间冲突（用户级与项目级同名）需要规则裁决。
  • 遗留问题：长会话里已经加载过的片段仍然占据历史，未必能在压缩中保留——下一阶段必须配合压缩策略。

【阶段 6】上下文压缩（/compact、Auto-Compact）与会话续接 ​

  • 痛点：长任务（>1h、几百轮工具调用）必然把上下文打爆。
  • 方案：
    • 显式 /compact：把已有历史交给模型生成结构化摘要，保留最近 N 轮原文 + 摘要；
    • 自动压缩：当 token 预算接近阈值（如 80%）时触发，过程对用户可见但无需手动干预；
    • 会话落盘 + resume：把会话存为 JSONL，下次可以带着摘要继续，而不是从零开始。
  • 关键设计：
    • 摘要里显式保留：当前任务目标、Plan/Todo、未完成的失败、关键文件清单；
    • 摘要里显式丢弃：成功的 grep 结果、被替代的尝试、噪声日志；
    • 这背后是一个"重要性优先级"启发式 [推测细节未公开]。
  • 取舍：
    • 优点：把"上下文窗口大小"这条物理上限延后到任务真正复杂时才出现；
    • 代价：① 摘要必然有损，模型可能"忘记"被压掉的关键约束；② 压缩本身就要花一次推理；③ 调试体验下降——用户难以审视"被丢了什么"。
  • 遗留问题：跨会话的"我以前怎么解决过这个 bug"仍然不可访问——这就推到了下一阶段的云端记忆。

【阶段 7】跨会话 / 跨设备：Codex Cloud Agent 的记忆形态 ​

  • 痛点：本地会话日志只在我这台机器上；云端任务跑完后什么都不剩；多人协作时 Memory 无法对齐。
  • 方案：
    • Codex Cloud Agent（OpenAI 在 2025 年中后陆续放出的形态）把 Agent 跑在 OpenAI 托管的容器里，仓库本身成为唯一的持久化载体；
    • 任务完成后 Agent 以 PR 形式回写代码、AGENTS.md 更新、甚至新增 prompt 片段——记忆通过 Git 历史持久化；
    • [推测] 云侧也存在任务日志/摘要的留痕，但默认不跨任务复用，避免泄露私有数据。
  • 取舍：
    • 优点：把"团队共享的项目记忆"和"个人云会话记忆"在物理上分开——前者走 Git，后者走云端账号；
    • 代价：① 强依赖仓库写权限与 PR 流程；② 用户级偏好（个人的 ~/.codex/AGENTS.md）在云端形态下重新成为问题——是绑定 OpenAI 账号同步，还是任务级注入？目前公开方案倾向于后者 [推测]。
  • 遗留问题：跨任务的"经验复用"——例如同一仓库里 100 次任务都掉进同一个坑——目前只能靠人手动总结进 AGENTS.md，没有自动归纳。

【阶段 8 · 推测】未来可能的方向 ​

方向价值风险
向量化语义记忆（对仓库 + 历史会话做 embedding）检索式调用，避免全文注入引入隐式行为，破坏可追溯性
结构化记忆图谱（实体-关系而非纯文本）精准查询，token 极致节省工程复杂度暴涨，编辑门槛高
记忆 GC（根据使用频率自动剪枝 AGENTS.md）解决长期项目的"记忆肥胖"误删风险，需要可逆机制
团队共享记忆中枢（独立于 Git）跨仓库经验复用隐私 / 权限模型复杂
与 IDE 的"行级标记"协同（把记忆挂到代码行而不是文件）局部上下文更准与 Git diff 兼容性问题

4. 关键设计原则提炼 ​

从 7 个演进阶段中可以归纳出 5 条可复用的设计原则：

  1. 显式优于隐式（Explicit > Implicit）

    • 表现：所有持久 Memory 都是人类可读的纯文本；写入永远经过 diff 确认；不偷偷做向量化。
    • 工程化含义：当你设计 Agent 记忆时，先想"用户怎么审查"，再想"模型怎么用"。

  2. Git 友好即正义（Versioned by Default）

    • AGENTS.md 放仓库根、随 PR 演进——记忆和代码享受同一套 Code Review、回滚、blame。
    • 反例：把项目记忆塞进 SQLite/向量库，团队协作必然失败。

  3. 分层 + 合并优于覆盖（Layered Append, not Replace）

    • 用户级 → 项目级 → 子目录级 都是追加注入，而不是"子级把父级抹掉"。
    • 这种"洋葱模型"让用户能预测最终生效的指令集。

  4. 预算意识（Token Budget as a First-Class Concern）

    • 从"全部常驻"到"按需 Skills/prompts"再到"自动压缩"，每一步都在跟上下文预算搏斗。
    • 启示：任何"自动加载"的设计都要配套"自动卸载"。

  5. 事实与指令二分（Facts vs. Instructions）

    • AGENTS.md 写"应该怎么做"（指令）；会话日志记"做过什么"（事实）；摘要从事实里提炼回指令。
    • 不要把它们混进同一个文件——这是 Cline 早期 .clinerules 膨胀的教训。

5. 与同类产品的横向对比 ​

表中的"Codex"指 Codex CLI + Cloud Agent 当前公开能力的合集。Codex CLI 与 Codex 在 OpenAI 体系内已合流，本表不再单列"Codex CLI"列，改为列出 Aider 作为另一参照。

维度CodexCursorClaude CodeClineAider
项目记忆载体AGENTS.md（仓库根，分层）.cursor/rules/*.mdc（多文件 + frontmatter glob）CLAUDE.md（兼容 AGENTS.md）.clinerules（单文件或目录）.aider.conf.yml + CONVENTIONS.md
全局记忆~/.codex/AGENTS.md + config.toml~/.cursor/rules、用户 Settings~/.claude/CLAUDE.md~/Documents/Cline/Rules（IDE 设定）~/.aider.conf.yml
写入触发方式手工 / Agent 提议 + 用户确认 / # 快捷 [推测]UI 创建 rule、Cmd+I 编辑# 快捷写入、/memory、Agent 主动写UI 编辑、Agent 主动写纯手工
加载粒度文件全文，按目录层级合并按 glob + alwaysApply 选择性加载文件全文 + 按目录合并文件全文全文
上下文压缩策略/compact + 自动压缩 + 会话落盘自动 truncation + Agent 内部摘要 [推测]/compact + auto-compact + Subagent 隔离上下文手动清空 / 新会话手动 /clear
跨会话续接codex resume + 会话 JSONLChat 历史 UIclaude --resume / --continue会话历史侧栏不直接支持，靠 .aider.chat.history.md
Skills / Prompt 片段.codex/prompts/* + /<name>Rules + Custom ModesSkills（独立目录 + frontmatter）无独立机制无
MCP 集成config.toml 声明设置面板~/.claude/mcp.json 等设置面板无原生 MCP
云端形态Codex Cloud Agent（无状态容器 + 仓库为持久层）Background AgentsClaude Code Cloud / Sandbox无无
跨工具兼容主推 AGENTS.md 标准，多 Agent 可共读仅 .cursor/rules 自有格式已兼容读取 AGENTS.md自有格式自有格式

横向观察：

  • Codex 在"标准化"上走得最远（推动 AGENTS.md 成为跨 Agent 共识）；
  • Cursor 在"选择性加载"上最激进（glob 控制粒度）；
  • Claude Code 在"记忆 + Subagent 上下文隔离"上最完整；
  • Cline / Aider 偏轻量，记忆体系最朴素。

6. 落地启示：5 条可执行工程实践 ​

如果我要为自己的 Coding Agent 设计 Memory 系统，从 Codex 的演进里最值得直接抄作业的 5 条：

  1. 统一记忆文件名为 AGENTS.md，不要造新方言

    • 直接复用社区共识，与 Codex / Claude Code / 第三方 Agent 共读；
    • 文件位置：<repo>/AGENTS.md、<sub>/AGENTS.md、~/.<your-agent>/AGENTS.md。

  2. 加载顺序 + 冲突解决，写进文档并对用户暴露

    • 顺序建议：用户级 → 仓库根 → 子目录（深→浅追加）；
    • 提供 /memory show 之类命令，让用户能实时看到当前生效的 Memory 拼装结果——这是 Codex 早期阶段最被诟病缺失的能力。

  3. 分离"指令"与"事实"两类文件

    • 指令：AGENTS.md（人可写、Git 跟踪、PR 审查）；
    • 事实：会话日志 ~/.<your-agent>/sessions/*.jsonl（Agent 自动写、对用户只读）；
    • 严禁把工具调用日志倒灌进 AGENTS.md。

  4. 写入永远经过 diff 确认 + 配置化的审批策略

    • Agent 想追加规则？必须 apply patch-style 给用户看 diff；
    • config.toml 里允许 auto_memory_write = ask | always | never，三档对应不同信任级别；
    • 这是把"记忆写入权"纳入权限模型的最小可行实现。

  5. Token 预算配套"按需 Prompt 片段 + 自动压缩"两件套

    • 在 <repo>/.<your-agent>/prompts/*.md 提供 /<name> 调用，把不常用指令延迟加载；
    • 当上下文使用率超过阈值（80% 是 Codex 社区观察到的常用值 [推测]）自动触发压缩；
    • 压缩时强制保留：当前 Plan / Todo、最近 K 轮原文、最近 M 个文件读结果，其余可摘要。

7. 参考资料 ​

由于 Codex 仍在快速演进，下列链接以"类别 + 入口"列出；具体页面随版本更新。

  • OpenAI 官方
    • Codex 产品页（openai.com/codex/ 系列入口）
    • Codex CLI 开源仓库 README 与 CHANGELOG（GitHub openai/codex）
    • OpenAI Developer Blog 中关于 Codex CLI、Codex IDE、Codex Cloud 的更新公告
    • AGENTS.md 标准说明页（OpenAI 推动的跨 Agent 协议）
  • Anthropic / 对照参考
    • Claude Code 官方 Memory & Subagents 文档（用于 §5 横向对比）
  • 协议 / 规范
    • Model Context Protocol（MCP）官方规范（用于 §2.6）
  • 社区分析 [社区]
    • HackerNews / Reddit 上对 ~/.codex/sessions/ 路径与压缩阈值的逆向观察
    • 社区博客对 AGENTS.md 与 CLAUDE.md 加载顺序的对比测试
    • 各 Coding Agent 横向评测文章（用于补足 Cursor、Cline、Aider 部分）

声明：本文涉及 Codex 内部实现细节（如压缩阈值、会话存储格式、# 快捷写入是否原生）的部分均已标注 [推测]；如需引入到正式技术决策，请以 OpenAI 官方仓库与文档当前版本为准。