Agent Memory 与 State：生产系统应该保存什么

证据快照：本文核对时间为 2026-08-05。OpenAI Agents SDK Sessions、LangGraph Persistence、Google ADK Session / State / Memory 与 Letta Context Hierarchy 都在持续迭代。本文提取较稳定的数据边界，不把某个框架当前的类名、表结构或托管产品当作通用标准。

摘要

Agent 的“记忆”不是一张向量表。生产系统至少要分开保存事件、当前状态、执行检查点、长期记忆、知识与文件资产，并为每条数据保留来源、作用域、有效期、权限和删除路径。

读者将学到什么

读完本文，你应该能够回答：

1. Session、State、Checkpoint、Memory、RAG 和 Artifact 分别解决什么问题；
2. 为什么把完整聊天记录塞回上下文，既不是状态管理，也不是长期记忆；
3. 哪些信息应该长期保存，哪些只能短暂存在，哪些不应写入数据库；
4. 如何设计支持恢复、并发、冲突、撤销、删除和多 Agent 协作的数据模型；
5. 怎样评估 Memory 的写入质量、检索质量、时间推理与安全风险。

问题背景：“让 Agent 记住”其实包含多种需求

产品需求里经常出现一句话：

让 Agent 记住之前发生的事情。

它可能指完全不同的能力：

• 刷新页面后继续聊天；
• 多步骤任务失败后从中间恢复；
• 新会话仍记得用户偏好；
• 检索过去某次决策；
• 访问公司文档和业务数据；
• 继续处理上次生成的文件；
• 多个 Agent 共享同一项业务事实。

如果用一张 memory 表解决所有问题，系统会出现三类混乱。

第一类是语义混乱。消息、订单状态、用户偏好、检索文档和工具结果都被叫作 Memory，但它们的生命周期、可信度和更新方式完全不同。

第二类是一致性混乱。模型摘要写着“用户已经付款”，业务数据库却显示仍未支付；旧摘要和新事实互相冲突，Agent 不知道应该相信谁。

第三类是治理混乱。用户要求删除个人信息时，团队无法确认它是否仍存在于原始事件、摘要、向量索引、缓存、Trace 和备份中。

因此，生产架构的第一原则不是先选向量数据库，而是先定义：

这条数据是什么事实，属于谁，能影响什么，保存多久，由谁更新，怎样撤销。

核心概念：先把六个对象彻底分开

OpenAI Agents SDK 的 Session 主要维护单个会话的历史；LangGraph 区分 thread-scoped checkpointer 与 cross-thread store；Google ADK 将 Session、State 和 Memory 分开；Letta 又区分始终驻留上下文的 memory blocks、可搜索的 archival memory、文件与外部 RAG。

这些框架命名不同，但可以归纳为六层。

Event：发生过什么

Event 是追加式事实记录：

{
  "event_id": "evt_01J...",
  "session_id": "ses_123",
  "sequence": 184,
  "type": "tool.completed",
  "actor": "agent:refund_agent",
  "created_at": "2026-08-05T06:18:22Z",
  "payload": {
    "tool_name": "lookup_order",
    "operation_id": "op_891",
    "result_ref": "artifact://tool-results/op_891.json"
  }
}

它回答“当时发生了什么”，适合审计、重放、调试和派生状态，不适合每轮全部塞进 Prompt。

OpenAI Agents SDK 的 MongoDB Session 使用单调递增的 seq 保证并发写入下的消息顺序。这个实现细节说明：顺序本身也是需要显式建模的数据，不能依赖数据库自然返回顺序。

State：现在是什么状态

State 是从事件或业务系统计算出的当前视图：

{
  "workflow_status": "WAITING_FOR_CONFIRMATION",
  "current_step": "confirm_shipping_address",
  "order_id": "ord_8842",
  "address_version": 3,
  "pending_action_id": "act_22",
  "last_event_sequence": 184
}

它回答“系统现在应该从哪里继续”。State 应该结构化、可校验、可版本化。

