メインコンテンツへ移動

Memory.recall()

Memory.recall() メソッドは、ページネーション、フィルタリングオプション、セマンティック検索に対応し、特定のスレッドからメッセージを取得します。

使用例
使用例への直接リンク

const { messages } = await memory.recall({
  threadId: 'thread-123',
  perPage: 20,
})

パラメータ
パラメータへの直接リンク

threadId:

string
メッセージを取得するスレッドの一意な識別子。

resourceId?:

string
スレッドを所有するリソースの任意の ID。指定すると、スレッドの所有権を検証します。

vectorSearchString?:

string
意味的に類似するメッセージを検索するための文字列。threadConfig でセマンティックリコールを有効にする必要があります。

perPage?:

number | false
ページごとに取得するメッセージ数。ページネーションなしですべてのメッセージを取得するには false に設定します。指定しない場合は threadConfig.lastMessages がデフォルトになります。

page?:

number
ページネーション用の 0 始まりのページ番号。perPage と組み合わせてメッセージを一括取得します。

include?:

{ id: string; threadId?: string; withPreviousMessages?: number; withNextMessages?: number }[]
任意のコンテキストメッセージとともに含める、特定のメッセージ ID の配列。各要素には id（必須）、任意の threadId（メインの threadId がデフォルト）、withPreviousMessages（前に含めるメッセージ数。ベクトル検索では 2、それ以外では 0 がデフォルト）、withNextMessages（後に含めるメッセージ数。ベクトル検索では 2、それ以外では 0 がデフォルト）を指定します。

filter?:

{ dateRange?: { start?: Date; end?: Date; startExclusive?: boolean; endExclusive?: boolean }; metadata?: Record<string, string | number | boolean | null> }
メッセージ取得用のフィルタオプション。dateRange は作成日時でメッセージを絞り込みます。metadata は AND 条件を使い、メッセージの浅いメタデータをスカラーのキーと値の完全一致で絞り込みます。メタデータ値には文字列、有限数、真偽値、または null を指定できます。

orderBy?:

{ field: 'createdAt'; direction: 'ASC' | 'DESC' }
取得するメッセージの並び順。デフォルトでは作成日時の降順です。

threadConfig?:

MemoryConfig
メッセージ取得とセマンティック検索の設定オプション。
MemoryConfig

lastMessages?:

number | false
取得する最新メッセージの数。無効にするには false に設定します。perPage を明示的に指定しない場合、この値がデフォルトとして使われます。

semanticRecall?:

boolean | { topK: number; messageRange: number | { before: number; after: number }; scope?: 'thread' | 'resource' }
メッセージ履歴のセマンティック検索を有効にします。真偽値または設定オプションを含むオブジェクトを指定できます。有効にする場合、ベクトルストアと embedder の両方を設定する必要があります。

workingMemory?:

WorkingMemory
Working Memory 機能の設定。有効にするには { enabled: boolean; template?: string; schema?: ZodObject<any> | JSONSchema7; scope?: 'thread' | 'resource' }、無効にするには { enabled: boolean } を指定できます。

threads?:

{ generateTitle?: boolean | { model: DynamicArgument<MastraLanguageModel>; instructions?: DynamicArgument<string> } }
Memory スレッドの作成に関する設定。generateTitle は会話のトランスクリプトからスレッドタイトルを自動生成するかどうかを制御します。真偽値またはカスタムモデルと指示を含むオブジェクトを指定できます。

メタデータによるフィルタリング
メタデータによるフィルタリングへの直接リンク

filter.metadata を使うと、メッセージに保存された浅いスカラーのメタデータと照合できます。

const { messages } = await memory.recall({
  threadId: 'thread-123',
  filter: {
    metadata: {
      category: 'billing',
      escalated: true,
      priority: 2,
      archivedAt: null,
    },
  },
})

すべてのメタデータ項目は AND 条件で組み合わされます。メッセージは、すべてのキーと値について型も含めて完全に一致する必要があります。null は、明示的に null が設定されたメタデータと一致します。キーが存在しない場合は一致しません。

メタデータフィルタで使用できるのは、string、有限の number、boolean、null という浅いスカラー値だけです。ネストされたオブジェクト、配列、NaN、無限大は使用できません。メタデータキーは英字またはアンダースコアで始め、英数字またはアンダースコアだけを含める必要があります。上限は 128 文字です。__proto__、constructor、prototype など、予約されたプロトタイプキーは使用できません。パフォーマンスはストレージバックエンドによって異なります。任意のメタデータフィルタでは候補メッセージの走査が必要になることがあるため、可能であれば threadId、resourceId、dateRange でクエリを絞り込んでください。

戻り値
戻り値への直接リンク

messages:

MastraDBMessage[]
データベース形式で取得されたメッセージの配列。

詳細な使用例
詳細な使用例への直接リンク

src/test-memory.ts
import { mastra } from './mastra'

const agent = mastra.getAgent('agent')
const memory = await agent.getMemory()

// Retrieve messages with pagination
const { messages } = await memory!.recall({
  threadId: 'thread-123',
  perPage: 50,
  vectorSearchString: 'What messages are there?',
  include: [
    {
      id: 'msg-123',
    },
    {
      id: 'msg-456',
      withPreviousMessages: 3,
      withNextMessages: 1,
    },
  ],
  threadConfig: {
    semanticRecall: true,
  },
})

console.log(messages) // MastraDBMessage[]

// Fetch all messages without pagination
const allMessages = await memory!.recall({
  threadId: 'thread-123',
  perPage: false, // Fetch all
})

// Convert to AI SDK format if needed
import { toAISdkV5Messages } from '@mastra/ai-sdk/ui'
const uiMessages = toAISdkV5Messages(messages)
On this page