セマンティックリコール

友人に「先週末は何してたの？」と尋ねると、相手は「先週末」に結びついた出来事を記憶から探し出し、何をしていたかを教えてくれるでしょう。Mastra のセマンティックリコールは、それに少し似ています。

📹 視聴: セマンティックリコールの概要、仕組み、Mastra での設定方法 → YouTube（5分）

セマンティックリコールの仕組み

セマンティックリコールは RAG ベースの検索で、recent conversation history に含まれなくなっても、長い対話にわたってエージェントが文脈を維持できるようにします。

メッセージのベクトル埋め込みによる類似検索を行い、各種ベクトルストアと統合し、取得したメッセージの前後に可変のコンテキストウィンドウを設定できます。

有効化すると、新しいメッセージを使って、意味的に類似するメッセージを見つけるためにベクトル DB にクエリします。

LLM の応答を受け取った後は、すべての新しいメッセージ（user、assistant、tool の呼び出し／結果）をベクトル DB に格納し、後続の対話で参照できるようにします。

クイックスタート

セマンティックリコールはデフォルトで有効になっているため、エージェントにメモリを持たせると自動的に利用されます：


import { Agent } from "@mastra/core/agent";
import { Memory } from "@mastra/memory";
import { openai } from "@ai-sdk/openai";
 
const agent = new Agent({
  name: "SupportAgent",
  instructions: "You are a helpful support agent.",
  model: openai("gpt-4o"),
  memory: new Memory(),
});

リコールの設定

セマンティックリコールの挙動を制御する主なパラメータは次の3つです。

topK: 取得する意味的に類似したメッセージの数
messageRange: 各一致に含める周辺コンテキストの範囲
scope: 現在のスレッド内を検索するか、リソースに属するすべてのスレッドを横断して検索するか。scope: 'resource' を指定すると、エージェントはユーザーの過去の会話全体から情報を想起できます。


const agent = new Agent({
  memory: new Memory({
    options: {
      semanticRecall: {
        topK: 3, // 最も類似したメッセージを3件取得
        messageRange: 2, // 各一致の前後2件のメッセージを含める
        scope: 'resource', // このユーザーの全スレッドを横断して検索
      },
    },
  }),
});

注意: 現在、セマンティックリコールにおける scope: 'resource' は、以下のストレージアダプターでサポートされています: LibSQL、Postgres、Upstash。

ストレージ設定

Semantic recall は、メッセージとその埋め込みを保存するためにストレージおよびベクターデータベースに依存します。


import { Memory } from "@mastra/memory";
import { Agent } from "@mastra/core/agent";
import { LibSQLStore, LibSQLVector } from "@mastra/libsql";
 
const agent = new Agent({
  memory: new Memory({
    // 省略した場合のデフォルトのストレージDB
    storage: new LibSQLStore({
      url: "file:./local.db",
    }),
    // 省略した場合のデフォルトのベクターデータベース
    vector: new LibSQLVector({
      connectionUrl: "file:./local.db",
    }),
  }),
});

ストレージ／ベクターのコード例:

Embedder の設定

セマンティックリコールは、メッセージを埋め込みベクトルに変換するために embedding model に依存します。AI SDK と互換性のある任意の embedding model を指定できます。

ローカルの埋め込みモデルである FastEmbed を使用するには、@mastra/fastembed をインストールします:


npm install @mastra/fastembed


pnpm add @mastra/fastembed


yarn add @mastra/fastembed


bun add @mastra/fastembed

次に、メモリで設定します:


import { Memory } from "@mastra/memory";
import { Agent } from "@mastra/core/agent";
import { fastembed } from "@mastra/fastembed";
 
const agent = new Agent({
  memory: new Memory({
    // ... other memory options
    embedder: fastembed,
  }),
});

または、OpenAI のような別のプロバイダーを使用することもできます:


import { Memory } from "@mastra/memory";
import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";
 
const agent = new Agent({
  memory: new Memory({
    // ... other memory options
    embedder: openai.embedding("text-embedding-3-small"),
  }),
});

無効化

Semantic Recall を使用するとパフォーマンスに影響があります。新しいメッセージは埋め込みベクトルに変換され、LLM に送信する前にベクターデータベースへのクエリに利用されます。

Semantic Recall はデフォルトで有効ですが、不要な場合は無効化できます:


const agent = new Agent({
  memory: new Memory({
    options: {
      semanticRecall: false,
    },
  }),
});

次のような場面では Semantic Recall を無効にするとよいでしょう:

会話履歴だけで現在のやり取りに十分なコンテキストがある場合
埋め込み生成やベクタークエリによる追加レイテンシが無視できない、リアルタイムの双方向音声などパフォーマンス重視のアプリケーションの場合

リコールされたメッセージの表示

トレースが有効な場合、セマンティックリコールによって取得されたメッセージは、（設定されていれば）直近の会話履歴と並んでエージェントのトレース出力に表示されます。

メッセージトレースの表示について詳しくは、Viewing Retrieved Messages を参照してください。