Google ADK 将 session.state 定义为可序列化的 Key-Value scratchpad，并区分 session、user:、app: 和 temp: 等作用域。它还明确建议通过 Context、Event Delta 和 append_event 更新 State，而不是直接改一个从存储层读取出来的对象，因为后者可能绕过事件历史、持久化和并发控制。

State 不等于聊天摘要。聊天摘要是模型生成文本；State 是程序可以依赖的当前事实。

Checkpoint：失败后从哪里恢复

Checkpoint 保存某一执行时刻的图状态、节点结果、等待条件和运行版本：

{
  "checkpoint_id": "cp_0092",
  "thread_id": "ticket_428",
  "graph_version": "refund-flow@17",
  "superstep": 6,
  "state_version": 31,
  "resume_node": "wait_for_human_approval",
  "pending_tasks": ["issue_refund"]
}

LangGraph 的 checkpointer 将图状态按 thread 保存为 checkpoint，用于 Human-in-the-loop、时间旅行和故障恢复；Store 则保存跨 thread 的长期数据。两者不能合并：恢复一次工作流需要精确执行版本，记住用户喜欢中文不需要恢复整个图。

Memory：过去什么信息值得再次使用

Long-term Memory 是从历史中提取出的、未来可能有用的信息：

{
  "memory_id": "mem_778",
  "namespace": ["tenant_8", "user_42", "preference"],
  "kind": "semantic",
  "content": "用户偏好中文回答，保留必要英文术语。",
  "source_event_ids": ["evt_120", "evt_121"],
  "confidence": 0.97,
  "valid_from": "2026-07-10T00:00:00Z",
  "valid_to": null,
  "sensitivity": "personal",
  "status": "active",
  "version": 2
}

Memory 回答的是：

过去发生的事情里，哪一小部分值得未来检索？

它不是完整历史，而是有选择、可追溯的派生数据。

Knowledge：外部世界是什么

公司文档、API 说明、产品目录和业务数据库不应被伪装成“用户记忆”。Memory 可以记录“用户上次选择了套餐 A”，Knowledge 则记录“套餐 A 目前包含什么”。前者是交互历史，后者是权威资料；冲突时通常应以业务权威源为准。

Artifact：大对象在哪里

生成的报告、上传 PDF、音频、图片、代码快照和完整工具结果，不应直接放进 State 或 Memory 正文。State 只保存引用、Hash 和状态；文件进入对象存储，元数据进入关系库。

心智模型：事实层、视图层与上下文层

核心判断是：

• Event、业务数据库和原始文件属于事实层；
• State、Checkpoint、Memory 与搜索索引属于可重建视图；
• 模型上下文只是一次调用的临时装配结果。

只要事实层仍在，视图可以重建；如果只保留模型摘要而丢掉来源，错误很难纠正。

Memory 也要分类

Semantic Memory：相对稳定的事实和偏好

例如用户偏好语言、项目 Python 版本、团队代码规范和默认时区。这类信息适合结构化字段、唯一约束和显式版本，不一定需要向量检索。

Episodic Memory：经历与决策

例如“上次部署因为缺少迁移而失败”“用户在方案比较中选择了低成本路线”。这类信息通常带时间、参与者、项目、来源和结果，适合时间过滤与语义检索结合。

Procedural Memory：做事方法与经验

例如发布前先跑构建、数据库写操作先展示预览、某工具超时后只重试一次。

Claude Code 当前明确区分两类跨会话上下文：CLAUDE.md 由用户维护，用来保存项目指令与规则；Auto Memory 由 Claude 根据纠正和工作经验写入，用来保存构建命令、调试经验和偏好。两者都会在新会话中作为上下文加载，但官方文档明确提醒，它们是 context，而不是 enforced configuration。

Letta 的 memory blocks 适合少量高优先级信息始终驻留上下文；更大的文件、archival memory 和外部 RAG 则按需读取。

因此，Procedural Memory 可以帮助 Agent 选择更好的做法，但权限、审批和不可绕过的安全规则仍应由应用层强制执行。

生产系统到底应该保存什么

应长期保存

