SemanticRecall

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

使用範例

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

語意回想處理器的設定選項

SemanticRecallOptions

storage:

MemoryStorage

用來擷取訊息的儲存執行個體

vector:

MastraVector

用於語意搜尋的向量儲存區

embedder:

MastraEmbeddingModel<string>

用來產生查詢嵌入的嵌入器

topK?:

number

要擷取的最相似訊息數量

messageRange?:

number | { before: number; after: number }

每個相符項目前後要包含的情境訊息數量。可以是單一數字（前後相同），也可以是分別指定數值的物件

scope?:

'thread' | 'resource'

語意搜尋的範圍。'thread' 只會搜尋目前對話串；'resource' 會搜尋該資源的所有對話串

threshold?:

number

最低相似度分數門檻（0–1）。低於此門檻的訊息會被篩除

indexName?:

string

向量儲存區的索引名稱。未提供時，會依嵌入器模型自動產生

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[]>

為新訊息建立嵌入，以便日後進行語意搜尋

延伸使用範例

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

輸出處理

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

跨對話串回想

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

相關資源

• 防護欄