VoltAgent Memory API 完整指南：`/api/memory/*` 端点解析、鉴权与语义检索实战

人工智能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 通过一组位于/api/memory/*下的 HTTP 端点将 Agent 的会话Conversation、消息Message、工作记忆Working Memory与语义搜索结果统一暴露给外部系统。本文以官方 API 文档为骨架结合 server-core 路由定义 与 内存处理器源码 逐端点展开你将掌握每个端点的参数、请求/响应结构、错误码语义以及多 Agent 场景下agentId解析规则、消息校验流程和语义搜索的底层依赖从而直接基于curl或任意 HTTP 客户端接入 VoltAgent 的记忆能力。Auth鉴权默认情况下这些端点受保护具体取决于服务端配置。使用authNext时内存端点属于非 public、非 console 的常规路由需要携带有效的用户 JWTAuthorization: Bearer token开发环境非production可用x-voltagent-dev: true绕过。完整策略见 Authentication。默认开发端口为3141下文示例均以http://localhost:3141为基准。公共参数理解 agentId / resourceId / userId / conversationId几乎所有内存端点都依赖四个核心标识参数参数位置必填性说明agentIdquery / body可选多 Agent 注册或未配置全局内存时必填用于定位具体 Agent 的内存实例resourceIdquery / body可选提供agentId时默认取该 Agent 的 ID源码中resourceId默认回退到resolved.resourceId即 Agent state 的iduserIdquery / body创建会话、保存/删除消息时必填标识内存数据的所属用户conversationIdpath / body视端点而定会话标识创建会话时若省略由服务端自动生成底层解析规则resolveMemory路由处理器会先调用resolveMemory()决定“这次请求作用于哪份 Memory”。从 memory.handlers.ts 可以看到完整的决策链显式agentId从AgentRegistry获取 AgentAgent 不存在返回404 Agent not foundAgent 未配置 Memory 返回400 Memory not configured for agent id无agentId先看AgentRegistry.getGlobalMemory()是否存在全局内存否则统计所有注册 Agent 中已配置 Memory 的数量——恰好 1 个时自动选用并回填agentId/resourceId多于 1 个时返回400 agentId is required when multiple agents are configured0 个时返回400 Memory not configured。这解释了文档中“agentId在多个 Agent 注册或未配置全局内存时是必填项”的实际原因多 Agent 场景下必须显式声明目标否则服务端无法确定操作哪块记忆。会话Conversation管理列出会话GET /api/memory/conversations查询参数agentId、resourceId、userId、limit、offset、orderBy、orderDirection。curl http://localhost:3141/api/memory/conversations?userIduser-123limit20响应示例{ success: true, data: { conversations: [ { id: conv-001, resourceId: assistant, userId: user-123, title: Support Chat, metadata: {}, createdAt: 2025-01-01T12:00:00.000Z, updatedAt: 2025-01-01T12:05:00.000Z } ], total: 1, limit: 20, offset: 0 } }实现细节处理器同时调用memory.queryConversations({ userId, resourceId, limit, offset, orderBy, orderDirection })与memory.countConversations(...)Promise.all并行响应中的total是忽略分页后的总数见 memory.handlers.ts。在 server-hono 路由 中limit/offset经parseNumber解析非法数值返回undefined即不限制orderBy采用白名单校验仅允许created_at、updated_at、title三者之一否则忽略orderDirection仅接受ASC/DESC大小写不敏感其余值被忽略roles这类逗号分隔参数会被split(,)展开为数组。获取会话GET /api/memory/conversations/:conversationIdcurl http://localhost:3141/api/memory/conversations/conv-001响应体形如{ success: true, data: { conversation: {...} } }。会话不存在时返回404 Conversation not found处理器在getConversation返回空值时构造见 memory.handlers.ts。创建会话POST /api/memory/conversations请求体{ userId: user-123, resourceId: assistant, title: New Chat, metadata: { source: web } }userId必填缺失返回400 userId is required未传resourceId时回退到 Agent ID两者皆无则400 resourceId is requiredtitle可选省略时服务端存储空字符串自动标题生成仅当 Agent 在创建会话时启用了Memory配置上的generateTitle才发生对应packages/core/src/memory/types.ts中 Memory 配置的generateTitle?: boolean | ConversationTitleConfig字段conversationId省略时由服务端用generateId()生成目标会话已存在时返回409 Conversation already exists由ConversationAlreadyExistsError捕获映射见 memory.handlers.ts。更新会话PATCH /api/memory/conversations/:conversationId请求体支持resourceId、userId、title、metadata中的任意组合{ title: Updated Title, metadata: { priority: high } }处理器只把显式传入的字段并入更新对象updates若没有任何可更新字段则返回400 No updates provided会话不存在时经ConversationNotFoundError映射为404。删除会话DELETE /api/memory/conversations/:conversationIdcurl -X DELETE http://localhost:3141/api/memory/conversations/conv-001成功响应{ success: true, data: { deleted: true } }。该操作会连同会话下的消息一并删除路由定义中明确写着 Delete a conversation and its messages from memory storage.。克隆会话POST /api/memory/conversations/:conversationId/clone请求体{ newConversationId: conv-002, title: Clone of Support Chat, includeMessages: true }newConversationId省略时自动生成title、metadata、userId、resourceId缺省时继承源会话includeMessages默认行为为true源码中body.includeMessages ! false才跳过复制复制消息时先getMessages(source.userId, conversationId)再整体addMessages到新会话响应会附带messageCount见 memory.handlers.ts新 ID 已被占用时返回409。消息Message管理列出消息GET /api/memory/conversations/:conversationId/messages查询参数agentId、limit、before、after、roles、userId。curl http://localhost:3141/api/memory/conversations/conv-001/messages?limit50注意事项roles接受逗号分隔列表如user,assistant,tool会被切分为字符串数组透传给memory.getMessages的roles过滤before/after期望 ISO 8601 时间戳路由层用parseDate转换为Date非法时间戳被忽略未传userId时处理器自动使用会话归属的userIdquery.userId ?? conversation.userId响应结构为{ success, data: { conversation, messages } }消息以UIMessage[]形式返回。保存消息POST /api/memory/save-messages请求体{ userId: user-123, conversationId: conv-001, messages: [ { role: user, content: Hi there }, { message: { role: assistant, content: Hello! } } ] }注意事项与实现细节每条消息都必须带userId与conversationId可以写在单条消息条目上也可以写在请求体顶层统一提供处理器做归一化时优先取条目级字段回退到 body 级字段见 memory.handlers.ts消息支持两种形态直接展开的 UIMessage或包裹在{ message: {...} }中的形式两者都会被识别消息 ID 省略时自动生成message.id || generateId()messages必须是非空数组否则400 messages array is required归一化后仍有条目缺conversationId/userId时返回400 Each message must include conversationId and userId每条消息的userId必须与会话归属者一致否则400 userId does not match conversation id最终按userId:conversationId分组逐组调用memory.addMessages响应{ success: true, data: { saved: 条数 } }会话不存在时返回404 Conversation not found: id。删除消息POST /api/memory/messages/delete请求体{ userId: user-123, conversationId: conv-001, messageIds: [msg-1, msg-2] }messageIds必须是非空数组400 messageIds array is requiredconversationId与userId均必填且userId必须匹配会话归属者否则400处理器先取出会话消息统计与messageIds命中的数量再调用memory.deleteMessages返回{ success: true, data: { deleted: 命中数 } }。工作记忆Working Memory工作记忆是随会话或用户持久化的轻量“便签”式内容通常是 Markdown 文本或结构化 JSON用于跨轮次保留偏好、上下文摘要等。获取工作记忆GET /api/memory/conversations/:conversationId/working-memory查询参数agentId、scope、userId。curl http://localhost:3141/api/memory/conversations/conv-001/working-memory?scopeconversationscopeuser需要查询串中提供userId处理器对 user 作用域缺失userId时返回400 userId is required for user-scoped working memory见 memory.handlers.tsscope仅识别user其余值一律按conversation处理conversation 作用域会先校验会话存在否则404并回退使用会话的userId内容为空null时返回404 Working memory not found响应除content外还带formatmarkdown/json来自memory.getWorkingMemoryFormat?.()与templatememory.getWorkingMemoryTemplate?.()便于客户端按 schema 化模板渲染。这印证了文档中“content可以是字符串或 JSON 对象当工作记忆基于 schema 时”的说法。更新工作记忆POST /api/memory/conversations/:conversationId/working-memory请求体{ content: Customer prefers email follow-ups., mode: append }content必填缺失返回400 content is required可以是字符串或 JSON 对象schema 化工作记忆mode支持replace与append两种源码中mode被透传为updateWorkingMemory的options: { mode }userId可选但一旦提供就必须与会话归属者一致否则400 userId does not match conversation id会话不存在返回404成功响应{ success: true, data: { updated: true } }。工作记忆相关的底层能力在 Memory 接口 中有完整定义getWorkingMemory/setWorkingMemory/deleteWorkingMemory均支持conversationId/userId/scope三维定位scope类型为WorkingMemoryScopeconversation|user。语义搜索GET /api/memory/search查询参数searchQuery、conversationId、userId、limit、threshold、agentId。curl http://localhost:3141/api/memory/search?searchQueryrefund%20policylimit5searchQuery必填缺失返回400 searchQuery is requiredlimit、threshold由路由层分别用parseNumber/parseFloatValue解析conversationId/userId会被组装为filter对象传入向量检索用于限定搜索范围前置条件该端点依赖 embedding 适配器与 vector 适配器均已配置否则分别抛出EmbeddingAdapterNotConfiguredError/VectorAdapterNotConfiguredError处理器将其统一映射为400——这正是文档所述“未配置则返回 400”的底层原因见 memory.handlers.ts调用链为memory.searchSimilar(query, { limit, threshold, filter })先经embedding.embed(query)生成查询向量再交给vector.search(queryVector, { limit, filter, threshold })完成相似度检索见 core 内存实现成功响应{ success: true, data: { results, count, query } }。错误语义速查路由定义definitions.ts为每个端点声明的状态码可归纳如下状态码典型场景200成功含查询与写操作400参数/请求体非法缺失userId、缺失content、空messages/messageIds、多 Agent 未传agentId、userId 与会话不匹配、未配置 embedding/vector 适配器404会话、消息或工作记忆不存在agentId指向的 Agent 不存在409创建/克隆会话时目标 ID 已存在ConversationAlreadyExistsError500底层存储或适配器异常处理器经buildErrorResponse兜底接入方式小结内存端点由各 Server Provider 注册Hono 实现见 packages/server-hono/src/routes/memory.routes.tsregisterMemoryRoutesElysia 与 serverless-hono 均有对应实现路由路径与摘要统一声明在 packages/server-core/src/routes/definitions.ts 的MEMORY_ROUTES中请求校验与业务逻辑全部收敛在 packages/server-core/src/handlers/memory.handlers.ts 的handle*系列函数服务端框架间可复用Memory 适配能力会话、消息、工作记忆、语义搜索由 packages/core/src/memory/types.ts 定义的Memory接口约束实际存储可由任意实现该接口的适配器提供。实操建议单 Agent 演示环境可直接省略agentId调用全部端点一旦注册多个 Agent务必在所有查询与写操作中显式携带agentId否则会命中400 agentId is required when multiple agents are configured。语义搜索前请先确认服务端已接入 embedding 与向量存储适配器再通过threshold调整相似度截断、用limit控制返回条数。赞分享人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆【免费下载链接】voltagentAI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework项目地址https://gitcode.com/gh_mirrors/vo/voltagent点击查看免费下载相关推荐Qwen Code Agent 工具完全指南子代理委派、Fork 并行执行与后台延续实战Qwen Code Agent 工具完全指南子代理委派、Fork 并行执行与后台延续实战 agent 是 Qwen Code开源终端 AI 编码代理中用于人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音Quarkdown native-library-processor用 KSP 在编译期生成 Kotlin 函数到 Quarkdown 函数的桥接层Quarkdown native library processor用 KSP 在编译期生成 Kotlin 函数到 Quarkdown 函数的桥接层 本文围绕人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音Mastra Memory 完全指南mastra/memory 的会话历史、语义召回与 Observational Memory 深度解析Mastra Memory 完全指南mastra/memory 的会话历史、语义召回与 Observational Memory 深度解析 Mastra人工智能Agent 框架AI AgentRAG后端上一篇STORM项目对DeepSeek R1模型的支持解析下一篇Nohost分布式抓包架构设计破解多团队HTTPS调试的3倍效率提升难题创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考