第 7 章 Chapter Outline：Working Memory 与 Long-term Memory

本文件是正文写作蓝图。工作记忆（Working Memory）、长期记忆（Long-term Memory）、Memory Record、写入与读取门槛、生命周期和教学案例都是本书的工程模型；它们不是 Claude Code、OpenAI Agents SDK、LangChain/LangGraph 或 MemGPT 的共同数据结构、默认策略或安全保证。涉及供应商和框架的行为时，正文写作当天必须重新核验 REF-006、REF-020 至 REF-022；REF-023 仅作为研究背景使用。

章节契约

读者完成后的能力： 能将当前任务的工作记忆、会话历史、跨任务长期记录、Context Packet、工作流状态和知识库候选资料分开；能为一条候选记忆写出来源、主体、作用范围、观察时间、写入理由、读取触发、有效性和修订或撤销条件；能在证据冲突、信息过期或范围不匹配时要求刷新或停止，而不是把旧记录当作当前事实。

前置知识： 已完成第 6 章，能为一次调用构造带来源、时效、预算和未知项的 Context Packet；理解规则、任务、数据、输出契约与验证结果各自的职责；能阅读对象、列表和简单断言。

章节边界： 本章不负责决定本次模型调用的资料预算和装配（第 6 章），不实现计划、检查点、状态机、并发或幂等恢复（第 10 章），不实现工具协议（第 11 章）、知识库或检索基础设施（第 13 章），不讨论反思如何产生经验候选（第 16 章）、长任务压缩（第 19 章）、成本优化（第 40 章）或授权、隐私、保留期限与审计（第 41 章）。本章尤其不把“保存过”“曾被模型看见”“能被检索”“当前可读取”或“已经验证”为同一件事。

小节蓝图

1. 记忆不是历史堆栈：先分开当前状态、会话记录与可复用记录

• 读者问题： 为什么一个 Agent 有对话历史、文件、日志和项目文档，仍然不能说它“记住了正确的事”？
• 叙述任务： 以原创教学场景开场：部署失败后的接手者拿到一次性终端输出、会话摘要、项目决策和半年前的修复建议。让读者先给每项资料命名，而不是立即决定存储位置。区分“本轮可观察的状态”“某个会话的消息历史”“经条件检查后可跨任务复用的记录”“本次模型输入”和“可检索候选”。
• 证据边界： REF-020 仅在 OpenAI Agents SDK 中描述特定会话跨 run 的消息历史；REF-021 明确其 sandbox memory 与 Session 消息历史不同；教学场景、分类方法和判断规则均为本书模型，不描述真实部署或账户。
• 计划工件： 五列表：资料样例、最小身份、可否跨任务复用、当前不应推断的结论、应移交的章节。样例包括失败断言、一次会话摘要、已批准决策、过期经验和检索条目。
• 验证： 读者能指出“某条资料在会话中存在”不证明其来源、范围、时效或可复用性，并将五个样例放入工作记忆、长期记忆候选、当前 Context Packet、知识库候选或未知项。
• 过渡： 分类之后，下一步不是选择文件夹，而是定义当前任务和跨任务记录各自的最小责任。

2. Working Memory 与 Long-term Memory：边界由任务、范围和生命周期决定

• 读者问题： 短期与长期是否只由“保存多久”决定？
• 叙述任务： 提出本书模型：工作记忆只服务于当前任务或当前阶段，包含目标、观察、中间结果、待办和未知项；长期记忆是跨任务可能复用、但仍要带来源、范围与生命周期的记录。用“当前失败断言”“已确认的仓库规则”“尚未复核的旧建议”对比时间长度、主体和读取条件。强调长期不等于永久，工作也不等于无需记录。
• 证据边界： REF-022 在 LangChain/LangGraph 语境中把短期记忆描述为 thread-scoped 状态、长期记忆描述为跨 thread 的数据；本书用任务、范围和生命周期建立可审查边界，不将该术语当成跨框架标准，也不设定通用 TTL。
• 计划工件： “工作 / 长期 / 两者都不是”决策表，字段为任务锚点、主体、作用范围、是否需要下一任务、是否可被当前证据复核与失效动作。
• 验证： 给定同一条“上次测试修复原因”记录，读者能解释何时它只应存在于当前工作记忆、何时能作为长期候选、何时必须因主体或证据不明而阻塞。
• 过渡： 仅靠分类仍无法让维护者复核一条记录，因此必须把可复用记忆当作有契约的工件。

3. Memory Record：把来源、范围与撤销条件写进记录本身