• 业务事实引用：订单 ID、工单 ID、文档 ID、状态版本；
• 恢复所需状态：当前节点、已完成步骤、待执行动作、运行版本；
• 高价值长期记忆：明确表达的偏好、稳定事实、项目决策与可复用经验；
• 治理元数据：来源、作用域、置信度、敏感级别、有效期、删除状态与提取器版本；
• 工具副作用的幂等键、审批与拒绝记录。

只应短暂保存

• 本轮中间计算和流式 Token；
• 未提交的工具参数；
• 推测执行结果；
• 临时检索候选；
• Prompt 缓存；
• 未确认的用户意图。

这类数据适合进程内存、Redis 或短 TTL 表。它们可以帮助执行，但不应自动变成用户画像。

不应默认保存

• 模型隐藏推理和冗长内部草稿；
• 密钥、访问令牌和认证头；
• 不必要的完整工具响应；
• 未经确认的敏感推断；
• 与任务无关的个人信息；
• 可从权威系统实时读取的易变事实；
• 没有来源、无法删除、无法解释用途的 Memory。

原则不是“少存一切”，而是：

只持久化未来有明确用途、能够治理、能够纠正的数据。

推荐的数据模型

Memory 为什么需要 Revision

长期记忆会变化：

v1：用户常驻杭州
v2：用户现在常驻北京

直接覆盖会丢失时间关系；两条都保持 active 又会冲突。更合理的设计是：

• memory_id 表示同一语义实体；
• revision 保存每次变化；
• valid_from / valid_to 表示有效区间；
• 当前 revision 用于默认读取；
• 历史 revision 用于时间问题和审计。

为什么必须保存来源 Event

没有来源的 Memory 无法回答：是谁说的、是明确表达还是模型推断、何时生效、后来是否被纠正、删除原会话后派生记录是否也要删除。

Memory 至少需要保存 source_event_ids、source_type、extractor_version 和 confidence。

Memory 写入：模型只能提交候选

更稳妥的写入流程是：

建议至少设置六道门：

1. 价值门：未来是否可能复用；
2. 置信度门：明确事实、可靠工具结果还是模型推断；
3. 敏感性门：是否涉及身份、健康、财务、凭据或私密内容；
4. 稳定性门：是长期偏好，还是一次性状态；
5. 冲突门：与已有 Memory 是重复、补充还是覆盖；
6. 权限门：写入 user、project、team 还是 agent namespace。

模型可以生成 Candidate，但最终写入应由确定性 Policy 和 Resolver 决定。

Memory 读取：相似度只是第一步

一个可解释的读取链路应接近：

Scope Filter
→ 时间与有效期过滤
→ 关键词 + 向量候选召回
→ 冲突与新鲜度重排
→ 任务适用性与安全门控
→ 上下文预算分配
→ 带来源注入模型

Scope Filter 必须先于向量召回

错误做法：

先在全库做 vector top-k
再过滤 user_id

租户、用户、项目、Agent、敏感级别和状态应成为检索前的硬过滤条件。跨用户泄漏不是“召回质量问题”，而是权限边界失败。

时间不是普通文本

长期问题经常包含“上次”“去年”“搬家前”“哪个决定后来被推翻”。Memory 应显式保存：

event_time
recorded_at
valid_from
valid_to
timezone
temporal_expression_original

“昨天”必须在写入时绑定会话时间和时区，不能只保存字符串。

LongMemEval 将长期记忆拆为信息提取、多 Session 推理、时间推理、知识更新和拒答。2025 年的 Memory-T1 也专门研究多 Session 时间推理中的时间过滤和证据选择。

相似 Memory 不等于应该进入上下文

2026 年的 Beyond Similarity 将 Memory Search 视为信任边界：语义相似但任务不适用的历史可能造成跨域泄漏、迎合、工具调用漂移和持久化注入。

因此 Memory Retriever 应增加 Admission Gate：

{
  "memory_id": "mem_778",
  "relevance": 0.84,
  "scope_ok": true,
  "time_ok": true,
  "task_applicable": true,
  "conflict": false,
  "safety_risk": "low",
  "admit": true
}

