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

# Memory API

Memory API 提供在 Mastra 中管理對話執行緒及訊息記錄的方法。

## 取得所有執行緒

取得指定資源的所有記憶執行緒：

```typescript
const threads = await mastraClient.listMemoryThreads({
  resourceId: 'resource-1',
  agentId: 'agent-1', // Optional - can be omitted if storage is configured
})
```

若省略 `agentId` 且伺服器已設定儲存空間，系統會直接透過儲存空間取得執行緒。多個 Agent 共用相同執行緒時（例如包含多個 Agent 步驟的 Workflow），此方式十分實用。

## 建立新執行緒

建立新的記憶執行緒：

```typescript
const thread = await mastraClient.createMemoryThread({
  title: 'New Conversation',
  metadata: { category: 'support' },
  resourceId: 'resource-1',
  agentId: 'agent-1',
})
```

## 使用指定執行緒

取得指定記憶執行緒的實例：

```typescript
const thread = mastraClient.getMemoryThread({ threadId: 'thread-id', agentId: 'agent-id' })
```

## 執行緒方法

### 取得執行緒詳情

取得指定執行緒的詳情：

```typescript
const details = await thread.get()
```

### 更新執行緒

更新執行緒屬性：

```typescript
const updated = await thread.update({
  title: 'Updated Title',
  metadata: { status: 'resolved' },
  resourceId: 'resource-1',
})
```

### 刪除執行緒

刪除執行緒及其訊息：

```typescript
await thread.delete()
```

### 複製執行緒

建立執行緒及其所有訊息的副本：

```typescript
const { thread: clonedThread, clonedMessages } = await thread.clone()
```

使用選項複製：

```typescript
const { thread: clonedThread, clonedMessages } = await thread.clone({
  newThreadId: 'custom-clone-id',
  title: 'Cloned Conversation',
  metadata: { branch: 'experiment-1' },
  options: {
    messageLimit: 10, // Only clone last 10 messages
  },
})
```

使用訊息篩選複製：

```typescript
const { thread: clonedThread } = await thread.clone({
  options: {
    messageFilter: {
      startDate: new Date('2024-01-01'),
      endDate: new Date('2024-01-31'),
    },
  },
})
```

複製回應包括：

- `thread`：新建立的複製執行緒，包含複製中繼資料
- `clonedMessages`：複製訊息的陣列，每則訊息均有新的 ID

## 訊息操作

### 儲存訊息

將訊息儲存至記憶：

```typescript
const result = await mastraClient.saveMessageToMemory({
  messages: [
    {
      role: 'user',
      content: 'Hello!',
      id: '1',
      threadId: 'thread-1',
      resourceId: 'resource-1',
      createdAt: new Date(),
      format: 2,
    },
  ],
  agentId: 'agent-1',
})

// result.messages contains the saved messages
console.log(result.messages)
```

### 取得執行緒訊息

取得與記憶執行緒相關的訊息：

```typescript
// Get all messages in the thread (paginated)
const result = await thread.listMessages()
console.log(result.messages) // Array of messages
console.log(result.total) // Total count
console.log(result.hasMore) // Whether more pages exist

// Get messages with pagination
const result = await thread.listMessages({
  page: 0,
  perPage: 20,
})

// Get messages with ordering
const result = await thread.listMessages({
  orderBy: { field: 'createdAt', direction: 'ASC' },
})

// Get messages with shallow metadata filters
const result = await thread.listMessages({
  filter: {
    metadata: {
      category: 'billing',
      escalated: true,
      priority: 2,
      archivedAt: null,
    },
  },
})
```

中繼資料篩選條件只會比對淺層純量值：`string`、有限的 `number`、`boolean` 及 `null`。每組鍵值都必須符合，採用 AND 語意。`null` 只會比對明確設為 `null` 的鍵。中繼資料鍵必須以字母或底線開首，而且只可包含英數字元或底線，長度上限為 128 個字元。不允許使用 `__proto__`、`constructor` 及 `prototype` 等保留原型鍵。效能視乎伺服器的儲存後端；任意中繼資料篩選條件可能需要掃描候選訊息。

### 刪除訊息

刪除執行緒中的一則或多則訊息：

```typescript
// Delete a single message
const result = await thread.deleteMessages('message-id')

// Delete multiple messages
const result = await thread.deleteMessages(['message-1', 'message-2', 'message-3'])

// Returns: { success: true, message: "Message deleted successfully" }
```

## 工作記憶

工作記憶讓 Agent 可在多次互動之間持續保留使用者資料。範圍可以限定於指定執行緒，亦可涵蓋某項資源（使用者）的所有執行緒。

### 取得工作記憶

取得執行緒目前的工作記憶：

```typescript
const workingMemory = await mastraClient.getWorkingMemory({
  agentId: 'agent-1',
  threadId: 'thread-1',
  resourceId: 'user-123', // Optional, required for resource-scoped memory
})
```

回應包括：

- `workingMemory`: 目前的工作記憶內容（字串或 null）
- `source`: 記憶來自 `"thread"` 還是 `"resource"` 範圍
- `workingMemoryTemplate`: 工作記憶使用的範本（如已設定）
- `threadExists`: 執行緒是否存在

### 更新工作記憶

更新執行緒的工作記憶內容：

```typescript
await mastraClient.updateWorkingMemory({
  agentId: 'agent-1',
  threadId: 'thread-1',
  workingMemory: `# User Profile
- Name: John Doe
- Location: New York
- Preferences: Prefers formal communication
`,
  resourceId: 'user-123', // Optional, required for resource-scoped memory
})

// Returns: { success: true }
```

使用資源範圍的工作記憶時，必須提供 `resourceId` 參數，讓記憶可在該使用者的所有對話執行緒之間持續保存。

### 取得記憶狀態

檢查記憶系統的狀態：

```typescript
const status = await mastraClient.getMemoryStatus('agent-id')
```