LangChain.js-v1-记忆管理最佳实践

LangChain.js v1 记忆管理最佳实践createAgent 一站式方案Agent 默认不跨会话记忆。每轮对话结束后LLM 不会保留上一轮的上下文信息。这不是 bug。Agent 的底层设计就是无状态的——每次调用都是一张白纸LLM 只看你当前传入的消息。让 Agent 有记忆意味着在架构层面把状态管理补上。LangChain.js 的答案在 v1 里变得很清晰createAgent 统一入口把短期记忆和长期记忆收敛到同一个 API。从技术实现的角度可以把 Agent 的记忆需求拆成三层。会话连续性——同一轮对话别断掉你说过的话下一句 Agent 还能引用。跨会话持久化——明天打开 Agent 它还能认出你是谁、偏好什么。行为记忆——Agent 记住哪些工具调用路径有效、哪些踩过坑下次自动规避。这三层正好对应 v1 记忆体系的技术栈checkpointer 管会话连续性store 管跨会话持久化社区工具补充行为记忆。LangChain 的记忆体系从 v0.3 到 v1 经历了一次彻底重写旧版 ConversationBufferMemory 已经废弃取而代之的是基于 LCEL 和 LangGraph 的分层架构。接下来逐层展开。短期记忆checkpointer 让 Agent 记住刚才说了什么createAgent 是 v1 引入的统一 Agent 创建入口。它的 API 签名很简洁createAgent({model,tools,systemPrompt?,checkpointer?,store?,contextSchema?})其中 checkpointer 负责短期记忆。配置 MemorySaver 后Agent 自动获得会话级消息持久化能力。每次调用时传入同一个 thread_idAgent 就能在同一会话中保持上下文。import{createAgent,tool}fromlangchain;import{MemorySaver}fromlangchain/langgraph;constagentcreateAgent({model:openai:gpt-4o-mini,tools:[getWeather],systemPrompt:你是一个友好的助手用中文回答。,checkpointer:newMemorySaver(),});constconfig{configurable:{thread_id:session-001}};// 第一轮awaitagent.invoke({messages:[{role:user,content:你好我叫小明我在北京。}]},config);// 第二轮 —— 自动记住上下文constr2awaitagent.invoke({messages:[{role:user,content:我叫什么名字}]},config);// → 你叫小明thread_id 是这里的关键。同一个 thread_id 下的所有消息共享一份状态快照换一个 thread_id就是全新的上下文。这种隔离机制天然支持多用户场景——每个用户分配独立的 thread_id互不干扰。你甚至可以让同一个用户在不同话题间切换每个话题一个 thread_id。MemorySaver 存的是 Checkpoint——完整的状态快照包含消息历史、执行步骤和中间变量。也正因如此服务重启后所有数据丢失它只适合开发调试。需要持久化时checkpointer 还支持另外两种后端。SqliteSaver 把快照写入本地 SQLite 文件适合单机部署的小型项目——数据不丢零运维成本一个文件就能带走全部对话历史。PostgresSaver 则面向生产环境支持分布式部署和多实例共享状态。如果你的 Agent 服务跑在 Kubernetes 上、后面挂着多个 PodPostgresSaver 是生产环境多实例部署的推荐方案。三种后端共享同一个 checkpointer 接口切换只需修改初始化代码。长期记忆store 让 Agent 记住你是谁checkpointer 解决了刚才说了什么但管不了明天还能认出你。thread_id 重启后状态丢失只是表象更深层的问题是checkpointer 的作用域限定在单个会话内而用户偏好、项目背景、公司信息这些数据天然需要跨会话共享。store 就是为这个场景设计的。它是应用级的持久化存储配合 contextSchema 定义用户标识工具通过 runtime.store 显式读写。与 checkpointer 的自动透明管理不同store 要求开发者显式决定什么时候存、存什么、什么时候取——这给了你更多控制权但也意味着你得想清楚数据模型。import{createAgent,tool,typeToolRuntime}fromlangchain;import{InMemoryStore}fromlangchain/langgraph;conststorenewInMemoryStore();constcontextSchemaz.object({userId:z.string()});constgetUserInfotool(async(_,runtime:ToolRuntimeunknown,z.infertypeofcontextSchema){constuserInfoawaitruntime.store.get([users],runtime.context.userId);returnuserInfo?.value?JSON.stringify(userInfo.value):未找到;},{name:get_user_info,description:根据 userId 查找用户信息,schema:z.object({})});constsaveUserInfotool(async({name,city},runtime:ToolRuntimeunknown,z.infertypeofcontextSchema){awaitruntime.store.put([users],runtime.context.userId,{name,city});return已保存;},{name:save_user_info,description:保存用户信息,schema:z.object({name:z.string(),city:z.string()})});constagentcreateAgent({model:openai:gpt-4o-mini,tools:[getUserInfo,saveUserInfo],checkpointer:newMemorySaver(),store,contextSchema,});contextSchema 定义了什么信息标识一个用户这里是 userIdAgent 在每次调用时从 config 中提取上下文工具内部通过 runtime.context 即可拿到。store 的数据键采用命名空间 键的二级结构——比如[users], userId——方便按业务领域组织数据。Checkpointer 和 store 的分工很明确但初学者容易混淆。一张表说清楚维度Checkpointer短期记忆Store长期记忆作用域单个 thread会话级跨所有 thread应用级存储内容完整状态快照消息、步骤、中间变量应用自定义数据用户偏好、事实、知识典型用途对话连续性、人机交互中断用户画像、跨会话知识、全局配置API 模式自动管理框架透明处理通过工具显式读写runtime.store数据键thread_id 自动隔离命名空间 键如 [“users”], userId后端实现MemorySaver / SqliteSaver / PostgresSaverInMemoryStore / PostgresStore一个判断标准如果数据生命周期跟一次对话绑定用 checkpointer如果数据需要跨对话、跨设备、跨时间存在用 store。超长对话当上下文膨胀到 LLM 吃不消checkpointer 虽然自动记录所有历史消息但它不会帮你做任何裁剪。一轮对话跑到几百条消息之后上下文窗口会被塞满响应变慢、token 消耗飙升甚至超出模型上下文限制直接报错。对于 Coding Agent 这类需要长时间密集交互的场景这个问题尤其突出。这种场景下需要在 checkpointer 之上叠加一层摘要策略。核心思路是当对话历史超过某个 token 阈值时自动将早期消息压缩为摘要保留近期消息的完整内容摘要部分作为背景知识前置注入。具体实现上可以在每次状态写入时检查 token 使用量一旦超过阈值就对历史消息执行摘要压缩。保留策略通常是近期 N 条消息 摘要的组合——既保留最近对话的细节又不会丢失早期的关键信息。触发阈值的选择取决于你使用的模型上下文窗口。建议将阈值设在窗口的 10%-15% 以内留出足够空间给当前轮次的思考和工具调用。要注意的是摘要本身会丢失信息。如果对话中涉及精确数据——比如用户报了一个订单号、一段配置参数——这些信息被压缩进摘要后可能变形。一个实用的做法是在 store 中单独存储这类不可压缩的结构化数据摘要只保留叙事性的上下文。社区工具推荐当内置方案不够用createAgent 的 checkpointer store 组合覆盖了大部分基础记忆需求但在行为记忆和用户画像构建这两个方向上社区有一些更专业的轮子。agentmemoryGitHub: rohitg00/agentmemoryMIT 协议23,000 Stars是目前最推荐的 Coding Agent 行为记忆方案。它的核心思路是零干预——通过 Hook 机制自动静默捕获所有 Agent 工具调用存入本地 SQLite。检索时走 BM25 全文 向量语义 知识图谱遍历经 RRF 融合排序据项目方公布的基准测试召回率达 95.2%远超同类方案 mem0 的 68.5%。关键是不需要调用任何 LLM 来写入或检索记忆这对高频 Coding Agent 场景来说能省下可观的 token 成本。通过 MCP 协议接入一行命令即可npx agentmemory/mcp。零 LLM 调用意味着没有网络往返开销记忆读写成本远低于调用 LLM 的方案。mem0GitHub: mem0ai/mem0Apache 2.041,000 Stars面向 LLM 应用的用户画像构建从对话中自动提取结构化事实。但每次写入记忆都需要调用 LLM部署还需要 Qdrant 或 Chroma 向量数据库。如果你的场景是面向 C 端用户的聊天产品mem0 的用户画像提取能力很对口但 Coding Agent 场景下agentmemory 的零 LLM 调用模式显然更经济。TencentDB Agent MemoryGitHub: Tencent/TencentDB-Agent-MemoryApache 2.02026 年 4 月开源是中文场景的首选。它采用四层渐进式记忆架构L0 原始对话、L1 原子记忆、L2 场景分块、L3 用户画像。纯 SQLite零外部依赖对中文分词和语义理解做了针对性优化信创和私有化部署场景友好。L1 层需要调用 LLM 做记忆提取但整体架构比 mem0 更轻量。如果你需要在国内服务器上部署、且用户交互以中文为主TencentDB Agent Memory 是中文场景最自然的选择。QMD由 Shopify CEO 发起是 OpenClaw 生态的核心工具对 workspace 下的 Markdown 文件建立 BM25 向量双重索引经 Reranker 融合排序三模型管线Embedding Reranker Query Expansion完全离线约 2.3GB适合文档驱动的记忆场景。Cognee专注知识图谱ECL 三阶段Extract 识别实体 → Cognify 推断关系 → Load 写入图数据库回答A 和 B 有什么关系这类推理性问题支持 PDF、DOCX、音频、图片等多种格式。Zep CE的独特卖点是时序感知——不仅记住说了什么还记住什么时候说的、是否已被更新覆盖2026 年与 LangGraph 深度整合但需要 Postgres pgvector部署较重。如果对照 LangMem 官方提出的三类记忆框架语义记忆存事实、程序记忆存行为规则、事件记忆存 Few-shot 示例社区工具的对应关系大致是语义记忆匹配 mem0 或 TencentDB Agent Memory程序记忆匹配 agentmemory事件记忆匹配 agentmemory 配合 Zep。选型不要求全。关键在于你的 Agent 最缺哪种记忆——是记不住用户偏好还是记不住工具调用的经验——然后只引入对应的那一款。三层搭配从最小启动到生产就绪从 checkpointer 起步按需叠加 store 和社区方案。记忆不是越多越好。每一层记忆都有它的存储成本和检索延迟盲目堆叠只会让 Agent 变慢、变贵、变难调试。从最小集合开始被用户真正抱怨的痛点驱动着往上加才是务实的策略。