被召回不代表必须注入；被注入也不代表拥有指令权限。

Context Builder：Memory 最终如何进入模型

每轮上下文应该由明确的预算和优先级装配，而不是简单拼接：

一个常见优先级是：

不可违反的系统策略
→ 当前业务状态与待决事项
→ 近期会话
→ 高置信度、强相关长期 Memory
→ 检索知识
→ Artifact 摘要与引用

Memory 不应因为“被长期保存”就自动获得高优先级。

最小实现：Event + State + Memory Candidate

下面的 Python 伪代码展示关键边界。

from __future__ import annotations

from dataclasses import dataclass
from datetime import UTC, datetime
from typing import Any, Protocol
from uuid import UUID, uuid4


@dataclass(frozen=True)
class Event:
    id: UUID
    session_id: UUID
    sequence: int
    type: str
    payload: dict[str, Any]
    created_at: datetime


@dataclass
class SessionState:
    session_id: UUID
    version: int
    last_sequence: int
    values: dict[str, Any]


@dataclass(frozen=True)
class MemoryCandidate:
    namespace: tuple[str, ...]
    kind: str
    subject: str
    predicate: str
    content: str
    source_event_ids: tuple[UUID, ...]
    confidence: float
    explicitly_stated: bool
    sensitivity: str


class Store(Protocol):
    async def append_event(
        self,
        event: Event,
        expected_last_sequence: int,
    ) -> None: ...

    async def compare_and_set_state(
        self,
        state: SessionState,
        expected_version: int,
    ) -> bool: ...

    async def find_active_memory(
        self,
        namespace: tuple[str, ...],
        subject: str,
        predicate: str,
    ) -> dict[str, Any] | None: ...

    async def commit_memory_revision(
        self,
        candidate: MemoryCandidate,
        previous_memory_id: UUID | None,
    ) -> UUID: ...


class MemoryPolicy:
    def allow(self, candidate: MemoryCandidate) -> bool:
        if candidate.confidence < 0.80:
            return False
        if candidate.sensitivity in {"credential", "secret"}:
            return False
        if not candidate.explicitly_stated and candidate.sensitivity == "sensitive":
            return False
        return True


async def apply_event(
    store: Store,
    state: SessionState,
    event_type: str,
    payload: dict[str, Any],
) -> SessionState:
    next_sequence = state.last_sequence + 1
    event = Event(
        id=uuid4(),
        session_id=state.session_id,
        sequence=next_sequence,
        type=event_type,
        payload=payload,
        created_at=datetime.now(UTC),
    )

    await store.append_event(
        event,
        expected_last_sequence=state.last_sequence,
    )

    next_state = SessionState(
        session_id=state.session_id,
        version=state.version + 1,
        last_sequence=next_sequence,
        values=reduce_state(state.values, event),
    )

    if not await store.compare_and_set_state(
        next_state,
        expected_version=state.version,
    ):
        raise RuntimeError("concurrent state update")

    return next_state

这个实现保留四个关键点：

1. Event 使用 Session 内单调序号；
2. State 使用版本号 CAS，避免并发覆盖；
3. Memory 写入先经过 Policy 与 Resolver；
4. Memory 保存来源事件，而不是只保存模型生成文本。

并发、多 Agent 与一致性

同一 Session 可能同时被用户消息、模型流、后台工具、人工审批和定时任务更新。常见策略包括：

• 单 Session 单 Writer；
• 乐观锁 + CAS；
• 数据库行锁；
• 基于事件序号的 Reducer；
• 按 entity / workflow 分区的队列。

不要让多个 Agent 读出同一个 JSON，各自修改后再整块覆盖。

多 Agent 共享的也不应是“全部记忆”。推荐 Namespace：

(tenant_id, user_id, "preference")
(tenant_id, project_id, "decision")
(tenant_id, agent_id, "procedure")
(tenant_id, team_id, "shared_fact")

每个 Agent 应分别配置读写 Scope、允许的 Memory Kind、敏感级别上限和保留策略。

