LangChain.js v1 记忆管理最佳实践:createAgent 一站式方案

简介: LangChain.js v1 推出 `createAgent` 一站式记忆方案,分三层解决Agent状态管理:`checkpointer`保会话连续性,`store`持跨会话长期记忆,社区工具补行为记忆。告别无状态设计,实现可扩展、可持久、可调试的智能体记忆体系。

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 的分层架构。接下来逐层展开。

image.png

短期记忆:checkpointer 让 Agent 记住"刚才说了什么"

createAgent 是 v1 引入的统一 Agent 创建入口。它的 API 签名很简洁:

createAgent({
    model, tools, systemPrompt?, checkpointer?, store?, contextSchema? })

其中 checkpointer 负责短期记忆。配置 MemorySaver 后,Agent 自动获得会话级消息持久化能力。每次调用时传入同一个 thread_id,Agent 就能在同一会话中保持上下文。

import {
    createAgent, tool } from "langchain";
import {
    MemorySaver } from "@langchain/langgraph";

const agent = createAgent({
   
  model: "openai:gpt-4o-mini",
  tools: [getWeather],
  systemPrompt: "你是一个友好的助手,用中文回答。",
  checkpointer: new MemorySaver(),
});

const config = {
    configurable: {
    thread_id: "session-001" } };

// 第一轮
await agent.invoke(
  {
    messages: [{
    role: "user", content: "你好!我叫小明,我在北京。" }] },
  config
);

// 第二轮 —— 自动记住上下文
const r2 = await agent.invoke(
  {
    messages: [{
    role: "user", content: "我叫什么名字?" }] },
  config
);
// → "你叫小明"

thread_id 是这里的关键。同一个 thread_id 下的所有消息共享一份状态快照;换一个 thread_id,就是全新的上下文。这种隔离机制天然支持多用户场景——每个用户分配独立的 thread_id,互不干扰。你甚至可以让同一个用户在不同话题间切换,每个话题一个 thread_id。

MemorySaver 存的是 Checkpoint——完整的状态快照,包含消息历史、执行步骤和中间变量。也正因如此,服务重启后所有数据丢失,它只适合开发调试。

需要持久化时,checkpointer 还支持另外两种后端。SqliteSaver 把快照写入本地 SQLite 文件,适合单机部署的小型项目——数据不丢,零运维成本,一个文件就能带走全部对话历史。PostgresSaver 则面向生产环境,支持分布式部署和多实例共享状态。如果你的 Agent 服务跑在 Kubernetes 上、后面挂着多个 Pod,PostgresSaver 是生产环境多实例部署的推荐方案。三种后端共享同一个 checkpointer 接口,切换只需修改初始化代码。

01-infographic-三层记忆架构.png

长期记忆:store 让 Agent 记住"你是谁"

checkpointer 解决了"刚才说了什么",但管不了"明天还能认出你"。thread_id 重启后状态丢失只是表象,更深层的问题是:checkpointer 的作用域限定在单个会话内,而用户偏好、项目背景、公司信息这些数据天然需要跨会话共享。

store 就是为这个场景设计的。它是应用级的持久化存储,配合 contextSchema 定义用户标识,工具通过 runtime.store 显式读写。与 checkpointer 的"自动透明管理"不同,store 要求开发者显式决定什么时候存、存什么、什么时候取——这给了你更多控制权,但也意味着你得想清楚数据模型。

import {
    createAgent, tool, type ToolRuntime } from "langchain";
import {
    InMemoryStore } from "@langchain/langgraph";

const store = new InMemoryStore();
const contextSchema = z.object({
    userId: z.string() });

const getUserInfo = tool(
  async (_, runtime: ToolRuntime<unknown, z.infer<typeof contextSchema>>) => {
   
    const userInfo = await runtime.store.get(["users"], runtime.context.userId);
    return userInfo?.value ? JSON.stringify(userInfo.value) : "未找到";
  },
  {
    name: "get_user_info", description: "根据 userId 查找用户信息", schema: z.object({
   }) }
);

const saveUserInfo = tool(
  async ({
    name, city }, runtime: ToolRuntime<unknown, z.infer<typeof contextSchema>>) => {
   
    await runtime.store.put(["users"], runtime.context.userId, {
    name, city });
    return "已保存";
  },
  {
    name: "save_user_info", description: "保存用户信息", schema: z.object({
    name: z.string(), city: z.string() }) }
);

