@mastra/mcp-docs-server 1.0.0-beta.8 → 1.0.0

package/.docs/raw/reference/memory/clone-utilities.mdx

@@ -0,0 +1,345 @@
+---
+title: "Reference: Clone Utility Methods | Memory"
+description: "Documentation for utility methods to work with cloned threads in Mastra Memory."
+packages:
+  - "@mastra/memory"
+---
+
+# 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
+
+```typescript
+const isClonedThread = memory.isClone(thread);
+```
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "thread",
+      type: "StorageThreadType",
+      description: "The thread object to check.",
+      isOptional: false,
+    },
+  ]}
+/>
+
+### Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "isClone",
+      type: "boolean",
+      description: "True if the thread is a clone, false otherwise.",
+    },
+  ]}
+/>
+
+### Example
+
+```typescript
+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
+
+```typescript
+const metadata = memory.getCloneMetadata(thread);
+```
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "thread",
+      type: "StorageThreadType",
+      description: "The thread object to extract clone metadata from.",
+      isOptional: false,
+    },
+  ]}
+/>
+
+### Returns
+
+Returns `ThreadCloneMetadata | null`:
+
+<PropertiesTable
+  content={[
+    {
+      name: "sourceThreadId",
+      type: "string",
+      description: "The ID of the original thread that was cloned.",
+    },
+    {
+      name: "clonedAt",
+      type: "Date",
+      description: "Timestamp when the clone was created.",
+    },
+    {
+      name: "lastMessageId",
+      type: "string",
+      description:
+        "The ID of the last message in the source thread at the time of cloning.",
+      isOptional: true,
+    },
+  ]}
+/>
+
+### Example
+
+```typescript
+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
+
+```typescript
+const sourceThread = await memory.getSourceThread(threadId);
+```
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "threadId",
+      type: "string",
+      description: "The ID of the cloned thread.",
+      isOptional: false,
+    },
+  ]}
+/>
+
+### Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "sourceThread",
+      type: "StorageThreadType | null",
+      description:
+        "The source thread if found, or null if the thread is not a clone or the source no longer exists.",
+    },
+  ]}
+/>
+
+### Example
+
+```typescript
+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
+
+```typescript
+const clones = await memory.listClones(sourceThreadId);
+```
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "sourceThreadId",
+      type: "string",
+      description: "The ID of the source thread to find clones for.",
+      isOptional: false,
+    },
+  ]}
+/>
+
+### Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "clones",
+      type: "StorageThreadType[]",
+      description:
+        "Array of threads that were cloned from the specified source thread.",
+    },
+  ]}
+/>
+
+### Example
+
+```typescript
+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
+
+```typescript
+const history = await memory.getCloneHistory(threadId);
+```
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "threadId",
+      type: "string",
+      description: "The ID of the thread to get clone history for.",
+      isOptional: false,
+    },
+  ]}
+/>
+
+### Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "history",
+      type: "StorageThreadType[]",
+      description:
+        "Array of threads representing the clone chain, ordered from the original root thread to the current thread.",
+    },
+  ]}
+/>
+
+### Example
+
+```typescript
+// 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
+
+```typescript 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.", {
+    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](/reference/v1/memory/cloneThread)
+- [Memory Class Reference](/reference/v1/memory/memory-class)
+- [getThreadById](/reference/v1/memory/getThreadById)
+- [listThreads](/reference/v1/memory/listThreads)

package/.docs/raw/reference/memory/cloneThread.mdx

