VoltAgent Working Memory 实战指南：跨会话持久化 Agent 上下文的三格式配置与源码解析

人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆【免费下载链接】voltagentAI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework项目地址https://gitcode.com/gh_mirrors/vo/voltagent点击查看免费下载Working Memory工作记忆是 VoltAgent 在完整消息历史之外维护的一份紧凑上下文它不保存每一轮对话而是沉淀出值得长期记住的关键事实、用户偏好与目标并在多轮交互中持续生效。本文以 working-memory.md 为核心脉络结合voltagent/core与voltagent/libsql的源码实现完整讲解三种存储格式Markdown 模板、Zod JSON Schema、自由文本、conversation/user两种作用域、Agent 自动注入的系统指令与内置工具、Append / Replace 两种更新模式以及编程式 API 的完整用法。读完本文你将能独立为 VoltAgent 应用配置一套具备跨会话记忆能力的 Agent并理解其底层存储与合并逻辑。什么是 Working MemoryWorking Memory 的定位是消息历史的有效补充而非替代。当对话轮次变长、消息窗口受限时模型会逐渐丢失早期出现的重要信息Working Memory 把用户的名字、时区、沟通风格、当前目标、项目进度这类高价值信息压缩成一份简短文档在每次生成时随系统提示词注入从而保证 Agent 在多轮甚至跨会话交互中保持连续性。从源码看Working Memory 由 Memory 类 统一管理配置项workingMemory挂载在MemoryConfig上类型定义。启用后整个生命周期由三层协作完成配置层Memory构造时读取workingMemory配置缓存到this.workingMemoryConfig存储层读写操作最终委托给storage适配器LibSQL、Postgres、Supabase 等的getWorkingMemory/setWorkingMemory/deleteWorkingMemory接口Agent 层Agent 将当前记忆内容与使用规则注入系统提示词并自动注册记忆工具供模型调用。启用与三种存储格式启用 Working Memory 只需在Memory配置中加入workingMemory对象核心开关为enabled。支持的三种格式通过互斥字段自动判定WorkingMemoryConfig 联合类型提供schemaZod 对象→ 格式为JSON数据经过 Zod 校验提供template字符串→ 格式为Markdown按模板结构维护文本两者都不提供 → 格式为自由文本Free-form。运行时可通过memory.getWorkingMemoryFormat()查询当前格式返回markdown | json | null见 index.ts配置了 schema 返回json否则一律视为markdown。Markdown Template结构化文本适合承载叙述性上下文——总结、笔记、观察、项目概况。模板中预先定义好分节骨架模型按骨架填充内容import { Agent, Memory } from voltagent/core; import { LibSQLMemoryAdapter } from voltagent/libsql; const memory new Memory({ storage: new LibSQLMemoryAdapter({ url: file:./.voltagent/memory.db }), workingMemory: { enabled: true, scope: conversation, // default template: # User Profile - Name: - Role: - Timezone: # Current Goals - # Preferences - , }, }); const agent new Agent({ name: Assistant, model: openai/gpt-4o-mini, memory, });这里url: file:./.voltagent/memory.db指向一个本地 LibSQL 文件数据库运行时会自动创建.voltagent目录。模板中的空字段会被保留——这是刻意设计源码生成的系统指令明确要求不要删除空节保持模板结构见下文 Agent 集成部分。JSON Schema需要类型安全与结构校验时使用 Zod Schema。模型写入的内容必须通过schema.safeParse校验非法结构会直接抛出Invalid working memory format错误对应测试用例见 working-memory.spec.tsimport { z } from zod; const memory new Memory({ storage: new LibSQLMemoryAdapter({ url: file:./.voltagent/memory.db }), workingMemory: { enabled: true, scope: user, // persist across conversations schema: z.object({ profile: z .object({ name: z.string().optional(), role: z.string().optional(), timezone: z.string().optional(), }) .optional(), preferences: z.array(z.string()).optional(), goals: z.array(z.string()).optional(), }), }, });字段尽可能标记为optional原因有二其一模型在信息不全时无需为凑齐必填字段而编造内容其二Append 模式下支持部分更新——只传{ goals: [...] }也能通过校验并合并进已有数据。校验通过后内容会经safeStringify以 2 空格缩进规范化后落库index.ts。Free-Form不提供template也不提供schemaWorking Memory 退化为无结构的自由文本适合临时性、探索性的场景const memory new Memory({ storage: new LibSQLMemoryAdapter({ url: file:./.voltagent/memory.db }), workingMemory: { enabled: true, // no template or schema }, });自由文本的优点是灵活缺点是缺少结构约束长期使用容易产生冗余。建议仅在原型阶段使用正式场景优先考虑前两种格式。Scope 作用域conversation 与 userscope决定记忆的隔离边界WorkingMemoryScope 类型Scope默认语义存储位置conversation✅上下文仅在该对话线程内生效conversations表的metadata.workingMemory字段user—上下文跨该用户的所有对话共享${tablePrefix}_users表的metadata.workingMemory字段隔离性由存储层保证。以 LibSQL 适配器实现 为例conversation作用域按conversationId读取对应会话记录的metadata.workingMemoryuser作用域则查询${tablePrefix}_users表中该userId的metadata.workingMemory。测试用例验证了两种作用域的读写行为working-memory.spec.tsconversation 作用域下会话 A 写入的记忆在会话 B 中读取为nulluser 作用域下同一用户的不同会话都能读到同一份记忆。所有官方适配器LibSQL、Postgres、Supabase、Managed Memory均同时支持两种作用域。写入user作用域时若该用户记录不存在适配器会自动执行INSERT创建见 memory-core.ts。Agent 集成系统指令注入与内置工具启用 Working Memory 后Agent 在每次生成时会自动完成两件事对应源码 agent.ts 中构建workingMemoryContext的逻辑。系统提示词注入Memory.getWorkingMemoryInstructions()会生成一段结构化指令index.ts追加到系统提示词末尾其中包含管理指南主动存储将来可能有用的信息、信息变化时立即更新、使用一致的 JSON/Markdown 格式、永远不向用户提及此系统关键更新规则Append 为默认推荐模式、Replace 模式会删除未包含的数据、JSON 支持部分字段更新格式特有约束JSON 遵循 schema 结构、Markdown 保持模板骨架模板与当前内容以context_template、current_context标签包裹注入便于模型定位未存储任何内容时current_context中会提示立即开始捕获相关信息。指令的措辞还随scope动态调整user作用域提示跨所有会话保持conversation作用域提示在整个对话期间保持。自动暴露的工具Agent 依据createWorkingMemoryToolsagent.ts自动注册三个工具工具参数说明get_working_memory()无读取当前 working memory 内容无内容时返回No working memory content found.update_working_memory(content, mode?)content遵循 schema或字符串mode为append/replace更新内容配置了 schema 时参数直接绑定该 Zod schemaclear_working_memory()无清空记忆内容update_working_memory的mode参数在工具层默认append见 agent.ts 的z.enum([replace, append]).default(append)这与文档中Append Mode (Default)一致。工具描述中会嵌入当前current_context与模板内容引导模型在追加前先了解已有数据。只读模式如果你在调用时设置了options.memory.options.readOnly: trueAgent 将只暴露get_working_memory()跳过所有写操作agent.ts 中isReadOnly分支。只读模式下已有记忆上下文仍会加载进系统提示词但模型无法修改或清空它。该选项的类型定义在 types.tsreadOnly: true表示本次调用内存只读可加载但不可持久化写入。适合审计、只读分析或对记忆有严格权限控制的场景。主动式记忆管理Agent 会主动根据对话流程维护记忆——这正是系统指令所引导的行为当用户在对话中提到新的偏好、目标或事实时模型自动调用update_working_memory沉淀信息无需开发者手动干预。更新模式Append 与 ReplaceAppend 模式Agent 默认Append 安全地将新信息与已有内容合并不会丢失旧数据。合并规则因格式而异JSON Schema 格式由simpleDeepMerge实现见 index.ts对象递归深合并simpleDeepMerge对两侧均为非数组对象时递归合并数组去重拼接[...new Set([...target, ...source])]基本类型新值覆盖旧值。// 已有 working memory: // { profile: { name: Alice }, goals: [Learn TypeScript] } // Agent 调用 update_working_memory 传入: // { goals: [Build an API] } // 合并结果: // { profile: { name: Alice }, goals: [Learn TypeScript, Build an API] }测试用例完整验证了深合并、数组去重与部分更新行为working-memory.spec.ts例如初始settings: { theme: dark }Append 传入settings: { language: en }后theme与language同时保留。Markdown 格式新内容以空行分隔符追加到已有内容之后${existingContent}\n\n${newContent}见 index.ts。Replace 模式Replace 用新内容完全覆盖旧内容未包含的数据会全部丢失await memory.updateWorkingMemory({ conversationId: thread-123, userId: user-456, content: { profile: { name: Bob } }, // existing data lost options: { mode: replace }, });Replace 模式仅在有意重置全部上下文时使用。Agent 工具描述中对其标注了强烈警告replace会彻底覆盖、删除其他字段并要求模型在必须使用时包含全部现有数据。⚠️实现细节提示直接调用Memory.updateWorkingMemory编程式 API 时若不传options.mode源码默认走replace分支const mode params.options?.mode || replace见 index.ts而 Agent 工具层的mode参数默认是append。为避免误删数据编程式调用时应显式指定mode并默认选择append。编程式 API不经过 Agent 的直接访问如果不想依赖模型自主调用工具可以绕过 Agent 直接读写记忆。所有方法都接收{ conversationId, userId }定位目标index.ts// 读取当前 working memory const content await memory.getWorkingMemory({ conversationId: thread-123, userId: user-456, }); console.log(content); // string (JSON 或 Markdown) // 更新显式 append 模式 await memory.updateWorkingMemory({ conversationId: thread-123, userId: user-456, content: { goals: [Complete onboarding] }, // object 或 string options: { mode: append }, }); // 更新replace 模式 await memory.updateWorkingMemory({ conversationId: thread-123, userId: user-456, content: Fresh context, options: { mode: replace }, }); // 清空 await memory.clearWorkingMemory({ conversationId: thread-123, userId: user-456, }); // 内省配置 const format memory.getWorkingMemoryFormat(); // markdown | json | null const template memory.getWorkingMemoryTemplate(); // string | null const schema memory.getWorkingMemorySchema(); // ZodObject | null几点编程式使用的注意点content支持字符串或普通对象对象会先经safeStringify序列化processContentindex.tsJSON 格式下若写入内容无法通过 schema 校验会抛出错误Markdown 格式不受此限制未启用 Working Memory 时getWorkingMemory返回nullupdateWorkingMemory抛出Working memory is not enabledclearWorkingMemory静默返回对应测试见 working-memory.spec.tsgetWorkingMemorySummary()可返回面向 UI/控制台的配置摘要是否启用、作用域、格式、模板内容、schema 字段类型映射见 index.tsschema 摘要会经 Zod 反射将字段类型名转换为友好名称。存储实现细节Working Memory 并不建独立的存储表而是复用会话与用户记录的metadata字段以workingMemory键保存字符串内容conversation 作用域写入conversations.metadata.workingMemory读取时若会话不存在返回null写入时若会话不存在抛出ConversationNotFoundErroruser 作用域写入${tablePrefix}_users.metadata.workingMemory适配器相关前缀用户记录不存在时自动INSERT创建已存在时UPDATE覆盖。以 LibSQL 实现 为参照SQL 层面大致为conversation 作用域通过getConversation(conversationId)拿到记录后修改metadata再updateConversationuser 作用域直接执行UPDATE ${usersTable} SET metadata ?, updated_at ? WHERE id ?或首次INSERT。deleteWorkingMemory则从 metadata 中移除workingMemory键。所有官方适配器LibSQL、Postgres、Supabase、Managed Memory都实现了这三组接口因此 Working Memory 的存储细节完全由所选适配器决定对上层 API 透明。完整示例一用户级偏好跨会话需求一个个人助手需要跨所有对话记住用户的偏好。使用user作用域 JSON Schemaimport { Agent, Memory } from voltagent/core; import { LibSQLMemoryAdapter } from voltagent/libsql; import { z } from zod; const userPreferencesSchema z.object({ name: z.string().optional(), timezone: z.string().optional(), communicationStyle: z.enum([formal, casual]).optional(), interests: z.array(z.string()).optional(), }); const memory new Memory({ storage: new LibSQLMemoryAdapter({ url: file:./.voltagent/memory.db }), workingMemory: { enabled: true, scope: user, // persist across all conversations schema: userPreferencesSchema, }, }); const agent new Agent({ name: Personal Assistant, instructions: Adapt responses based on user preferences stored in working memory., model: openai/gpt-4o-mini, memory, }); // 第一次对话模型发现并沉淀用户偏好 await agent.generateText(I prefer casual communication and Im into AI and music., { memory: { userId: user-123, conversationId: conv-1, }, }); // 换一个对话线程Agent 依然记得用户偏好 await agent.generateText(What should I learn next?, { memory: { userId: user-123, conversationId: conv-2, // different thread }, });关键点两次调用共享userId: user-123但conversationId不同。由于作用域是user第二次对话仍能读取第一次沉淀的记忆从而给出个性化建议。完整示例二会话级项目目标按项目隔离需求一个项目管理 Agent为每个项目维护独立上下文。使用conversation作用域 Markdown 模板用conversationId区分项目const projectMemory new Memory({ storage: new LibSQLMemoryAdapter({ url: file:./.voltagent/memory.db }), workingMemory: { enabled: true, scope: conversation, // isolated per project template: # Project Context - Name: - Deadline: - Tech Stack: # Current Sprint - Goals: - Blockers: , }, }); const agent new Agent({ name: Project Manager, instructions: Track project context and help with sprint planning., model: openai/gpt-4o-mini, memory: projectMemory, }); // 每个项目对应一个 conversationId互不干扰 await agent.generateText(Lets plan the e-commerce project using Next.js., { memory: { userId: user-123, conversationId: project-ecommerce, }, }); await agent.generateText(For the analytics dashboard, well use React and D3., { memory: { userId: user-123, conversationId: project-analytics, }, });这里project-ecommerce与project-analytics各自拥有独立的 Working Memory电商项目的技术栈信息不会泄漏到分析项目中。完整可运行的对照实现可参考 examples/with-working-memory/src/index.ts它同时定义了一个user作用域 Zod Schema 的 JSON Memory Agent 和一个conversation作用域 Markdown 模板的 Markdown Memory Agent并通过VoltAgent Hono 服务器暴露/api/agent/generateText接口。用npm create voltagent-applatest -- --example with-working-memory即可搭建POST 请求携带userId/conversationId即可观察模型调用记忆工具的完整链路详见 示例 README。最佳实践结构化数据用 JSON Schema用户档案、配置类信息需要类型安全与校验时优先 JSON叙述性上下文用 Markdown 模板总结、笔记、观察、项目背景这类自由文本用模板更自然默认使用 Append 模式比 Replace 更安全保留已有数据仅在有意重置时使用 Replace用户级偏好用user作用域姓名、时区、沟通风格、兴趣爱好会话级数据用conversation作用域目标、任务、项目细节、阶段性进度保持紧凑Working Memory 是消息历史的补充而非替代只沉淀高价值、可复用的事实避免内容膨胀稀释注意力。系统指令也反复强调随时保存有用信息与保持结构因此模板与 schema 设计越精简模型维护成本越低。进一步阅读语义搜索Semantic Search检索相关的历史消息与 Working Memory 形成互补托管记忆Managed Memory零配置的 Working Memory 存储方案LibSQL / Turso自托管 Working Memory 存储记忆概览Overview了解 VoltAgent 记忆体系全貌。赞分享人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆【免费下载链接】voltagentAI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework项目地址https://gitcode.com/gh_mirrors/vo/voltagent点击查看免费下载相关推荐VoltAgent Working Memory 实战用会话级与用户级持久记忆让 Agent 记住重要上下文VoltAgent Working Memory 实战用会话级与用户级持久记忆让 Agent 记住重要上下文 导读 本篇技术指南围绕 VoltAgent 官方人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音VoltAgent Supabase Memory 实战指南用 Supabase Postgres 持久化 Agent 会话记忆VoltAgent Supabase Memory 实战指南用 Supabase Postgres 持久化 Agent 会话记忆 导读 本文围绕 VoltAg人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音balenaEtcher 快速烧录指南安全制作 SD 卡与 U 盘启动盘balenaEtcher 快速烧录指南安全制作 SD 卡与 U 盘启动盘 给树莓派灌系统最怕的不是慢而是手滑把镜像写进系统盘。balenaEtcher 是桌面应用开发工具智能硬件上一篇PyTorch FakeTensor 深度解析不执行计算即可获得张量元数据shape/dtype/device的模拟机制下一篇Carbon 语言元组与元组索引Tuples and Tuple Indexingp003646 提案全解析与实现验证创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考