const agent = createAgent({
   
  model: "openai:gpt-4o-mini",
  tools: [getUserInfo, saveUserInfo],
  checkpointer: new MemorySaver(),
  store,
  contextSchema,
});

contextSchema 定义了什么信息标识一个用户(这里是 userId),Agent 在每次调用时从 config 中提取上下文,工具内部通过 runtime.context 即可拿到。store 的数据键采用"命名空间 + 键"的二级结构——比如 ["users"], userId——方便按业务领域组织数据。

image.png

Checkpointer 和 store 的分工很明确,但初学者容易混淆。一张表说清楚:

维度 Checkpointer(短期记忆) Store(长期记忆)
作用域 单个 thread(会话级) 跨所有 thread(应用级)
存储内容 完整状态快照(消息、步骤、中间变量) 应用自定义数据(用户偏好、事实、知识)
典型用途 对话连续性、人机交互中断 用户画像、跨会话知识、全局配置
API 模式 自动管理,框架透明处理 通过工具显式读写(runtime.store)
数据键 thread_id 自动隔离 命名空间 + 键(如 ["users"], userId)
后端实现 MemorySaver / SqliteSaver / PostgresSaver InMemoryStore / PostgresStore

一个判断标准:如果数据生命周期跟一次对话绑定,用 checkpointer;如果数据需要跨对话、跨设备、跨时间存在,用 store。

image.png

超长对话:当上下文膨胀到 LLM 吃不消

checkpointer 虽然自动记录所有历史消息,但它不会帮你做任何裁剪。一轮对话跑到几百条消息之后,上下文窗口会被塞满,响应变慢、token 消耗飙升,甚至超出模型上下文限制直接报错。对于 Coding Agent 这类需要长时间密集交互的场景,这个问题尤其突出。

这种场景下需要在 checkpointer 之上叠加一层摘要策略。核心思路是:当对话历史超过某个 token 阈值时,自动将早期消息压缩为摘要,保留近期消息的完整内容,摘要部分作为"背景知识"前置注入。具体实现上,可以在每次状态写入时检查 token 使用量,一旦超过阈值就对历史消息执行摘要压缩。保留策略通常是"近期 N 条消息 + 摘要"的组合——既保留最近对话的细节,又不会丢失早期的关键信息。

触发阈值的选择取决于你使用的模型上下文窗口。建议将阈值设在窗口的 10%-15% 以内,留出足够空间给当前轮次的思考和工具调用。

要注意的是,摘要本身会丢失信息。如果对话中涉及精确数据——比如用户报了一个订单号、一段配置参数——这些信息被压缩进摘要后可能变形。一个实用的做法是,在 store 中单独存储这类"不可压缩"的结构化数据,摘要只保留叙事性的上下文。

image.png

社区工具推荐:当内置方案不够用

createAgent 的 checkpointer + store 组合覆盖了大部分基础记忆需求,但在行为记忆和用户画像构建这两个方向上,社区有一些更专业的轮子。

