@mastra/memory 1.1.0 → 1.2.0-alpha.1

package/dist/docs/{memory/04-working-memory.md → references/docs-memory-working-memory.md}

@@ -1,8 +1,6 @@
-> Learn how to configure working memory in Mastra to store persistent user data, preferences.
-
 # Working Memory
 
-While [message history](https://mastra.ai/docs/memory/message-history) and [semantic recall](./semantic-recall) help agents remember conversations, working memory allows them to maintain persistent information about users across interactions.
+While [message history](https://mastra.ai/docs/memory/message-history) and [semantic recall](https://mastra.ai/docs/memory/semantic-recall) help agents remember conversations, working memory allows them to maintain persistent information about users across interactions.
 
 Think of it as the agent's active thoughts or scratchpad – the key information they keep available about the user or task. It's similar to how a person would naturally remember someone's name, preferences, or important details during a conversation.
 
@@ -19,7 +17,7 @@ Working memory can persist at two different scopes:
 
 Here's a minimal example of setting up an agent with working memory:
 
-```typescript {11-15}
+```typescript
 import { Agent } from "@mastra/core/agent";
 import { Memory } from "@mastra/memory";
 
@@ -43,7 +41,7 @@ const agent = new Agent({
 
 Working memory is a block of Markdown text that the agent is able to update over time to store continuously relevant information:
 
-<YouTube id="UMy_JHLf1n8" />
+[YouTube video player](https://www.youtube-nocookie.com/embed/UMy_JHLf1n8)
 
 ## Memory Persistence Scopes
 
@@ -136,7 +134,7 @@ Templates guide the agent on what information to track and update in working mem
 
 Here's an example of a custom template. In this example the agent will store the users name, location, timezone, etc as soon as the user sends a message containing any of the info:
 
-```typescript {5-28}
+```typescript
 const memory = new Memory({
   options: {
     workingMemory: {
@@ -172,19 +170,13 @@ const memory = new Memory({
 
 ## Designing Effective Templates
 
-A well-structured template keeps the information easy for the agent to parse and update. Treat the
-template as a short form that you want the assistant to keep up to date.
+A well-structured template keeps the information easy for the agent to parse and update. Treat the template as a short form that you want the assistant to keep up to date.
 
-- **Short, focused labels.** Avoid paragraphs or very long headings. Keep labels brief (for example
-  `## Personal Info` or `- Name:`) so updates are easy to read and less likely to be truncated.
-- **Use consistent casing.** Inconsistent capitalization (`Timezone:` vs `timezone:`) can cause messy
-  updates. Stick to Title Case or lower case for headings and bullet labels.
-- **Keep placeholder text simple.** Use hints such as `[e.g., Formal]` or `[Date]` to help the LLM
-  fill in the correct spots.
-- **Abbreviate very long values.** If you only need a short form, include guidance like
-  `- Name: [First name or nickname]` or `- Address (short):` rather than the full legal text.
-- **Mention update rules in `instructions`.** You can instruct how and when to fill or clear parts of
-  the template directly in the agent's `instructions` field.
+- **Short, focused labels.** Avoid paragraphs or very long headings. Keep labels brief (for example `## Personal Info` or `- Name:`) so updates are easy to read and less likely to be truncated.
+- **Use consistent casing.** Inconsistent capitalization (`Timezone:` vs `timezone:`) can cause messy updates. Stick to Title Case or lower case for headings and bullet labels.
+- **Keep placeholder text simple.** Use hints such as `[e.g., Formal]` or `[Date]` to help the LLM fill in the correct spots.
+- **Abbreviate very long values.** If you only need a short form, include guidance like `- Name: [First name or nickname]` or `- Address (short):` rather than the full legal text.
+- **Mention update rules in `instructions`.** You can instruct how and when to fill or clear parts of the template directly in the agent's `instructions` field.
 
 ### Alternative Template Styles
 
@@ -281,8 +273,7 @@ Schema-based working memory uses **merge semantics**, meaning the agent only nee
 
 ## Example: Multi-step Retention
 
-Below is a simplified view of how the `User Profile` template updates across a short user
-conversation:
+Below is a simplified view of how the `User Profile` template updates across a short user conversation:
 
 ```nohighlight
 # User Profile
@@ -308,11 +299,9 @@ conversation:
 - Timezone: CET
 ```
 
-The agent can now refer to `Sam` or `Berlin` in later responses without requesting the information
-again because it has been stored in working memory.
+The agent can now refer to `Sam` or `Berlin` in later responses without requesting the information again because it has been stored in working memory.
 
-If your agent is not properly updating working memory when you expect it to, you can add system
-instructions on _how_ and _when_ to use this template in your agent's `instructions` setting.
+If your agent is not properly updating working memory when you expect it to, you can add system instructions on _how_ and _when_ to use this template in your agent's `instructions` setting.
 
 ## Setting Initial Working Memory
 
@@ -322,7 +311,7 @@ While agents typically update working memory through the `updateWorkingMemory` t
 
 When creating a thread, you can provide initial working memory through the metadata's `workingMemory` key:
 
-```typescript title="src/app/medical-consultation.ts"
+```typescript
 // Create a thread with initial working memory
 const thread = await memory.createThread({
   threadId: "thread-123",
@@ -353,7 +342,7 @@ await agent.generate("What's my blood type?", {
 
 You can also update an existing thread's working memory:
 
-```typescript title="src/app/medical-consultation.ts"
+```typescript
 // Update thread metadata to add/modify working memory
 await memory.updateThread({
   id: "thread-123",
@@ -375,7 +364,7 @@ await memory.updateThread({
 
 Alternatively, use the `updateWorkingMemory` method directly:
 
-```typescript title="src/app/medical-consultation.ts"
+```typescript
 await memory.updateWorkingMemory({
   threadId: "thread-123",
   resourceId: "user-456", // Required for resource-scoped memory

package/dist/docs/references/reference-core-getMemory.md

@@ -0,0 +1,50 @@
+# Mastra.getMemory()
+
+The `.getMemory()` method retrieves a memory instance from the Mastra registry by its key. Memory instances are registered in the Mastra constructor and can be referenced by stored agents.
+
+## Usage example
+
+```typescript
+const memory = mastra.getMemory("conversationMemory");
+
+// Use the memory instance
+const thread = await memory.createThread({
+  resourceId: "user-123",
+  title: "New Conversation",
+});
+```
+
+## Parameters
+
+**key:** (`TMemoryKey extends keyof TMemory`): The registry key of the memory instance to retrieve. Must match a key used when registering memory in the Mastra constructor.
+
+## Returns
+
+**memory:** (`TMemory[TMemoryKey]`): The memory instance with the specified key. Throws an error if the memory is not found.
+
+## Example: Registering and Retrieving Memory
+
+```typescript
+import { Mastra } from "@mastra/core";
+import { Memory } from "@mastra/memory";
+import { LibSQLStore } from "@mastra/libsql";
+
+const conversationMemory = new Memory({
+  storage: new LibSQLStore({ id: 'conversation-store', url: ":memory:" }),
+});
+
+const mastra = new Mastra({
+  memory: {
+    conversationMemory,
+  },
+});
+
+// Later, retrieve the memory instance
+const memory = mastra.getMemory("conversationMemory");
+```
+
+## Related
+
+- [Mastra.listMemory()](https://mastra.ai/reference/core/listMemory)
+- [Memory overview](https://mastra.ai/docs/memory/overview)
+- [Agent Memory](https://mastra.ai/docs/agents/agent-memory)

package/dist/docs/references/reference-core-listMemory.md

@@ -0,0 +1,56 @@
+# Mastra.listMemory()
+
+The `.listMemory()` method returns all memory instances registered with the Mastra instance.
+
+## Usage example
+
+```typescript
+const memoryInstances = mastra.listMemory();
+
+for (const [key, memory] of Object.entries(memoryInstances)) {
+  console.log(`Memory "${key}": ${memory.id}`);
+}
+```
+
+## Parameters
+
+This method takes no parameters.
+
+## Returns
+
+**memory:** (`Record<string, MastraMemory>`): An object containing all registered memory instances, keyed by their registry keys.
+
+## Example: Checking Registered Memory
+
+```typescript
+import { Mastra } from "@mastra/core";
+import { Memory } from "@mastra/memory";
+import { LibSQLStore } from "@mastra/libsql";
+
+const conversationMemory = new Memory({
+  id: "conversation-memory",
+  storage: new LibSQLStore({ id: 'conversation-store', url: ":memory:" }),
+});
+
+const analyticsMemory = new Memory({
+  id: "analytics-memory",
+  storage: new LibSQLStore({ id: 'analytics-store', url: ":memory:" }),
+});
+
+const mastra = new Mastra({
+  memory: {
+    conversationMemory,
+    analyticsMemory,
+  },
+});
+
+// List all registered memory instances
+const allMemory = mastra.listMemory();
+console.log(Object.keys(allMemory)); // ["conversationMemory", "analyticsMemory"]
+```
+
+## Related
+
+- [Mastra.getMemory()](https://mastra.ai/reference/core/getMemory)
+- [Memory overview](https://mastra.ai/docs/memory/overview)
+- [Agent Memory](https://mastra.ai/docs/agents/agent-memory)

package/dist/docs/references/reference-memory-clone-utilities.md

@@ -0,0 +1,199 @@
+# Cloned Thread Utilities
+
+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
+
+**thread:** (`StorageThreadType`): The thread object to check.
+
+### 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
+
+**thread:** (`StorageThreadType`): The thread object to extract clone metadata from.
+
+### 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
+
+**threadId:** (`string`): The ID of the cloned thread.
+
+### 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
+
+**sourceThreadId:** (`string`): The ID of the source thread to find clones for.
+
+### 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
+
+**threadId:** (`string`): The ID of the thread to get clone history for.
+
+### 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
+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
+}
+```

package/dist/docs/references/reference-memory-cloneThread.md

@@ -0,0 +1,130 @@
+# 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
+
+**sourceThreadId:** (`string`): The ID of the thread to clone
+
+**newThreadId?:** (`string`): Optional custom ID for the cloned thread. If not provided, one will be generated.
+
+**resourceId?:** (`string`): Optional resource ID for the cloned thread. Defaults to the source thread's resourceId.
+
+**title?:** (`string`): Optional title for the cloned thread. Defaults to '\[source title] (Copy)'.
+
+**metadata?:** (`Record<string, unknown>`): Optional metadata to merge with the source thread's metadata. Clone metadata is automatically added.
+
+**options?:** (`CloneOptions`): Optional filtering options for the clone operation.
+
+### Options Parameters
+
+**messageLimit?:** (`number`): Maximum number of messages to clone. When set, clones the most recent N messages.
+
+**messageFilter?:** (`MessageFilter`): Filter criteria for selecting which messages to clone.
+
+### MessageFilter Parameters
+
+**startDate?:** (`Date`): Only clone messages created on or after this date.
+
+**endDate?:** (`Date`): Only clone messages created on or before this date.
+
+**messageIds?:** (`string[]`): Only clone messages with these specific IDs.
+
+## Returns
+
+**thread:** (`StorageThreadType`): The newly created cloned thread with clone metadata.
+
+**clonedMessages:** (`MastraDBMessage[]`): 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:
+
+**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.
+
+## Extended Usage Example
+
+```typescript
+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",
+});
+```

package/dist/docs/references/reference-memory-createThread.md

@@ -0,0 +1,68 @@
+# Memory.createThread()
+
+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
+
+**resourceId:** (`string`): Identifier for the resource this thread belongs to (e.g., user ID, project ID)
+
+**threadId?:** (`string`): Optional custom ID for the thread. If not provided, one will be generated.
+
+**title?:** (`string`): Optional title for the thread
+
+**metadata?:** (`Record<string, unknown>`): Optional metadata to associate with the thread
+
+## Returns
+
+**id:** (`string`): Unique identifier of the created thread
+
+**resourceId:** (`string`): Resource ID associated with the thread
+
+**title:** (`string`): Title of the thread (if provided)
+
+**createdAt:** (`Date`): Timestamp when the thread was created
+
+**updatedAt:** (`Date`): Timestamp when the thread was last updated
+
+**metadata:** (`Record<string, unknown>`): Additional metadata associated with the thread
+
+## Extended usage example
+
+```typescript
+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/memory/memory-class)
+- [Getting Started with Memory](https://mastra.ai/docs/memory/overview) (Covers threads concept)
+- [getThreadById](https://mastra.ai/reference/memory/getThreadById)
+- [listThreads](https://mastra.ai/reference/memory/listThreads)
+- [recall](https://mastra.ai/reference/memory/recall)

package/dist/docs/references/reference-memory-getThreadById.md

@@ -0,0 +1,24 @@
+# Memory.getThreadById()
+
+The `.getThreadById()` method retrieves a specific thread by its ID.
+
+## Usage Example
+
+```typescript
+await memory?.getThreadById({ threadId: "thread-123" });
+```
+
+## Parameters
+
+**threadId:** (`string`): The ID of the thread to be retrieved.
+
+## Returns
+
+**thread:** (`Promise<StorageThreadType | null>`): A promise that resolves to the thread associated with the given ID, or null if not found.
+
+### Related
+
+- [Memory Class Reference](https://mastra.ai/reference/memory/memory-class)
+- [Getting Started with Memory](https://mastra.ai/docs/memory/overview) (Covers threads concept)
+- [createThread](https://mastra.ai/reference/memory/createThread)
+- [listThreads](https://mastra.ai/reference/memory/listThreads)