Clone Utility Methods

The Memory class provides utility methods for working with cloned threads. These methods help you check clone status, retrieve clone metadata, navigate clone relationships, and track clone history.

isClone()

Checks whether a thread is a clone of another thread.

Usage

const isClonedThread = memory.isClone(thread);

Parameters

thread:

StorageThreadType

The thread object to check.

Returns

isClone:

boolean

True if the thread is a clone, false otherwise.

Example

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

Retrieves the clone metadata from a thread if it exists.

Usage

const metadata = memory.getCloneMetadata(thread);

Parameters

thread:

StorageThreadType

The thread object to extract clone metadata from.

Returns

Returns ThreadCloneMetadata | null:

sourceThreadId:

string

The ID of the original thread that was cloned.

clonedAt:

Date

Timestamp when the clone was created.

lastMessageId?:

string

The ID of the last message in the source thread at the time of cloning.

Example

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

Retrieves the original source thread that a cloned thread was created from.

Usage

const sourceThread = await memory.getSourceThread(threadId);

Parameters

threadId:

string

The ID of the cloned thread.

Returns

sourceThread:

StorageThreadType | null

The source thread if found, or null if the thread is not a clone or the source no longer exists.

Example

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

Lists all threads that were cloned from a specific source thread.

Usage

const clones = await memory.listClones(sourceThreadId);

Parameters

sourceThreadId:

string

The ID of the source thread to find clones for.

Returns

clones:

StorageThreadType[]

Array of threads that were cloned from the specified source thread.

Example

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

Retrieves the full clone history chain for a thread, tracing back to the original.

Usage

const history = await memory.getCloneHistory(threadId);

Parameters

threadId:

string

The ID of the thread to get clone history for.

Returns

history:

StorageThreadType[]

Array of threads representing the clone chain, ordered from the original root thread to the current thread.

Example

// 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}`);
}

---

Complete Example

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.", {
    threadId: originalThread.id,
    resourceId: "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
}

Related

• cloneThread
• Memory Class Reference
• getThreadById
• listThreadsByResourceId