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

# Memory.recall()

`Memory.recall()` 方法會從特定執行緒擷取訊息，並支援分頁、篩選選項與語意搜尋。

## 使用範例

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

**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 執行緒建立相關的設定。generateTitle 控制是否根據對話逐字稿自動產生執行緒標題。可為布林值或包含自訂模型與指示的物件。

## 中繼資料篩選

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

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

## 延伸使用範例

```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 類別參考](https://mastra.zisheng.pro/zh-TW/reference/memory/memory-class)
- [Memory 入門](https://mastra.zisheng.pro/zh-TW/docs/memory/overview)
- [語意回憶](https://mastra.zisheng.pro/zh-TW/docs/memory/semantic-recall)
- [createThread](https://mastra.zisheng.pro/zh-TW/reference/memory/createThread)