精读: OpenAI Codex 记忆系统

编排/Harness 视角见 Agent 框架 · Codex 总架构精读

调研元信息

一句话定位

Codex 的记忆系统是一个两阶段异步 AI pipeline：Phase1 并行从每个会话（rollout）中提取结构化记忆，Phase2 串行将所有提取结果合并为统一的记忆文件系统——整个过程在后台自动完成，用户无需干预 [源码][文档]。

日常类比

想象一个勤劳的实习生每天做完工作后会写工作笔记（Phase1），周末有个主管把所有人的笔记收集起来，整理成一份部门手册（Phase2）。实习生写笔记是并行的（最多 8 人同时写），但主管整理手册必须独占——因为同时有两个人改同一份手册会乱。手册还有个特别规则：引用次数越多的笔记越会被保留，超过 30 天没人引用的笔记会被清理掉。

类比边界：与真实主管不同，Phase2 的 consolidation agent 是一个受限沙箱中的 AI——没有网络、不能请求人工审批、写入范围仅限记忆目录。

记忆类型标注

本文主要讨论 User memory（系统/Agent 自动写入的持久化记忆），兼及 Agent profile（AGENTS.md）与 User memory 的边界划分。

架构总览

Codex 记忆系统分为两个 crate：codex-memories-write（写路径）和 codex-memories-read（读路径），外加 codex-state 中的 SQLite 持久层做协调 [源码]。

flowchart TB
    subgraph trigger["触发层"]
        S[Root Session 启动]
    end

    subgraph gates["Gate 检查"]
        G1[非 ephemeral?]
        G2[MemoryTool 启用?]
        G3[非子 Agent?]
        G4[StateDB 可用?]
        G5[API 余量 ≥ 25%?]
    end

    subgraph write["写路径 — codex-memories-write"]
        PRUNE[清理过期 stage-1]
        P1[Phase1: 并行提取]
        P2[Phase2: 全局合并]
    end

    subgraph read["读路径 — codex-memories-read"]
        INJ[Developer Instruction 注入]
        CIT[Citation 解析]
        USE[Usage 统计]
    end

    subgraph storage["存储层"]
        DB[(SQLite<br/>stage1_outputs<br/>jobs)]
        FS[文件系统<br/>~/.codex/memories/]
    end

    S --> G1 --> G2 --> G3 --> G4 --> G5
    G5 --> PRUNE --> P1 --> P2
    P1 -->|per-rollout 结果| DB
    P2 -->|读取 DB| DB
    P2 -->|写入产物| FS
    FS --> INJ
    INJ --> CIT --> USE
    USE -->|usage_count++| DB

触发条件

记忆 pipeline 在 root session 启动时自动触发，需要全部 gate 通过 [源码]：

API 余量检查是一个精巧的设计：当用户 API 配额紧张时，记忆生成主动让路，把额度留给用户真正的编码任务 [源码]。

写路径: Phase1 — 并行提取

数据流

flowchart LR
    subgraph claim["Job 领取"]
        SCAN[扫描 ≤5000 threads]
        CLAIM[Claim ≤2 个 rollout]
    end

    subgraph extract["并行提取 (concurrency=8)"]
        LOAD[加载 rollout items]
        FILTER[过滤非记忆内容]
        PROMPT[构建提取 prompt]
        MODEL[发送到模型<br/>reasoning=Low]
        PARSE[解析 JSON 输出]
        REDACT[Secret 脱敏]
    end

    subgraph persist["持久化"]
        DB_WRITE[写入 stage1_outputs]
    end

    SCAN --> CLAIM --> LOAD --> FILTER --> PROMPT --> MODEL --> PARSE --> REDACT --> DB_WRITE

关键参数

内容过滤

Phase1 在构建 prompt 前会做严格的内容过滤 [源码]：

过滤后的 rollout 内容还会做一轮 secret 脱敏——API key、token 等敏感信息在进入模型前就被清除 [源码]。

提取 prompt 设计

Phase1 的 system prompt（stage_one_system.md，约 570 行）定义了一套完整的提取决策框架 [源码]：

最小信号门：核心判断是”未来 Agent 是否会因为有了这条记忆而表现更好？”如果答案不确定，返回空 JSON——宁可漏提也不误提。

高信号类别包括：用户偏好、程序性知识（怎么做某件事）、任务地图（项目结构概览）、环境事实（本地配置特殊性）。

输出结构是一个固定 JSON schema：

{
  "rollout_summary": "任务结构化摘要",
  "rollout_slug": "简短标识符或null",
  "raw_memory": "YAML frontmatter + Task 块"
}

raw_memory 的格式值得注意：它用 YAML frontmatter（description / task / task_group / task_outcome / cwd / keywords）开头，后跟 ### Task N 块，每块含 Preference signals / Reusable knowledge / Failures / References 四个子节。这种结构化格式让 Phase2 的合并有据可循 [源码]。

与 mem0 的对照

写路径: Phase2 — 全局合并

Phase2 是记忆系统最复杂的部分。它的核心思路是：把所有 Phase1 的提取结果当作”原材料”，启动一个受限 AI Agent 将它们合并成结构化的记忆文件系统 [源码]。

数据流

