LangChain / LangGraph Memory 记忆体系技术文档作用域判定 · 官方现版本实现 · 工程坑点本文在保留原稿「作用域判定」核心思想的基础上按LangChain 官方现版本0.3 / 1.0重写了实现层。 ⚠️ 原稿第一节列出的ConversationBufferMemory等 7 个 Memory 类已被官方废弃并在 1.0 移除 现版本from langchain.memory import ...会直接抛ImportError。详见 §2.4 废弃对照表。一、核心判定原则全文纲领原稿此节完全正确短期记忆 / 长期记忆的划分与底层存储介质无关判定标准只有业务作用域是否支持跨会话cross-session复用。类型作用域官方对应机制是否跨会话短期记忆绑定单一会话线程thread_idCheckpointer❌ 换 thread_id 即清空长期记忆跨多个会话线程namespaceStore✅ 新开对话仍可召回短期记忆维持本轮对话上下文。即使持久化入库如存 PG也仅供当前 thread 断点续传不会给全新会话复用。长期记忆新开对话依然可召回不会一次性全塞进 Prompt采用按需检索仅将相关片段注入上下文。重要呼应原稿这套「按作用域划分、与介质无关」的思想恰好就是 LangChain 官方新架构的设计哲学。 官方把持久化明确拆成两套互补系统 -Checkpointers—— 将线程的图状态持久化为检查点用于线程内的短期记忆 -Stores—— 在图状态之外持久化应用定义的数据用于跨线程的长期记忆。 官方原文Most applications can use both: checkpointer to track the current thread, store to track persistent information across threads.二、短期记忆会话内记忆2.1 业务作用与数据特点保存当前会话上下文让大模型知晓本轮对话历史、Agent 工具调用过程、上一轮返回结果是维持单轮对话连贯性的基础。维度说明数据内容完整对话消息含 ToolMessage注入方式全量注入LLM 上下文窗口约束受 Token 上限约束需裁剪/摘要作用域单个thread_id2.2 现版本官方实现LangGraph Checkpointerfrom langgraph.checkpoint.memory import InMemorySaver # 开发 from langgraph.checkpoint.postgres import PostgresSaver # 生产 from langgraph.graph import StateGraph, MessagesState, START DB_URI postgresql://user:pwdhost:5432/db?sslmodedisable with PostgresSaver.from_conn_string(DB_URI) as checkpointer: checkpointer.setup() # ⚠️ 首次使用必须调用 graph builder.compile(checkpointercheckpointer) graph.invoke({messages: [{role: user, content: hi, Im Bob}]}, {configurable: {thread_id: user-1-thread-a}})thread_id就是会话主键。同一个 thread_id 续聊换一个 thread_id 就是全新会话。2.3 存储介质选型介质实现适用说明内存InMemorySaver旧名MemorySaver仅开发/测试进程重启即丢失SQLiteSqliteSaver本地需持久化的开发单文件跨重启PostgreSQLPostgresSaver/AsyncPostgresSaver生产多实例首选多副本共享状态RedisRedis checkpointer高频短会话需自行实现/选型⚠️原稿说「Redis 生产首选」需加限定Redis 适合带 TTL 的短会话缓存一旦需要断点续传/人在回路/时间旅行LangGraph 的核心能力必须落到 PG——因为 checkpointer 存的是图状态快照不是简单消息列表Redis 做 TTL 自动过期会把未完成流程的状态抹掉。2.4 ⚠️ 废弃对照表原稿第一节的 7 个类 → 官方替代原稿 Memory 类现版本状态官方替代ConversationBufferMemoryv0.3.1 弃用 / 1.0 移除LangGraph CheckpointerMemorySaver/PostgresSaverConversationBufferWindowMemory同上Checkpointer 节点内trim_messages(max_tokens...)ConversationTokenBufferMemory同上Checkpointer trim_messages按 token 显式裁剪ConversationSummaryMemory同上自建摘要节点定期摘要并写回 stateConversationSummaryBufferMemory同上摘要节点 trim_messages工程推荐组合ConversationEntityMemory同上Store语义记忆 实体抽取节点ConversationKGMemory同上图数据库 / Store外部集成关键事实LangChain 1.0from langchain.memory import ConversationBufferMemory → ImportError不是 DeprecationWarning 这些 legacy 类连同 ConversationChain 一起迁到独立的 langchain-classic 包。官方迁移一行总结History lives in the graph state, not in a memory object.为什么这套 API 会被淘汰值得写进复盘 每一代 LangChain 记忆方案都耦合在具体编排层上BufferMemory→ 绑定ConversationChainRunnableWithMessageHistory→ 绑定 LCELCheckpointer→ 绑定 LangGraph。编排层一重构记忆方案就跟着碎。这是结构性问题不是 bug。 → 工程启示尽量把记忆内容的 schema 与业务语义握在自己手里PG 表结构让框架只负责存取别把记忆长在框架的抽象里。2.5 短期记忆管理官方三种手段手段作用适用Trim messages按 token/条数裁剪通用最简单Delete messages删除指定消息清理敏感/无效轮次Summarize messages老轮次压成摘要长会话节省 token三、长期记忆跨会话记忆3.1 业务作用与数据特点持久存储跨会话信息新会话可召回用户偏好、历史任务经验、业务事实、执行策略。维度短期记忆长期记忆作用域单 thread跨 threadnamespace注入方式全量注入按需检索仅命中片段数据形态原始消息序列结构化事实 / 向量片段 / 规则典型介质内存 / Redis / PGPG 表 / PGVector / Store为什么长期记忆必须按需检索而不全塞除了 token 成本还有个硬原因Lost in the Middle。研究显示模型的准确率呈U 形曲线—— 相关信息在输入开头或结尾时准确率最高埋在中间时急剧下降。 所以上下文窗口够大不等于可以全塞进去放对位置、做精选和容量本身一样重要。3.2 现版本官方实现LangGraph Storefrom langgraph.store.memory import InMemoryStore # 开发 from langgraph.store.postgres import PostgresStore # 生产 store InMemoryStore() # 或 PostgresStore namespace (user_id, memories) # ⚠️ 是 tuple不是字符串 store.put(namespace, str(uuid.uuid4()), {food_preference: I like pizza}) items store.search(namespace, query用户喜欢吃什么, limit3)⚠️ 只传 checkpointer 是最常见的架构错误—— 那样只得到持久化的聊天记录不会自动得到跨会话的用户知识。两者必须同时配置graph builder.compile(checkpointercheckpointer, storestore)3.3 三类长期记忆Agent 架构常用分类原稿分类与官方一致 ✅类型英文存什么例子推荐存储语义记忆Semantic事实、用户偏好用户习惯简洁回答、技术栈偏好PG 结构化表profileschema 严格情景记忆Episodic过往任务、历史交互上次执行的任务、报错与处理过程PGVectorcollection向量检索程序记忆Procedural流程、规则、执行策略Agent 工具调用规范、任务处理步骤配置表 / 知识库 / 可改写 system promptLangMemLangChain 官方长期记忆 SDK把这三类都实现了其中程序记忆Agent 根据反馈改写自己的 system prompt是它独有的能力。3.4 存储介质选型含集成路径变更介质适用备注PostgreSQL 普通表结构化长记忆用户偏好、基础配置工程落地首选PGVector情景记忆、历史交互片段复用现有 PG无需独立向量库向量数据库Chroma / Milvus / Qdrant海量片段检索千万级以上中小规模不必引入Markdown / JSON 文件仅原型 Demo生产不推荐无并发、无多用户管理图数据库实体关系、知识图谱多跳关系场景⚠️PGVector 集成路径已变更原稿未覆盖路径状态langchain_community.vectorstores.PGVector已弃用langchain-community 归档langchain_postgres.PGVector正在被淘汰✅langchain_postgres.PGEnginePGVectorStore新项目应直接用这个⚠️驱动坑langchain-postgres要求psycopg3包名psycopg不是psycopg2也不是asyncpg。 连接串要写成postgresqlpsycopg://...安装psycopg[binary,pool]。 大量旧教程仍用 psycopg2照抄会直接报错。四、常见误区澄清#误区正解1❌ 存数据库 长期记忆放内存 短期记忆✅介质不决定记忆类型。PG 存thread_id绑定的会话消息只用于当前会话断点续传 →短期记忆PG 存用户偏好新会话可读 →长期记忆2❌ 长记忆只能用 MD 文件保存✅ MD 仅适合原型。正式工程结构化长记忆用 PG历史片段用 PGVector3❌ 配了 checkpointer 就有跨会话记忆了✅最常见的架构错误。checkpointer 只管单 thread跨会话必须另外配Store4❌ 长期记忆应该全量注入 prompt✅ 按需检索。全量注入除了 token 成本还会触发Lost in the Middle中间信息准确率骤降5❌MemorySaver可以上生产✅ 它是InMemorySaver进程重启即失生产用PostgresSaver6❌ 记忆写在请求同步路径上✅ 记忆抽取要放后台对话结束后异步跑否则拖慢响应五、记忆体系坑点清单工程必读5.1 摘要记忆丢失细节不可逆摘要是有损压缩一旦压掉就找不回来。LangMem 官方也点出两难过度抽取 → 精度下降抽取不足 → 召回率低。风险表现数字/ID/代码被改写摘要里用户提到订单号丢失了具体单号时序被压平先做了 A 再做了 B 压成 做了 A 和 B否定被吞不要用 MySQL 压成 数据库选型对策关键事实数字、ID、代码、时间、否定判断必须结构化入库摘要只用于压缩过程性叙述不能作为唯一事实源。5.2 向量检索召回错误坑说明对策相似度 ≠ 相关性embedding 模型决定召回天花板语义相近但业务无关会被召回相似度 重要性时效强度近期/频繁使用加权组合打分多跳关系召回不到「Acme 的负责人是 DanaDana 偏好 Slack」——单条片段里没有完整链路纯向量检索抓不到引入图结构实体关系辅助召回过滤导致结果不足over-filtering向量检索叠加WHERE过滤后返回条数不够pgvector 0.8 的iterative index scanhnsw.iterative_scan索引与算子不匹配用vector_cosine_ops建的索引查询用 L2 距离 →退化成全表扫描opclass 与查询算子必须对齐cosine ↔5.3 记忆冲突与过时长期记忆第一大坑用户偏好会变第 3 轮说用 Python第 47 轮说改用 TypeScript——两条都在库里相似度检索可能返回任意一条Agent 给出自相矛盾的回答。⚠️注意 2026 年的变化Mem0 v2.0.02026-04把抽取改成了单次 ADD-only一次 LLM 调用抽出新事实直接追加不再自动与已有记忆做 UPDATE/DELETE 调和官方去重仅剩精确匹配MD5。 好处是延迟减半、评测分数大涨代价是记忆库不再自动自纠矛盾事实会并存。→记忆一致性成了你自己流水线的责任不再是数据库的能力。必须自建调和机制定期 LLM 对账 / 版本号 失效标记 / 按时间优先。5.4 Store 使用坑官方细节极易踩坑说明limit默认 10超出静默截断没有任何溢出信号。要显式设大或offset分页namespace_prefix是前缀匹配不是精确匹配查(alice,)会连(alice,memories)、(alice,preferences)一起返回 → 命名空间污染默认排序依赖后端实现PostgresStore按updated_at降序最新在前InMemoryStore按插入顺序最新在最后→ 不要跨实现依赖顺序需排序就客户端按updated_at排indexFalse存了但搜不到Store 语义搜索需配置index{embed:..., dims:..., fields:[...]}不配置或关闭则该条不可被语义检索5.5 Checkpointer 使用坑坑说明首次必须checkpointer.setup()PostgresSaver 第一次使用要建表langgraph dev可能静默忽略自定义 checkpointer状态落在内存里每次热重载销毁→ 你以为有持久化实际没有Redis TTL 会抹掉未完成流程checkpointer 存的是图状态快照不是消息列表TTL 过期 未完成的 human-in-the-loop 流程丢失5.6 LangMem 性能坑直接决定架构LangMem 检索延迟可能达到接近 1 分钟级别且版本尚未到 1.0。→只能放后台异步整理记忆绝不能放在用户同步请求路径上。推荐架构请求路径只读记忆PG/PGVector 直查毫秒级记忆抽取/整理放后台任务对话结束后触发。六、工程选型建议本 AG / Agent 项目层次选型理由短期会话记忆PostgresSavercheckpointer Redis 做热会话缓存需要断点续传 / 人在回路 → 必须持久化Redis 只做加速不唯一持有结构化长期记忆用户偏好、配置PostgreSQL 普通表schema 严格、可审计、可直接 JOIN历史任务情景记忆PGVector复用现有 PG中小规模无需独立向量库注意用新集成路径PGVectorStore记忆抽取链路后台异步对话结束后触发避免拖慢用户响应LangMem 延迟高不能同步用一致性维护自建调和流水线定期对账 / 版本 失效标记现成库不再自动去重矛盾落地最小骨架# 短期checkpointer 按 thread_id # 长期store 按 (user_id, memories) namespace # 两者同时编译进图 checkpointer PostgresSaver.from_conn_string(DB_URI) store PostgresStore.from_conn_string(DB_URI) # 语义搜索配 index graph builder.compile(checkpointercheckpointer, storestore) config {configurable: {thread_id: thread_id, user_id: user_id}} result await graph.ainvoke({messages: [...]}, configconfig) # 响应返回后再异步触发记忆抽取不阻塞用户 asyncio.create_task(extract_and_consolidate_memories(user_id, result[messages]))七、精简摘要可用于 PPTLangChain 记忆划分不依赖存储介质核心看作用域。短期记忆绑定单一会话线程thread_id/ Checkpointer维持本轮上下文可放内存、Redis、PostgreSQL长期记忆支持跨会话召回namespace/ Store存储用户偏好与历史任务可用 PG、PGVector。短期记忆全量注入 Prompt长期记忆按需检索、仅召回相关片段。一句话记忆Checkpointer 管这次聊到哪Store 管这个用户是谁。两者都要配。八、版本与迁移速查项结论ConversationBufferMemoryv0.3.1 弃用1.0 移除→ 迁langchain-classic或改用 CheckpointerConversationChain/LLMChain已移除 → LCEL / LangGraphRunnableWithMessageHistory自 v0.3 起标记弃用 → 用 CheckpointerMemorySaver现名InMemorySaver仅开发用langchain_community.vectorstores.PGVector已弃用 →langchain_postgres.PGVectorStorepsycopg 驱动langchain-postgres 需psycopg3postgresqlpsycopg://检测手段pytest -W error::DeprecationWarning—— 把弃用警告变成测试失败任何残留的旧模式在上线前就会暴露。