• 读者问题： 一条“团队约定”或“Agent 经验”最少应包含什么，才能被下一位执行者安全地重新判断？
• 叙述任务： 定义本书的 Memory Record：kind、scope、subject、source、observed_at、write_reason、read_trigger、validity、revision_or_revocation。用两条对照记录展示：没有来源的“总是先重试”与带任务范围、失败证据、有效条件和撤销路径的经验候选。说明字段名可替换，但来源、范围、时间、读取条件和生命周期不能悄悄省略。
• 证据边界： 该结构、必填字段和示例都是本书设计；REF-006、REF-021 与 REF-022 只提供不同产品或框架的持久指令、工作区记忆、namespace 和状态范围背景，不证明这些字段由任何系统自动生成。
• 计划工件： Memory Record 模板及字段责任表：每个字段回答的问题、缺失时的动作、可以说明什么、不能说明什么。
• 验证： 每条准备跨任务读取的记录都能回答“从哪来、对谁有效、为何写入、何时读取、何时过期或撤销”；缺一项时输出 blocked 或 refresh_required，而非补写推测值。
• 过渡： 记录格式满足最低要求后，还要决定什么信息有资格进入记录，而非让所有任务输出自动沉淀。

4. 写入门槛：从候选信息到可维护记忆

• 读者问题： 为什么“任务完成后自动总结并保存”会积累风险？
• 叙述任务： 建立写入门槛：候选信息先核对直接来源、主体和 scope；再说明它为哪个未来任务减少何种不确定性；最后声明有效期或复核事件，以及撤销或修订路径。将模型产出的解释、未验证诊断、敏感数据、跨主体经验和与当前证据冲突的摘要标为候选或阻塞，而不是自动晋升为长期记忆。
• 证据边界： REF-021 明确提醒其 beta sandbox memory 可能过时，当前环境应优先；REF-022 讨论热路径与后台写入在延迟、新鲜度和复杂度上的取舍。写入门槛、分类动作和升级规则是本书模型，不是自动记忆功能的保证或合规机制。
• 计划工件： 写入闸门表：source、scope、subject、write reason、敏感性、有效性、撤销路径和动作（工作记忆、长期候选、阻塞、人工升级）。
• 验证： 读者能在“有来源但 scope 过大”“有作用但来源缺失”“有来源与 scope 但已过期”三种情况中选择不同动作，并明确不会因为记录存在就推断事实、权限或任务完成。
• 过渡： 即使记录被允许写入，下一项任务也不能不加筛选地把它送入模型；读取同样需要一道门槛。

5. 读取门槛：记忆是候选资料，不是当前事实或模型输入的捷径

• 读者问题： 下一次任务何时可以读取一条长期记录，何时必须重新查看当前环境？
• 叙述任务： 将长期记忆定位为第 6 章 Context Packet 之前的候选资料。读取时检查任务锚点、主体、scope、触发条件、有效性、与当前直接证据的冲突，以及是否只应保留引用。说明会话历史可以为对话连续性提供背景，但不自动变成跨任务事实；当前证据优先于过期摘要。
• 证据边界： REF-020 只说明该 SDK 如何在 run 前后维护 Session 历史；REF-021 只在其 sandbox memory 语境中推荐渐进披露并警告过时性。本文的读取闸门、冲突动作和 Context Packet 衔接均为本书工程模型，不描述通用模型输入策略。
• 计划工件： 读取决策表：匹配则作为候选资料、超出当前预算则保留指针、冲突或过期则刷新、主体不符则阻塞、影响权限或敏感数据则升级到第 41 章设计。
• 验证： 给定一条旧的“验证命令”和一条新的失败输出，读者能保留旧记录的来源与历史范围，但要求刷新，而不会让旧命令覆盖当前观察。
• 过渡： 读取后的比对会产生修订、过期和撤销；这要求记忆具有显式生命周期而不是只增不减的列表。

6. 生命周期与冲突：修订、过期与撤销都是正常结果

