把用户偏好写进 state,换一个会话就丢了;把每轮消息塞进 Store,几个月后翻出几十万条同义记录;还有人给 Command 里加了个 store 字段,发现长期记忆纹丝不动。这几类问题都发生在同一个地方,工具函数里同时伸手去拿两类记忆,却没分清它们各自归谁管。
前一篇把工具内读写长期记忆的规矩讲完了,本篇往前一步,专讲工具里短期记忆与长期记忆的区别。官方在 tools 文档里把 state 定义成当前会话内的可变数据,把 store 定义成跨会话存活的持久存储,两者都挂在 ToolRuntime 上,从同一行签名进到工具里。名字挨得近,行为差得远。
本篇给一套一个工具同时用两类记忆的完整写法,再把作用域、生命周期、写入方式、失效边界逐项拆开,最后用两个实验验证。
一、先认清三个容器,别把 context 也算成记忆
工具签名里声明 runtime: ToolRuntime,运行时由工具节点自动注入,模型看不到这个参数。官方文档给出的属性里,和「记住什么」相关的一共三个。
| 属性 | 定位 | 作用域 | 是否持久化 |
|---|---|---|---|
runtime.state |
短期记忆,当前会话内的可变数据 | 按 thread_id 隔离 |
需要 checkpointer |
runtime.context |
单次调用传入的静态身份 | 每次 invoke 一份 | 不持久化,只读 |
runtime.store |
长期记忆,跨会话存活的 JSON 文档库 | 按 namespace 加 key 归档 | 需要 store 后端 |
最容易混淆的是 context 和 store。用户 id 属于身份,每次调用传进来,用完就走,它本身不记住任何东西;用户偏好属于记忆,写进 store 才会跨会话存在。至于 state,它记录的是「这次聊到哪了」,比如本会话刚查过的订单号、已调用工具次数、消息列表。
判断口径可以压成一句话,判断当前是谁用 context,记录这一轮进展用 state,记录很久以后还要用的结论用 store。
二、作用域的差别,一句话是会话编号对命名空间
短期记忆靠 checkpointer 落盘,靠 thread_id 分界。同一个 thread_id 的多次 invoke 共享一份 state,换一个编号就是全新一份,官方文档明确写了不同 thread 之间保持隔离。
长期记忆靠 store 落盘,靠命名空间加 key 分界。命名空间是个元组,和 thread_id 没有任何关系,所以换会话、换设备、隔几周再回来,只要命名空间对得上就能取回。
from dataclasses import dataclass
from langchain.agents import create_agent, AgentState
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.store.memory import InMemoryStore
@dataclass
class Context:
user_id: str
tenant_id: str
class SessionState(AgentState):
current_order_id: str
store = InMemoryStore()
agent = create_agent(
"claude-sonnet-4-6",
tools=[],
store=store,
checkpointer=InMemorySaver(),
state_schema=SessionState,
context_schema=Context,
)
这段装配里三个容器各自独立。store 和 checkpointer 是两套完全不同的后端,生产环境分别换 PostgresStore 与 PostgresSaver,各自都要跑一次 setup() 建表。漏配 checkpointer 时 state 每次调用都是空的,漏配 store 时 runtime.store 直接是 None,这两种症状很像,排查方向却相反。
调用侧也要把两件事分开传,thread_id 进 config,context 单独给。
cfg_a = {
"configurable": {
"thread_id": "session-a"}}
cfg_b = {
"configurable": {
"thread_id": "session-b"}}
ctx = Context(user_id="u_123", tenant_id="t_42")
agent.invoke({
"messages": [{
"role": "user", "content": "记住我喜欢蓝色"}]},
config=cfg_a, context=ctx)

