Cloned thread utility

Memory class 提供多個用於處理 cloned thread 的 utility method。這些方法可協助你檢查 clone 狀態、擷取 clone metadata、瀏覽 clone 關係，以及追蹤 clone 記錄。

isClone()

檢查某個 thread 是否為另一個 thread 的 clone。

用法

const isClonedThread = memory.isClone(thread)

參數

thread:

StorageThreadType

要檢查的 thread 物件。

範例

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()

如 thread 包含 clone metadata，便會擷取該 metadata。

用法

const metadata = memory.getCloneMetadata(thread)

參數

thread:

StorageThreadType

要從中擷取 clone metadata 的 thread 物件。

範例

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()

擷取建立 cloned thread 時所依據的原始 source thread。

用法

const sourceThread = await memory.getSourceThread(threadId)

參數

threadId:

string

Cloned thread 的 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()

列出從指定 source thread clone 而來的所有 thread。

用法

const clones = await memory.listClones(sourceThreadId)

參數

sourceThreadId:

string

要為其尋找 clone 的 source thread 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()

擷取 thread 的完整 clone 記錄鏈，並反向追溯至原始 thread。

用法

const history = await memory.getCloneHistory(threadId)

參數

threadId:

string

要取得 clone 記錄的 thread 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
}