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

# SemanticRecall

`SemanticRecall` 是一種**混合處理器**，可透過向量嵌入，對對話歷史記錄執行語意搜尋。在輸入時，它會執行語意搜尋來找出相關的歷史訊息；在輸出時，它會為新訊息建立嵌入，以便日後進行語意擷取。

## 使用範例

```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`): 語意回想處理器的設定選項

**options.storage** (`MemoryStorage`): 用來擷取訊息的儲存執行個體

**options.vector** (`MastraVector`): 用於語意搜尋的向量儲存區

**options.embedder** (`MastraEmbeddingModel<string>`): 用來產生查詢嵌入的嵌入器

**options.topK** (`number`): 要擷取的最相似訊息數量

**options.messageRange** (`number | { before: number; after: number }`): 每個相符項目前後要包含的情境訊息數量。可以是單一數字（前後相同），也可以是分別指定數值的物件

**options.scope** (`'thread' | 'resource'`): 語意搜尋的範圍。'thread' 只會搜尋目前對話串；'resource' 會搜尋該資源的所有對話串

**options.threshold** (`number`): 最低相似度分數門檻（0–1）。低於此門檻的訊息會被篩除

**options.indexName** (`string`): 向量儲存區的索引名稱。未提供時，會依嵌入器模型自動產生

**options.logger** (`IMastraLogger`): 選用的結構化記錄器執行個體

## 回傳值

**id** (`string`): 設為 'semantic-recall' 的處理器識別碼

**name** (`string`): 設為 'SemanticRecall' 的處理器顯示名稱

**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'`，將跨對話串訊息格式化為附有時間戳記的系統訊息
6. 加入帶有 `source: 'memory'` 標記的回想訊息

### 輸出處理

1. 從新的使用者訊息和 assistant 訊息擷取文字內容
2. 為每則訊息產生嵌入
3. 將嵌入連同中繼資料（訊息 ID、對話串 ID、資源 ID、角色、內容、時間戳記）儲存在向量儲存區
4. 對嵌入使用 LRU 快取，以避免重複呼叫 API

### 跨對話串回想

當 `scope` 設為 `'resource'` 時，處理器可以回想其他對話串的訊息。這些跨對話串訊息會格式化為附有時間戳記和對話標籤的系統訊息，提供對話發生時間與位置的情境。

## 相關資源

- [防護欄](https://mastra.zisheng.pro/zh-TW/docs/agents/guardrails)