已複製執行緒輔助工具

Memory 類別提供用來處理已複製執行緒的輔助方法。這些方法可協助你檢查複製狀態、擷取複製中繼資料、周遊複製關聯，並追蹤複製歷程記錄。

isClone()

檢查執行緒是否為另一個執行緒的複本。

用法

const isClonedThread = memory.isClone(thread)

參數

thread:

StorageThreadType

要檢查的執行緒物件。

範例

const thread = await memory.getThreadById({ threadId: 'some-thread-id' })

if (memory.isClone(thread)) {
  console.log('This thread was cloned from another thread')
} else {
  console.log('This is an original thread')
}

getCloneMetadata()

擷取執行緒的複製中繼資料（若存在）。

用法

const metadata = memory.getCloneMetadata(thread)

參數

thread:

StorageThreadType

要從中擷取複製中繼資料的執行緒物件。

範例

const thread = await memory.getThreadById({ threadId: 'cloned-thread-id' })
const cloneInfo = memory.getCloneMetadata(thread)

if (cloneInfo) {
  console.log(`Cloned from: ${cloneInfo.sourceThreadId}`)
  console.log(`Cloned at: ${cloneInfo.clonedAt}`)
}

getSourceThread()

擷取建立已複製執行緒時所依據的原始來源執行緒。

用法

const sourceThread = await memory.getSourceThread(threadId)

參數

threadId:

string

已複製執行緒的 ID。

範例

const sourceThread = await memory.getSourceThread('cloned-thread-id')

if (sourceThread) {
  console.log(`Original thread title: ${sourceThread.title}`)
  console.log(`Original thread created: ${sourceThread.createdAt}`)
}

listClones()

列出從特定來源執行緒複製的所有執行緒。

用法

const clones = await memory.listClones(sourceThreadId)

參數

sourceThreadId:

string

要尋找其複本之來源執行緒的 ID。

範例

const clones = await memory.listClones('original-thread-id')

console.log(`Found ${clones.length} clones`)
for (const clone of clones) {
  console.log(`- ${clone.id}: ${clone.title}`)
}

getCloneHistory()

擷取執行緒的完整複製歷程記錄鏈，向前追溯至原始執行緒。

用法

const history = await memory.getCloneHistory(threadId)

參數

threadId:

string

要取得複製歷程記錄之執行緒的 ID。

範例

// If thread-c was cloned from thread-b, which was cloned from thread-a
const history = await memory.getCloneHistory('thread-c')

// history = [thread-a, thread-b, thread-c]
console.log(`Clone depth: ${history.length - 1}`)
console.log(`Original thread: ${history[0].id}`)
console.log(`Current thread: ${history[history.length - 1].id}`)

// Display the clone chain
for (let i = 0; i < history.length; i++) {
  const prefix = i === 0 ? 'Original' : `Clone ${i}`
  console.log(`${prefix}: ${history[i].title}`)
}

完整範例

src/clone-management.ts

import { mastra } from './mastra'

async function manageClones() {
  const agent = mastra.getAgent('agent')
  const memory = await agent.getMemory()

  // Create an original conversation
  const originalThread = await memory.createThread({
    resourceId: 'user-123',
    title: 'Original Conversation',
  })

  // Have a conversation...
  await agent.generate("Hello! Let's discuss project options.", {
    memory: {
      thread: originalThread.id,
      resource: 'user-123',
    },
  })

  // Create multiple branches (clones) to explore different paths
  const { thread: optionA } = await memory.cloneThread({
    sourceThreadId: originalThread.id,
    title: 'Option A - Conservative Approach',
  })

  const { thread: optionB } = await memory.cloneThread({
    sourceThreadId: originalThread.id,
    title: 'Option B - Aggressive Approach',
  })

  // Check clone status
  console.log(memory.isClone(originalThread)) // false
  console.log(memory.isClone(optionA)) // true
  console.log(memory.isClone(optionB)) // true

  // Get clone metadata
  const metadataA = memory.getCloneMetadata(optionA)
  console.log(metadataA?.sourceThreadId) // originalThread.id

  // List all clones of the original
  const allClones = await memory.listClones(originalThread.id)
  console.log(`Total alternatives: ${allClones.length}`) // 2

  // Get source thread from a clone
  const source = await memory.getSourceThread(optionA.id)
  console.log(source?.id === originalThread.id) // true

  // Create a deeper clone chain
  const { thread: optionA2 } = await memory.cloneThread({
    sourceThreadId: optionA.id,
    title: 'Option A - Variant 2',
  })

  // Get the full history
  const history = await memory.getCloneHistory(optionA2.id)
  // history = [originalThread, optionA, optionA2]
  console.log(`Clone depth: ${history.length - 1}`) // 2
}