LangGraph 记忆管理详解：短期记忆、长期记忆与 Runtime Context

前面我们已经学习了 Checkpoint、失败恢复和 Time Travel。

接下来进入 Agent 开发里更常见的另一个概念：

Memory。

在 LangGraph 中，可以把相关能力分成三类：
text 复制代码
短期记忆
长期记忆
Runtime Context
它们看起来都像是在"保存信息"，但作用范围完全不同。

1. 三种信息到底怎么区分？

类型	保存位置	作用范围	是否持久化
短期记忆	State + Checkpointer	同一个 thread_id	是
长期记忆	Store	跨会话	是
Runtime Context	runtime.context	当前一次调用	否

text 复制代码

短期记忆
当前会话记住了什么

长期记忆
这个用户长期有什么信息

Runtime Context
这一次调用临时需要什么

例如：

text 复制代码

聊天历史
当前会话中已经查询过的用户偏好
↓
短期记忆

用户长期偏好
用户画像
跨会话保存的数据
↓
长期记忆

当前登录用户
会员等级
Trace ID
本次功能开关
↓
Runtime Context

2. 短期记忆：State + Checkpointer

短期记忆其实我们前面一直都在使用。

只要：

python 复制代码

graph = builder.compile(
    checkpointer=checkpointer
)

并且多次调用复用同一个：

python 复制代码

thread_id

State 就可以在这个会话中继续保留。

所以短期记忆的核心不是单独存在一个 Memory 对象，而是：

text 复制代码

State
+
Checkpointer
+
thread_id

它更适合保存：

text 复制代码

聊天消息
当前任务状态
本轮 Agent 已得到的结果
会话过程中缓存的用户信息

3. 长期记忆：Store 实现跨会话共享

短期记忆主要围绕 thread_id 工作，但有些信息不应该随着会话变化而丢失，例如：

text 复制代码

Alice 喜欢跑步
Alice 喜欢某种酸奶
Alice 正在学习计算机组成原理

这些数据更适合放入：

text 复制代码

Store

LangGraph 的长期记忆通常采用：

text 复制代码

namespace + key + value

组织数据。

例如：

python 复制代码

namespace = (
    "users",
    "Alice"
)

key = "preferences"

value = {
    "course": "计算机组成原理",
    "sports": "跑步",
    "food": "奶皮子酸奶"
}

写入：

python 复制代码

store.put(
    namespace,
    key,
    value
)

读取：

python 复制代码

item = store.get(
    namespace,
    key
)

长期记忆存储器会在编译图时传入：

python 复制代码

graph = builder.compile(
    checkpointer=checkpointer,
    store=store
)

节点中则可以通过：

python 复制代码

runtime.store

访问。

一个很常见的流程是：

text 复制代码

第一次调用
State 中没有 preferences
        ↓
从 Store 查询长期记忆
        ↓
写入 State
        ↓
后续节点直接读取

第二次调用
复用同一个 thread_id
        ↓
preferences 已存在于 State
        ↓
不必再次查询 Store

这正好体现了：

text 复制代码

Store
负责长期保存

State
负责当前会话使用

如果使用 PostgresStore，长期记忆可以保存到 PostgreSQL；如果要支持语义模糊检索，还需要为 Store 配置索引和 embedding。

4. Runtime Context：只对当前调用有效

还有一些信息既不适合放进长期记忆，也没必要保存进 Checkpoint，例如：

text 复制代码

当前登录用户名
会员等级
请求来源
Trace ID
模型配置
数据库连接
本次功能开关

这些信息只服务于当前一次调用，可以使用：

text 复制代码

Runtime Context

例如定义：

python 复制代码

@dataclass
class UserContext:
    username: str
    membership_level: str

构建图：

python 复制代码

builder = StateGraph(
    state_schema=OverallState,
    context_schema=UserContext
)

调用时传入：

python 复制代码

graph.invoke(
    {
        "user_input": "你好"
    },
    context=UserContext(
        username="Alice",
        membership_level="VIP"
    )
)

节点中通过：

python 复制代码

runtime.context

访问。

需要注意：

Runtime Context 不会被持久化。

即使下一次调用继续使用相同 thread_id，也不会自动继承上一次的 Context。

所以可以简单区分：

text 复制代码

跨调用共享、需要保存
↓
State / Store

只在当前调用生效
↓
Runtime Context