@mastra/memory 1.5.1 → 1.5.2

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)

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

@@ -0,0 +1,145 @@
+# Memory.listThreads()
+
+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.
+
+> **Warning:** 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
+
+**filter?:** (`{ resourceId?: string; metadata?: Record<string, unknown> }`): Optional filter object. resourceId filters threads by resource ID. metadata filters threads by metadata key-value pairs (AND logic - all must match)
+
+**page?:** (`number`): Page number (0-indexed) to retrieve
+
+**perPage?:** (`number | false`): Maximum number of threads to return per page, or false to fetch all
+
+**orderBy?:** (`{ field: 'createdAt' | 'updatedAt', direction: 'ASC' | 'DESC' }`): Sort configuration with field and direction (defaults to { field: 'createdAt', direction: 'DESC' })
+
+## Returns
+
+**result:** (`Promise<StorageListThreadsOutput>`): A promise that resolves to paginated thread results with metadata
+
+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
+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/memory/memory-class)
+- [Getting Started with Memory](https://mastra.ai/docs/memory/overview)
+- [createThread](https://mastra.ai/reference/memory/createThread)
+- [getThreadById](https://mastra.ai/reference/memory/getThreadById)