@mastra/memory 0.0.0-error-handler-fix-20251020202607 → 0.0.0-esbuild-bundle-worker-20260807182016

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

@@ -0,0 +1,57 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# 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)

package/dist/docs/references/reference-file-based-agents-memory.md

@@ -0,0 +1,58 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Memory
+
+A file-based agent gets [memory](https://mastra.ai/docs/memory/overview) from a `memory.ts` file that default-exports a [`Memory`](https://mastra.ai/reference/memory/memory-class) instance. Use this page for the file-based convention; use the memory docs for message history, semantic recall, storage, and processors.
+
+Without `memory.ts` or `config.memory`, the agent has no memory by default. Each `generate()` or `stream()` call starts without remembered conversation state unless you pass the prior context yourself.
+
+## Quickstart
+
+Create `memory.ts` next to the agent's `config.ts`:
+
+```typescript
+import { Memory } from '@mastra/memory'
+
+export default new Memory()
+```
+
+The exported instance becomes the agent's `memory`. If your app configures a storage provider on the main Mastra instance, memory data is stored there. See [storage](https://mastra.ai/docs/storage/overview) for more information.
+
+Use the same `resource` and `thread` values when calling the agent to continue a conversation:
+
+```typescript
+const response = await weatherAgent.generate('Remember that I prefer Celsius.', {
+  memory: {
+    resource: 'user-123',
+    thread: 'weather-chat',
+  },
+})
+```
+
+## Configure memory
+
+Pass options to `new Memory()` when the default behavior isn't enough.
+
+```typescript
+import { Memory } from '@mastra/memory'
+
+export default new Memory({
+  options: {
+    lastMessages: 20,
+    workingMemory: {
+      enabled: true,
+      scope: 'resource',
+    },
+  },
+})
+```
+
+Visit the [`Memory` reference](https://mastra.ai/reference/memory/memory-class) for constructor options. Use these pages for related memory features:
+
+- [Storage](https://mastra.ai/docs/storage/overview): configure persistence for memory data.
+- [Semantic recall](https://mastra.ai/docs/memory/semantic-recall): retrieve relevant past messages by semantic meaning.
+- [Memory processors](https://mastra.ai/docs/memory/memory-processors): filter, trim, or transform messages before memory adds them to model context.
+
+## Precedence with config
+
+`config.memory` wins over `memory.ts`. If neither is present, the assembled file-based agent has no memory. See [`config.ts` precedence](https://mastra.ai/reference/file-based-agents/config) for the full merge table.

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

@@ -0,0 +1,203 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Cloned thread utilities
+
+The Memory class provides utility methods for working with cloned threads. These methods help you check clone status, retrieve clone metadata, traverse 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.", {
+    memory: {
+      thread: originalThread.id,
+      resource: '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,173 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Memory.cloneThread()
+
+The `.cloneThread()` method creates a copy of an existing conversation thread, including all its messages. It supports 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
+
+The following example creates a `Memory` instance and clones an existing thread.
+
+```typescript
+import { Memory } from '@mastra/memory'
+import { LibSQLStore } from '@mastra/libsql'
+
+const memory = new Memory({
+  storage: new LibSQLStore({ id: 'memory-store', url: 'file:./memory.db' }),
+})
+
+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. If omitted, the clone uses Clone of ${sourceThread.title} when the source thread has a title. Otherwise, the title is empty.
+
+**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.messageLimit** (`number`): Maximum number of messages to clone. When set, clones the most recent N messages.
+
+**options.messageFilter** (`MessageFilter`): Filter criteria for selecting which messages to clone.
+
+**options.messageFilter.startDate** (`Date`): Only clone messages created on or after this date.
+
+**options.messageFilter.endDate** (`Date`): Only clone messages created on or before this date.
+
+**options.messageFilter.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.
+
+**messageIdMap** (`Record<string, string>`): A mapping from source message IDs to their corresponding cloned message IDs.
+
+### 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'),
+    },
+  },
+})
+
+// Clone specific messages
+const { thread: selectedMessagesClone } = await memory.cloneThread({
+  sourceThreadId: 'original-thread-123',
+  options: {
+    messageFilter: {
+      messageIds: ['message-1', 'message-2'],
+    },
+  },
+})
+
+// Continue conversation on the cloned thread
+const response = await agent.generate('Try a different approach', {
+  memory: {
+    thread: fullClone.id,
+    resource: fullClone.resourceId,
+  },
+})
+```
+
+Pass the cloned `thread.id` and `thread.resourceId` to `agent.generate()` to continue the conversation from the cloned thread.
+
+## 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. It ensures that semantic search works correctly on the cloned thread.
+
+In this example, `embeddingModel` is the embedding model configured for the project.
+
+```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',
+})
+```
+
+## Working memory
+
+When working memory is enabled, `cloneThread()` copies or shares working memory based on the working-memory scope and the clone's `resourceId`:
+
+- **Thread-scoped working memory**: The working memory is copied to the cloned thread.
+- **Resource-scoped working memory with the same `resourceId`**: The working memory is shared because the source and cloned threads belong to the same resource.
+- **Resource-scoped working memory with a different `resourceId`**: The working memory is copied to the cloned thread's resource.
+
+## Observational Memory
+
+When [Observational Memory](https://mastra.ai/docs/memory/observational-memory) is enabled, `cloneThread()` automatically clones the OM records associated with the source thread. The behavior depends on the OM scope:
+
+- **Thread-scoped OM**: The OM record is cloned to the new thread. All internal message ID references are remapped to point to the cloned messages.
+- **Resource-scoped OM (same `resourceId`)**: The OM record is shared between the source and cloned threads since they belong to the same resource. No duplication occurs.
+- **Resource-scoped OM (different `resourceId`)**: The OM record is cloned to the new resource. Message IDs are remapped and any thread-identifying tags within observations are updated to reference the cloned thread.
+
+Only the current (most recent) OM generation is cloned. Older history generations aren't copied. Transient processing state (observation/reflection in-progress flags) is reset on the cloned record.

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

@@ -0,0 +1,70 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# 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,26 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# 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)