> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# SemanticRecall

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

## 用法示例

```typescript
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 的配置选项

**options.storage** (`MemoryStorage`): 用于检索消息的存储实例

**options.vector** (`MastraVector`): 用于语义搜索的向量存储

**options.embedder** (`MastraEmbeddingModel<string>`): 用于生成查询嵌入的 Embedder

**options.topK** (`number`): 要检索的最相似消息数量

**options.messageRange** (`number | { before: number; after: number }`): 每个匹配项之前/之后要包含的上下文消息数量。可以是单个数字（前后相同），也可以是分别指定数值的对象

**options.scope** (`'thread' | 'resource'`): 语义搜索范围。'thread' 仅在当前 thread 中搜索。'resource' 在该 resource 的所有 thread 中搜索

**options.threshold** (`number`): 最低相似度分数阈值（0-1）。低于此阈值的消息会被过滤掉

**options.indexName** (`string`): 向量存储的索引名称。如果未提供，则根据 Embedder 模型自动生成

**options.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[]>`): 为新消息创建嵌入，以支持日后的语义搜索

## 扩展用法示例

```typescript
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 消息会被格式化为带时间戳和对话标签的系统消息，以提供对话发生时间和位置的上下文。

## 相关内容

- [防护机制](https://mastra.zisheng.pro/docs/agents/guardrails)