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

# SemanticRecall

`SemanticRecall` は、ベクトル埋め込みを使用して会話履歴をセマンティック検索できる **hybrid 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`): semantic recall 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 のメッセージをタイムスタンプ付きの 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](https://mastra.zisheng.pro/ja/docs/agents/guardrails)