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

# Memory.cloneThread()

`.cloneThread()` 方法會複製現有對話執行緒，包括其中所有訊息。它支援從對話中的特定時間點建立分歧的對話路徑。啟用語意回憶時，此方法也會為已複製訊息建立向量 embedding。

## 使用範例

下列範例會建立 `Memory` 執行個體，並複製現有執行緒。

```typescript
import { Memory } from '@mastra/memory'
import { LibSQLStore } from '@mastra/libsql'

const memory = new Memory({
  storage: new LibSQLStore({ id: 'memory-store', url: 'file:./memory.db' }),
})

const { thread, clonedMessages } = await memory.cloneThread({
  sourceThreadId: 'original-thread-123',
})
```

## 參數

**sourceThreadId** (`string`): 要複製之執行緒的 ID

**newThreadId** (`string`): 已複製執行緒的選用自訂 ID。若未提供，系統會自動產生。

**resourceId** (`string`): 已複製執行緒的選用資源 ID。預設為來源執行緒的 resourceId。

**title** (`string`): 已複製執行緒的選用標題。若省略，且來源執行緒有標題，複本會使用 Clone of ${sourceThread.title}。否則標題為空。

**metadata** (`Record<string, unknown>`): 要與來源執行緒中繼資料合併的選用中繼資料。系統會自動新增複製中繼資料。

**options** (`CloneOptions`): 複製操作的選用篩選選項。

**options.messageLimit** (`number`): 要複製的訊息數量上限。設定時會複製最近 N 則訊息。

**options.messageFilter** (`MessageFilter`): 選取要複製訊息的篩選條件。

**options.messageFilter.startDate** (`Date`): 只複製在此日期當天或之後建立的訊息。

**options.messageFilter.endDate** (`Date`): 只複製在此日期當天或之前建立的訊息。

**options.messageFilter.messageIds** (`string[]`): 只複製這些特定 ID 的訊息。

## 回傳值

**thread** (`StorageThreadType`): 新建立、包含複製中繼資料的已複製執行緒。

**clonedMessages** (`MastraDBMessage[]`): 已複製訊息的陣列，並已指派新 ID 至新執行緒。

**messageIdMap** (`Record<string, string>`): 來源訊息 ID 與對應已複製訊息 ID 之間的對應。

### 複製中繼資料

已複製執行緒的中繼資料包含具有下列內容的 `clone` 屬性：

**sourceThreadId** (`string`): 被複製之原始執行緒的 ID。

**clonedAt** (`Date`): 建立複本時的時間戳記。

**lastMessageId** (`string`): 複製當下來源執行緒中最後一則訊息的 ID。

## 延伸使用範例

```typescript
import { mastra } from './mastra'

const agent = mastra.getAgent('agent')
const memory = await agent.getMemory()

// Clone a thread with all messages
const { thread: fullClone } = await memory.cloneThread({
  sourceThreadId: 'original-thread-123',
  title: 'Alternative Conversation Path',
})

// Clone with a custom ID
const { thread: customIdClone } = await memory.cloneThread({
  sourceThreadId: 'original-thread-123',
  newThreadId: 'my-custom-clone-id',
})

// Clone only the last 5 messages
const { thread: partialClone, clonedMessages } = await memory.cloneThread({
  sourceThreadId: 'original-thread-123',
  options: {
    messageLimit: 5,
  },
})

// Clone messages from a specific date range
const { thread: dateFilteredClone } = await memory.cloneThread({
  sourceThreadId: 'original-thread-123',
  options: {
    messageFilter: {
      startDate: new Date('2024-01-01'),
      endDate: new Date('2024-01-31'),
    },
  },
})

// Clone specific messages
const { thread: selectedMessagesClone } = await memory.cloneThread({
  sourceThreadId: 'original-thread-123',
  options: {
    messageFilter: {
      messageIds: ['message-1', 'message-2'],
    },
  },
})

// Continue conversation on the cloned thread
const response = await agent.generate('Try a different approach', {
  memory: {
    thread: fullClone.id,
    resource: fullClone.resourceId,
  },
})
```

將已複製的 `thread.id` 與 `thread.resourceId` 傳給 `agent.generate()`，即可從已複製執行緒繼續對話。

## 向量 embedding

當 Memory 執行個體已啟用語意回憶，並設定 vector store 與 embedder 時，`cloneThread()` 會自動為所有已複製訊息建立向量 embedding，確保語意搜尋能在已複製執行緒上正常運作。

在此範例中，`embeddingModel` 是為專案設定的 embedding 模型。

```typescript
import { Memory } from '@mastra/memory'
import { LibSQLStore, LibSQLVector } from '@mastra/libsql'

const memory = new Memory({
  storage: new LibSQLStore({ id: 'memory-store', url: 'file:./memory.db' }),
  vector: new LibSQLVector({ id: 'vector-store', url: 'file:./vector.db' }),
  embedder: embeddingModel,
  options: {
    semanticRecall: true,
  },
})

// Clone will also create embeddings for cloned messages
const { thread } = await memory.cloneThread({
  sourceThreadId: 'original-thread',
})

// Semantic search works on the cloned thread
const results = await memory.recall({
  threadId: thread.id,
  vectorSearchString: 'search query',
})
```

## Working memory

啟用 working memory 時，`cloneThread()` 會根據 working-memory 範圍及複本的 `resourceId`，複製或共用 working memory：

- **執行緒範圍的 working memory**：Working memory 會複製到已複製執行緒。
- **具有相同 `resourceId`、資源範圍的 working memory**：由於來源與已複製執行緒屬於相同資源，因此會共用 working memory。
- **具有不同 `resourceId`、資源範圍的 working memory**：Working memory 會複製到已複製執行緒的資源。

## Observational Memory

啟用 [Observational Memory](https://mastra.zisheng.pro/zh-TW/docs/memory/observational-memory) 時，`cloneThread()` 會自動複製與來源執行緒相關聯的 OM 記錄。行為取決於 OM 範圍：

- **執行緒範圍的 OM**：OM 記錄會複製到新執行緒。所有內部訊息 ID 參照都會重新對應至已複製訊息。
- **資源範圍的 OM（相同 `resourceId`）**：由於來源與已複製執行緒屬於相同資源，因此會共用 OM 記錄，不會重複建立。
- **資源範圍的 OM（不同 `resourceId`）**：OM 記錄會複製到新資源。訊息 ID 會重新對應，observation 內所有用來識別執行緒的標籤也會更新為參照已複製執行緒。

只會複製目前（最新）的 OM generation，不會複製較舊的歷史 generation。已複製記錄上的暫態處理狀態（observation／reflection 進行中旗標）會重設。