跳至主要內容

Memory.recall()

Memory.recall() 方法可從指定 thread 擷取訊息，並支援分頁、篩選選項及語意搜尋。

使用範例
使用範例 的直接連結

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

參數
參數 的直接連結

threadId:

string
要從中擷取訊息的 thread 唯一識別碼

resourceId?:

string
擁有該 thread 的 resource 選用 ID。如有提供，便會驗證 thread 的擁有權

vectorSearchString?:

string
用於尋找語意相近訊息的搜尋字串。必須在 threadConfig 中啟用 semantic recall。

perPage?:

number | false
每頁要擷取的訊息數目。設為 false 可在不分頁的情況下取得所有訊息。如未提供，預設為 threadConfig.lastMessages。

page?:

number
從零開始計算的分頁頁碼。與 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 語意，按完全相符的純量鍵值配對篩選淺層訊息 metadata。Metadata 值可以是字串、有限數值、布林值或 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' }
在訊息記錄中啟用語意搜尋。可以是布林值，亦可以是包含設定選項的物件。啟用後，必須同時設定 vector store 及 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 thread 建立相關的設定。generateTitle 控制是否根據對話記錄自動產生 thread 標題。可以是布林值，亦可以是包含自訂 model 及指示的物件。

Metadata 篩選
Metadata 篩選 的直接連結

使用 filter.metadata 配對儲存在訊息上的淺層純量 metadata：

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

所有 metadata 項目會以 AND 語意合併。訊息必須以完全相同的型別配對每個鍵及值。null 只會配對明確設為 null 的 metadata，不會配對缺少的鍵。

Metadata 篩選只支援淺層純量值：string、有限 number、boolean 及 null。不支援巢狀物件、陣列、NaN 及無限值。Metadata 鍵必須以字母或底線開頭，而且只可包含英數字元或底線，長度上限為 128 個字元。不允許使用 __proto__、constructor 及 prototype 等保留的 prototype 鍵。效能視乎 storage backend。任意 metadata 篩選可能需要掃描候選訊息，因此請盡可能使用 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