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

# Memory.recall()

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

## 使用範例

```typescript
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`): 訊息擷取及語意搜尋的設定選項

**threadConfig.lastMessages** (`number | false`): 要擷取的最新訊息數目。設為 false 可停用。如未明確提供 perPage，便會以此值作為預設值。

**threadConfig.semanticRecall** (`boolean | { topK: number; messageRange: number | { before: number; after: number }; scope?: 'thread' | 'resource' }`): 在訊息記錄中啟用語意搜尋。可以是布林值，亦可以是包含設定選項的物件。啟用後，必須同時設定 vector store 及 embedder。

**threadConfig.workingMemory** (`WorkingMemory`): working memory 功能的設定。可以是 { enabled: boolean; template?: string; schema?: ZodObject\<any> | JSONSchema7; scope?: 'thread' | 'resource' }，或以 { enabled: boolean } 停用。

**threadConfig.threads** (`{ generateTitle?: boolean | { model: DynamicArgument<MastraLanguageModel>; instructions?: DynamicArgument<string> } }`): 與 memory thread 建立相關的設定。generateTitle 控制是否根據對話記錄自動產生 thread 標題。可以是布林值，亦可以是包含自訂 model 及指示的物件。

## Metadata 篩選

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

```typescript
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[]`): 以資料庫格式表示的已擷取訊息陣列

## 進階使用範例

```typescript
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)
```

### 相關內容

- [Memory class 參考](https://mastra.zisheng.pro/zh-HK/reference/memory/memory-class)
- [Memory 入門](https://mastra.zisheng.pro/zh-HK/docs/memory/overview)
- [Semantic Recall](https://mastra.zisheng.pro/zh-HK/docs/memory/semantic-recall)
- [createThread](https://mastra.zisheng.pro/zh-HK/reference/memory/createThread)