跳至主要內容

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
分頁使用的零起始頁碼。搭配 perPage 使用，以批次擷取訊息。

include?:

{ id: string; threadId?: string; withPreviousMessages?: number; withNextMessages?: number }[]
要包含的特定訊息 ID 陣列，可選擇包含 context 訊息。每個項目都有 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 語意，依完全相符的純量 key-value 配對篩選訊息的淺層中繼資料。中繼資料值可以是字串、有限數字、布林值或 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 執行緒建立相關的設定。generateTitle 控制是否根據對話逐字稿自動產生執行緒標題。可為布林值或包含自訂模型與指示的物件。

中繼資料篩選
「中繼資料篩選」的直接連結

使用 filter.metadata 比對儲存在訊息上的淺層純量中繼資料：

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

所有中繼資料項目都以 AND 語意組合。訊息必須以完全相同的型別符合每個 key 與 value。null 只會比對明確設為 null 的中繼資料，不會比對缺少的 key。

中繼資料篩選器只支援淺層純量值：string、有限的 number、boolean 及 null。不支援巢狀物件、陣列、NaN 與無限值。中繼資料 key 必須以字母或底線開頭，且只能包含英數字元或底線，長度上限為 128 個字元。不允許 __proto__、constructor 和 prototype 等保留的 prototype key。效能取決於儲存後端。任意中繼資料篩選器可能需要掃描候選訊息，因此請盡可能使用 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