如果把一个企业级 Agent 拆开来看最容易被低估的技术模块就是记忆系统。对话能力再强只要每次请求都像第一次见面就无法建立稳定的用户画像也无法保证多轮任务的一致性。企业级 Agent 与玩具 Demo 的分水岭往往不在模型选型而在记忆架构是否支持“先记住、再决策、后更新”的完整闭环。这次我们来看一种从 Context 到 Long-term Memory 的 Agent 记忆系统架构。基于 LangChain、LangGraph 和 DeepAgent 这组框架把会话记忆、长期记忆、向量召回和状态持久化串成一条可治理的工程链路。文章会先给出记忆分层模型再分别演示 LangChain 的 Memory 组件、LangGraph 的 StateGraph 持久化以及 DeepAgent 在长期记忆上的设计思路最后落到工程治理、API 接口和故障排查。如果你正在做企业级 Agent 开发或者准备从单轮 Prompt 工程转向带状态的 Agent 架构这篇内容可以直接作为设计参考。需要说明的是框架 API 会随版本变化文中的代码示例以通用实现思路为主具体调用请以你使用的版本为准。1. 核心能力速览与记忆分层模型企业级 Agent 记忆不能只靠“把历史消息塞进 Prompt”。Context 窗口有限塞多了会丢重点塞少了又失去上下文。正确做法是把记忆拆成多个层次按访问频率和生命周期分别管理。记忆层生命周期典型内容主要存储工程治理重点会话记忆Session Memory单次会话内当前对话轮次、临时状态Redis、内存、Sqlite窗口大小、Token 预算消息缓冲Message Buffer近几轮最近 N 条消息LangChain BufferMemory裁剪、去重、格式统一工作记忆Working Memory任务执行期间中间结果、工具输出、条件分支状态LangGraph State状态字段设计、节点更新摘要记忆Summary Memory会话或任务结束后历史对话的关键结论LangChain SummaryMemory摘要触发时机、压缩策略长期记忆Long-term Memory跨会话、长期用户偏好、业务实体、历史事实向量库 关系库写入、召回、更新、遗忘技能记忆Skill Memory长期工具调用方式、流程模板知识库、Skill 注册中心版本管理、权限控制从这张表可以看到记忆不是单一存储而是分层协同。LangChain 负责把短期记忆和摘要记忆接入模型调用LangGraph 负责把工作记忆变成图节点之间的状态流转DeepAgent 这类强调长期记忆的框架则可以把跨会话的记忆能力封装成服务。这种分层架构的好处是每一层都可以独立扩展也都可以单独设置过期策略。企业级系统真正需要的不是“什么都能记住”而是“该记住的记住、该忘掉的忘掉、该归类的归类”。2. 为什么企业级 Agent 必须做长期记忆很多人认为模型支持长上下文之后长期记忆就不重要了。这个判断在企业场景下并不成立。第一长上下文不等于长期记忆。即使用户每次把全部历史都塞进窗口模型也只在这一轮调用里“看过”这些内容并没有形成跨请求的稳定状态。一旦用户关闭页面再打开长上下文方案不会自动恢复之前的业务上下文。第二Token 成本是硬约束。假设一个用户每天产生 200 条对话记录平均每条 100 Token一个月就是 60 万 Token。每次都回放全部历史成本会线性增长而且大量历史内容与当前任务无关。长期记忆的作用是提炼关键信息而不是全量回放。第三企业业务要求一致性和可审计性。客户支持、金融咨询、医疗导诊这类场景Agent 必须证明自己“记住了”用户的偏好和之前的结论。如果每次回答都重新推理很容易出现前后不一致甚至违反业务规则。第四多轮任务的稳定性依赖状态。Agent 在执行复杂任务时可能需要查询多个工具、经过多个决策分支。LangGraph 的状态管理本质上就是让中间结果在节点之间传递避免重复计算和上下文丢失。因此从 Context 到 Long-term Memory 的演进不是为了让对话更“智能”而是让 Agent 在工程上可信任、可复现、可治理。3. 环境准备与前置条件如果要在本地复现下面的示例建议先准备一套干净的 Python 环境。企业级项目推荐使用虚拟环境隔离依赖避免多个项目互相污染。3.1 环境要求Python 3.10 或更高版本。操作系统Windows、Linux、macOS 均可但生产环境更推荐 Linux。至少 8GB 内存如果使用本地向量库做长文本索引建议 16GB 以上。不需要 GPU 也能运行框架级示例如果要接入本地 embedding 模型再按需配置推理资源。数据库依赖Redis可选、SQLite内置、向量数据库如 Chroma、FAISS 或云上的 Milvus。3.2 安装 LangChain 与 LangGraph# 创建并激活虚拟环境Windows 下激活名不同请按系统提示操作 python -m venv .venv source .venv/bin/activate # 安装核心框架 pip install langchain langgraph # 如果使用 OpenAI 模型可以安装对应包 pip install langchain-openai # 如果需要本地向量库可以安装 Chroma pip install chromadbDeepAgent 如果来自独立仓库需要额外安装。由于不同社区版本的安装方式差异较大建议直接查看官方仓库的 README# 示例实际以官方文档为准 pip install deepagent安装完成后可以用下面这段代码快速验证环境是否可用import langchain import langgraph print(LangChain version:, langchain.__version__) print(LangGraph available:, langgraph is not None)只要能正常打印版本说明基础依赖已经就位。接下来进入记忆系统的具体实现。4. 基于 LangChain 的 Context 管理与记忆组件LangChain 对短期记忆的支持比较成熟核心思路是把“历史消息”作为一种输入包装器在调用模型前自动拼接调用后自动追加。4.1 会话缓冲记忆最基础的实现是ConversationBufferMemory。它会把历史消息原样保存每次调用模型时全部传给模型。这种方式适合短会话但超过一定轮次后 Token 开销会快速上升。from langchain.memory import ConversationBufferMemory from langchain_openai import ChatOpenAI memory ConversationBufferMemory(return_messagesTrue) memory.chat_memory.add_user_message(我叫李然偏好简洁的技术文档。) memory.chat_memory.add_ai_message(好的我会记住你的偏好。) llm ChatOpenAI(modelgpt-4o-mini) response llm.invoke(memory.chat_memory.messages) print(response.content)这段代码演示了最基础的“拼接记忆”过程。实际企业级场景中不建议直接使用这种无限增长的 buffer而应该设置轮次上限或 Token 上限。4.2 摘要记忆针对长对话LangChain 提供ConversationSummaryMemory。它不会保存全部消息而是让模型定期把历史对话压缩成摘要。摘要本身可以继续参与上下文组装从而控制 Token 增长速度。from langchain.memory import ConversationSummaryMemory from langchain_openai import ChatOpenAI llm ChatOpenAI(modelgpt-4o-mini, temperature0) summary_memory ConversationSummaryMemory(llmllm, return_messagesTrue) summary_memory.save_context({input: 这个客户希望月底前完成发票系统迁移。}, {output: 已记录后续优先处理迁移排期。}) print(summary_memory.buffer)需要说明的是摘要记忆并不是完全替代原始消息。更稳妥的做法是近 N 轮保留原始消息更早的轮次保留摘要二者按优先级拼接。这样既能保证近期信息的完整性又能控制总 Token。4.3 Context 治理的关键参数无论使用哪种 Memory 组件都需要在工程层面关注三个参数max_token_limit单次上下文最大 Token 数。max_conversation_round保留原始消息的轮次上限。summary_threshold触发摘要的轮次阈值。这些参数通常不写在代码里而是放在配置中心方便按业务场景动态调整。企业级应用建议建立一套“上下文预算”机制把模型窗口的 70% 留给当前任务30% 留给历史摘要和检索结果。5. 基于 LangGraph 的会话状态与持久化LangChain 解决了“记忆怎么拼进 Prompt”的问题LangGraph 则解决“记忆怎么在图节点之间流动”的问题。企业级 Agent 通常不是简单的单次调用而是“用户输入 - 意图判断 - 调用工具 - 生成回答”的多步骤流程。LangGraph 用StateGraph来定义这些步骤state 本身就是一个可更新的记忆对象。5.1 一个带状态的最小 Agent下面代码定义一个最简单的图包含两个节点一个是接收用户输入一个是生成最终回答。核心点在于通过 state 保存中间消息。from typing import TypedDict, Annotated from langgraph.graph import StateGraph, START, END from langgraph.checkpoint.sqlite import SqliteSaver class AgentState(TypedDict): messages: list user_name: str def collect_input(state: AgentState): # 这里可以从用户输入中提取关键信息 if not state.get(user_name): # 真实场景会从对话中抽取 state[user_name] 从历史中识别的用户 return {user_name: state[user_name]} def generate_reply(state: AgentState): # 简化示例直接基于 state 生成回复 reply f{state[user_name]}这是基于完整上下文生成的回答。 return {messages: state[messages] [reply]} with SqliteSaver.from_conn_string(:memory:) as checkpointer: graph StateGraph(AgentState) graph.add_node(collect, collect_input) graph.add_node(generate, generate_reply) graph.add_edge(START, collect) graph.add_edge(collect, generate) graph.add_edge(generate, END) app graph.compile(checkpointercheckpointer) config {configurable: {thread_id: conversation-001}} result app.invoke( {messages: [帮我查一下订单状态], user_name: }, configconfig ) print(result[messages])这段代码有两点很重要thread_id是 LangGraph 持久化会话的标识。同一个thread_id下的多次调用会共享同一份历史状态。SqliteSaver是检查点机制可以将图执行到一半的状态保存下来服务重启后也能恢复。5.2 检查点检查点机制与长期记忆的关系LangGraph 的检查点机制天然适合做工作记忆持久化。每一次图执行完成后state 会被序列化到检查点存储中。后续调用只需传入同一个thread_id就能继续上一次的对话。如果把检查点存储换成 PostgreSQL、Redis 或云数据库就有了企业级状态管理的基础。这也是为什么 LangGraph 在企业级 Agent 中越来越被重视——它把“记忆”变成了图执行的一部分而不是外层拼接。5.3 条件路由与循环控制对记忆的影响在真实任务中Agent 可能需要根据中间结果决定下一步走向。LangGraph 的conditional_edges可以实现条件路由而循环和子图可以处理多步工具调用。记忆在这些结构中表现为 state 的更新频率和方向。举个例子如果 Agent 需要先查订单再判断是否发放优惠券那么“订单状态”这个中间结果必须写入 state。如果 state 设计不合理节点之间就会互相丢失信息。建议把 state 分为“业务字段”和“消息字段”两部分业务字段用于任务执行消息字段用于最终展示。6. DeepAgent 框架下的长期记忆与上下文召回如果说 LangChain 和 LangGraph 更偏向通用编排那么 DeepAgent 这类社区框架的侧重点则是“长期记忆作为系统一等公民”。这类框架通常把记忆拆成多个代理模块记录器负责写入检索器负责召回遗忘器负责清理。具体能力要以官方文档为准这里给出通用设计思路。6.1 DeepAgent 记忆模块的典型分层以当前社区资料可以看到DeepAgent 会强调从短期 Context 到长期 Memory 的自动升级。例如不重要的消息在会话结束后直接丢弃关键结论和用户偏好则写入长期记忆库当新对话开始时先检索相关记忆再作为上下文注入。用户输入 - DeepAgent 意图识别 - 记忆检索向量相似度 - 注入历史结论与用户偏好 - Agent 编排可选 LangGraph 子图 - 生成回答 - 异步记忆更新这种设计的价值在于避免了每次都要把全部历史塞进 Prompt。长期记忆通过向量检索只取最相关的片段短期记忆通过会话 ID 恢复二者配合形成完整的上下文。6.2 一个通用的记忆召回伪代码def get_relevant_memory(user_query: str, top_k: int 3): # 将用户查询转成向量 query_vector embed_model.embed_query(user_query) # 在长期记忆库中检索最相关的历史片段 results vector_store.similarity_search_by_vector( query_vector, ktop_k ) return [item.text for item in results] def build_context(user_input: str): # 先拿短期记忆再拿长期记忆 short_term session_repository.get_current_session() long_term get_relevant_memory(user_input) context 短期记忆\n short_term \n长期记忆\n \n.join(long_term) return context这段伪代码体现的核心思想是长期记忆不是“存储所有历史”而是“按需检索历史”。实际工程中检索后的片段还需要经过权限过滤和重排序才能注入 Prompt。6.3 DeepAgent 与 LangChain、LangGraph 的组合方式从工程角度看三者并不冲突。一种常见的组合方式DeepAgent 负责长期记忆的写入、召回和遗忘策略。LangChain 负责模型调用、Prompt 模板和工具封装。LangGraph 负责带状态的多步编排把 DeepAgent 的检索结果作为 state 中的一部分供后续节点使用。这种组合的好处是职责清晰。长期记忆的存取规则集中在 DeepAgent会话流程的状态管理集中在 LangGraph模型交互细节集中在 LangChain。遇到问题时可以快速定位是记忆问题、状态问题还是模型调用问题。7. 记忆系统的工程治理存储、检索、更新与安全企业级 Agent 记忆系统不能只做到“能记住”还要做到“可治理”。从存储选型到安全审计每一环都需要设计。7.1 存储选型存储类型适用场景优点风险内存 / SQLite单机测试、轻量会话部署简单不具备高可用Redis会话缓存、短期状态低延迟容量有限向量数据库长期记忆的语义检索召回能力强需要索引维护PostgreSQL业务实体、审计日志事务支持好需要建模混合存储企业级生产各取所长运维复杂度高生产环境建议混合存储用户偏好和业务实体放关系库历史对话生成的向量放向量库会话中的短期状态放 Redis。单一存储很难同时满足查询延迟、容量和事务性要求。7.2 记忆写入与更新策略记忆写入不能阻塞主流程。用户提问后Agent 可以先返回回答再异步把“本次对话中的关键结论”写入长期记忆库。写入前需要经过信息抽取和脱敏过滤避免把敏感原始文本直接存进向量库。更新策略上推荐采用“先查重、再覆盖”的机制。如果一条新记忆和已有记忆高度相似应该做合并而不是不断插入重复片段。长期不访问的记忆则可以进入冷存储或直接遗忘。7.3 权限与隐私合规在企业级场景中记忆数据可能包含客户信息、商业机密和个人隐私。以下边界必须处理所有写入记忆库的文本应执行 PII 脱敏。不同角色只能访问与自己相关的记忆片段。记忆检索结果在注入模型前应再次过滤。用户应拥有“删除我的记忆”的权利系统需要提供遗忘接口。敏感场景下需要记录记忆写入者和写入时间的审计日志。这些不仅是技术问题也是合规问题。在做 Agent 记忆系统时如果涉及人脸、声音、个人身份等敏感数据必须确认用户授权和业务使用边界。7.4 批量任务与 API 接口设计记忆系统往往需要提供批量接口用于历史数据导入、用户画像初始化、记忆清理等场景。一个典型的记忆服务 API 可以设计如下{ action: add_memory, user_id: user-001, session_id: session-001, content: 用户偏好简洁的技术文档, metadata: { source: conversation, timestamp: 2025-01-20T10:00:00Z } }对应的 REST 接口可以包括POST /memory写入记忆。GET /memory/search?query...检索记忆。DELETE /memory/{id}遗忘单条记忆。POST /memory/batch批量导入记忆。批量任务要特别注意幂等性。同一批数据重复提交时不应产生重复记忆。建议 metadata 中保留唯一业务 ID写入前先去重。7.5 批量任务状态管理如果 Agent 本身支持批量处理例如批量生成客服总结或批量构建用户画像LangGraph 的 state 可以配合任务队列使用。每个批量任务使用一个独立thread_id将任务状态保存在检查点中。这样即使任务中途崩溃也能从最后一个检查点恢复不需要重新处理全部数据。8. 资源占用与性能观察记忆系统对性能的影响主要体现在三个地方模型 Token 消耗、向量检索延迟、状态存储的读写压力。8.1 Token 消耗短期记忆越长每次调用的 Token 消耗越高。可以通过日志记录每次请求的 token 用量并设定告警。建议在记忆分层完成后统计“近 N 轮消息摘要”和“长期记忆召回片段”各占多少 Token找到成本拐点。8.2 向量检索延迟长期记忆召回的核心瓶颈是向量库查询速度。小规模场景下Chroma 的内存索引足够当向量条数达到百万级建议使用专门的向量数据库并维护好索引的构建频率。可以使用类似下面的伪代码统计检索耗时import time start time.time() results vector_store.similarity_search(query, k3) print(f召回耗时: {time.time() - start:.3f}s)如果召回耗时超过预期优先优化向量库索引而不是盲目增加机器。8.3 状态存储读写LangGraph 的检查点机制会把每次 state 变更都写入存储。频繁写入对 SQLite 这类单机存储可能造成压力。生产环境建议使用 PostgreSQL 作为检查点存储。控制 state 字段大小不在 state 中放入超长文本。定期清理历史检查点只保留最近 N 次任务快照。8.4 可观测性设计企业级记忆系统必须可观测。建议为每次记忆写入和召回增加 trace_id并记录用户 ID 与会话 ID。记忆类型短期/长期/摘要。写入或召回的内容长度。模型调用的 token 数。操作耗时。这些日志既用于问题排查也用于后续优化记忆策略。9. 常见问题与排查方法问题现象可能原因排查方式解决方案会话历史丢失未使用 checkpointer 或 thread_id 不一致检查 LangGraph 配置与调用参数统一 thread_id配置 checkpointerContext 越来越长导致 Token 超限未做消息裁剪和摘要压缩查看 Token 用量日志设置 max_token_limit启用摘要记忆长期记忆召回结果不相关Embedding 模型与语料不匹配在测试集上评估召回效果更换 Embedding 模型增加重排序检索结果包含敏感信息未执行 PII 脱敏和权限过滤检查检索链路日志在写入和召回两段均做过滤批量任务中状态互相污染多个任务共用同一份 state检查 thread_id 是否唯一每个任务使用独立 thread_id模型回答前后不一致关键业务字段未写入 state检查节点返回字段把关键业务信息显式写入 state记忆写入失败向量库连接异常或写入超时查看存储日志增加重试和异步队列服务重启后记忆丢失使用了内存态存储检查存储配置更换为持久化存储排查时建议先看日志再复现最小用例。不要在生产环境直接改记忆策略先在测试环境验证。10. 最佳实践与使用建议10.1 先小规模验证再全面上线不要一开始就接入全部记忆类型。建议先实现会话记忆和状态持久化跑通一个端到端流程再逐渐加入摘要记忆和长期向量召回。每一步都留出评估环节。10.2 建立一套最小可运行配置在项目中保留一个最小的 Agent 模板包含一个 LangGraph 状态图。一个 SQLite 检查点。一个短期记忆配置。一个基础向量检索调用。以后每次改动记忆策略都基于这个模板做回归测试。10.3 记忆更新要异步化不要把记忆写入放在请求主链路中。使用消息队列处理记忆写入、摘要生成和向量索引更新能显著降低用户感知延迟。异步写入失败后可以通过重试机制补偿。10.4 设计遗忘机制真正企业级记忆系统必须允许“遗忘”。可以通过定期清理、TTL 过期、LRU 淘汰等方式实现。对用户明确要求删除的记忆要能快速从关系库和向量库中同时移除。10.5 定期做记忆质量审计长期记忆的质量会直接影响 Agent 回答质量。建议定期抽样检查记忆库中的内容看看是否过时、重复或带有偏见。发现低质量记忆时及时清理或归档。10.6 合规与安全涉及用户隐私、版权素材、商业机密的内容必须经过授权确认。调用任何外部模型或工具时也要注意数据的合规边界。记忆系统中的原始文本不宜长期保留可以只保留脱敏后的结构化信息。11. 总结与下一步企业级 Agent 记忆系统的本质是把“模型上下文”和“业务状态”统一起来治理。LangChain 提供记忆包装能力LangGraph 提供状态流转和持久化能力DeepAgent 这类框架则把长期记忆变成可检索、可更新的服务。最值得先验证的功能是 LangGraph 的thread_id持久化和检查点机制。把这两点跑通你就已经解决了 Agent 状态丢失的一大半问题。最容易踩的坑则是 state 字段设计不合理导致业务信息在节点之间传递失败。建议从最小图中的 message 列表开始再逐步增加业务字段。后续可以继续扩展的方向包括接入真实向量库做大规模长期记忆、设计记忆异步写入队列、完善记忆审计与权限控制以及在多 Agent 协作场景中共享记忆。这套架构不一定需要一步到位但分层理念可以直接复用短期记忆保实时摘要记忆控成本长期记忆做召回检查点机制促恢复。掌握这条链路你就能让 Agent 真正“记住”该记住的事情而不是单纯依赖模型窗口。