@mastra/memory 1.1.0-alpha.1 → 1.2.0-alpha.0

package/dist/docs/{memory/02-storage.md → references/docs-memory-storage.md}

@@ -1,10 +1,8 @@
-> Configure storage for Mastra
-
 # Storage
 
-For agents to remember previous interactions, Mastra needs a database. Use a storage adapter for one of the [supported databases](#supported-providers) and pass it to your Mastra instance. 
+For agents to remember previous interactions, Mastra needs a database. Use a storage adapter for one of the [supported databases](#supported-providers) and pass it to your Mastra instance.
 
-```typescript title="src/mastra/index.ts"
+```typescript
 import { Mastra } from "@mastra/core";
 import { LibSQLStore } from "@mastra/libsql";
 
@@ -16,18 +14,17 @@ export const mastra = new Mastra({
 });
 ```
 
-> **Sharing the database with Mastra Studio**
-When running `mastra dev` alongside your application (e.g., Next.js), use an absolute path to ensure both processes access the same database:
-
-```typescript
-url: "file:/absolute/path/to/your/project/mastra.db"
-```
-
-Relative paths like `file:./mastra.db` resolve based on each process's working directory, which may differ.
+> **Sharing the database with Mastra Studio:** When running `mastra dev` alongside your application (e.g., Next.js), use an absolute path to ensure both processes access the same database:
+>
+> ```typescript
+> url: "file:/absolute/path/to/your/project/mastra.db"
+> ```
+>
+> Relative paths like `file:./mastra.db` resolve based on each process's working directory, which may differ.
 
 This configures instance-level storage, which all agents share by default. You can also configure [agent-level storage](#agent-level-storage) for isolated data boundaries.
 
-Mastra automatically creates the necessary tables on first interaction. See the [core schema](https://mastra.ai/reference/storage/overview#core-schema) for details on what gets created, including tables for messages, threads, resources, workflows, traces, and evaluation datasets.
+Mastra automatically creates the necessary tables on first interaction. See the [core schema](https://mastra.ai/reference/storage/overview) for details on what gets created, including tables for messages, threads, resources, workflows, traces, and evaluation datasets.
 
 ## Supported providers
 
@@ -44,8 +41,7 @@ Each provider page includes installation instructions, configuration parameters,
 - [LanceDB](https://mastra.ai/reference/storage/lance)
 - [Microsoft SQL Server](https://mastra.ai/reference/storage/mssql)
 
-> **Note:**
-libSQL is the easiest way to get started because it doesn’t require running a separate database server.
+> **Tip:** libSQL is the easiest way to get started because it doesn’t require running a separate database server.
 
 ## Configuration scope
 
@@ -55,7 +51,7 @@ Storage can be configured at the instance level (shared by all agents) or at the
 
 Add storage to your Mastra instance so all agents, workflows, observability traces and scores share the same memory provider:
 
-```typescript title="src/mastra/index.ts"
+```typescript
 import { Mastra } from "@mastra/core";
 import { PostgresStore } from "@mastra/pg";
 
@@ -75,9 +71,9 @@ This is useful when all primitives share the same storage backend and have simil
 
 #### Composite storage
 
-[Composite storage](https://mastra.ai/reference/storage/composite) is an alternative way to configure instance-level storage. Use `MastraCompositeStore` to set the `memory` domain (and any other [domains](https://mastra.ai/reference/storage/composite#storage-domains) you need) to different storage providers.
+[Composite storage](https://mastra.ai/reference/storage/composite) is an alternative way to configure instance-level storage. Use `MastraCompositeStore` to set the `memory` domain (and any other [domains](https://mastra.ai/reference/storage/composite) you need) to different storage providers.
 
-```typescript title="src/mastra/index.ts"
+```typescript
 import { Mastra } from "@mastra/core";
 import { MastraCompositeStore } from "@mastra/core/storage";
 import { MemoryLibSQL } from "@mastra/libsql";
@@ -88,7 +84,6 @@ export const mastra = new Mastra({
   storage: new MastraCompositeStore({
     id: "composite",
     domains: {
-      // highlight-next-line
       memory: new MemoryLibSQL({ url: "file:./memory.db" }),
       workflows: new WorkflowsPG({ connectionString: process.env.DATABASE_URL }),
       observability: new ObservabilityStorageClickhouse({
@@ -107,7 +102,7 @@ This is useful when different types of data have different performance or operat
 
 Agent-level storage overrides storage configured at the instance level. Add storage to a specific agent when you need data boundaries or compliance requirements:
 
-```typescript title="src/mastra/agents/your-agent.ts"
+```typescript
 import { Agent } from "@mastra/core/agent";
 import { Memory } from "@mastra/memory";
 import { PostgresStore } from "@mastra/pg";
@@ -123,19 +118,18 @@ export const agent = new Agent({
 });
 ```
 
-> **Note:**
-[Mastra Cloud Store](https://mastra.ai/docs/mastra-cloud/deployment#using-mastra-cloud-store) doesn't support agent-level storage.
+> **Warning:** [Mastra Cloud Store](https://mastra.ai/docs/mastra-cloud/deployment) doesn't support agent-level storage.
 
 ## Threads and resources
 
-Mastra organizes conversations using two identifiers: 
+Mastra organizes conversations using two identifiers:
 
 - **Thread** - a conversation session containing a sequence of messages.
 - **Resource** - the entity that owns the thread, such as a user, organization, project, or any other domain entity in your application.
 
 Both identifiers are required for agents to store information:
 
-  **generate:**
+**Generate**:
 
 ```typescript
 const response = await agent.generate("hello", {
@@ -146,8 +140,7 @@ const response = await agent.generate("hello", {
 });
 ```
 
-  
-  **stream:**
+**Stream**:
 
 ```typescript
 const stream = await agent.stream("hello", {
@@ -158,10 +151,7 @@ const stream = await agent.stream("hello", {
 });
 ```
 
-  
-
-> **Note:**
-[Studio](https://mastra.ai/docs/getting-started/studio) automatically generates a thread and resource ID for you. When calling `stream()` or `generate()` yourself, remember to provide these identifiers explicitly.
+> **Note:** [Studio](https://mastra.ai/docs/getting-started/studio) automatically generates a thread and resource ID for you. When calling `stream()` or `generate()` yourself, remember to provide these identifiers explicitly.
 
 ### Thread title generation
 
@@ -169,7 +159,7 @@ Mastra can automatically generate descriptive thread titles based on the user's
 
 Use this option when implementing a ChatGPT-style chat interface to render a title alongside each thread in the conversation list (for example, in a sidebar) derived from the thread’s initial user message.
 
-```typescript title="src/mastra/agents/my-agent.ts"
+```typescript
 export const agent = new Agent({
   id: "agent",
   memory: new Memory({
@@ -182,9 +172,9 @@ export const agent = new Agent({
 
 Title generation runs asynchronously after the agent responds and does not affect response time.
 
-To optimize cost or behavior, provide a smaller [`model`](/models) and custom `instructions`:
+To optimize cost or behavior, provide a smaller [`model`](https://mastra.ai/models) and custom `instructions`:
 
-```typescript title="src/mastra/agents/my-agent.ts"
+```typescript
 export const agent = new Agent({
   id: "agent",
   memory: new Memory({
@@ -206,17 +196,17 @@ Semantic recall has different storage requirements - it needs a vector database
 
 Some storage providers enforce record size limits that base64-encoded file attachments (such as images) can exceed:
 
-| Provider | Record size limit |
-| -------- | ----------------- |
-| [DynamoDB](https://mastra.ai/reference/storage/dynamodb) | 400 KB |
-| [Convex](https://mastra.ai/reference/storage/convex) | 1 MiB |
-| [Cloudflare D1](https://mastra.ai/reference/storage/cloudflare-d1) | 1 MiB |
+| Provider                                                           | Record size limit |
+| ------------------------------------------------------------------ | ----------------- |
+| [DynamoDB](https://mastra.ai/reference/storage/dynamodb)           | 400 KB            |
+| [Convex](https://mastra.ai/reference/storage/convex)               | 1 MiB             |
+| [Cloudflare D1](https://mastra.ai/reference/storage/cloudflare-d1) | 1 MiB             |
 
 PostgreSQL, MongoDB, and libSQL have higher limits and are generally unaffected.
 
 To avoid this, use an input processor to upload attachments to external storage (S3, R2, GCS, [Convex file storage](https://docs.convex.dev/file-storage), etc.) and replace them with URL references before persistence.
 
-```typescript title="src/mastra/processors/attachment-uploader.ts"
+```typescript
 import type { Processor } from "@mastra/core/processors";
 import type { MastraDBMessage } from "@mastra/core/memory";
 

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
+}
+```