LangChain 之 Agent 工具内短期记忆与长期记忆区别

简介: 本文详解LangGraph中短期记忆(state)与长期记忆(store)的本质区别:前者按`thread_id`隔离、依赖`checkpointer`暂存会话状态;后者以命名空间为键、通过`store`持久化跨会话数据。厘清作用域、写入方式、生命周期与读取机制,避免常见错配,让记忆各司其职。

把用户偏好写进 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 是同一个。发现两者对不上,先看是不是装配时传了另一个实例。

八、上线检查清单

把工具侧两类记忆的边界逐项过一遍,能挡掉大部分「记忆时灵时不灵」的线上问题。

  1. store 与 checkpointer 都传了,工具、中间件、Agent 三处指向同一批实例。
  2. thread_id 由应用按会话稳定生成,不交给模型填,用户身份只从 context 取。
  3. 命名空间前段带 tenant_id 与 user_id,写入用完整命名空间,不用短前缀。
  4. 一条数据只进一个容器,跨会话结论进 store,本会话进展进 state,身份进 context。
  5. 返回 Command 必带 ToolMessage 且调用标识匹配,并行改同一字段定义了 reducer。
  6. store.put 前先 get 补全字段,覆盖语义明确,追加写有去重。
  7. 裁剪、删除、总结只针对 state 的 messages,清理长期记忆走显式 delete。
  8. 生产换数据库后端并各跑一次 setup(),换会话与换用户两个实验都通过。

工具里同时伸手拿两类记忆,价值是把「这一轮要用的」和「以后还要用的」一次分清,代价是两套后端、两套写入语义、两套失效方式都得各自立住。把作用域、返回值、生命周期这三处边界想清楚,再跑一遍双实验,长期记忆才算从示例走到可用。下一篇进入记忆综合案例,把短期状态、长期偏好、消息摘要和工具容错放进同一个客服助手里看它们怎么配合。

目录
相关文章
|
17天前
|
Linux 开发工具 iOS开发
Codex保姆级教程(下载+安装+登录+使用,含所有版本,2026最新)
Codex是OpenAI推出的开源AI编程智能体,本地运行,可理解整个代码库,支持自然语言指令改代码、执行命令、跑测试、修Bug,兼容Win/macOS/Linux。(239字)
7076 53
|
4天前
|
JSON 前端开发 API
阿里云最新Qwen4-Max大模型介绍:模型定位、特征、能力、适用场景解析
2026 年 11 月 11 日,阿里发布第四代旗舰模型Qwen4-Max预览版,首发千问 AI 平台 Token Plan,并同步接入千问办公、Qoder 等入口。该版本聚焦知识理解、世界感知、编程与 Agentic 四项升级,主打复杂编程、专业办公、前端设计与专业软件操作。预览期至 11 月 25 日 24:00,到期后模型标识下线;限时 2 折、新用户再享 5 折,最低 1 折可体验。
|
5天前
|
云安全 人工智能 安全
|
17天前
|
JavaScript API iOS开发
DeepSeek Harness下载、安装、配置一篇搞定(2026整理,送常用插件)
DeepSeek Harness(DSH)是DeepSeek于2026年开源的MIT协议AI Agent框架,支持插件化组装模型、工具、沙箱与UI,兼容主流大模型。本文提供免Node.js的桌面端安装包(Win/macOS),含详细图文教程及热门插件推荐。
5485 65
|
12天前
|
Linux 开发工具 iOS开发
2026最新codex下载安装保姆级使用教程(下载+安装+登录+使用,含所有历史版本)
本文详解OpenAI Codex国内快速上手指南:提供Win/macOS/Linux全平台免安装包、npm/Homebrew等多方式安装、账号/API Key双登录、简体中文切换,覆盖下载、安装、汉化、使用及高频避坑(如微软商店失败、npm超时等),10分钟即可跑通。
2762 9
|
4天前
|
人工智能 前端开发 API
阿里云Qwen4-Max 大模型详解:定位、特征、能力、适用场景与相对Qwen3-Max差异解析
2026年11月11日,阿里发布第四代旗舰模型Qwen4-Max预览版,首发千问AI平台Token Plan并接入千问办公、Qoder等入口。该版本聚焦知识理解、世界感知、编程与Agentic四项升级,主打复杂编程、专业办公、前端设计与专业软件操作等真实任务。预览期为11月11日10:00至11月25日24:00,仅支持Token Plan调用,到期后模型标识下线;限时2折、新用户再享5折,最低1折可体验。
|
9天前
|
人工智能 安全 API
DeepSeek Harness下载、安装、配置一篇搞定(2026整理,送常用插件)
DeepSeek Harness(dsh)是DeepSeek AI于2026年开源的轻量级Agent运行框架,基于Cordis内核,践行“一切皆插件”理念。支持Web/桌面双端,开箱即用;内置多模型接入、丰富插件生态(超3.5万),适配编程、办公、创作等场景。(239字)
1791 1
|
2天前
|
弹性计算 人工智能 API
Codex超详细入门指南(下载·安装·登录·上手,全版本覆盖,2026最新版)
建议收藏本教程,2026 全年各版本更新随时回来查阅。如果你在搭建过程中遇到任何问题,欢迎结合 阿里云工单系统 提交技术支持请求,或在 阿里云开发者社区 搜索 Codex 相关话题交流。 祝你编码愉快,效率翻倍!
1208 0
|
8天前
|
人工智能 iOS开发 开发者
2026年 Codex 下载地址更新:codexdown.cn 已更换为 codexdown.cc(附 Codex 客户端下载)
2026年Codex官方下载站已由codexdown.cn正式迁移至codexdown.cc,提供Windows/macOS最新客户端、历史版本、安装教程及配置指南,开发者可一站式获取稳定、安全、签名验证的AI编程工具资源。(239字)
1639 0

热门文章

最新文章