SemanticRecall

SemanticRecall 是一种混合 Processor，使用向量嵌入对对话历史记录进行语义搜索。输入时，它执行语义搜索以查找相关的历史消息。输出时，它为新消息创建嵌入，以支持日后的语义检索。

用法示例

import { SemanticRecall } from '@mastra/core/processors'
import { openai } from '@ai-sdk/openai'

const processor = new SemanticRecall({
  storage: memoryStorage,
  vector: vectorStore,
  embedder: openai.embedding('text-embedding-3-small'),
  topK: 5,
  messageRange: 2,
  scope: 'resource',
})

构造函数参数

options:

SemanticRecallOptions

语义召回 Processor 的配置选项

SemanticRecallOptions

storage:

MemoryStorage

用于检索消息的存储实例

vector:

MastraVector

用于语义搜索的向量存储

embedder:

MastraEmbeddingModel<string>

用于生成查询嵌入的 Embedder

topK?:

number

要检索的最相似消息数量

messageRange?:

number | { before: number; after: number }

每个匹配项之前/之后要包含的上下文消息数量。可以是单个数字（前后相同），也可以是分别指定数值的对象

scope?:

'thread' | 'resource'

语义搜索范围。'thread' 仅在当前 thread 中搜索。'resource' 在该 resource 的所有 thread 中搜索

threshold?:

number

最低相似度分数阈值（0-1）。低于此阈值的消息会被过滤掉

indexName?:

string

向量存储的索引名称。如果未提供，则根据 Embedder 模型自动生成

logger?:

IMastraLogger

用于结构化日志记录的可选 logger 实例

返回值

id:

string

设置为 'semantic-recall' 的 Processor 标识符

name:

string

设置为 'SemanticRecall' 的 Processor 显示名称

processInput:

(args: { messages: MastraDBMessage[]; messageList: MessageList; abort: (reason?: string) => never; tracingContext?: TracingContext; requestContext?: RequestContext }) => Promise<MessageList | MastraDBMessage[]>

对历史消息执行语义搜索，并将相关上下文添加到消息列表

processOutputResult:

(args: { messages: MastraDBMessage[]; messageList?: MessageList; abort: (reason?: string) => never; tracingContext?: TracingContext; requestContext?: RequestContext }) => Promise<MessageList | MastraDBMessage[]>

为新消息创建嵌入，以支持日后的语义搜索

扩展用法示例

src/mastra/agents/semantic-memory-agent.ts

import { Agent } from '@mastra/core/agent'
import { SemanticRecall, MessageHistory } from '@mastra/core/processors'
import { PostgresStorage } from '@mastra/pg'
import { PgVector } from '@mastra/pg'
import { openai } from '@ai-sdk/openai'

const storage = new PostgresStorage({
  id: 'pg-storage',
  connectionString: process.env.DATABASE_URL,
})

const vector = new PgVector({
  id: 'pg-vector',
  connectionString: process.env.DATABASE_URL,
})

const semanticRecall = new SemanticRecall({
  storage,
  vector,
  embedder: openai.embedding('text-embedding-3-small'),
  topK: 5,
  messageRange: { before: 2, after: 1 },
  scope: 'resource',
  threshold: 0.7,
})

export const agent = new Agent({
  id: 'semantic-memory-agent',
  name: 'semantic-memory-agent',
  instructions: 'You are a helpful assistant with semantic memory recall',
  model: 'openai/gpt-5.6-sol',
  inputProcessors: [semanticRecall, new MessageHistory({ storage, lastMessages: 50 })],
  outputProcessors: [semanticRecall, new MessageHistory({ storage })],
})

行为

输入处理

1. 从最后一条用户消息中提取用户查询
2. 为查询生成嵌入
3. 执行向量搜索以查找语义相似的消息
4. 检索匹配的消息及其周围上下文（基于 messageRange）
5. 对于 scope: 'resource'，将跨 thread 消息格式化为带时间戳的系统消息
6. 添加带有 source: 'memory' 标签的召回消息

输出处理

1. 从新的用户和 assistant 消息中提取文本内容
2. 为每条消息生成嵌入
3. 将嵌入及元数据（消息 ID、thread ID、resource ID、角色、内容、时间戳）存储在向量存储中
4. 对嵌入使用 LRU 缓存，以避免重复的 API 调用

跨 thread 召回

当 scope 设置为 'resource' 时，此 Processor 可以召回其他 thread 中的消息。这些跨 thread 消息会被格式化为带时间戳和对话标签的系统消息，以提供对话发生时间和位置的上下文。

相关内容

• 防护机制