agentmemory(GitHub: rohitg00/agentmemory,MIT 协议,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 的方案。

mem0(GitHub: mem0ai/mem0,Apache 2.0,41,000+ Stars)面向 LLM 应用的用户画像构建,从对话中自动提取结构化事实。但每次写入记忆都需要调用 LLM,部署还需要 Qdrant 或 Chroma 向量数据库。如果你的场景是面向 C 端用户的聊天产品,mem0 的用户画像提取能力很对口;但 Coding Agent 场景下,agentmemory 的零 LLM 调用模式显然更经济。

TencentDB Agent Memory(GitHub: Tencent/TencentDB-Agent-Memory,Apache 2.0,2026 年 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 最缺哪种记忆——是记不住用户偏好,还是记不住工具调用的经验——然后只引入对应的那一款。

image.png

三层搭配:从最小启动到生产就绪

从 checkpointer 起步,按需叠加 store 和社区方案。

记忆不是越多越好。每一层记忆都有它的存储成本和检索延迟,盲目堆叠只会让 Agent 变慢、变贵、变难调试。从最小集合开始,被用户真正抱怨的痛点驱动着往上加,才是务实的策略。

image.png

相关文章
|
1月前
|
自然语言处理 Python
提示词工程怎么写才有效:拆解 5 大核心要素与实战代码示例
提示词工程不是玄学话术,而是一套可复用的设计方法。本文拆解 5 大核心要素,给出结构化提示词模板与 3 段实战代码,附常见坑。
399 0
提示词工程怎么写才有效:拆解 5 大核心要素与实战代码示例
|
10月前
|
人工智能 安全 机器人
AI 智能体的开发方法
AI智能体已超越对话机器人,演进为具备目标拆解、长期记忆与环境交互的自主系统。本文详解五大核心:架构设计(感知-思考-行动)、多Agent协作、数据驱动优化、安全护栏及主流开发范式,助您构建可靠数字员工。(239字)
|
3月前
|
缓存 前端开发 程序员
V4-Flash-Vision-Exp 上线,Harness 多模态接入实测
V4-Flash-Vision-Exp 刚上线,用 DeepSeek Harness 实测多模态新模型,含 API 接入、图片理解与价格细账
|
24天前
|
人工智能 Linux API
Magpie, 轻量本地AI网关!免费Token用不完!
Magpie 是开源AI编程模型调度网关,上线一月获1.8万Star。它通过本地高性能网关统一托管多平台API密钥、账号与免费额度,实现跨Agent的模型秒级切换、静默额度轮换与资源复用,显著降低碎片化管理成本。(239字)
Magpie, 轻量本地AI网关!免费Token用不完!
|
1月前
|
人工智能 自然语言处理 API
阿里云千问大模型191款全模态,Qwen3.8-Max坐镇,Flash档低至0.8元、新人100万Token免费领
阿里云千问(Qwen)是阿里巴巴自研的大模型系列,依托百炼平台汇聚 191 款模型,覆盖文本生成、多模态理解、图像与视频生成、语音识别合成等全模态能力。旗舰 Qwen3.8-Max 可自主编程、一次对话交付生产级成果,Qwen3.8-Flash 以百万级上下文兼顾性能与成本,并附开源版本与 Kimi、DeepSeek、GLM 等第三方模型。平台支持云端调用与私有化部署,按 token、张、秒计费,配合免费额度与优惠活动,为个人开发者到大型企业提供从选型到落地的全链路服务。
|
7月前
|
人工智能 监控 Kubernetes
LoongCollector + ACS Agent Sandbox:构建 AI Agent 生产级运行平台
文章介绍了阿里云ACSAgentSandbox与LoongCollector协同构建的AIAgent生产级运行平台,通过沙箱隔离保障运行时安全,并以高性能、全链路可观测能力解决Agent行为不可预测和执行风险难题。
3855 100
|
5月前
|
Ubuntu Linux KVM
虚拟机搭建教程(二)
教程来源 https://zlpow.cn/ 本文详解Windows、Linux三大平台虚拟化实战:Windows下用VMware安装Ubuntu 24.04(含Tools与快照),VirtualBox部署CentOS Stream 9;Linux主机通过KVM命令行及virt-manager搭建高性能虚拟机,覆盖配置、联网、增强工具与管理全流程。
|
5月前
|
关系型数据库 MySQL 数据库
MySQL下载安装教程 | Windows安装MySQL 8.0详解(2026最新)
MySQL是Oracle维护的开源关系型数据库,支持SQL操作,广泛用于Web应用、企业系统及数据分析。提供免费社区版和商业版,安装简便,兼容LAMP/LEMP架构,适合学习与生产环境。(239字)
5576 11
|
10月前
|
存储 人工智能 搜索推荐
AI Agent 记忆系统:从短期到长期的技术架构与实践
当智能体需要处理越来越复杂的任务和更长的对话历史,核心挑战是什么,又该如何突破。
2517 67
|
6月前
|
人工智能
GEO已经完蛋了?
DeepSeek R1 升级重击劣质GEO:百万级上下文+信源ABC分级,让水文、伪背书、关键词堆砌彻底失效。GEO未死,只是回归本质——用真实问题、可信信源、扎实内容赢得AI信任。正向GEO,才是AI时代的长期主义。(239字)

热门文章

最新文章