SemanticRecall

SemanticRecall 是一個混合 processor，可使用向量 embedding 對對話歷史記錄進行語意搜尋。處理輸入時，它會執行語意搜尋，以找出相關的歷史訊息。處理輸出時，它會為新訊息建立 embedding，以便日後進行語意擷取。

使用範例

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',
})

Constructor 參數

options:

SemanticRecallOptions

語意回憶 processor 的設定選項

SemanticRecallOptions

storage:

MemoryStorage

用於擷取訊息的儲存空間實例

vector:

MastraVector

用於語意搜尋的向量儲存空間

embedder:

MastraEmbeddingModel<string>

用於產生查詢 embedding 的 embedder

topK?:

number

要擷取的最相似訊息數目

messageRange?:

number | { before: number; after: number }

每個配對項目前後要包含的 context 訊息數目。可以是單一數字（前後相同），亦可以是分別指定數值的物件

scope?:

'thread' | 'resource'

語意搜尋的範圍。'thread' 只會搜尋目前 thread。'resource' 會搜尋該 resource 的所有 thread

threshold?:

number

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

indexName?:

string

向量儲存空間的索引名稱。如未提供，則會根據 embedder 模型自動產生

logger?:

IMastraLogger

用於結構化 logging 的可選 logger 實例

傳回值

id:

string

Processor 標識符，設為 'semantic-recall'

name:

string

Processor 顯示名稱，設為 'SemanticRecall'

processInput:

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

對歷史訊息執行語意搜尋，並將相關 context 加入訊息清單

processOutputResult:

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

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

進階使用範例

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. 為查詢產生 embedding
3. 執行向量搜尋，以找出語意相似的訊息
4. 擷取配對的訊息及其前後 context（根據 messageRange）
5. 對於 scope: 'resource'，將跨 thread 訊息格式化為包含 timestamp 的系統訊息
6. 加入帶有 source: 'memory' tag 的已回憶訊息

輸出處理

1. 從新的使用者及 assistant 訊息擷取文字內容
2. 為每則訊息產生 embedding
3. 將 embedding 連同 metadata（訊息 ID、thread ID、resource ID、role、內容、timestamp）儲存在向量儲存空間中
4. 對 embedding 使用 LRU cache，避免重複的 API 呼叫

跨 thread 回憶

當 scope 設為 'resource' 時，processor 可以回憶其他 thread 中的訊息。這些跨 thread 訊息會格式化為包含 timestamp 及對話標籤的系統訊息，提供對話在何時及何處發生的 context。

相關內容

• Guardrails