Mastra 语义召回配置指南：为 Agent 定制 Semantic Recall 与向量检索

Mastra 语义召回配置指南为 Agent 定制 Semantic Recall 与向量检索【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra语义召回Semantic Recall是 Mastra 基于向量检索RAG的记忆扩展能力它能让 Agent 跳出最近几条消息的限制跨过漫长的对话历史找到与当前问题语义最相关的内容。本文以配置语义召回为主线完整讲解Memory实例的存储、向量库、嵌入器与options配置项并结合 packages/memory 源码剖析topK、messageRange、scope、filter等高级参数的底层语义让你可以照着配置出一套可运行、可调优的长期记忆 Agent。前置条件向量存储与嵌入器缺一不可语义召回的本质是把文本变成向量、再用向量相似度找历史消息因此它有两个硬性前提向量存储Vector Store负责保存消息的向量嵌入并提供相似性检索接口。嵌入器Embedder负责把消息文本转换为高维向量同一语义越相近的文本向量距离越近。Mastra 提供了多种向量存储适配器包括 LibSQL、Chroma、Pinecone、Qdrant、Postgres配合 pgvector。本教程使用LibSQLVector它和LibSQLStore同属mastra/libsql包用一个本地 SQLite 文件即可同时承载对话历史与向量数据最适合本地开发和课程演示。完整的向量存储接入方式可参考课程 Vector Store Configuration。语义召回的运行前提是Memory实例同时配置了vector与embedder这一点在 packages/memory/src/index.ts 中有多处守卫判断例如if (this.vector this.embedder config.semanticRecall)缺少任何一个语义召回都不会执行。基础配置开启语义召回的最小完整示例在 配置语义召回 中给出的示例是一个同时开启近期对话历史与语义召回的完整配置import { Agent } from mastra/core/agent import { Memory } from mastra/memory import { LibSQLStore, LibSQLVector } from mastra/libsql // Create a memory instance with semantic recall 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: { lastMessages: 20, // Include the last 20 messages in the context semanticRecall: true, // Enable semantic recall with default settings }, }) // 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. When a user shares information about themselves, acknowledge it and remember it for future reference. If asked about something mentioned earlier in the conversation, recall it accurately. You can also recall relevant information from older conversations when appropriate. , model: openai/gpt-5.4, memory: memory, })逐项拆解每个配置块storage对话历史存储。LibSQLStore负责持久化消息记录id用于标识存储实例多个存储共用一个库文件时靠id区分url指向 SQLite 文件路径。注意注释中的关键提示该路径是相对.mastra/output目录解析的即 Mastra 构建输出目录别把它当成源码目录下的相对路径。vector向量数据库。LibSQLVector负责保存和检索消息的向量嵌入。与storage的id类似id: learning-memory-vector用于区分同一个文件中的向量集合。embedder嵌入器。示例中使用了 OpenAI 的openai/text-embedding-3-small。任何与 Mastra 兼容的嵌入模型都可以用于此配置不一定局限于 OpenAI。从源码实现看语义召回的所有相似性搜索都依赖this.embedder与this.vector协同工作因此这里配置的模型将直接决定召回的语义质量与成本。options.lastMessages近期对话窗口。lastMessages: 20表示把最近 20 条消息作为固定上下文注入 Agent。它和语义召回是互补关系lastMessages负责最近发生的事语义召回负责很久以前但语义相关的事。options.semanticRecall语义召回开关。这里以布尔值true开启使用全部默认参数。从 packages/memory/src/index.ts 可以看出semanticRecall: true等价于使用topK DEFAULT_TOP_K即4与messageRange DEFAULT_MESSAGE_RANGE即{ before: 1, after: 1 }。默认值常量定义在 packages/memory/src/index.tsconst DEFAULT_MESSAGE_RANGE { before: 1, after: 1 } as const; const DEFAULT_TOP_K 4;instructions与modelAgent 的系统提示中明确描述了记忆能力的行为准则记住用户偏好、准确回忆前文信息、适当调用更早的对话模型选用openai/gpt-5.4。在实战中良好的指令与语义召回配置配合才能让模型主动、准确地使用检索到的历史信息。语义召回是如何工作的一次检索的完整链路要理解上述配置中的每一项有必要先弄清语义召回的运行流程。课程 How Semantic Recall Works 将其概括为四步对用户当前消息创建向量嵌入Embedding在历史消息的向量空间中执行相似性搜索取出最相关的一批消息由topK决定数量连同匹配消息前后的上下文由messageRange决定范围一起拼入 Agent 的上下文窗口。由于向量捕获的是语义而非字面检索可以在措辞不同的情况下命中含义相近的旧消息。例如用户之前说过 Im working on a project with a deadline next month之后问 When is my project due?系统仍能依据两者的语义相似度找到那条旧消息。这正是语义召回区别于普通关键词搜索、也区别于仅包含最近消息的对话历史的核心价值。更基础的概念背景可参见课程 What is Semantic Recall。高级配置用对象形式精确控制召回行为当默认参数无法满足需求时可以把semanticRecall从布尔值改为对象精细控制检索行为参考课程 Advanced configuration of semantic recallconst memory new Memory({ storage: new LibSQLStore({ id: learning-memory-storage, url: file:../../memory.db, // relative path from the .mastra/output directory }), vector: new LibSQLVector({ url: file:../../vector.db, // relative path from the .mastra/output directory }), embedder: openai.embedding(text-embedding-3-small), options: { semanticRecall: { topK: 3, messageRange: { before: 2, after: 1, }, scope: resource, // Search all threads for this resource filter: { projectId: { $eq: project-a } }, }, }, })topK控制检索条数topK决定每次召回最多返回多少条相似消息默认值为4。调高topK会带回更多候选对复杂话题更有利但也可能混入相关性较低的内容增加上下文与成本开销调低则更精准但可能漏掉边缘相关信息。源码中该值通过config?.semanticRecall?.topK ?? defaultTopK解析缺省时回退到DEFAULT_TOP_K 4。messageRange控制上下文窗口messageRange决定每条命中消息附带多少上下文。它支持两种写法数字形式messageRange: 2表示匹配消息前后各取 2 条对象形式messageRange: { before: 2, after: 1 }表示匹配消息之前取 2 条、之后取 1 条。从 packages/memory/src/index.ts 的实现可以看到数字形式会被同时应用于before与after对象形式则分别读取。默认值{ before: 1, after: 1 }。附带前后文是为了让 Agent 理解匹配消息的完整语境避免只见树木不见森林。scope限定检索范围scope控制搜索范围thread只检索当前线程Thread内的消息resource检索该资源Resource通常对应一个用户名下所有线程的消息。默认行为偏向资源级检索。在源码中判断条件为config?.semanticRecall?.scope ! thread时按资源范围处理并且当启用资源级检索而调用侧未提供resourceId时会抛出明确提示要求提供resourceId或显式把scope设为thread见 packages/memory/src/index.ts。选择scope: resource是跨会话长期记忆的关键——它让 Agent 能回忆起同一用户过去多轮对话中的信息。filter按元数据精确过滤filter基于线程Thread元数据限制召回结果常用于多租户场景例如按项目 ID、分类或优先级过滤。一个关键细节是过滤器匹配的是消息保存时写入嵌入的元数据快照。如果之后线程元数据发生变化已存在的嵌入仍保留旧元数据直到这些消息被再次保存或重新索引。filter支持的比较运算符与常见用法如下运算符含义示例$eq等于{ projectId: { $eq: my-project } }$ne不等于{ status: { $ne: archived } }$gt/$gte大于 / 大于等于{ priority: { $gte: 3 } }$lt/$lte小于 / 小于等于{ priority: { $lt: 5 } }$in属于数组{ category: { $in: [work, research] } }$nin不属于数组{ category: { $nin: [spam] } }$and逻辑与{ $and: [{ projectId: { $eq: project-a } }, { priority: { $gte: 3 } }] }$or逻辑或{ $or: [{ a: { $eq: 1 } }, { b: { $eq: 2 } }] }针对常见场景的组合示例// Filter by project const options { semanticRecall: { filter: { projectId: { $eq: my-project } } }, } // Filter by multiple categories const options { semanticRecall: { filter: { category: { $in: [work, research] } } }, } // Filter by project and priority const options { semanticRecall: { filter: { $and: [{ projectId: { $eq: project-a } }, { priority: { $gte: 3 } }], }, }, }实战验证在 Playground 中检验跨主题召回配置完成后可以通过 Testing Semantic Recall 中的步骤验证效果用上述配置更新 Agent 代码通过npm run dev重启开发服务器打开 Playground默认地址 http://localhost:4111/选择 MemoryAgent依次输入多个不同主题的消息制造话题漂移Lets talk about my work project firstIm working on a new website for a clientThe deadline is in two weeksNow lets switch topics. Im also planning a vacationIll be visiting Japan next monthIll be staying in Tokyo and KyotoLets talk about something else. Im learning to play guitarI practice for 30 minutes every dayCan you remind me about my work project deadline?尽管项目截止日期是若干条消息之前提到的且后续对话早已切换话题Agent 仍应能正确回忆起这条信息——这正是语义召回区别于近期对话窗口的体现它能从对话历史的任意位置检索语义相关内容。验证时还可以刻意调整topK与messageRange参数观察召回行为的变化调大topK看是否能找回更多相关片段调大messageRange看匹配消息的上下文是否更完整。小结配置 Mastra 语义召回的核心要点可归纳为缺一不可的前置vector向量库与embedder嵌入器是语义召回运行的前提布尔开关 默认值semanticRecall: true即使用topK: 4与messageRange: { before: 1, after: 1 }的默认行为对象精调topK控制召回数量messageRange控制每条命中的上下文宽度scope决定线程内检索还是跨线程资源级检索filter基于线程元数据做多租户级过滤与近期历史互补lastMessages覆盖最近对话语义召回覆盖更早但语义相关的内容两者共同构成 Agent 的完整记忆上下文。通过组合这些参数你可以为不同的业务场景单线程问答、跨会话用户画像、多项目数据隔离定制恰到好处的语义召回策略让 Agent 真正记住该记住的内容。进一步的记忆组合与最佳实践可继续参考课程后续章节 Combining Memory Features 与 Memory Best Practices。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考