Mastra 工作记忆（Working Memory）机制深度解析：Agent 如何跨对话记住用户

Mastra 工作记忆Working Memory机制深度解析Agent 如何跨对话记住用户【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra导读本文围绕 Mastra 框架中的工作记忆Working Memory展开讲解它如何以一段可持续更新的 Markdown 文本形式让 Agent 在每次对话开始时读取、并在学到新信息时主动更新从而跨对话记住用户姓名、位置、偏好等长期信息。读完本文你将掌握工作记忆与对话历史、语义召回的本质区别理解其底层实现WorkingMemory 处理器、updateWorkingMemory工具、作用域与模板机制并能独立完成配置、自定义模板与 Playground 实测验证。什么是工作记忆工作记忆是 Mastra 记忆体系三大组成部分之一。在 Mastra 的上下文中Agent 的上下文窗口被划分为三个主要部分详见课程 01-understanding-memory.md系统指令与用户信息即工作记忆Working Memory最近的消息对话历史Conversation History较早的相关消息语义召回Semantic Recall工作记忆可以被理解为 Agent 的活页草稿本scratchpad它存放关于用户或任务的关键信息就像一个人在对话中自然记住对方的名字、偏好和重要细节一样。与对话历史、语义召回聚焦于回忆过去的消息不同工作记忆专门用于存储持续相关的结构化信息例如用户画像信息姓名、位置、偏好任务特定细节项目目标、截止日期会话状态当前主题、未解决的问题这种设计让 Agent 能够保持对用户和对话上下文的持久理解——即使对话历史中的具体消息不断变化工作记忆中的关键信息依然稳定可用从而让 Agent 在多次交互中提供越来越个性化、上下文相关的响应参见课程 19-what-is-working-memory.md。工作记忆的核心工作方式本课文档20-how-working-memory-works.md给出了工作记忆的权威定义工作记忆被实现为一块 Agent 可以随时间更新的 Markdown 文本。Agent 在每次对话开始时读取这些信息并在获得新信息时更新它。具体表现为以下闭环流程读取Agent 在每轮对话开始时读取工作记忆内容将其作为系统上下文注入。捕获当用户分享了需要长期记住的信息如姓名、位置、偏好时Agent 调用工具更新工作记忆。更新工作记忆中的内容被替换为包含新信息的最新版本。复用在后续对话中Agent 无需用户重复提供即可访问这些信息。工作记忆以结构化格式通常是 Markdown存储这种结构为 Agent 提供了明确的信息追踪清单——告诉它应该关注哪些信息、如何组织这些信息从而降低记忆写入的随意性提高检索与更新的效率。工作记忆 vs 对话历史本质区别文档中强调了一个关键区别对话历史是实际消息交换的逐字记录raw record。工作记忆是从中提炼出的、关于用户或任务的关键信息摘要distilled summary。正因为工作记忆是提炼后的摘要从它获取用户信息比从原始对话历史中反复提取要更高效、更聚焦。对话历史通常只覆盖最近的有限条消息受上下文窗口限制而工作记忆无论信息是什么时候提到的都能结构化地保存并随时取用。源码级原理WorkingMemory 处理器要深入理解工作记忆如何工作需要看它的底层实现。工作记忆的核心实现位于 packages/core/src/processors/memory/working-memory.ts 中的WorkingMemory类它本身是一个INPUT 处理器Processor负责在请求进入 LLM 之前完成注入。其processInput执行流程如下解析运行上下文通过parseMemoryRequestContext(requestContext)获取当前threadId与resourceId。按作用域读取记忆scope thread从线程元数据thread.metadata.workingMemory读取scope resource默认从资源resource.workingMemory读取并使用working-memory:resource:${resourceId}作为缓存键避免重复查询存储。确定模板按templateProvider→ 显式传入的template→ 内置默认模板的优先级解析模板。生成系统指令根据readOnly与useVNext开关生成三种不同的注入指令之一详见下文三种注入模式。注入消息列表通过messageList.addSystem(instruction, memory)将工作记忆指令作为系统消息前置到消息列表中。类中还内置了一个defaultWorkingMemoryTemplate默认模板结构如下# User Information - **First Name**: - **Last Name**: - **Location**: - **Occupation**: - **Interests**: - **Goals**: - **Events**: - **Facts**: - **Projects**:默认模板中暴露的配置项WorkingMemoryConfig接口定义了完整的可配置项源码见 working-memory.ts配置项类型默认值说明templateWorkingMemoryTemplate内置默认模板工作记忆内容的模板format可为markdown或jsonJSON 时content可为字符串或对象scopethread \| resourceresourcethread记忆限定在当前线程resource记忆在该资源的所有线程间共享useVNextbooleanfalse是否启用新一代工作记忆指令vNext 版本对未变化时无需重复调用更新工具等行为做了优化readOnlybooleanfalse只读模式工作记忆仅作为上下文提供不注入更新工具与更新指令loggerIMastraLogger-可选的结构化日志实例三种注入模式处理器会按配置生成三种不同的系统指令常规工具模式默认getWorkingMemoryToolInstruction生成的指令包含WORKING_MEMORY_SYSTEM_INSTRUCTION明确要求 Agent 通过updateWorkingMemory工具存储和更新相关信息并给出详细准则——例如只要信息可能再次被引用就存储它信息变化时主动更新无论变化多小必须以字符串形式把数据传给memory字段等。指令还会把模板与现有数据分别包裹在working_memory_template与working_memory_data标签中注入。vNext 模式getWorkingMemoryToolInstructionVNext生成的指令更强调如果记忆没有变化无需再次调用更新工具以及不要因当前对话不相关而删除跨对话仍有用的信息。只读模式getReadOnlyWorkingMemoryInstruction生成的指令仅提供working_memory_data上下文并明确告知 Agent 当前会话中记忆是只读的你无法更新它。数据如何被更新updateWorkingMemory 工具工作记忆的更新并不由上述 INPUT 处理器完成而是通过Memory类暴露的updateWorkingMemory工具实现工具注册代码见 packages/core/src/memory/mock.ts。这是一个标准的 Mastra 工具其关键实现要点工具 IDupdate-working-memory注册名为updateWorkingMemory常量定义见 packages/core/src/memory/working-memory-utils.ts。输入 Schema{ memory: z.string() }——Agent 调用时必须把完整的记忆内容作为字符串传入。作用域校验thread作用域要求必须存在threadIdresource作用域要求必须存在resourceId否则抛错。线程兜底创建若目标线程不存在会调用memory.createThread自动创建并校验线程的resourceId与当前请求一致。合并语义当工作记忆配置了schema时启用合并语义merge semantics——新数据与现有数据通过deepMergeWorkingMemory深度合并只更新传入字段未配置 schema 时则是整体覆盖写入工具描述会相应变化任何未包含的数据都将被覆盖。持久化最终通过memory.updateWorkingMemory({ threadId, resourceId, workingMemory, memoryConfig })写入存储。另外需要说明的是工作记忆的底层存储是带标签的结构化文本。工具模块 working-memory-utils.ts 中定义了working_memory、/working_memory标签以及system-reminder标签的解析工具函数extractWorkingMemoryTags、removeWorkingMemoryTags、extractWorkingMemoryContent等这些函数采用基于indexOf的解析方式以避免正则回溯ReDoS风险。当使用workingMemory.useStateSignals: true时工具名会从updateWorkingMemory改名为setWorkingMemory以便与传统剥离过滤器区分相关测试见 working-memory-utils.test.ts 与 mock-working-memory-merge.test.ts。配置工作记忆在 Mastra 中启用工作记忆只需要在Memory实例的options.workingMemory中开启开关。课程 21-configuring-working-memory.md 给出了完整示例import { Agent } from mastra/core/agent import { Memory } from mastra/memory import { LibSQLStore, LibSQLVector } from mastra/libsql // Create a memory instance with working memory configuration const memory new Memory({ storage: new LibSQLStore({ id: learning-memory-storage, url: file:../../memory.db, // relative path from the .mastra/output directory }), // Storage for message history vector: new LibSQLVector({ id: learning-memory-vector, url: file:../../vector.db, // relative path from the .mastra/output directory }), // Vector database for semantic search embedder: openai/text-embedding-3-small, // Embedder for message embeddings options: { semanticRecall: { topK: 3, messageRange: { before: 2, after: 1, }, }, workingMemory: { enabled: true, }, }, }) // Create an agent with the configured memory export const memoryAgent new Agent({ name: MemoryAgent, instructions: You are a helpful assistant with advanced memory capabilities. You can remember previous conversations and user preferences. IMPORTANT: You have access to working memory to store persistent information about the user. When you learn something important about the user, update your working memory. This includes: - Their name - Their location - Their preferences - Their interests - Any other relevant information that would help personalize the conversation Always refer to your working memory before asking for information the user has already provided. Use the information in your working memory to provide personalized responses. , model: openai/gpt-5.4, memory: memory, })配置要点总结workingMemory.enabled是否启用工作记忆workingMemory.template工作记忆内容的模板详见下节在Memory的options中可以与semanticRecall等记忆特性并行配置互不冲突Agent 的instructions同样关键它们引导 Agent 该把什么信息存入工作记忆、以及如何利用这些信息作答。建议在指令中明确学到用户重要信息时更新工作记忆以及在向用户询问其已提供过的信息之前先查阅工作记忆。自定义工作记忆模板内置默认模板适用于通用场景但生产级 Agent 通常需要针对具体用例设计模板。课程 22-custom-working-memory-templates.md 中的示例展示了如何通过workingMemory.template传入自定义 Markdown 模板options: { semanticRecall: { topK: 3, messageRange: { before: 2, after: 1, }, }, workingMemory: { enabled: true, template: # User Profile ## Personal Info - Name: - Location: - Timezone: ## Preferences - Communication Style: [e.g., Formal, Casual] - Interests: - Favorite Topics: ## Session State - Current Topic: - Open Questions: - [Question 1] - [Question 2] , }, }模板本质上是一份定义工作记忆结构的 Markdown 文档包含个人信息、偏好、会话状态等不同类型信息的章节。其作用有三引导Agent 该追踪什么信息、如何组织这些信息为跨会话的工作记忆提供一致的结构让 Agent 更容易查找和更新特定信息片段。从源码看见上文WorkingMemoryConfig与模板解析逻辑模板的format支持markdown与json两种形式JSON 模板同样会生成相应的空对象骨架供 Agent 填充。设计模板时应基于 Agent 的具体需求考虑它需要记住用户或任务的哪些信息。在 Playground 中验证工作记忆课程 23-testing-working-memory.md 提供了一套完整的实测路径按上述配置更新 Agent 代码使用npm run dev重启开发服务器打开 Playgroundhttp://localhost:4111/选择 MemoryAgent进行一段会透露个人信息的对话例如Hi, my name is JordanI live in Toronto, CanadaI prefer casual communicationIm interested in artificial intelligence and music productionWhat do you know about me so far?切换到新话题后再回头验证记忆是否持久Lets talk about the latest AI developments就 AI 展开一段对话What was my name again and where do I live?预期结果是Agent 能完整回忆出此前透露的姓名、地点、沟通偏好与兴趣——即使对话已经切换到其他话题。这正是工作记忆区别于对话历史的核心证据对话历史只包含最近的消息而工作记忆以结构化方式跨话题、跨轮次保存重要信息。实践建议与最佳实践课程 24-working-memory-in-practice.md 指出工作记忆特别适合以下场景个人助手需要记住用户偏好客户支持 Agent需要追踪问题细节教育类 Agent需要记住学生的学习进度任务导向 Agent需要追踪复杂任务的状态。合理使用工作记忆可以让 Agent 显得更个性化、更体贴。配套的最佳实践包括有选择性地写入只存放跨多个对话仍然相关的信息不要让瞬态细节挤爆工作记忆指令要清晰明确告诉 Agent 何时、如何更新工作记忆并指示它在询问用户已提供过的信息前先检查记忆精心设计模板按 Agent 的具体需求组织模板结构用清晰的标签和分区让信息易于查找充分测试验证 Agent 能正确更新与检索工作记忆并覆盖冲突信息、用户更正等边界情况。小结工作记忆是 Mastra 记忆体系中最适合承载用户画像与任务状态的一层它以结构化 Markdown 文本为存储格式以 INPUT 处理器在每轮对话开始时注入系统指令以updateWorkingMemory工具实现按需更新并通过thread/resource作用域控制记忆的可见范围。相比逐字记录的对话历史它是更高效、更聚焦的提炼摘要。你可以继续深入学习同一课程中的后续章节25-combining-memory-features.md 讲述了如何将工作记忆与对话历史、语义召回组合使用29-memory-best-practices.md 则汇总了记忆体系的整体最佳实践也可以直接阅读源码中对应的处理器实现working-memory.ts与测试用例working-memory.test.ts深入验证本文所述的行为细节。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考