LangGraph 持久化与长期记忆怎么配:Checkpointer、Store 与 PostgreSQL 实战

在生产环境跑 LangGraph,单靠 InMemorySaver 一重启就会丢失全部对话。本文按官方文档讲清线程内短期检查点(Checkpointer)与跨线程长期记忆(Store)的分工,以及用 langgraph-checkpoint-postgres 对接 PostgreSQL 的完整步骤。

NNathaniel bigo··原创首发·AI 辅助撰写
9 分钟读完
资料核对于 2026-11-18 · 依据官方文档与公开资料整理 免费账号 账号

结论先说

  1. LangGraph 把记忆明确拆成两套各司其职的组件:Checkpointer(检查点) 管「当前这一个对话窗口(thread_id)聊到了哪一步」,Store(长期存储) 管「同一个用户(user_id)打开新窗口也该记住的长期偏好」。
  2. 上线生产首选开源免费的 langgraph-checkpoint-postgres:无需购买商业托管平台(费用边界见 /guides/langgraph-pricing-open-source-vs-platform),直接连你们自己的 PostgreSQL 即可支撑多节点无状态扩容。
  3. 首次连上空数据库后必须先调一次 .setup():用于自动创建存放快照与记忆键值所需的系统数据表。
  4. FastAPI 异步生产服务请统一用异步版 AsyncPostgresSaver 与 AsyncPostgresStore,避免同步数据库驱动阻塞整个异步事件循环。

Checkpointer 与 Store 双层记忆对比

图:本站根据 LangGraph 官方文档 Persistence 与 Memory 整理的示意图

本文根据 LangChain / LangGraph 官方文档《Persistence》《Memory》与 langgraph-checkpoint-postgres 仓库文档整理,核对日期 2026-11-18。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 LangChain 官方网站。

适用于谁

  • 搜「langgraph postgres checkpointer」「langgraph 长期记忆 store」「langgraph 持久化」的后端开发者;
  • 在入门示例(见 /guides/langgraph-quickstart-install-first-graph)里用通了内存保存器,准备把服务搬上多实例生产容器、解决重启丢记录问题的人;
  • 发现用户开一个新对话窗口(换了新 thread_id)后,智能体就把该用户的老习惯全忘了,想知道怎么跨会话共享用户画像的人。

一、先彻底分清:什么时候查 Checkpointer、什么时候读写 Store

很多人在做聊天应用时只配了 checkpointer,上线后马上遇到一个典型尴尬:用户小张昨天在「会话 A」里交代过「我是素食主义者、报告一律用表格展示」;今天小张点左上角「新建对话」开启了「会话 B」(分配了全新的 thread_id),智能体瞬间把这两条偏好忘得一干二净。

原因就在于两层存储的键维度完全不同:

  • Checkpointer(按 thread_id 隔离):保存的是每一次节点跳转后的完整 State 快照。它的本职工作是支撑多轮追问、人工审批挂起恢复(见 /guides/langgraph-human-in-the-loop-interrupt-guide)与断点时间旅行。不同 thread_id 之间互不可见;
  • Store(按自定义命名空间如 ("memories", user_id) 组织):它是一个独立于具体线程之外的跨会话文档库(还可选配向量语义检索)。无论小张新建多少个聊天窗口,只要节点按他的 user_id 去 store 里查,就能读出他之前沉淀下来的个人档案。

接入 PostgreSQL 持久化四步流程

图:本站根据 langgraph-checkpoint-postgres 官方文档 整理的示意图

二、安装依赖与连接 PostgreSQL 双层存储示例

如果你只是在单机写桌面小工具,装 langgraph-checkpoint-sqlite 落盘成单个本地文件就够用;如果是多实例后端服务,直接安装官方的 PostgreSQL 包与底层 psycopg(v3)驱动:

bash
pip install -U langgraph langgraph-checkpoint-postgres "psycopg[binary,pool]"

下面的异步代码展示了如何同时启用 AsyncPostgresSaver 和 AsyncPostgresStore,并在节点函数里通过类型注解自动拿到 BaseStore 实例读写跨会话记忆:

python
import asyncio
import uuid
from langchain_core.runnables import RunnableConfig
from langgraph.graph import StateGraph, MessagesState, START, END
from langgraph.checkpoint.postgres.aio import AsyncPostgresSaver
from langgraph.store.postgres.aio import AsyncPostgresStore
from langgraph.store.base import BaseStore

DB_URI = "postgresql://postgres:[email protected]:5432/agent_db"