@@ -0,0 +1,237 @@
+---
+title: "Reference: Memory.cloneThread() | Memory"
+description: "Documentation for the `Memory.cloneThread()` method in Mastra, which creates a copy of a conversation thread with all its messages."
+packages:
+  - "@mastra/memory"
+---
+
+# Memory.cloneThread()
+
+The `.cloneThread()` method creates a copy of an existing conversation thread, including all its messages. This enables creating divergent conversation paths from a specific point in a conversation. When semantic recall is enabled, the method also creates vector embeddings for the cloned messages.
+
+## Usage Example
+
+```typescript
+const { thread, clonedMessages } = await memory.cloneThread({
+  sourceThreadId: "original-thread-123",
+});
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "sourceThreadId",
+      type: "string",
+      description: "The ID of the thread to clone",
+      isOptional: false,
+    },
+    {
+      name: "newThreadId",
+      type: "string",
+      description:
+        "Optional custom ID for the cloned thread. If not provided, one will be generated.",
+      isOptional: true,
+    },
+    {
+      name: "resourceId",
+      type: "string",
+      description:
+        "Optional resource ID for the cloned thread. Defaults to the source thread's resourceId.",
+      isOptional: true,
+    },
+    {
+      name: "title",
+      type: "string",
+      description:
+        "Optional title for the cloned thread. Defaults to '[source title] (Copy)'.",
+      isOptional: true,
+    },
+    {
+      name: "metadata",
+      type: "Record<string, unknown>",
+      description:
+        "Optional metadata to merge with the source thread's metadata. Clone metadata is automatically added.",
+      isOptional: true,
+    },
+    {
+      name: "options",
+      type: "CloneOptions",
+      description: "Optional filtering options for the clone operation.",
+      isOptional: true,
+    },
+  ]}
+/>
+
+### Options Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "messageLimit",
+      type: "number",
+      description:
+        "Maximum number of messages to clone. When set, clones the most recent N messages.",
+      isOptional: true,
+    },
+    {
+      name: "messageFilter",
+      type: "MessageFilter",
+      description: "Filter criteria for selecting which messages to clone.",
+      isOptional: true,
+    },
+  ]}
+/>
+
+### MessageFilter Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "startDate",
+      type: "Date",
+      description: "Only clone messages created on or after this date.",
+      isOptional: true,
+    },
+    {
+      name: "endDate",
+      type: "Date",
+      description: "Only clone messages created on or before this date.",
+      isOptional: true,
+    },
+    {
+      name: "messageIds",
+      type: "string[]",
+      description: "Only clone messages with these specific IDs.",
+      isOptional: true,
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "thread",
+      type: "StorageThreadType",
+      description: "The newly created cloned thread with clone metadata.",
+    },
+    {
+      name: "clonedMessages",
+      type: "MastraDBMessage[]",
+      description:
+        "Array of the cloned messages with new IDs assigned to the new thread.",
+    },
+  ]}
+/>
+
+### Clone Metadata
+
+The cloned thread's metadata includes a `clone` property with:
+
+<PropertiesTable
+  content={[
+    {
+      name: "sourceThreadId",
+      type: "string",
+      description: "The ID of the original thread that was cloned.",
+    },
+    {
+      name: "clonedAt",
+      type: "Date",
+      description: "Timestamp when the clone was created.",
+    },
+    {
+      name: "lastMessageId",
+      type: "string",
+      description:
+        "The ID of the last message in the source thread at the time of cloning.",
+      isOptional: true,
+    },
+  ]}
+/>
+
+## Extended Usage Example
+
+```typescript title="src/test-clone.ts"
+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"),
+    },
+  },
+});
+
+// Continue conversation on the cloned thread
+const response = await agent.generate("Let's try a different approach", {
+  threadId: fullClone.id,
+  resourceId: fullClone.resourceId,
+});
+```
+
+## Vector Embeddings
+
+When the Memory instance has semantic recall enabled (with a vector store and embedder configured), `cloneThread()` automatically creates vector embeddings for all cloned messages. This ensures that semantic search works correctly on the cloned thread.
+
+```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",
+});
+```
+
+### Related
+
+- [Memory Class Reference](/reference/v1/memory/memory-class)
+- [createThread](/reference/v1/memory/createThread)
+- [Clone Utility Methods](/reference/v1/memory/clone-utilities)
+- [recall](/reference/v1/memory/recall)
+- [Semantic Recall](/docs/v1/memory/semantic-recall)

package/.docs/raw/reference/memory/createThread.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Memory.createThread() | Memory"
 description: "Documentation for the `Memory.createThread()` method in Mastra, which creates a new conversation thread in the memory system."
+packages:
+  - "@mastra/memory"
 ---
 
 # Memory.createThread()
@@ -9,7 +11,7 @@ The `.createThread()` method creates a new conversation thread in the memory sys
 
 ## Usage Example
 
-```typescript copy
+```typescript
 await memory?.createThread({ resourceId: "user-123" });
 ```
 
@@ -85,7 +87,7 @@ await memory?.createThread({ resourceId: "user-123" });
 
 ## Extended usage example
 
-```typescript title="src/test-memory.ts" showLineNumbers copy
+```typescript title="src/test-memory.ts"
 import { mastra } from "./mastra";
 
 const agent = mastra.getAgent("agent");
@@ -115,5 +117,5 @@ console.log(response.text);
 - [Memory Class Reference](/reference/v1/memory/memory-class)
 - [Getting Started with Memory](/docs/v1/memory/overview) (Covers threads concept)
 - [getThreadById](/reference/v1/memory/getThreadById)
-- [listThreadsByResourceId](/reference/v1/memory/listThreadsByResourceId)
-- [query](/reference/v1/memory/query)
+- [listThreads](/reference/v1/memory/listThreads)
+- [recall](/reference/v1/memory/recall)

package/.docs/raw/reference/memory/deleteMessages.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Memory.deleteMessages() | Memory"
 description: "Documentation for the `Memory.deleteMessages()` method in Mastra, which deletes multiple messages by their IDs."
+packages:
+  - "@mastra/core"
 ---
 
 # Memory.deleteMessages()
@@ -9,7 +11,7 @@ The `.deleteMessages()` method deletes multiple messages by their IDs.
 
 ## Usage Example
 
-```typescript copy
+```typescript
 await memory?.deleteMessages(["671ae63f-3a91-4082-a907-fe7de78e10ec"]);
 ```
 
@@ -40,7 +42,7 @@ await memory?.deleteMessages(["671ae63f-3a91-4082-a907-fe7de78e10ec"]);
 
 ## Extended usage example
 
-```typescript title="src/test-memory.ts" showLineNumbers copy
+```typescript title="src/test-memory.ts"
 import { mastra } from "./mastra";
 import { MastraDBMessage } from "@mastra/core";
 

package/.docs/raw/reference/memory/getThreadById.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Memory.getThreadById() | Memory"
 description: "Documentation for the `Memory.getThreadById()` method in Mastra, which retrieves a specific thread by its ID."
+packages:
+  - "@mastra/memory"
 ---
 
 # Memory.getThreadById()
@@ -44,4 +46,4 @@ await memory?.getThreadById({ threadId: "thread-123" });
 - [Memory Class Reference](/reference/v1/memory/memory-class)
 - [Getting Started with Memory](/docs/v1/memory/overview) (Covers threads concept)
 - [createThread](/reference/v1/memory/createThread)
-- [listThreadsByResourceId](/reference/v1/memory/listThreadsByResourceId)
+- [listThreads](/reference/v1/memory/listThreads)