SemanticRecall

SemanticRecall は、ベクトル埋め込みを使用して会話履歴をセマンティック検索できる hybrid 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

semantic recall 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 のメッセージをタイムスタンプ付きの system メッセージとして整形する
6. 取得したメッセージに source: 'memory' タグを付けて追加する

出力処理

1. 新しい user および assistant メッセージからテキストコンテンツを抽出する
2. 各メッセージの埋め込みを生成する
3. 埋め込みをメタデータ（メッセージ ID、thread ID、resource ID、role、content、timestamp）とともにベクトルストアへ保存する
4. 埋め込みに LRU キャッシュを使用して、重複する API 呼び出しを避ける

thread をまたぐ取得

scope を 'resource' に設定すると、processor は別の thread からメッセージを取得できます。これらのメッセージは、会話がいつ、どこで行われたかを示すコンテキストを提供するため、タイムスタンプと会話ラベル付きの system メッセージとして整形されます。

関連情報

• Guardrails