如何为 Mastra 代理启用 semantic recall 按语义检索历史消息【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastraMastra 代理的消息历史默认只保留最近 N 条消息超出窗口的早期对话对模型不可见。semantic recall 通过在 LLM 请求前用用户输入查询向量库、在 LLM 响应后把新消息写入向量库让代理在长对话中仍能按语义找到并引用早期消息。本文的任务是在一个已有的 Mastra 项目上完成 semantic recall 的启用配置、手动调用recall()检索并通过 tracing 验证召回结果。前提已有一个 Mastra 项目TypeScript 环境代理通过mastra/core/agent的Agent创建。semantic recall 默认关闭启用它必须同时提供 vector store 和 embedder二者缺一都不生效。准备工作安装包并配置存储按文档要求semantic recall 依赖mastra/memory和一个存储/向量适配器。主路径使用文档示例中的 LibSQL本地文件无需额外服务npm install mastra/memorylatest mastra/libsqllatest在 Mastra 主实例上配置 storage使所有代理共享消息存储import { Mastra } from mastra/core import { LibSQLStore } from mastra/libsql export const mastra new Mastra({ storage: new LibSQLStore({ id: mastra-storage, url: :memory:, }), })如果你希望数据持久化到文件把url换成文档中使用的file:./local.db这类值即可:memory:表示数据仅存于内存。启用 semantic recall在代理的Memory配置中做三件事提供storage、提供vector向量库、提供embedder并在options里设置semanticRecall: true。import { Agent } from mastra/core/agent import { Memory } from mastra/memory import { LibSQLStore, LibSQLVector } from mastra/libsql import { ModelRouterEmbeddingModel } from mastra/core/llm const agent new Agent({ id: support-agent, name: SupportAgent, instructions: You are a helpful support agent., model: openai/gpt-5.6-sol, memory: new Memory({ storage: new LibSQLStore({ id: agent-storage, url: file:./local.db, }), vector: new LibSQLVector({ id: agent-vector, url: file:./local.db, }), embedder: new ModelRouterEmbeddingModel(openai/text-embedding-3-small), options: { semanticRecall: true, }, }), })说明文档中各部分的用途storage和vector可以指向同一个 LibSQL 数据库文件vector缺省时使用默认的向量库但显式写出更清晰。embedder使用 Model Router 时传provider/model字符串即可。文档列出的受支持嵌入模型包括 OpenAI 的text-embedding-3-small、text-embedding-3-large、text-embedding-ada-002和 Google 的gemini-embedding-001也可通过providerId: openrouter对象形式访问 OpenRouter 上的多供应商模型。Model Router 会自动从环境变量检测 API keyOPENAI_API_KEY、GOOGLE_API_KEY、OPENROUTER_API_KEYGoogle 模型还会回退到GOOGLE_GENERATIVE_AI_API_KEY。代码中的model: openai/gpt-5.6-sol是文档示例的模型值可按你的账号替换为其它provider/model格式模型。启用后的工作机制每次调用代理时新用户消息先被向量化并查询向量库命中的早期消息作为语义召回部分进入上下文LLM 响应返回后本轮所有新消息用户、助手、工具调用/结果会被插入向量库供后续对话召回。手动调用 recall() 按语义检索除了代理调用时的自动召回还可以用Memory.recall()主动按语义查找消息。recall()相比listMessages的区别是支持vectorSearchString做语义检索const memory await agent.getMemory() // 基本召回按 thread 拉取消息类似 listMessages const { messages } await memory!.recall({ threadId: thread-123, perPage: 50, }) // 语义召回按含义查找消息 const { messages: relevantMessages } await memory!.recall({ threadId: thread-123, vectorSearchString: What did we discuss about the project deadline?, threadConfig: { semanticRecall: true, }, })注意使用vectorSearchString时必须在threadConfig中开启semanticRecall。threadId是要查询的线程 ID需替换为你调用generate()/stream()时实际使用的值。返回值是MastraDBMessage[]格式的消息数组。调用代理本身时需要传入resource和thread来组织对话例如await agent.generate(What did we discuss about the deadline last week?, { memory: { resource: user-123, thread: conversation-123, }, })同一个resource下不同thread的消息也都能被召回取决于下面的scope配置因此用哪组 ID 决定了能检索到什么范围的历史。调优召回行为topK、messageRange、scope、filter把semanticRecall: true换成对象形式即可调整行为const agent new Agent({ id: agent, memory: new Memory({ options: { semanticRecall: { topK: 3, // 检索 3 条最相似消息 messageRange: 2, // 每条命中消息附带前后各 2 条上下文消息 scope: resource, // 在该 resource 的所有 thread 中搜索 filter: { projectId: { $eq: project-a } }, }, }, }), })四个选项的含义topK控制取回多少条相似消息messageRange控制每条命中消息附带多少条前后消息scope决定只搜当前 thread 还是该 resource 的所有 threadfilter用元数据条件限制结果。两个与执行相关的限制scope: resource只被 LibSQL、OracleDB、PostgreSQL、MongoDB、Upstash 这几个存储适配器支持。如果你的向量库不在其中只能使用 thread 范围内的检索。filter匹配的是消息保存时写入嵌入的线程元数据。之后修改线程元数据不会更新已有嵌入那些消息保持旧元数据直到被重新保存或索引。filter支持的运算符$and、$eq、$gt、$gte、$in、$lt、$lte、$ne、$nin、$or。文档中的常见组合示例// 按项目过滤 const options { semanticRecall: { filter: { projectId: { $eq: my-project } } }, } // 多个分类 const options { semanticRecall: { filter: { category: { $in: [work, research] } } }, } // 项目 优先级组合条件 const options { semanticRecall: { filter: { $and: [{ projectId: { $eq: project-a } }, { priority: { $gte: 3 } }], }, }, }可选分支本地嵌入与 PostgreSQL 索引优化FastEmbed本地嵌入模型不想依赖外部嵌入 API 时可安装mastra/fastembednpm install mastra/fastembedlatestimport { Memory } from mastra/memory import { Agent } from mastra/core/agent import { fastembed } from mastra/fastembed const agent new Agent({ id: agent, memory: new Memory({ embedder: fastembed, }), })FastEmbed 还提供面向非英语内容的多语言 E5 模型它是不对称的暴露为multilingualE5LargePassage索引侧和multilingualE5LargeQuery检索侧两个模型。Memory 对存储和召回使用同一个 embedder所以要二选一保持一致地用只有在你同时控制索引和检索两侧的场景如自建 RAG才用成对的 passage/query 模型。E5 产出 1024 维向量向量索引必须按相同维度创建且不能与其它 embedder 的向量混用在同一索引里。PostgreSQL HNSW 索引用 PostgreSQL 做向量库时可通过indexConfig配置索引类型。Mastra 默认创建 IVFFlat 索引文档建议 HNSW尤其配合 OpenAI 嵌入的 inner product 距离const agent new Agent({ memory: new Memory({ storage: new PgStore({ id: agent-storage, connectionString: process.env.DATABASE_URL, }), vector: new PgVector({ id: agent-vector, connectionString: process.env.DATABASE_URL, }), options: { semanticRecall: { topK: 5, messageRange: 2, indexConfig: { type: hnsw, // 使用 HNSW 提升性能 metric: dotproduct, // 适合 OpenAI 嵌入 m: 16, // 双向链接数默认 16 efConstruction: 64, // 构建时候选列表大小默认 64 }, }, }, }), })这一分支面向消息量达到数千条以上的 PostgreSQL 部署索引参数的详细调优见文档中的 PgVector 配置指南。验证召回结果文档给出的验证方式是 tracing启用 tracing 后经 semantic recall 检索到的消息会出现在代理的 trace 输出中与最近消息历史如已配置一起展示。操作步骤在 Studio 打开Observability选项卡选择最近一次代理请求的 trace。找到 LLM call 的 spans检查该请求实际送入模型的上下文。确认其中包含语义召回的消息部分且它们与最近消息历史按时间戳交错排布同一线程的召回结果作为普通消息插入跨线程的召回结果被格式化为 system message。如果你走的是手动路径则验证点就是recall()的返回值传入vectorSearchString后返回的messages数组即命中的消息及其上下文。限制与何时保持关闭每次开启 semantic recall 的调用都会增加延迟新消息要先转成嵌入并查询向量库然后才发给 LLM。文档建议以下情况保持semanticRecall: false默认值最近消息历史已能提供足够上下文或构建实时双向语音等对延迟敏感的应用嵌入和向量查询的延迟会明显可感。向量库选型有 18 个适配器Astra、Chroma、MongoDB、PostgreSQL、Qdrant、Upstash 等各适配器的安装与参数见对应向量库参考文档scope: resource的支持面见上文说明。主路径的完整流程是安装mastra/memory与mastra/libsql→ 在Memory中配齐storage、vector、embedder并设置semanticRecall→ 用带resource/thread的调用积累对话 → 通过 Studio 的 trace 或recall({ vectorSearchString, threadConfig: { semanticRecall: true } })确认早期消息能被语义命中。若需要继续深入可阅读 semantic recall 文档、Memory 总览、消息历史 与 recall() 参考。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 如何为 Mastra 代理启用 semantic recall 按语义检索历史消息
如何为 Mastra 代理启用 semantic recall 按语义检索历史消息【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastraMastra 代理的消息历史默认只保留最近 N 条消息超出窗口的早期对话对模型不可见。semantic recall 通过在 LLM 请求前用用户输入查询向量库、在 LLM 响应后把新消息写入向量库让代理在长对话中仍能按语义找到并引用早期消息。本文的任务是在一个已有的 Mastra 项目上完成 semantic recall 的启用配置、手动调用recall()检索并通过 tracing 验证召回结果。前提已有一个 Mastra 项目TypeScript 环境代理通过mastra/core/agent的Agent创建。semantic recall 默认关闭启用它必须同时提供 vector store 和 embedder二者缺一都不生效。准备工作安装包并配置存储按文档要求semantic recall 依赖mastra/memory和一个存储/向量适配器。主路径使用文档示例中的 LibSQL本地文件无需额外服务npm install mastra/memorylatest mastra/libsqllatest在 Mastra 主实例上配置 storage使所有代理共享消息存储import { Mastra } from mastra/core import { LibSQLStore } from mastra/libsql export const mastra new Mastra({ storage: new LibSQLStore({ id: mastra-storage, url: :memory:, }), })如果你希望数据持久化到文件把url换成文档中使用的file:./local.db这类值即可:memory:表示数据仅存于内存。启用 semantic recall在代理的Memory配置中做三件事提供storage、提供vector向量库、提供embedder并在options里设置semanticRecall: true。import { Agent } from mastra/core/agent import { Memory } from mastra/memory import { LibSQLStore, LibSQLVector } from mastra/libsql import { ModelRouterEmbeddingModel } from mastra/core/llm const agent new Agent({ id: support-agent, name: SupportAgent, instructions: You are a helpful support agent., model: openai/gpt-5.6-sol, memory: new Memory({ storage: new LibSQLStore({ id: agent-storage, url: file:./local.db, }), vector: new LibSQLVector({ id: agent-vector, url: file:./local.db, }), embedder: new ModelRouterEmbeddingModel(openai/text-embedding-3-small), options: { semanticRecall: true, }, }), })说明文档中各部分的用途storage和vector可以指向同一个 LibSQL 数据库文件vector缺省时使用默认的向量库但显式写出更清晰。embedder使用 Model Router 时传provider/model字符串即可。文档列出的受支持嵌入模型包括 OpenAI 的text-embedding-3-small、text-embedding-3-large、text-embedding-ada-002和 Google 的gemini-embedding-001也可通过providerId: openrouter对象形式访问 OpenRouter 上的多供应商模型。Model Router 会自动从环境变量检测 API keyOPENAI_API_KEY、GOOGLE_API_KEY、OPENROUTER_API_KEYGoogle 模型还会回退到GOOGLE_GENERATIVE_AI_API_KEY。代码中的model: openai/gpt-5.6-sol是文档示例的模型值可按你的账号替换为其它provider/model格式模型。启用后的工作机制每次调用代理时新用户消息先被向量化并查询向量库命中的早期消息作为语义召回部分进入上下文LLM 响应返回后本轮所有新消息用户、助手、工具调用/结果会被插入向量库供后续对话召回。手动调用 recall() 按语义检索除了代理调用时的自动召回还可以用Memory.recall()主动按语义查找消息。recall()相比listMessages的区别是支持vectorSearchString做语义检索const memory await agent.getMemory() // 基本召回按 thread 拉取消息类似 listMessages const { messages } await memory!.recall({ threadId: thread-123, perPage: 50, }) // 语义召回按含义查找消息 const { messages: relevantMessages } await memory!.recall({ threadId: thread-123, vectorSearchString: What did we discuss about the project deadline?, threadConfig: { semanticRecall: true, }, })注意使用vectorSearchString时必须在threadConfig中开启semanticRecall。threadId是要查询的线程 ID需替换为你调用generate()/stream()时实际使用的值。返回值是MastraDBMessage[]格式的消息数组。调用代理本身时需要传入resource和thread来组织对话例如await agent.generate(What did we discuss about the deadline last week?, { memory: { resource: user-123, thread: conversation-123, }, })同一个resource下不同thread的消息也都能被召回取决于下面的scope配置因此用哪组 ID 决定了能检索到什么范围的历史。调优召回行为topK、messageRange、scope、filter把semanticRecall: true换成对象形式即可调整行为const agent new Agent({ id: agent, memory: new Memory({ options: { semanticRecall: { topK: 3, // 检索 3 条最相似消息 messageRange: 2, // 每条命中消息附带前后各 2 条上下文消息 scope: resource, // 在该 resource 的所有 thread 中搜索 filter: { projectId: { $eq: project-a } }, }, }, }), })四个选项的含义topK控制取回多少条相似消息messageRange控制每条命中消息附带多少条前后消息scope决定只搜当前 thread 还是该 resource 的所有 threadfilter用元数据条件限制结果。两个与执行相关的限制scope: resource只被 LibSQL、OracleDB、PostgreSQL、MongoDB、Upstash 这几个存储适配器支持。如果你的向量库不在其中只能使用 thread 范围内的检索。filter匹配的是消息保存时写入嵌入的线程元数据。之后修改线程元数据不会更新已有嵌入那些消息保持旧元数据直到被重新保存或索引。filter支持的运算符$and、$eq、$gt、$gte、$in、$lt、$lte、$ne、$nin、$or。文档中的常见组合示例// 按项目过滤 const options { semanticRecall: { filter: { projectId: { $eq: my-project } } }, } // 多个分类 const options { semanticRecall: { filter: { category: { $in: [work, research] } } }, } // 项目 优先级组合条件 const options { semanticRecall: { filter: { $and: [{ projectId: { $eq: project-a } }, { priority: { $gte: 3 } }], }, }, }可选分支本地嵌入与 PostgreSQL 索引优化FastEmbed本地嵌入模型不想依赖外部嵌入 API 时可安装mastra/fastembednpm install mastra/fastembedlatestimport { Memory } from mastra/memory import { Agent } from mastra/core/agent import { fastembed } from mastra/fastembed const agent new Agent({ id: agent, memory: new Memory({ embedder: fastembed, }), })FastEmbed 还提供面向非英语内容的多语言 E5 模型它是不对称的暴露为multilingualE5LargePassage索引侧和multilingualE5LargeQuery检索侧两个模型。Memory 对存储和召回使用同一个 embedder所以要二选一保持一致地用只有在你同时控制索引和检索两侧的场景如自建 RAG才用成对的 passage/query 模型。E5 产出 1024 维向量向量索引必须按相同维度创建且不能与其它 embedder 的向量混用在同一索引里。PostgreSQL HNSW 索引用 PostgreSQL 做向量库时可通过indexConfig配置索引类型。Mastra 默认创建 IVFFlat 索引文档建议 HNSW尤其配合 OpenAI 嵌入的 inner product 距离const agent new Agent({ memory: new Memory({ storage: new PgStore({ id: agent-storage, connectionString: process.env.DATABASE_URL, }), vector: new PgVector({ id: agent-vector, connectionString: process.env.DATABASE_URL, }), options: { semanticRecall: { topK: 5, messageRange: 2, indexConfig: { type: hnsw, // 使用 HNSW 提升性能 metric: dotproduct, // 适合 OpenAI 嵌入 m: 16, // 双向链接数默认 16 efConstruction: 64, // 构建时候选列表大小默认 64 }, }, }, }), })这一分支面向消息量达到数千条以上的 PostgreSQL 部署索引参数的详细调优见文档中的 PgVector 配置指南。验证召回结果文档给出的验证方式是 tracing启用 tracing 后经 semantic recall 检索到的消息会出现在代理的 trace 输出中与最近消息历史如已配置一起展示。操作步骤在 Studio 打开Observability选项卡选择最近一次代理请求的 trace。找到 LLM call 的 spans检查该请求实际送入模型的上下文。确认其中包含语义召回的消息部分且它们与最近消息历史按时间戳交错排布同一线程的召回结果作为普通消息插入跨线程的召回结果被格式化为 system message。如果你走的是手动路径则验证点就是recall()的返回值传入vectorSearchString后返回的messages数组即命中的消息及其上下文。限制与何时保持关闭每次开启 semantic recall 的调用都会增加延迟新消息要先转成嵌入并查询向量库然后才发给 LLM。文档建议以下情况保持semanticRecall: false默认值最近消息历史已能提供足够上下文或构建实时双向语音等对延迟敏感的应用嵌入和向量查询的延迟会明显可感。向量库选型有 18 个适配器Astra、Chroma、MongoDB、PostgreSQL、Qdrant、Upstash 等各适配器的安装与参数见对应向量库参考文档scope: resource的支持面见上文说明。主路径的完整流程是安装mastra/memory与mastra/libsql→ 在Memory中配齐storage、vector、embedder并设置semanticRecall→ 用带resource/thread的调用积累对话 → 通过 Studio 的 trace 或recall({ vectorSearchString, threadConfig: { semanticRecall: true } })确认早期消息能被语义命中。若需要继续深入可阅读 semantic recall 文档、Memory 总览、消息历史 与 recall() 参考。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考