三、写入方式完全不同,一个靠返回值一个靠副作用
这是工具里最容易写错的一处。改短期记忆要走 Command,它是给框架的状态更新指令,本次调用结束后由框架合并进 state;写长期记忆是立刻生效的一次存储调用,和工具返回什么无关。
同一个工具里同时记两件事,写法如下。
from langchain.messages import ToolMessage
from langchain.tools import ToolRuntime, tool
from langgraph.types import Command
@tool
def bind_order(order_id: str,
runtime: ToolRuntime[Context, SessionState]) -> Command:
"""记录本轮查询的订单号,并累计该用户常查的类目。"""
assert runtime.store is not None
ctx = runtime.context
ns = (ctx.tenant_id, ctx.user_id, "habits")
item = runtime.store.get(ns, "category_count")
count = item.value.get("count", 0) if item else 0
runtime.store.put(ns, "category_count", {
"count": count + 1})
return Command(update={
"current_order_id": order_id,
"messages": [ToolMessage(
content=f"订单 {order_id} 已记录",
tool_call_id=runtime.tool_call_id,
)],
})
这里有三条边界要记牢。
第一,store.put 在返回之前就写完了,哪怕后面 Command 抛错,长期记忆也已经落库,需要事务语义就得自己补偿。第二,Command.update 里的字段必须是 state schema 里声明过的,往里塞一个 store_count 不会写进 Store,只会因为没有对应字段而被忽略或报错。第三,返回 Command 时框架不会自动包装工具消息,必须自带 ToolMessage 且 tool_call_id 用 runtime.tool_call_id,否则工具节点直接抛 ValueError。返回普通字符串时框架会自动包装,也就顺带改不了 state。
第四个细节是并发。模型可能在一批里并行调用多个工具,都改同一个 state 字段时后写覆盖先写,要给字段定义 reducer。
from typing import Annotated
import operator
class SessionState(AgentState):
current_order_id: str
viewed_order_ids: Annotated[list[str], operator.add]
Store 那边没有这套合并机制,同一个 namespace 加 key 再 put 是整份文档覆盖,只改一个字段却只传一个字段,其余字段会丢。所以上面先 get 再 put 补全,不能省。
四、读的时候,一个拿列表一个拿文档
两类记忆的数据形态也差得远。state 里最核心的是 messages,是一个消息对象列表,加上自定义字段;store 里是一条条 JSON 文档,取回的是 Item 对象,内容在 .value 里。
from langchain.tools import ToolRuntime, tool
@tool
def recall(runtime: ToolRuntime[Context, SessionState]) -> str:
"""同时汇报本会话进展与跨会话偏好。"""
assert runtime.store is not None
ctx = runtime.context
# 短期,读当前会话内的消息与自定义字段
turn_count = len(runtime.state["messages"])
order_id = runtime.state.get("current_order_id", "无")
# 长期,按命名空间精确取回一份文档
ns = (ctx.tenant_id, ctx.user_id, "preferences")
pref = runtime.store.get(ns, "profile")
pref_text = str(pref.value) if pref else "暂无档案"
return f"本会话 {turn_count} 条消息,订单 {order_id},长期档案 {pref_text}"
读 store 时若要枚举某类记忆,用 search,注意它默认只取十条,超出部分静默截断。另外传的是命名空间前缀而不是精确路径,传短了会把所有子命名空间的条目一起捞回来,多租户场景很危险。这两点在上一篇讲过,放到工具里同样成立。
state 的读取则完全免费,不需要额外调用,它本来就在本次执行的上下文里。代价是它整个都要进模型上下文,消息越攒越多,所以才需要裁剪和总结。
五、生命周期的差别,裁剪只动短期不动长期
官方文档给出三种处理长会话的做法,裁剪、删除、总结,它们操作的对象全是 state 里的 messages。
from langchain.agents.middleware import SummarizationMiddleware
from langgraph.checkpoint.memory import InMemorySaver
# 沿用上面的 store、checkpointer 与 state_schema,只追加一个中间件
summarizing_agent = create_agent(
"claude-sonnet-4-6",
tools=[],
store=store,
checkpointer=InMemorySaver(),
middleware=[SummarizationMiddleware(
model="gpt-5.4-mini",
trigger=("tokens", 4000),
keep=("messages", 20),
)],
)
SummarizationMiddleware 把旧消息压成摘要,RemoveMessage 直接删消息,两者都只改 state。长期记忆里的偏好档案、类目计数不受任何影响,换会话之后依然在。反过来说,想把一条写错的长期记忆清掉,只能显式 delete(namespace, key),裁剪多少轮消息都没用。
这里有个实测很直观的对照。官方删除消息的示例里,把最早那条 hi! I'm bob 删掉后,模型最后回答「我不知道你的名字」。如果当初把名字写进了 store,删消息根本不会让模型忘掉它。两类记忆的失效方式完全不同,短期记忆随会话裁剪而衰减,长期记忆只能由应用主动清理。
| 维度 | 短期记忆 state | 长期记忆 store |
|---|---|---|
| 隔离单位 | thread_id |
namespace 加 key |
| 后端 | checkpointer |
store |
| 写入 | 返回 Command |
调 put,立即生效 |
| 读取 | runtime.state["messages"] |
get 或 search |
| 数据形态 | 消息列表加自定义字段 | JSON 文档 |
| 并发 | 字段可定义 reducer | 同 key 覆盖写 |
| 失效 | 换会话、裁剪、删除、总结 | 换会话无效,需 delete |
| 成本 | 全量进模型上下文 | 按需取回,条数可控 |

