Appearance
Conversation、Checkpoint 与 Short-Term Memory
1. 为什么这组知识要一起学
分清 Run State、Session、Checkpoint、Short/Long-Term Memory 与 RAG，并建立可恢复、可解释的状态模型。
这几个知识点处在同一条工程链上。如果只记单个名词，很容易在真实系统里把责任放错层：例如让模型管理程序事实、让数据库 transaction 承担外部 API 原子性，或把一个 provider SDK 的行为误认为 Agent 的通用规律。
2. Mental Model
State 是执行事实，Session 是交互连续性容器，Memory 是选择性保留的跨时信息；三者不应混成一个“历史消息列表”。
text
Events/Observations → Run State → Checkpoint/Event Log → Session History / Memory Candidate → Persist → Retrieve → Context3. 核心机制
Conversation History
History 是发生过的消息，不等于当前应注入的 context，也不等于长期 memory；可以完整保存、选择性读取。
Checkpoint
Checkpoint 是可恢复的一致状态切片，通常还要带版本、next step、pending writes；它不是随便 dump 一个 dict。
Short-Term Memory
短期 memory 与 thread/session 强相关，常用 recent history、summary 或工作状态；重点是控制大小和连续性。
4. 最小实现 / 伪代码
下面代码只表达边界和生命周期，不要求照抄到项目中：
python
@dataclass
class MemoryRecord:
scope: str
content: str
provenance: str
created_at: datetime
supersedes: str | None = None真正实现时应把 I/O、状态持久化、错误翻译和策略注入拆成可测试组件，而不是把示例扩成一个巨型函数。
5. 在 Shadow Harness 中怎么落地
RunState、SessionStore、CheckpointStore、MemoryStore 分接口；Memory 带 scope/provenance/freshness，context 只按需注入。
建议为本章涉及的行为留下明确的 domain object、interface 和 trace event；只要一个关键行为只能通过读日志猜测，就说明 Runtime contract 仍不够清晰。
6. Production Engineering 检查项
- 状态要可序列化
- memory write 需要 policy
- 多用户/多 agent scope 隔离
- 冲突与过时 memory 要可更新/删除
7. Failure Modes
7.1 conversation history = memory
当出现「conversation history = memory」时，先辨认出错的是 RunState、Session history 还是 Memory，再检查 scope、provenance、版本和持久化边界。 这类问题通常需要修改 contract、policy、state 或 adapter，而不是只追加 Prompt。
7.2 vector DB = memory
当出现「vector DB = memory」时，先辨认出错的是 RunState、Session history 还是 Memory，再检查 scope、provenance、版本和持久化边界。 这类问题通常需要修改 contract、policy、state 或 adapter，而不是只追加 Prompt。
7.3 把所有 observed facts 永久保存
当出现「把所有 observed facts 永久保存」时，先辨认出错的是 RunState、Session history 还是 Memory，再检查 scope、provenance、版本和持久化边界。 这类问题通常需要修改 contract、policy、state 或 adapter，而不是只追加 Prompt。
7.4 crash 后只能靠 transcript 猜状态
当出现「crash 后只能靠 transcript 猜状态」时，先辨认出错的是 RunState、Session history 还是 Memory，再检查 scope、provenance、版本和持久化边界。 这类问题通常需要修改 contract、policy、state 或 adapter，而不是只追加 Prompt。
8. Trade-offs
event log 可重建但体积大；snapshot 恢复快但需版本管理；实际常 snapshot + event/audit 混合。
设计记录最好明确：当前约束是什么、备选方案有哪些、为什么现在选这个、未来什么条件出现时需要重构。 这样 ADR 才能随着模型和基础设施变化被重新审视。
9. Experiment / Evaluation
做 crash/restart 测试；写入冲突 memory；验证 session history trimming 不破坏 durable task state。
实验应固定数据集、版本和环境，至少记录 success、latency、token/cost、attempt/step 数以及失败类型；涉及随机模型时需要重复运行而不是只看一次结果。
10. 常见问题
基础：Conversation History 最容易被误解的点是什么？
History 是发生过的消息，不等于当前应注入的 context，也不等于长期 memory；可以完整保存、选择性读取。
机制：这些能力在一次 Run 的哪个生命周期阶段生效？
沿着 Events/Observations → Run State → Checkpoint/Event Log → Session History / Memory Candidate → Persist → Retrieve → Context 找位置，并明确它的输入、输出、持久化事实和失败传播。
工程：如果这一层失败，应该由谁恢复？
先区分 transient failure、invalid input、permission、semantic failure 与 irreversible side effect。恢复策略属于拥有该状态与副作用的 Runtime/adapter，而不是交给模型自由决定。
设计：规模扩大 10 倍后，哪个假设最先失效？
优先检查 context/token、并发/连接池、catalog 大小、持久化吞吐、trace 体积、身份与租户隔离。不要默认“多加机器”能解决语义和一致性问题。
11. Sources
12. 本文结论
掌握本文的标准不是能背定义，而是能画出数据流、写出最小 contract、解释失败恢复，并用测试或 benchmark 证明设计没有只停留在概念层。