flowchart TB
    LOCK[获取全局锁<br/>cooldown=6h]
    SELECT[从 DB 选择 top-N memories<br/>按 usage_count + recency 排序]
    SYNC[同步到文件系统]
    DIFF[Git diff vs baseline]

    LOCK --> SELECT --> SYNC --> DIFF

    DIFF -->|无变更| DONE1[标记成功, 跳过]
    DIFF -->|有变更| WRITE_DIFF[写 phase2_workspace_diff.md]

    WRITE_DIFF --> SPAWN[启动 Consolidation Agent]

    subgraph sandbox["沙箱环境"]
        AGENT[Consolidation Agent<br/>reasoning=Medium]
        AGENT -->|读| RAW[raw_memories.md]
        AGENT -->|读| SUMMARIES[rollout_summaries/]
        AGENT -->|写| MEMORY[MEMORY.md]
        AGENT -->|写| SUMMARY[memory_summary.md]
        AGENT -->|写| SKILLS[skills/]
    end

    SPAWN --> AGENT
    AGENT --> HEARTBEAT[每 90s 心跳续约]
    HEARTBEAT --> VERIFY[验证 ownership]
    VERIFY --> RESET[重置 git baseline]
    RESET --> DONE2[标记成功]

全局锁与冷却

Phase2 是全局串行的——同一时间只能有一个 consolidation 在运行 [源码]。

冷却期的设计意图是避免频繁 consolidation：记忆的整合不需要实时性，6 小时一次已经足够 [源码]。

Input Selection — 使用频率驱动的遗忘

Phase2 不会把所有 Phase1 输出都喂给 consolidation agent，而是做一轮 usage-based selection [源码]：

排序规则：
  1. usage_count DESC  — 被引用越多越重要
  2. COALESCE(last_usage, source_updated_at) DESC — 最近使用优先
  3. source_updated_at DESC — 同等条件取更新的
  4. thread_id DESC — 确定性打破平局

这是一种隐式遗忘机制：不是主动删除记忆，而是让不被引用的记忆在 30 天后自然淘汰。对比 Graphiti 的时序失效（通过 valid_at / invalid_at 显式标记）和 mem0 的无遗忘设计，Codex 选择了中间路线 [已有]。

Consolidation Agent 沙箱

Phase2 的 consolidation agent 在极其严格的沙箱中运行 [源码]：

Consolidation Prompt

Phase2 的 prompt（consolidation.md，约 881 行）定义了两种模式 [源码]：

INIT 模式（首次构建）：从零开始，把所有 raw_memories 整理成 MEMORY.md + memory_summary.md + skills/。

INCREMENTAL UPDATE 模式（增量更新）：利用 git diff 作为路由——新增/修改的 rollout summary 进入 ingestion queue，被删除的进入 forgetting queue，然后做外科手术式更新。

文件系统产物

memory_summary.md 必须以 v1 开头——这不是版本号装饰，而是 consolidation agent 用于判断是否已初始化的标记 [源码]。

与 DB-Agent-Memory 的对照

读路径: Developer Instruction 注入

Codex 的记忆读路径与 Claude Code 截然不同：它不做按需向量检索，而是将记忆作为 developer instruction 直接注入 [源码]。

注入机制

memory_summary.md（摘要层）总是被加载——这意味着每个 session 都会看到完整的记忆摘要。需要更深层记忆时，Agent 可以通过文件读取工具访问 MEMORY.md 和 rollout_summaries/ [源码][文档]。

Citation 解析

当 Agent 在回答中引用了记忆，读路径会解析 citation 标记 [源码]：

解析结果用于两个目的：(1) 给用户展示记忆来源；(2) 递增 usage_count，直接影响 Phase2 的 input selection 排序。这形成了一个正反馈循环：被引用越多的记忆越不容易被遗忘 [源码]。

与 Claude Code 读路径的对照

与 AGENTS.md（Profile）的边界

Codex 明确区分了两种持久化配置 [源码]：

Phase1 的内容过滤中，AGENTS.md 指令被显式移除——这正是”Profile 不应被记忆系统记住”原则的代码体现 [源码]。

状态管理: SQLite 协调

记忆 pipeline 的协调完全依赖 SQLite [源码]：

stage1_outputs 表

CREATE TABLE stage1_outputs (
  thread_id TEXT PRIMARY KEY,
  source_updated_at INTEGER NOT NULL,
  raw_memory TEXT NOT NULL,
  rollout_summary TEXT NOT NULL,
  rollout_slug TEXT,
  generated_at INTEGER NOT NULL,
  usage_count INTEGER,           -- citation 递增
  last_usage INTEGER,            -- 最近引用时间
  selected_for_phase2 INTEGER DEFAULT 0,
  selected_for_phase2_source_updated_at INTEGER
);

jobs 表

CREATE TABLE jobs (
  kind TEXT,            -- 'phase1' / 'phase2'
  job_key TEXT,         -- thread_id 或 'global'
  status TEXT,
  worker_id TEXT,
  ownership_token TEXT, -- 防止锁被窃取
  lease_until INTEGER,  -- 租约到期时间
  retry_remaining INTEGER DEFAULT 3,
  input_watermark INTEGER,
  last_success_watermark INTEGER,
  PRIMARY KEY (kind, job_key)
);

Watermark 机制值得注意：Phase2 完成后记录 last_success_watermark，下次 Phase2 只处理 watermark 之后的新数据。但计算时取 max(claimed_watermark, max(source_updated_at))，确保 watermark 永远不会后退 [源码]。

局限性

1. Phase2 单点瓶颈：全局锁 + 6h 冷却意味着高频使用场景下 consolidation 可能跟不上 Phase1 的产出速度。
2. 异步延迟：Phase1 要求 rollout 至少 idle 6 小时才处理，Phase2 还有 6h 冷却——新 session 可能看不到前一个 session 的记忆。
3. Consolidation Agent 失败：如果 Agent 在 1h 租约内未完成，锁过期后重试，但只有 3 次重试机会。
4. 无增量读取优化：memory_summary.md 全量注入，随着记忆增长可能占用大量上下文。
5. 遗忘粒度粗：以整个 rollout 为单位遗忘，不能选择性保留某条 rollout 中的部分记忆。

证据等级汇总

与开源记忆项目对照总表