@mastra/memory 1.0.0-beta.8 → 1.0.0

package/dist/docs/memory/06-reference.md

@@ -0,0 +1,687 @@
+# Memory API Reference
+
+> API reference for memory - 6 entries
+
+
+---
+
+## Reference: Clone Utility Methods
+
+> Documentation for utility methods to work with cloned threads in Mastra Memory.
+
+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
+
+### Returns
+
+### 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
+
+### Returns
+
+Returns `ThreadCloneMetadata | null`:
+
+### 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
+
+### Returns
+
+### 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
+
+### Returns
+
+### 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
+
+### Returns
+
+### 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](https://mastra.ai/reference/v1/memory/cloneThread)
+- [Memory Class Reference](https://mastra.ai/reference/v1/memory/memory-class)
+- [getThreadById](https://mastra.ai/reference/v1/memory/getThreadById)
+- [listThreads](https://mastra.ai/reference/v1/memory/listThreads)
+
+---
+
+## Reference: Memory.cloneThread()
+
+> Documentation for the `Memory.cloneThread()` method in Mastra, which creates a copy of a conversation thread with all its messages.
+
+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
+
+### Options Parameters
+
+### MessageFilter Parameters
+
+## Returns
+
+### Clone Metadata
+
+The cloned thread's metadata includes a `clone` property with:
+
+## 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](https://mastra.ai/reference/v1/memory/memory-class)
+- [createThread](https://mastra.ai/reference/v1/memory/createThread)
+- [Clone Utility Methods](https://mastra.ai/reference/v1/memory/clone-utilities)
+- [recall](https://mastra.ai/reference/v1/memory/recall)
+- [Semantic Recall](https://mastra.ai/docs/v1/memory/semantic-recall)
+
+---
+
+## Reference: Memory.createThread()
+
+> Documentation for the `Memory.createThread()` method in Mastra, which creates a new conversation thread in the memory system.
+
+The `.createThread()` method creates a new conversation thread in the memory system. Each thread represents a distinct conversation or context and can contain multiple messages.
+
+## Usage Example
+
+```typescript
+await memory?.createThread({ resourceId: "user-123" });
+```
+
+## Parameters
+
+## Returns
+
+## Extended usage example
+
+```typescript title="src/test-memory.ts"
+import { mastra } from "./mastra";
+
+const agent = mastra.getAgent("agent");
+const memory = await agent.getMemory();
+
+const thread = await memory?.createThread({
+  resourceId: "user-123",
+  title: "Memory Test Thread",
+  metadata: {
+    source: "test-script",
+    purpose: "memory-testing",
+  },
+});
+
+const response = await agent.generate("message for agent", {
+  memory: {
+    thread: thread!.id,
+    resource: thread!.resourceId,
+  },
+});
+
+console.log(response.text);
+```
+
+### Related
+
+- [Memory Class Reference](https://mastra.ai/reference/v1/memory/memory-class)
+- [Getting Started with Memory](https://mastra.ai/docs/v1/memory/overview) (Covers threads concept)
+- [getThreadById](https://mastra.ai/reference/v1/memory/getThreadById)
+- [listThreads](https://mastra.ai/reference/v1/memory/listThreads)
+- [recall](https://mastra.ai/reference/v1/memory/recall)
+
+---
+
+## Reference: Memory.getThreadById()
+
+> Documentation for the `Memory.getThreadById()` method in Mastra, which retrieves a specific thread by its ID.
+
+The `.getThreadById()` method retrieves a specific thread by its ID.
+
+## Usage Example
+
+```typescript
+await memory?.getThreadById({ threadId: "thread-123" });
+```
+
+## Parameters
+
+## Returns
+
+### Related
+
+- [Memory Class Reference](https://mastra.ai/reference/v1/memory/memory-class)
+- [Getting Started with Memory](https://mastra.ai/docs/v1/memory/overview) (Covers threads concept)
+- [createThread](https://mastra.ai/reference/v1/memory/createThread)
+- [listThreads](https://mastra.ai/reference/v1/memory/listThreads)
+
+---
+
+## Reference: Memory.listThreads()
+
+> Documentation for the `Memory.listThreads()` method in Mastra, which retrieves threads with optional filtering by resourceId and/or metadata.
+
+The `listThreads()` method retrieves threads with pagination support and optional filtering by `resourceId`, `metadata`, or both.
+
+## Usage Examples
+
+### List all threads with pagination
+
+```typescript
+const result = await memory.listThreads({
+  page: 0,
+  perPage: 10,
+});
+```
+
+### Fetch all threads without pagination
+
+Use `perPage: false` to retrieve all matching threads at once.
+
+> **Note:**
+
+Generally speaking it's recommended to use pagination, especially for large datasets. Use this option cautiously.
+
+```typescript
+const result = await memory.listThreads({
+  filter: { resourceId: "user-123" },
+  perPage: false,
+});
+```
+
+### Filter by resourceId
+
+```typescript
+const result = await memory.listThreads({
+  filter: { resourceId: "user-123" },
+  page: 0,
+  perPage: 10,
+});
+```
+
+### Filter by metadata
+
+```typescript
+const result = await memory.listThreads({
+  filter: { metadata: { category: "support", priority: "high" } },
+  page: 0,
+  perPage: 10,
+});
+```
+
+### Combined filter (resourceId & metadata)
+
+```typescript
+const result = await memory.listThreads({
+  filter: {
+    resourceId: "user-123",
+    metadata: { status: "active" },
+  },
+  page: 0,
+  perPage: 10,
+});
+```
+
+## Parameters
+
+## Returns
+
+The return object contains:
+
+- `threads`: Array of thread objects
+- `total`: Total number of threads matching the filter
+- `page`: Current page number (same as the input `page` parameter)
+- `perPage`: Items per page (same as the input `perPage` parameter)
+- `hasMore`: Boolean indicating if more results are available
+
+## Extended usage example
+
+```typescript title="src/test-memory.ts"
+import { mastra } from "./mastra";
+
+const agent = mastra.getAgent("agent");
+const memory = await agent.getMemory();
+
+let currentPage = 0;
+const perPage = 25;
+let hasMorePages = true;
+
+// Fetch all active threads for a user, sorted by creation date
+while (hasMorePages) {
+  const result = await memory?.listThreads({
+    filter: {
+      resourceId: "user-123",
+      metadata: { status: "active" },
+    },
+    page: currentPage,
+    perPage: perPage,
+    orderBy: { field: "createdAt", direction: "ASC" },
+  });
+
+  if (!result) {
+    console.log("No threads");
+    break;
+  }
+
+  result.threads.forEach((thread) => {
+    console.log(`Thread: ${thread.id}, Created: ${thread.createdAt}`);
+  });
+
+  hasMorePages = result.hasMore;
+  currentPage++; // Move to next page
+}
+```
+
+## Metadata Filtering
+
+The metadata filter uses AND logic - all specified key-value pairs must match for a thread to be included in the results:
+
+```typescript
+// This will only return threads where BOTH conditions are true:
+// - category === 'support'
+// - priority === 'high'
+await memory.listThreads({
+  filter: {
+    metadata: {
+      category: "support",
+      priority: "high",
+    },
+  },
+});
+```
+
+## Related
+
+- [Memory Class Reference](https://mastra.ai/reference/v1/memory/memory-class)
+- [Getting Started with Memory](https://mastra.ai/docs/v1/memory/overview) (Covers threads/resources concept)
+- [createThread](https://mastra.ai/reference/v1/memory/createThread)
+- [getThreadById](https://mastra.ai/reference/v1/memory/getThreadById)
+
+---
+
+## Reference: Memory Class
+
+> Documentation for the `Memory` class in Mastra, which provides a robust system for managing conversation history and thread-based message storage.
+
+The `Memory` class provides a robust system for managing conversation history and thread-based message storage in Mastra. It enables persistent storage of conversations, semantic search capabilities, and efficient message retrieval. You must configure a storage provider for conversation history, and if you enable semantic recall you will also need to provide a vector store and embedder.
+
+## Usage example
+
+```typescript title="src/mastra/agents/test-agent.ts"
+import { Memory } from "@mastra/memory";
+import { Agent } from "@mastra/core/agent";
+
+export const agent = new Agent({
+  name: "test-agent",
+  instructions: "You are an agent with memory.",
+  model: "openai/gpt-5.1",
+  memory: new Memory({
+    options: {
+      workingMemory: {
+        enabled: true,
+      },
+    },
+  }),
+});
+```
+
+> To enable `workingMemory` on an agent, you’ll need a storage provider configured on your main Mastra instance. See [Mastra class](../core/mastra-class) for more information.
+
+## Constructor parameters
+
+### Options parameters
+
+## Returns
+
+## Extended usage example
+
+```typescript title="src/mastra/agents/test-agent.ts"
+import { Memory } from "@mastra/memory";
+import { Agent } from "@mastra/core/agent";
+import { LibSQLStore, LibSQLVector } from "@mastra/libsql";
+
+export const agent = new Agent({
+  name: "test-agent",
+  instructions: "You are an agent with memory.",
+  model: "openai/gpt-5.1",
+  memory: new Memory({
+    storage: new LibSQLStore({
+      id: 'test-agent-storage',
+      url: "file:./working-memory.db",
+    }),
+    vector: new LibSQLVector({
+      id: 'test-agent-vector',
+      url: "file:./vector-memory.db",
+    }),
+    options: {
+      lastMessages: 10,
+      semanticRecall: {
+        topK: 3,
+        messageRange: 2,
+        scope: "resource",
+      },
+      workingMemory: {
+        enabled: true,
+      },
+      generateTitle: true,
+    },
+  }),
+});
+```
+
+## PostgreSQL with index configuration
+
+```typescript title="src/mastra/agents/pg-agent.ts"
+import { Memory } from "@mastra/memory";
+import { Agent } from "@mastra/core/agent";
+import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
+import { PgStore, PgVector } from "@mastra/pg";
+
+export const agent = new Agent({
+  name: "pg-agent",
+  instructions: "You are an agent with optimized PostgreSQL memory.",
+  model: "openai/gpt-5.1",
+  memory: new Memory({
+    storage: new PgStore({
+      id: 'pg-agent-storage',
+      connectionString: process.env.DATABASE_URL,
+    }),
+    vector: new PgVector({
+      id: 'pg-agent-vector',
+      connectionString: process.env.DATABASE_URL,
+    }),
+    embedder: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
+    options: {
+      lastMessages: 20,
+      semanticRecall: {
+        topK: 5,
+        messageRange: 3,
+        scope: "resource",
+        indexConfig: {
+          type: "hnsw", // Use HNSW for better performance
+          metric: "dotproduct", // Optimal for OpenAI embeddings
+          m: 16, // Number of bi-directional links
+          efConstruction: 64, // Construction-time candidate list size
+        },
+      },
+      workingMemory: {
+        enabled: true,
+      },
+    },
+  }),
+});
+```
+
+### Related
+
+- [Getting Started with Memory](https://mastra.ai/docs/v1/memory/overview)
+- [Semantic Recall](https://mastra.ai/docs/v1/memory/semantic-recall)
+- [Working Memory](https://mastra.ai/docs/v1/memory/working-memory)
+- [Memory Processors](https://mastra.ai/docs/v1/memory/memory-processors)
+- [createThread](https://mastra.ai/reference/v1/memory/createThread)
+- [recall](https://mastra.ai/reference/v1/memory/recall)
+- [getThreadById](https://mastra.ai/reference/v1/memory/getThreadById)
+- [listThreads](https://mastra.ai/reference/v1/memory/listThreads)
+- [deleteMessages](https://mastra.ai/reference/v1/memory/deleteMessages)
+- [cloneThread](https://mastra.ai/reference/v1/memory/cloneThread)
+- [Clone Utility Methods](https://mastra.ai/reference/v1/memory/clone-utilities)