async def chat_node(state: MessagesState, config: RunnableConfig, *, store: BaseStore):
    user_id = config["configurable"]["user_id"]
    namespace = ("user_profiles", user_id)

    # 1. 跨线程读取该用户过往保存的所有长期偏好
    saved_items = await store.asearch(namespace)
    prefs = [item.value.get("note", "") for item in saved_items]

    last_text = state["messages"][-1].content
    # 2. 若用户本轮明确交代记住某事,写入跨会话 Store
    if "请记住:" in last_text:
        await store.aput(namespace, str(uuid.uuid4()), {"note": last_text})

    summary = ";".join(prefs) if prefs else "暂无历史偏好"
    reply = f"已读取您的跨会话档案({summary}),收到本轮消息:{last_text}"
    return {"messages": [("assistant", reply)]}

async def main():
    async with (
        AsyncPostgresSaver.from_conn_string(DB_URI) as checkpointer,
        AsyncPostgresStore.from_conn_string(DB_URI) as store,
    ):
        # 首次连接空库时执行建表迁移(幂等操作)
        await checkpointer.setup()
        await store.setup()

        builder = StateGraph(MessagesState)
        builder.add_node("chat", chat_node)
        builder.add_edge(START, "chat")
        builder.add_edge("chat", END)

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

        # 会话 1:写入一条长期偏好
        cfg_thread_1 = {"configurable": {"thread_id": "t-001", "user_id": "u_zhang"}}
        await graph.ainvoke({"messages": [("user", "请记住:报表统一用周度口径")]}, cfg_thread_1)

        # 会话 2:换了全新的 thread_id,依然能从 store 读出刚才存下的偏好
        cfg_thread_2 = {"configurable": {"thread_id": "t-002", "user_id": "u_zhang"}}
        out = await graph.ainvoke({"messages": [("user", "帮我生成本周汇总")]}, cfg_thread_2)
        print(out["messages"][-1].content)

if __name__ == "__main__":
    asyncio.run(main())

三、生产环境连接池与 CLI 部署避坑提醒

  1. 手动建连接池必配两个参数:from_conn_string 适合快速测试;在长生命周期的 FastAPI 应用生命周期(lifespan)里自建 AsyncConnectionPool 时,官方文档特别强调必须在连接参数里打开 autocommit=True 和 row_factory=dict_row,否则 .setup() 建表事务不提交或读取行字段时报键错误;
  2. 与 langgraph.json 托管模式区分开:如果你是用官方 CLI 服务启动(配置见 /guides/langgraph-json-config-guide),服务端框架会自动接管底层的 checkpointer 与 store 注入,节点函数里照常声明 *, store: BaseStore 即可直接用,不需要在 compile() 时手工传连接串;
  3. 控制检查点表体积膨胀:高频工具循环每走一步都会写一行快照,对已经完结超过几十天的陈旧临时会话,建议定期按 thread_id 清理归档。日常用大模型辅助编写数据库清理脚本或排查连接池异常时,个人官方订阅说明也可参考 /chongzhi/chatgpt-plus。

常见问题

Q:Store 支持按自然语言语义搜索几百条历史记忆吗?

支持。在初始化 PostgresStore(或 InMemoryStore)时传入 index={"embed": 嵌入模型, "dims": 向量维度} 并确保 PostgreSQL 开启了 pgvector 扩展后,store.asearch(namespace, query="饮食习惯") 就会自动执行向量相似度检索,只召回最相关的几条记忆省下上下文。

Q:报 psycopg.OperationalError 连不上本地数据库怎么查?

先确认连接串里的端口、库名是否已提前手动 CREATE DATABASE agent_db;(.setup() 只负责在已有库内建表,不会替你新建数据库本身),并核对密码含特殊符号时是否做了 URL 编码。

相关教程

参考资料

  • LangChain / LangGraph 官方文档:Persistence & Memory Store — https://docs.langchain.com/
  • langchain-ai/langgraph 官方 GitHub 仓库 — https://github.com/langchain-ai/langgraph