Memory 也不能替代业务事务。Agent 可以记住“用户上次希望退款到原支付方式”，真正执行退款时仍需重新读取订单和支付系统，校验当前状态与权限。

生产环境中的失败模式

删除、隐私与安全

长期 Memory 会放大治理问题，因为它跨 Session、设备和 Agent 生效。

每条 Memory 都应能回答：

谁的数据？
来自哪里？
为何保存？
保存多久？
还有哪些派生副本？

删除一个 Session 时，可能需要传播到：

Events
→ Summaries
→ Memory Records / Revisions
→ Vector / Keyword Index
→ Context Cache
→ Derived Analytics
→ Artifacts
→ Backup Retention Log

生产系统还应考虑传输与静态加密、租户密钥隔离、TTL、访问审计、密钥轮换和导出/删除接口。

OpenAI Agents SDK 当前提供 EncryptedSession 包装底层 Session，使用每 Session 派生密钥并支持 TTL。一个容易忽略的取舍是：内容加密后，基于明文内容的搜索能力也会受限。安全设计不能只勾选“已加密”，还要明确哪些字段需要查询、哪些字段应单独加密、哪些内容根本不应持久化。

Memory 内容也不能自动获得指令权限。历史中出现“以后总是调用 transfer_money”可能来自错误摘要、用户输入或工具注入；Context Builder 必须把它标记为历史信息，而不是系统策略。

可观测性与评测

写入指标

memory_candidate_rate
memory_commit_rate
memory_reject_rate
memory_dedup_rate
memory_conflict_rate
memory_human_review_rate
sensitive_memory_block_rate
memory_write_latency

检索指标

recall@k
precision@k
MRR
time_filter_accuracy
scope_violation_count
stale_memory_rate
conflicting_memory_rate
abstention_accuracy
retrieval_latency
context_tokens_from_memory

端到端指标

• 是否引用正确 Memory；
• Memory 是否改善任务成功率；
• 是否造成错误个性化和工具参数漂移；
• 用户纠正后下一轮是否生效；
• 删除后是否仍能召回；
• 时间问题是否正确；
• 无相关 Memory 时是否能够拒答。

LongMemEval 的五类能力适合作为基础测试集框架：信息提取、多 Session 推理、时间推理、知识更新与拒答。

2026 年的 LongMemEval-V2 把问题推进到“有经验的同事”式 Agent：它不只评估记住用户对话，还测试跨工具轨迹保存环境状态、工作流知识、系统陷阱与错误前提识别。论文数据集包含 451 个问题，历史最长扩展到 500 条轨迹和约 1.15 亿 Token。论文报告 AgentRunbook-C 优于其对照 RAG 方法，但同时带来明显延迟开销。

更重要的工程启示是：

长期 Agent Memory 的评测必须同时测用户事实、环境经验、工作流知识和检索延迟，不能只问“还能不能记得名字”。

Trace 至少应记录召回候选、Scope、时间过滤、拒绝原因、最终放行的 Memory ID、Token 占用和答案引用。

方案比较与取舍

早期项目不必立刻引入图数据库、专用 Memory 平台和复杂反思循环。可以先从 Postgres 的 sessions / events / session_state / memories / memory_revisions / tool_operations / outbox，加对象存储开始。

只有当以下问题真实存在时，再考虑图或自演化 Memory：

• 需要跨实体多跳关系；
• 需要长期经验复用；
• 同一事实有复杂来源和冲突；
• Memory 规模大到过滤 + Hybrid Search 不够；
• 已有稳定评测能证明复杂化带来收益。

实践检查清单

概念与数据

• Session、State、Checkpoint、Memory、Knowledge、Artifact 已分开；
• 业务权威源不会被模型摘要覆盖；
• Event 有 Session 内单调 Sequence；
• State 有 Schema、Version 和 last_event_sequence；
• Checkpoint 记录 Runtime / Graph 版本；
• Memory 有 Namespace、来源、置信度、有效期和敏感级别；
• Memory 更新采用 Revision，而不是无条件覆盖；
• Artifact 在 State 中只保存引用。