六、四种常见错配,症状都很像
工具里两类记忆写混了,表现出来都是「模型记不住」,排查方向却完全不同。
| 症状 | 多半是哪种错配 | 优先检查 |
|---|---|---|
| 换会话后偏好丢失 | 长期数据写进了 state | 改用 store.put 并带用户身份 |
| Store 越攒越大且互相串 | 每轮消息写进了 store | 消息留在 state,store 只存结论 |
| 工具里取不到身份 | 把 context 当成存储 | 身份每次 invoke 传 context |
| Command 改不动长期记忆 | 往 update 里塞了 store 字段 | 拆成 put 加 Command 两步 |

第三种尤其隐蔽。context 里带着 user_id,看着很像「已经记住用户了」,其实它每次调用都得重新传,不传就没有。命名空间必须靠它拼出来,但它自己不承担记忆职责。
还有一类是漏配后端。runtime.store 类型允许为 None,创建函数没传 store 时工具里拿到空值;state 那边没传 checkpointer 时,同一 thread_id 的第二次调用读不到第一次写的内容。取值前各加一句断言,报错位置会比后面一串属性错误清楚得多。
七、两个实验,把边界跑出来
装配完成后别急着看模型说了什么,直接把两类记忆各自验一遍。以下代码与上面的装配处在同一个作用域内。
cfg_a = {
"configurable": {
"thread_id": "session-a"}}
cfg_b = {
"configurable": {
"thread_id": "session-b"}}
u1 = Context(user_id="u_123", tenant_id="t_42")
u2 = Context(user_id="u_999", tenant_id="t_42")
# 会话 a 里写入,state 与 store 各写一份
agent.invoke({
"messages": [{
"role": "user", "content": "查订单 ORD-8899"}]},
config=cfg_a, context=u1)
# 实验一,换会话编号
same_user_new_thread = agent.invoke(
{
"messages": [{
"role": "user", "content": "我刚才查的订单号是多少"}]},
config=cfg_b, context=u1)
# 实验二,换用户身份
other_user = agent.invoke(
{
"messages": [{
"role": "user", "content": "我常查的类目统计是多少"}]},
config=cfg_a, context=u2)
# 绕开模型,直接核对两个容器
print("会话 a 快照", agent.get_state(cfg_a).values.get("current_order_id"))
print("会话 b 快照", agent.get_state(cfg_b).values.get("current_order_id"))
print("长期文档", store.get(("t_42", "u_123", "habits"), "category_count"))
实验一的预期是订单号读不到,类目计数还在,说明短期记忆按会话断开了,长期记忆没有。实验二换成另一个用户,不该读到 u_123 的类目计数,说明命名空间隔离生效。最后三行绕开模型直接查两个容器,把「模型说了什么」和「实际存了什么」分开验证,这一步最容易漏。
get_state 返回的是 StateSnapshot,.values 里就是当前 state;这里的 store 就是装配时传给 create_agent 的那个实例,与工具里的 runtime.store 是同一个。发现两者对不上,先看是不是装配时传了另一个实例。
八、上线检查清单
把工具侧两类记忆的边界逐项过一遍,能挡掉大部分「记忆时灵时不灵」的线上问题。
store与checkpointer都传了,工具、中间件、Agent 三处指向同一批实例。thread_id由应用按会话稳定生成,不交给模型填,用户身份只从context取。- 命名空间前段带 tenant_id 与 user_id,写入用完整命名空间,不用短前缀。
- 一条数据只进一个容器,跨会话结论进 store,本会话进展进 state,身份进 context。
- 返回
Command必带ToolMessage且调用标识匹配,并行改同一字段定义了 reducer。 store.put前先get补全字段,覆盖语义明确,追加写有去重。- 裁剪、删除、总结只针对 state 的
messages,清理长期记忆走显式delete。 - 生产换数据库后端并各跑一次
setup(),换会话与换用户两个实验都通过。
工具里同时伸手拿两类记忆,价值是把「这一轮要用的」和「以后还要用的」一次分清,代价是两套后端、两套写入语义、两套失效方式都得各自立住。把作用域、返回值、生命周期这三处边界想清楚,再跑一遍双实验,长期记忆才算从示例走到可用。下一篇进入记忆综合案例,把短期状态、长期偏好、消息摘要和工具容错放进同一个客服助手里看它们怎么配合。