Nathaniel 的更多内容

  1. 01

    LangGraph 流式输出(Streaming)详解:逐字 Token 流、节点进度与自定义事件写法

    多步智能体如果等全部节点跑完才返回,网页前端就会白屏干等十几秒。本文按 LangGraph 官方文档讲清 updates、messages、custom 与 values 四种 stream_mode 的区别,以及组合订阅逐字打字机输出加工具内部实时进度的完整代码。

    其他 AI 工具0
  2. 02

    LangGraph 多智能体怎么写:Supervisor 主管包与 Subgraph 隔离子图实战

    在 LangGraph 里把单个图扩展成多智能体协作有两条官方路线:快速原型用预置包 langgraph-supervisor,大型生产系统用原生子图(Subgraph)嵌套。本文讲清两种写法的完整代码、私有状态隔离防 Token 膨胀技巧以及检查点传播规则。

    其他 AI 工具0
  3. 03

    LangGraph 人工介入审批怎么写:interrupt 暂停图运行与 Command 恢复实战

    企业之所以选 LangGraph,很大程度看中它能安全挂起等待人工审批(Human-in-the-Loop)。本文按官方最新规范讲清 interrupt() 动态暂停、Checkpointer 必备条件、Command(resume=...) 恢复执行,以及防止副作用重复运行的重入规则。

    其他 AI 工具0
  4. 04

    多 Agent 协作平台怎么选:Dify、扣子(Coze)、n8n 与 LangGraph 多智能体机制对比

    搜「多agent协作平台」时,Dify、扣子、n8n 和 LangGraph 都宣称支持多智能体,但底层的调度方式完全不同。本文跳过基础安装,专门从多 Agent 角色跳转、子代理工具调用、上下文隔离与私有化部署四个维度帮你一次选准。

    其他 AI 工具0
  5. 05

    企业微信有官方 MCP 和 CLI 吗:@wecom/cli 安装初始化、长连接机器人与接入教程

    搜「企业 微信 有 mcp 吗」不用再东拼西凑民间群机器人脚本了:企业微信官方已推出 @wecom/cli 命令行工具并内置 stdio 模式的 MCP Server。本文按官方开发者文档讲清安装、智能机器人长连接初始化、业务命令与接入 Claude Code 步骤。

    Claude其他 AI 工具0
  6. 06

    MCP 收费吗:开源协议免费边界、第三方 API 账单与隐形 Token 开销说明

    搜「mcp 收费 吗」的人常担心装多了插件会被扣费。MCP(模型上下文协议)本身和官方 SDK 采用 MIT 协议完全免费;实际使用中可能产生费用的只有两处:挂载过多工具占用的大模型上下文 Token,以及部分外部商业数据源自带的 API 套餐。

    Claude其他 AI 工具0

同产品的其他教程

  1. 01

    MCP 协议最新版本更新了什么:无状态架构、OAuth 2.1、结构化输出与异步 Tasks 详解

    搜「mcp 重大 更新」「mcp 协议 更新」想补齐规范演进脉络?本文对照 modelcontextprotocol.io 官方规范更新日志,梳理从 Streamable HTTP 到无状态优先架构、OAuth 2.1 资源服务器、Elicitation 交互补参与异步 Tasks 扩展的核心变化。

    Claude其他 AI 工具0
  2. 02

    A2A 和 MCP 有什么区别:工具连接协议与智能体通信协议的边界和配合

    很多人问「有了 MCP 为什么还要出 A2A,两者是不是二选一的竞争关系」。两份官方规范都明确写明它们是上下互补关系:MCP 负责给单个智能体挂载工具与数据源,A2A 负责让多个独立黑盒智能体跨团队、跨框架互相派单协作。

    Claude其他 AI 工具0
  3. 03

    A2A 协议是什么、怎么用:Agent2Agent 智能体互联规范、名片发现与 Python 接入流程

    A2A(Agent2Agent)是由 Google 发起并移交 Linux 基金会托管的开放智能体通信协议,用来让不同团队、不同框架开发的独立智能体跨网络互相派单协作。本文按官方规范讲清 Agent Card、Task 状态机与 Python SDK 接入步骤。

    Gemini其他 AI 工具0
  4. 04

    AutoGen 现在怎么样了?微软官方演进路线与 Microsoft Agent Framework 入门

    搜 AutoGen 新教程常被 0.2、0.4、社区分支和 Semantic Kernel 绕晕。按微软官方文档,微软已将 AutoGen 与 Semantic Kernel 两支团队合并推出统一的开源框架 Microsoft Agent Framework。本文讲清现状与 Python 快速上手。

    ChatGPT其他 AI 工具0
  5. 05

    CrewAI 多轮对话与记忆怎么配:memory=True 三层记忆、人工介入与 Flows 状态持久化

    刚用上 CrewAI 的人常疑惑 kickoff 跑完就结束,怎么做多轮连续对话与跨次记忆。本文按官方文档拆解 memory=True 的短期/长期/实体三层记忆、嵌入模型配置,以及用 Flows 状态流和 @persist 搭建多轮会话的实战写法。

    其他 AI 工具0
  6. 06

    CrewAI 入门教程:Agent 角色、Task 任务、执行流程(Process)与第一个团队示例

    CrewAI 是主打「拟人化角色分工」的 Python 多智能体开源框架。本文按官方文档讲清安装要求、Agent(角色/目标/背景)、Task(任务描述与预期输出)和 Process(顺序接力与经理层级模式)的配合逻辑,并给出最小可运行代码。

    其他 AI 工具0

0 条评论

登录 后参与评论

还没有评论,来抢沙发~