作为一个 39 岁的技术人我最近在啃 DeepAgents 框架的长期记忆章节时发现了一个很有意思的设计——Agent 的记忆不是像人类大脑那样自然存在的而是通过文件系统 存储后端 路由机制这套组合拳来实现的。上一章我们学完了 Skills可复用的能力包但 Skills 解决的是Agent 会做什么而本章的 Memory 解决的是Agent 记得什么。今天我们就来把这个机制扒开揉碎讲得明明白白。一、DeepAgents 中的记忆机制是怎么实现的1.1 记忆机制的整体架构DeepAgents 将记忆作为一等公民——Agent 以文件形式读写记忆你用 Backend 控制这些文件存储在哪里。整个流程可以概括为三步步骤做什么类比1. 准备存储与文件配置 Backend 和 Store预置记忆文件装修房子准备好书架2. 加载记忆memory指定文件路径内容进入系统提示词入住时把书摆上书架3. 更新记忆可选通过提示词约定写入规则Agent 调用edit_file更新读完后往书架上添新书# memory 是读取配置指定哪些文件的内容会被注入系统提示词# skills 是程序性记忆先注入元数据正文由 Agent 按需读取agentcreate_deep_agent(modelmodel,memory[/memories/preferences.md],# 加载用户偏好skills[/skills/],# 加载技能包backend...,# 控制文件存在哪里)关键细节在 DeepAgents 0.7.10 中缺失的记忆文件会被跳过不会自动创建缺失文件的路径也不会作为已加载记忆注入提示词。所以要固定偏好的写入位置需要同时约定写入路径——仅声明memory不能保证 Agent 使用这个文件名。1.2 memory vs backend它们各自管什么这是很多初学者容易混淆的地方。我们用一张表说清楚参数职责类比如果不配置会怎样memory读配置告诉框架启动时把哪些文件的内容加载到系统提示词里“请帮我把书架上那本《用户手册》拿给我看”Agent 启动时不加载任何已有记忆backend存储配置告诉框架文件实际存在哪里、怎么路由“书架是实木的还是金属的、放在哪个房间”文件存在默认的 StateBackend对话结束就没了它们的关系是这样的memory[/memories/preferences.md] ↓ 告诉框架要加载这个文件 ↓ 框架去 backend 中找这个路径 ↓ backend CompositeBackend( routes{/memories/: StoreBackend(...)} ↑ 告诉框架 /memories/ 开头的文件存在 StoreBackend 里 )memory负责**“加载什么”backend负责存在哪、怎么找**。两者配合缺一不可。二、Agent 的两种记忆短期记忆和长期记忆的应用场景区别人类有短期记忆和长期记忆——你记得今天的对话内容短期也记得你的名字和偏好长期。Agent 也一样但需要不同的技术来实现。2.1 短期记忆Thread-scoped定义同一个对话线程thread内持久化对话结束后消失。实现方式默认的StateBackend将文件存在 LangGraph 的 Agent State 中通过Checkpointer机制保证同一 thread 内多轮对话不丢失。应用场景当前任务的中间结果比如草稿、临时笔记对话上下文“你刚才说了什么”本次会话中产生的临时文件类比就像你的工作桌面——当前任务的资料都摊在上面但下班清理后就干净了。换一个 thread_id桌面就清空了。2.2 长期记忆Cross-thread定义跨不同对话线程保留的信息不随对话结束而消失。实现方式通过StoreBackend存储在持久化存储中内存、PostgreSQL、LangSmith 平台等。应用场景用户的偏好设置“我喜欢简洁的代码风格”项目的背景知识“我们用 React TypeScript”累积的研究成果多次对话中逐渐收集的资料Agent 从反馈中学到的改进指令类比就像你的书房书架——不管今天聊什么书架上的书都在那里明天来还在。2.3 两者的对比维度短期记忆长期记忆作用域单个 thread对话线程跨所有 thread底层存储Agent State内存中的状态字典Store持久化存储生命周期thread 结束即消失永久保留除非手动删除实现机制CheckpointerStoreBackend CompositeBackend典型用途对话上下文、临时文件用户偏好、项目知识、Agent 经验类比工作桌面书房书架三、DeepAgents 中短期记忆的实现机制和记忆管理策略3.1 Checkpointer短期记忆的基础Checkpointer 是 LangGraph 的短期记忆机制。它的工作原理很简单每次 Agent 执行完一步自动保存当前状态消息历史、文件系统状态、任务清单等下次调用时如果thread_id相同自动恢复上次的状态开发用MemorySaver内存重启丢失生产用PostgresSaver数据库持久化来看实际代码演示fromlanggraph.checkpoint.memoryimportInMemorySaver checkpointerInMemorySaver()agentcreate_deep_agent(modelmodel,checkpointercheckpointer,)# 同一个 thread_id 内Agent 记得之前的对话config{configurable:{thread_id:conversation-001}}agent.invoke({messages:[{role:user,content:我叫张三}]},configconfig)agent.invoke({messages:[{role:user,content:我叫什么名字}]},configconfig)# Agent 能回答你叫张三# 换一个 thread_idAgent 不记得了config2{configurable:{thread_id:conversation-002}}agent.invoke({messages:[{role:user,content:我叫什么名字}]},configconfig2)# Agent 不知道你是谁实际运行效果Thread 1 ID: conversation-001 Thread 2 ID: conversation-002 → 两个 thread 之间状态完全隔离互不干扰 Thread 1 保存了: 我叫张三 Thread 2 是空的: [] → 换 thread 后Agent 不记得之前对话的内容关键限制Checkpointer 只在同一个thread_id内有效。不同的对话不同thread_id之间状态完全隔离。3.2 短期记忆的管理策略随着对话越来越长消息历史可能超出 LLM 的上下文窗口。LangChain 提供了三种应对策略策略做法适用场景Trim裁剪只保留最近 N 条消息丢弃更早的简单粗暴适合不需要历史上下文的场景Delete删除用RemoveMessage精确删除特定消息需要选择性清理如删除敏感信息Summarize总结用 LLM 将旧消息压缩为摘要需要保留历史语义是最推荐的方式在 DeepAgents 中Summarize 策略已经自动内置SummarizationMiddleware。create_deep_agent()在已知模型窗口大小时默认到 85% 触发缺少窗口信息时使用固定 token 阈值。如果你需要自定义裁剪逻辑可以用 LangChain 的before_model中间件fromlangchain.messagesimportRemoveMessagefromlanggraph.graph.messageimportREMOVE_ALL_MESSAGESfromlangchain.agentsimportAgentStatefromlangchain.agents.middlewareimportbefore_modelfromlanggraph.runtimeimportRuntimebefore_modeldeftrim_messages(state:AgentState,runtime:Runtime)-dict|None:只保留最近几条消息防止上下文溢出。messagesstate[messages]iflen(messages)3:returnNone# 不需要裁剪first_msgmessages[0]# 保留第一条通常是系统消息recentmessages[-3:]# 保留最近 3 条return{messages:[RemoveMessage(idREMOVE_ALL_MESSAGES),first_msg,*recent,]}agentcreate_deep_agent(modelmodel,middleware[trim_messages],)before_model是 LangChain 的中间件装饰器——它在每次模型调用之前执行可以修改传给模型的消息。对应地还有after_model模型调用之后执行。3.3 进阶自定义 AgentStateLangChain 允许你扩展默认的AgentState添加自定义字段classCustomAgentState(AgentState):user_id:str# 用户 IDpreferences:dict# 用户偏好agentcreate_agent(modelmodel,state_schemaCustomAgentState,checkpointercheckpointer,)工具可以通过ToolRuntime读写这些自定义状态字段tooldefget_user_info(runtime:ToolRuntime)-str:查询当前用户信息。user_idruntime.state[user_id]# 从 Agent State 中读取returnf用户ID:{user_id}tooldefupdate_preferences(new_theme:str,runtime:ToolRuntime):更新用户偏好设置。fromlanggraph.typesimportCommand current_prefsruntime.state.get(preferences,{})current_prefs[theme]new_themereturnCommand(update{preferences:current_prefs})关键点runtime.state是读状态Command(update{...})是写状态。这样工具不仅能返回结果给模型还能直接修改 Agent 的短期记忆。四、DeepAgents 中的长期记忆路径路由与用户隔离4.1 长期记忆都有哪些DeepAgents 的长期记忆通过Store存储主要包括记忆类型存储内容作用域典型文件路径Agent 级记忆Agent 从多次对话中积累的知识所有用户共享/memories/AGENTS.md用户级记忆个人偏好、私有笔记单个用户/memories/preferences.md组织级记忆合规策略、公司政策全组织共享/policies/compliance.md项目记忆技术栈、架构文档项目组成员/memories/project/tech-stack.md研究记忆研究笔记、参考资料研究者/memories/research/sources.md情景记忆过去的完整对话记录单个用户通过 Checkpointer 搜索4.2 如何分清不同用户的长期记忆——namespace 机制DeepAgents 通过namespace命名空间来隔离不同用户、不同 Agent 的记忆。# Agent 级记忆所有用户共享namespace(my-coding-agent,memories)# 用户级记忆按用户隔离namespace(user-123,memories)# 用户 Anamespace(user-456,memories)# 用户 B实际运行效果Agent 级记忆所有用户共享 Namespace: (my-coding-agent, memories) 内容: ## Agent 知识库 - 本项目使用 React TypeScript - 代码规范ESLint Prettier 用户 A 的私有记忆 Namespace: (alice, memories) 内容: # Alice 的偏好 - 深色主题 - 中文注释 用户 B 的私有记忆 Namespace: (bob, memories) 内容: # Bob 的偏好 - 浅色主题 - 英文注释 关键区别 Agent 级: namespace (assistant_id, memories) → 所有用户读同一份 用户级: namespace (user_id, memories) → 各用户隔离4.3 什么是路径路由机制路径路由是CompositeBackend的核心能力。它的思想很简单不同的文件路径路由到不同的后端存储。fromdeepagents.backendsimportCompositeBackend,StateBackend,StoreBackend backendCompositeBackend(defaultStateBackend(),# 默认路由临时文件routes{/memories/:StoreBackend(namespacelambdart:(rt.context.user_id,memories),),/policies/:StoreBackend(namespacelambdart:(rt.context.org_id,),),},)4.4 路径路由在长期记忆中起到什么作用路径路由解决了三个核心问题1. 透明的存储切换Agent 操作文件的方式完全一样——都是调用write_file、read_file。区别只在于路径前缀write_file(/workspace/draft.txt, 草稿) → StateBackend (临时对话后消失) write_file(/notes.txt, 笔记) → StateBackend (临时对话后消失) write_file(/memories/preferences.md, 偏好) → StoreBackend (持久化) write_file(/policies/compliance.md, 合规) → StoreBackend (持久化)2. 存储空间的隔离/memories/和/policies/路由到不同的 namespace互不干扰。3. 路由前缀的自动剥离Agent 看到的虚拟路径: /memories/preferences.md 实际 Store 中的 key: /preferences.md路由前缀 /memories/ 被自动剥离 实际 Store 中的 namespace: (user_id, memories)大坑提醒如果 Store key 写成/memories/preferences.md带路由前缀CompositeBackend 在返回结果时还会补一次/memories/最终暴露成错误的/memories/memories/preferences.md。Store key 不应该包含路由前缀五、四种实用场景通俗讲解四种场景的使用方式场景 1用户偏好记忆preferences.md一句话总结让 Agent 记住我喜欢什么。怎么用配置memory[/memories/preferences.md]在 system_prompt 中约定“当用户明确要求记住偏好时用edit_file更新/memories/preferences.md”用户说记住我的偏好Agent 就会调用edit_file写入实际运行效果[场景 1] 用户偏好记忆 — preferences.md → 每次对话 Agent 都能记住并使用用户偏好场景 2自我改进的 AgentAGENTS.md一句话总结让 Agent 随着时间越用越聪明。怎么用配置memory[/memories/AGENTS.md]约定 Agent 从用户反馈中学习“当用户指出错误时记录到 AGENTS.md”随着时间推移AGENTS.md 积累越来越多经验实际运行效果[场景 2] 自我改进的 Agent — AGENTS.md → Agent 随时间积累知识越来越懂这个领域示例文件内容## 从反馈中学到的经验 - 2026-01-15: 用户希望减少解释直接给代码 - 2026-01-20: 用户希望错误信息附带修复建议场景 3知识库累积project/*.md一句话总结让 Agent 跨多次对话逐渐构建项目知识库。怎么用按项目子目录组织文件/memories/project/tech-stack.md每次对话Agent 读取已有内容追加新信息新对话启动时Agent 加载完整的项目知识实际运行效果[场景 3] 知识库累积 — project/tech-stack.md → 跨多次对话逐渐构建项目知识库示例文件内容## 项目技术栈 - 前端: React 18 TypeScript - 后端: FastAPI Python 3.12 - 数据库: PostgreSQL 16 - 部署: Docker K8s场景 4研究项目持续推进research/*.md一句话总结让大型研究任务可以分多次对话持续推进。怎么用用多个memory 路径加载不同研究文件Agent 启动时加载所有文件了解当前进度每次对话更新对应的文件agentcreate_deep_agent(modelmodel,memory[/memories/research/sources.md,# 参考资料/memories/research/notes.md,# 研究笔记/memories/research/report.md,# 研究报告],...)实际运行效果[场景 4] 研究项目持续推进 — 多个 memory 文件 /research/sources.md ✓ /research/notes.md ✓ /research/report.md ✓ → Agent 启动时加载所有文件每次对话更新进度核心使用原则原则说明按主题拆分文件不要把所有记忆塞进一个大文件拆分成preferences.md、tech-stack.md、sources.md等memory 加载提示词约定写入memory负责读取system_prompt负责约定写入规则持久化路径要有意义用/memories/project/tech-stack.md而不是/memories/file1.md六、组织记忆和情景记忆场景与实现6.1 组织级记忆Organization-level Memory用在什么场景公司的合规政策“不得披露内部定价”全组织共享的知识库安全规则和行为准则核心特点跨所有用户和 Agent 共享通常设为只读防止恶意用户注入攻击由应用代码而非 Agent填充内容如何实现agentcreate_deep_agent(modelmodel,memory[/memories/preferences.md,# 用户级可读写/policies/compliance.md,# 组织级只读],backendCompositeBackend(defaultStateBackend(),routes{/memories/:StoreBackend(namespacelambdart:(rt.context.user_id,memories),# 用户级),/policies/:StoreBackend(namespacelambdart:(rt.context.org_id,),# 组织级),},),)从应用代码中填充组织级记忆fromlanggraph_sdkimportget_clientfromdeepagents.backends.utilsimportcreate_file_data clientget_client(urlDEPLOYMENT_URL)awaitclient.store.put_item((org_id,),/compliance.md,create_file_data(## 合规政策 - 不得披露内部定价 - 金融建议必须附加免责声明 ),)安全提醒如果一个用户能写入另一个用户读取的记忆恶意用户可以注入指令。共享策略应该用只读模式——通过应用代码填充不让 Agent 写入。6.2 情景记忆Episodic Memory用在什么场景回忆上次是怎么解决这个问题的搜索过去的完整对话记录Agent 回溯上次调试过程直接跳到可能的根因和语义记忆的区别语义记忆记是什么事实和偏好→/memories/preferences.md情景记忆记发生了什么完整经历→ 过去的对话历史如何实现DeepAgents 的Checkpointer 天然支持情景记忆——每次对话都被完整持久化。要让过去的对话变得可搜索可以包装一个搜索工具fromlanggraph_sdkimportget_clientfromlangchain.toolsimporttool,ToolRuntime clientget_client(urlDEPLOYMENT_URL)toolasyncdefsearch_past_conversations(query:str,runtime:ToolRuntime)-str:搜索过去的对话以获取相关上下文。user_idcurrent_user_id(runtime)threadsawaitclient.threads.search(metadata{user_id:user_id},limit5,)results[]forthreadinthreads:historyawaitclient.threads.get_history(thread_idthread[thread_id])results.append(history)returnstr(results)这对执行复杂多步任务的 Agent 尤为有用——比如代码 Agent 可以回溯上次调试过程直接跳到可能的根因。6.3 记忆的六个维度全景官方文档将记忆系统拆分为六个可独立配置的维度维度核心问题选项持续时间保留多久短期单次对话/ 长期跨对话信息类型记什么情景记忆 / 程序性记忆Skills/ 语义记忆事实作用域谁能看用户级 / Agent 级 / 组织级更新策略何时写入对话中默认/ 对话间后台整合检索方式如何读取启动加载memory/ 按需读取Skills权限控制Agent 能写吗读写默认/ 只读共享策略这六个维度互相独立你可以自由组合。比如“用户偏好” 长期 语义记忆 用户级 对话中写入 启动加载 读写“合规政策” 长期 语义记忆 组织级 应用代码写入 启动加载 只读七、从开发到生产Store 的升级路径阶段Store 类型特点开发阶段InMemoryStore零配置快速迭代重启丢失生产阶段PostgresStore真正持久化可伸缩需要pip install langgraph-checkpoint-postgresLangSmith 部署平台自动配置无需手动管理平台自动提供持久化存储记忆文件格式deepagents 0.5 v2 格式{content:第一行\n第二行\n第三行,encoding:utf-8,created_at:2024-01-15T10:30:00Z,modified_at:2024-01-15T11:45:00Z}不要手写底层 JSONAgent 外部后端服务、初始化脚本预填记忆时应使用create_file_data辅助函数。小结本章我们深入剖析了 DeepAgents 的记忆系统短期记忆靠 Checkpointer管同一个 thread 内的状态持久化长期记忆靠 Store CompositeBackend跨 thread 保留信息memory是读配置backend是存储配置两者配合才完整路径路由让 Agent 用统一方式操作文件底层自动路由到正确的存储namespace实现了用户级、Agent 级、组织级的隔离四种实用场景告诉你通用记忆能力在实际中怎么用组织记忆用只读模式防注入情景记忆用搜索工具回溯历史记忆机制的本质就是把记忆变成文件把存储变成后端把隔离变成路由规则。理解了这个底层逻辑你就能灵活应对各种记忆需求。下一章我们将学习 Human-in-the-Loop——如何为敏感操作添加人工审批构建安全的人机协作流程。