写入与读取

• Memory 写入经过 Candidate、Policy 和 Resolver；
• 未确认推断不会升级为稳定事实；
• 数据库与搜索索引通过 Outbox 同步；
• 工具副作用有 operation_id 和幂等控制；
• 权限与 Namespace 在召回前硬过滤；
• 检索考虑时间、有效期、新鲜度和冲突；
• Memory 有 Admission Gate；
• 注入上下文的 Memory 数量和 Token 有预算。

可靠性与安全

• Session 并发更新使用 CAS、锁或单 Writer；
• 恢复 Checkpoint 不会重复执行写操作；
• Memory 内容不能覆盖系统安全策略；
• 敏感数据有加密、TTL 和访问审计；
• 删除传播到摘要、索引、缓存和 Artifact；
• 用户可以查看、纠正和删除长期记忆。

评测

• 有 Memory 写入 Precision / Recall 抽样集；
• 有时间推理、事实更新和拒答测试；
• 监控 stale、conflict 和 scope violation；
• 端到端评测包含有 Memory / 无 Memory 对照；
• 复杂 Memory 方案的收益能够被指标证明。

总结

Agent Memory 的核心不是让模型拥有无限上下文，而是建立清晰的数据责任体系：

1. Event 记录发生过什么；
2. State 表示现在在哪里；
3. Checkpoint 保证失败后能够继续；
4. Memory 只保存未来值得复用的历史信息；
5. Knowledge 由外部权威源维护；
6. Artifact 保存文件与大对象；
7. Context Builder 每轮按权限、时间和预算组装模型上下文。

真正可靠的生产系统不会先问“Memory 用哪个向量库”，而会先问：

这条信息是谁的、是否可信、何时有效、能影响什么、如何纠正、如何删除。

只要这些问题没有答案，记得越多，系统可能越不可靠。

参考资料

1. OpenAI Agents SDK — Sessions
2. OpenAI Agents SDK — Encrypted Sessions
3. LangGraph Persistence
4. Google ADK — Session, State, and Memory
5. Google ADK — State
6. Google ADK — MemoryService
7. Letta — Context Hierarchy
8. Claude Code — How Claude remembers your project
9. MemGPT: Towards LLMs as Operating Systems
10. Generative Agents: Interactive Simulacra of Human Behavior
11. LongMemEval
12. Mem0
13. Memory-T1
14. Beyond Similarity: Trustworthy Memory Search for Personal AI Agents
15. LongMemEval-V2 与 官方仓库

图片清单

agent-memory-state-cover.png

• 用途：文章原创封面与社交分享卡片；
• 比例：16
  ；
• Alt 文本：多个透明数据层围绕 Agent 核心，组织成事件、状态、检查点、长期记忆、知识与文件资产；
• 生成提示词：A refined editorial illustration for a technical article about production-grade agent memory and state. A central abstract AI agent is surrounded by distinct translucent layers: an event timeline, a structured state ledger, recovery checkpoints, a selective long-term memory archive, searchable knowledge, and file artifacts. Show clear separation and controlled data flows, version history, provenance links and deletion paths. Modern technical magazine aesthetic, deep navy, warm white and restrained cyan accents, spacious 16:9 composition, no text, no letters, no numbers, no logo, no watermark.；
• 状态：待生成。

agent-memory-state-layers.mmd

• 用途：事实层、视图层与上下文层架构；
• Alt 文本：Agent 持久化系统的事实层、派生视图层与上下文组装层。

agent-memory-state-er.mmd

• 用途：核心关系数据模型；
• Alt 文本：Session、Event、Checkpoint、Memory Revision、Artifact 与 Tool Operation 的关系。

agent-memory-write-pipeline.mmd

• 用途：Memory 写入流程；
• Alt 文本：长期记忆从候选提取、策略门控、冲突解析到版本化提交和索引更新。

agent-memory-context-builder.mmd

• 用途：上下文组装流程；
• Alt 文本：系统策略、当前状态、近期会话、长期记忆、知识和 Artifact 摘要按预算进入模型上下文。