05. 上下文与记忆管理¶
Codex 每次模型采样前都会构造模型可见上下文。上下文不仅包含用户输入和聊天历史，还包含工具结果、项目规则、权限说明、环境信息、可用能力、压缩摘要和长期记忆（memory，跨会话保存和读取的稳定信息）。上下文系统让模型看到足够、正确、不过量且可恢复的工作现场。
模型只能基于本次采样输入决策，而真实任务的事实分散在历史、工具输出、项目规则、权限状态、动态工具、长期记忆和持久化记录里。Codex 的上下文系统不是把这些材料堆进提示词，而是把它们分层、设基线、按需注入，并在压缩、恢复和分叉后重新构造模型工作现场。
上下文分层¶
Codex 的上下文可以分为四层。
任务上下文包含本轮用户输入、待处理输入、assistant 输出和工具结果。它描述当前任务已经发生的事实。
规则上下文包含 AGENTS.md、用户配置指令、权限说明、环境信息和协作模式。它描述模型在当前项目和当前运行环境中应遵守的约束。
能力上下文包含工具规范、技能、插件、连接器、MCP 工具和动态工具。它描述模型本轮能够请求哪些动作、能够参考哪些任务说明。
长期上下文包含压缩摘要、恢复/分叉恢复出的历史和 memories。它维持长会话和跨会话的连续性。
这四层不是简单拼接，而是按采样时机编排。任务上下文每次采样都会变化；规则上下文在首次轮次建立基线，后续主要注入差异；能力上下文在每次采样前重新计算；长期上下文通过压缩、持久化记录和长期记忆影响后续提示词。
每次采样前:
1. 从历史取任务事实
2. 计算规则上下文是否相对基线变化
3. 计算本轮可见工具和技能注入
4. 合并压缩或恢复恢复出的历史
5. 加入长期记忆使用说明与可引用记忆
6. 规范化为当前模型可接受的提示词 input
任务上下文¶
任务上下文提供模型下一步决策所需的事实。测试失败输出、文件内容、patch 应用结果、权限拒绝信息都属于任务上下文。
工具结果必须进入历史。模型运行测试后需要读取失败输出，读取文件后需要看到文件内容，patch 被拒绝后需要看到拒绝原因。没有这些反馈，模型无法基于真实环境继续推进任务。
待处理输入也属于任务上下文。用户在运行中追加的限制会与最新工具结果一起进入下一次采样，使模型在当前任务现场中调整方案。
任务上下文强调因果顺序。模型请求工具、运行时执行工具、工具输出回填历史，这三者必须保持对应关系。若只把工具输出作为普通文本追加，模型就无法可靠判断输出来自哪个动作，连续工具调用场景会失去可解释性。
规则上下文¶
规则上下文描述项目和运行环境的约束。AGENTS.md 是项目规则来源，用户配置指令是全局或会话级偏好，权限说明描述当前可执行边界，环境信息描述 cwd、平台、日期和相关上下文。
AGENTS.md 不是聊天历史。它更接近项目工作规约，包含测试方式、代码风格、目录约定、提交要求和禁止操作等信息。多层 AGENTS.md 会按项目层级组织，使全局规则和局部规则共同影响模型行为。
权限说明属于模型可见规则，但不是安全边界。它帮助模型选择合理策略；实际执行仍由本地运行时检查。
规则上下文需要在会话恢复时保持一致。恢复后模型若只看到聊天历史而看不到当时的项目规则和权限变化，就可能基于错误规则继续任务。因此初始规则、设置变化和上下文基线都会进入可恢复记录。
能力上下文¶
能力上下文控制模型本轮能看到哪些工具和说明。工具规范让模型知道可请求的动作，技能文档让模型知道特定任务的处理方式，插件和连接器提供外部能力入口。
完整能力不会无差别注入。大量工具和技能会占用上下文，并增加误用概率。Codex 根据配置、显式引用、MCP 状态、动态工具和功能开关计算本轮可见能力。
技能通常先以摘要形式出现。完整 SKILL.md 只在显式触发或本轮需要时注入。工具也可能采用 direct 或延迟暴露方式，先提供发现能力，再按需展开具体工具。
能力上下文和权限上下文相互独立。模型看到某个工具规范，表示它可以请求该动作；该动作最终能否执行仍由权限系统决定。这个分离允许 Codex 在不扩大执行权限的前提下，向模型展示必要的动作接口。
上下文基线与增量注入¶
完整初始上下文可能很大，包含规则、环境、权限、技能、插件和可用能力。Codex 不会每轮完整重复注入。首次真实轮次建立上下文基线，后续轮次主要注入相对基线的变化。
例如权限、当前目录、模型和环境均未变化时，后续轮次只需要加入新的用户输入和历史。权限从工作区可写变为只读时，系统注入这一变化，使模型更新行为策略。
基线机制减少重复 token 消耗，同时保留配置变化对模型行为的影响。
基线失效时，系统会重新注入完整上下文。例如压缩可能清除旧基线，恢复可能根据持久化记录重建基线，模型切换或权限变化也可能触发增量上下文。基线机制不是单纯优化 token，而是保证模型对长期会话规则变化有连续认知。
历史¶
历史是模型下一次采样使用的材料，不等同于 UI 聊天列表。它保存用户输入、assistant 输出、工具调用、工具结果和上下文 item。
构造提示词前，历史会被规范化。缺失或孤立的工具输出会被清理，当前模型不支持的内容会被过滤或转换，过长工具输出可能被截断。规范化的目标是生成模型 API 可接受且语义完整的输入。
历史规范化还保护模型协议约束。某些模型要求工具调用与工具输出成对出现，某些模型不支持特定媒体类型，某些输出过长会挤占上下文窗口。规范化阶段将内部历史转换成当前模型可接受的输入形态。
历史在实现上承担工作记忆的角色。它不是最终持久化格式，也不是客户端展示格式，而是当前会话内持续增长和被规范化的模型工作集。工具输出会先进入历史，随后被持久化到持久化记录；压缩会用摘要替换历史的一部分；回滚会裁剪历史并可能重置上下文基线。
压缩¶
长会话会超过模型上下文窗口，压缩用摘要替换旧历史。压缩不是简单删除旧消息，而是重写模型工作记忆。
有效的压缩摘要应保留用户目标、已执行命令、工具结果、修改过的文件、仍需遵守的约束和当前剩余任务。摘要取代旧历史后，模型仍应能够继续任务。
压缩还影响上下文基线。手动压缩或采样前压缩可能清除基线，使下一次普通轮次重新注入完整规则。轮次中压缩需要让当前轮次立即继续，因此会保留必要初始上下文并建立新的基线。
压缩的质量直接影响后续智能体行为。摘要若遗漏用户约束，模型可能在压缩后违反原要求；摘要若遗漏工具结果，模型可能重复已经失败的方案；摘要若遗漏文件修改，模型可能误判当前工作区状态。
压缩的实现可以视为一次特殊任务。它读取当前历史，生成摘要与替换历史，再决定初始上下文如何处理。手动或采样前压缩往往清除旧参考上下文，使下一个普通轮次重新注入完整规则；轮次中压缩则必须把必要初始上下文放入替换历史，使当前轮次不被打断。
恢复与分叉¶
恢复恢复的是模型现场，而不只是界面文本。系统需要恢复历史、上下文基线、压缩状态、动态工具、记忆模式和会话元数据。
分叉从旧会话某个历史点创建新会话。新会话不共享旧进程内存，但会基于持久化记录恢复足够上下文，使模型能够从该历史点继续。
持久化记录因此需要保存响应条目、轮次上下文、压缩替换历史和关键事件。
恢复与分叉的差异在于目标状态。恢复恢复同一线程的后续运行，分叉创建一条新的历史分支。两者都依赖同一套可恢复上下文材料，但分叉需要将历史点之后的运行与原线程分离。
长期记忆读取¶
长期记忆提供跨会话长期上下文。启用长期记忆后，模型上下文会包含记忆使用规则，并允许模型在受控方式下引用长期记忆。
模型使用长期记忆时会留下引用标记。运行时通过这些标记记录本轮是否引用长期记忆，并在存在外部上下文或敏感内容时控制长期记忆污染。
长期记忆读取影响模型可见知识，不提供额外执行权限。
长期记忆引用也会影响后续写入策略。引用了长期记忆的轮次可以产生记忆用量指标；包含外部上下文或敏感来源的轮次可能需要避免污染长期记忆。长期记忆读取因此同时参与上下文构造和记忆治理。
长期记忆读取不把所有记忆文件无条件复制进提示词。运行时会注入记忆使用规则，使模型在需要时引用长期记忆；模型引用后会产生引用标记，会话再记录本轮记忆使用情况。这个设计将“长期记忆可用性”和“本轮实际引用”分开。
长期记忆写入¶
长期记忆写入不在每个轮次主流程同步执行。写入过程从持久化历史中提炼稳定事实，生成中间结果，获取写入锁，再通过受限内部任务整理记忆文件。
这种后台化流程避免当前用户任务被记忆整理阻塞，也避免多个会话并发写入长期记忆导致状态不一致。
长期记忆写入与普通轮次循环分离后，长期记忆成为异步派生结果。当前任务只依赖已存在的记忆；新提炼出的记忆会在后续会话中发挥作用。这个延迟模型避免将“总结长期经验”混入用户当前任务的关键路径。
后台写入可以分成两个阶段。第一阶段从状态数据库选择合格持久化记录，抽取候选记忆和会话摘要，生成中间产物。第二阶段获取全局写锁，同步记忆工作区，并用受限内部任务合并、去重和更新记忆文件。写入完成后，新的记忆文件成为后续会话的读取来源。
上下文系统的整体作用¶
上下文系统将任务事实、项目规则、可用能力、长历史摘要和长期记忆组织成模型可用输入。它同时控制 token 开销、保护任务连续性、支持恢复/分叉，并确保模型基于真实工具反馈继续决策。代价是上下文不再是一个透明字符串，而是一套需要维护基线、差异、规范化和恢复语义的工作记忆系统。