@mastra/memory 1.5.0 → 1.5.1

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

@@ -1,130 +0,0 @@
-# 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

@@ -1,68 +0,0 @@
-# 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

@@ -1,24 +0,0 @@
-# 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

@@ -1,145 +0,0 @@
-# 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)

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

@@ -1,147 +0,0 @@
-# Memory Class
-
-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
-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](https://mastra.ai/reference/core/mastra-class) for more information.
-
-## Constructor parameters
-
-**storage?:** (`MastraCompositeStore`): Storage implementation for persisting memory data. Defaults to \`new DefaultStorage({ config: { url: "file:memory.db" } })\` if not provided.
-
-**vector?:** (`MastraVector | false`): Vector store for semantic search capabilities. Set to \`false\` to disable vector operations.
-
-**embedder?:** (`EmbeddingModel<string> | EmbeddingModelV2<string>`): Embedder instance for vector embeddings. Required when semantic recall is enabled.
-
-**options?:** (`MemoryConfig`): Memory configuration options.
-
-### Options parameters
-
-**lastMessages?:** (`number | false`): Number of most recent messages to include in context. Set to \`false\` to disable loading conversation history into context. Use \`Number.MAX\_SAFE\_INTEGER\` to retrieve all messages with no limit. To prevent saving new messages, use the \`readOnly\` option instead. (Default: `10`)
-
-**readOnly?:** (`boolean`): When true, prevents memory from saving new messages and provides working memory as read-only context (without the updateWorkingMemory tool). Useful for read-only operations like previews, internal routing agents, or sub agents that should reference but not modify memory. (Default: `false`)
-
-**semanticRecall?:** (`boolean | { topK: number; messageRange: number | { before: number; after: number }; scope?: 'thread' | 'resource' }`): Enable semantic search in message history. Can be a boolean or an object with configuration options. When enabled, requires both vector store and embedder to be configured. Default topK is 4, default messageRange is {before: 1, after: 1}. (Default: `false`)
-
-**workingMemory?:** (`WorkingMemory`): Configuration for working memory feature. Can be \`{ enabled: boolean; template?: string; schema?: ZodObject\<any> | JSONSchema7; scope?: 'thread' | 'resource' }\` or \`{ enabled: boolean }\` to disable. (Default: `{ enabled: false, template: '# User Information\n- **First Name**:\n- **Last Name**:\n...' }`)
-
-**observationalMemory?:** (`boolean | ObservationalMemoryOptions`): Enable Observational Memory for long-context agentic memory. Set to \`true\` for defaults, or pass a config object to customize token budgets, models, and scope. See \[Observational Memory reference]\(/reference/memory/observational-memory) for configuration details. (Default: `false`)
-
-**generateTitle?:** (`boolean | { model: DynamicArgument<MastraLanguageModel>; instructions?: DynamicArgument<string> }`): Controls automatic thread title generation from the user's first message. Can be a boolean or an object with custom model and instructions. (Default: `false`)
-
-## Returns
-
-**memory:** (`Memory`): A new Memory instance with the specified configuration.
-
-## Extended usage example
-
-```typescript
-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
-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/memory/overview)
-- [Semantic Recall](https://mastra.ai/docs/memory/semantic-recall)
-- [Working Memory](https://mastra.ai/docs/memory/working-memory)
-- [Observational Memory](https://mastra.ai/docs/memory/observational-memory)
-- [Memory Processors](https://mastra.ai/docs/memory/memory-processors)
-- [createThread](https://mastra.ai/reference/memory/createThread)
-- [recall](https://mastra.ai/reference/memory/recall)
-- [getThreadById](https://mastra.ai/reference/memory/getThreadById)
-- [listThreads](https://mastra.ai/reference/memory/listThreads)
-- [deleteMessages](https://mastra.ai/reference/memory/deleteMessages)
-- [cloneThread](https://mastra.ai/reference/memory/cloneThread)
-- [Clone Utility Methods](https://mastra.ai/reference/memory/clone-utilities)