• 读者问题： 旧记录与当前观察相冲突时，为什么不能简单覆盖或删除？
• 叙述任务： 描述本书生命周期：观察 → 记忆候选 → 来源/范围/生命周期检查 → 工作记忆或长期记录 → 当前任务读取 → 当前证据复核 → 保留、修订、过期或撤销。解释保留历史来源、修订关系和撤销理由的意义：下一位维护者可以知道“为什么不再使用”，而不是把删除误读为从未发生。明确“过期”表示不能直接用作当前事实，不等于记录错误；“撤销”也不自动表示安全事故或权限处罚。
• 证据边界： REF-023 仅提供在有限上下文下使用分层记忆的研究背景；生命周期图、状态名称、冲突动作和版本关系均为本书模型，不主张 MemGPT 或任何产品使用相同流程。
• 计划图示： chapter-07-memory-record-lifecycle.mmd 展示候选、检查、两类记忆、当前证据复核与四种终态。图中不从写入直连“事实”“授权”“完成”或“安全”。
• 验证： 图和正文必须共同说明：当前直接证据可让一条旧记录进入 refresh_required，但不能凭空推断其替代值；每条修订或撤销都保留来源指针与理由。
• 过渡： 读者已具备单条记录的判断规则，最后用一个无外部副作用的接手场景检验整条链路。

7. 完整工程案例：让接手者从失败观察构造可审查记忆决策

• 读者问题： 一个维护任务跨越多次会话时，如何把“上次怎么做”转化为“这次可以验证什么”？
• 叙述任务： 设计原创教学案例：一位 Agent 在受控的虚构项目中接手测试失败。输入包括当前失败断言、带来源的项目决策、过期经验、无来源摘要和下一步任务锚点。案例先创建工作记忆，再审查哪项可以成为长期候选，下一轮读取时用新的失败证据复核。输出明确区分工作项、长期候选、阻塞项与刷新请求。
• 证据边界： 案例不读取真实仓库、不运行测试、不调用模型、网络、文件、向量库、账户、凭证或供应商 memory；它不证明真实修复、权限控制、数据保留或模型推理正确。
• 计划示例： 07-working-memory-and-long-term-memory.example-plan.md 将定义纯内存 decideMemoryRecord。输入为任务锚点与带 scope、source、observedAt、validity 和主体的候选记录；输出为 working、long_term_candidate、blocked 或 refresh_required，并给出原因与下一步。实现只表达本书的显式判断规则。
• 验证： 最小测试至少覆盖：当前观察进入工作记忆、范围与来源齐全的经验成为长期候选、缺来源阻塞、过期记录要求刷新、主体或任务不匹配时不读取。预期全部来自纯函数契约，而非模型输出或真实系统行为。
• 过渡： 第 10 章会把当前状态放入可恢复工作流；第 13 章会讨论如何检索候选资料；第 16 章讨论如何产出经验候选；第 41 章再设计权限、隐私与审计。本章只提供跨任务记录的可审查边界。

章节工件状态

1. 已完成：Research Brief 与候选参考资料。REF-006、REF-020 至 REF-023 的允许陈述、外推边界与正文当天复核要求已登记。
2. 本阶段完成：Chapter Outline。为正文、事实核验、图示、示例和后续审查定义了读者问题、证据边界、验证条件与跨章节责任。
3. 已完成：Fact Check。已逐项复核会话历史、auto memory、sandbox memory、thread-scoped 状态、跨任务数据与分层记忆的来源范围；动态产品细节仍保留正文当天复核。
4. 已完成 Mermaid 图源与 Diagram Review。diagrams/mermaid/chapter-07-memory-record-lifecycle.mmd 只表达本书的 Memory Record 生命周期，已用 Mermaid CLI 11.16.0 导出 SVG/PNG 并实际查看 PNG；阻塞分支会在补证或人工裁决后回到检查，跨任务分支保持为长期候选。
5. 已完成 Example Plan 与 Example Implementation。07-working-memory-and-long-term-memory.example-plan.md 记录纯内存 decideMemoryRecord 的元数据、状态、六条测试路径、红绿结果和无外部副作用边界；它不得访问外部系统或模拟真实 Agent memory。
6. 已完成 First Draft、Technical Review、Example Implementation 与 Diagram Review；decideMemoryRecord 的 6 项 Node 内置测试和演示已实际运行。Language Editing、Validation 与 Final Review 尚未开始。

Outline 完成检查

• [x] 每个主要小节包含读者问题、叙述任务、证据边界、计划工件、验证和过渡。
• [x] 明确区分工作记忆、长期记忆、会话历史、Context Packet、工作流状态、知识库候选、检索和压缩。
• [x] 明确了与第 6、10、13、16、19、40、41 章的边界，未将保存、读取、检索或分层表述为正确性、安全、授权或完成保证。
• [x] 图示、案例与示例都要求来源、主体、范围、时效、触发、冲突处理与撤销或修订理由。
• [x] 未提前写入正文、图源、示例实现、SDK API、默认保留期、成本、产品性能、真实工具行为或未验证的安全结论。