@mastra/mcp-docs-server 0.13.21 → 0.13.22-alpha.1

package/.docs/raw/reference/memory/Memory.mdx

@@ -1,305 +1,157 @@
-# Memory Class Reference
+---
+title: "Reference: Memory Class | Memory | Mastra Docs"
+description: "Documentation for the `Memory` class in Mastra, which provides a robust system for managing conversation history and thread-based message storage."
+---
 
-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.
-
-## Basic Usage
-
-```typescript copy showLineNumbers
-import { Memory } from "@mastra/memory";
-import { Agent } from "@mastra/core/agent";
-
-const agent = new Agent({
-  memory: new Memory(),
-  ...otherOptions,
-});
-```
-
-## Custom Configuration
-
-```typescript copy showLineNumbers
-import { Memory } from "@mastra/memory";
-import { LibSQLStore, LibSQLVector } from "@mastra/libsql";
-import { Agent } from "@mastra/core/agent";
-
-const memory = new Memory({
-  // Optional storage configuration - libsql will be used by default
-  storage: new LibSQLStore({
-    url: "file:./memory.db",
-  }),
-
-  // Optional vector database for semantic search
-  vector: new LibSQLVector({
-    url: "file:./vector.db",
-  }),
-
-  // Memory configuration options
-  options: {
-    // Number of recent messages to include
-    lastMessages: 20,
-
-    // Semantic search configuration
-    semanticRecall: {
-      topK: 3, // Number of similar messages to retrieve
-      messageRange: {
-        // Messages to include around each result
-        before: 2,
-        after: 1,
-      },
-    },
-
-    // Working memory configuration
-    workingMemory: {
-      enabled: true,
-      template: `
-# User
-- First Name:
-- Last Name:
-`,
-    },
-
-    // Thread configuration
-    threads: {
-      generateTitle: true, // Enable title generation using agent's model
-      // Or use a different model for title generation
-      // generateTitle: {
-      //   model: openai("gpt-4.1-nano"), // Use cheaper model for titles
-      //   instructions: "Generate a concise title based on the initial user message.", // Custom instructions for title
-      // },
-    },
-  },
-});
-
-const agent = new Agent({
-  memory,
-  ...otherOptions,
-});
-```
-
-### Working Memory
-
-The working memory feature allows agents to maintain persistent information across conversations. When enabled, the Memory class automatically manages working memory updates using a dedicated tool call.
-
-Example configuration:
-
-```typescript copy showLineNumbers
-const memory = new Memory({
-  options: {
-    workingMemory: {
-      enabled: true,
-      template: "# User\n- **First Name**:\n- **Last Name**:",
-    },
-  },
-});
-```
-
-If no template is provided, the Memory class uses a default template that includes fields for user details, preferences, goals, and other contextual information in Markdown format. See the [Working Memory guide](/docs/memory/working-memory.mdx#designing-effective-templates) for detailed usage examples and best practices.
-
-### Thread Title Generation
-
-The `generateTitle` feature automatically creates meaningful titles for conversation threads based on the user's first message. This helps organize and identify conversations in your application.
-
-#### Basic Usage
-
-```typescript copy showLineNumbers
-const memory = new Memory({
-  options: {
-    threads: {
-      generateTitle: true, // Use the agent's model for title generation
-    },
-  },
-});
-```
-
-#### Cost Optimization with Custom Models and Instructions
-
-You can specify a different (typically cheaper) model and custom instructions for title generation while using a high-quality model for the main conversation:
-
-```typescript copy showLineNumbers
-import { openai } from "@ai-sdk/openai";
-
-const memory = new Memory({
-  options: {
-    threads: {
-      generateTitle: {
-        model: openai("gpt-4.1-nano"), // Cheaper model for titles
-        instructions: "Generate a concise, friendly title based on the initial user message.", // Custom title instructions
-      },
-    },
-  },
-});
-
-const agent = new Agent({
-  model: openai("gpt-4o"), // High-quality model for main conversation
-  memory,
-});
-```
-
-#### Dynamic Model Selection and Instructions
+# Memory Class
 
-You can also use a function to dynamically determine the model and instructions based on runtime context:
-
-```typescript copy showLineNumbers
-const memory = new Memory({
-  options: {
-    threads: {
-      generateTitle: {
-        model: (ctx: RuntimeContext) => {
-          // Use different models based on context
-          const userTier = ctx.get("userTier");
-          return userTier === "premium" 
-            ? openai("gpt-4.1")
-            : openai("gpt-4.1-nano");
-        },
-        instructions: (ctx: RuntimeContext) => {
-          const language = ctx.get("userLanguage") || "English";
-          return `Generate a concise, engaging title in ${language} based on the user's first message.`;
-        },
-      },
-    },
-  },
-});
-```
-### embedder
-
-An embedding model is required if `semanticRecall` is enabled.
-
-One option is to use `@mastra/fastembed`, which provides an on-device/local embedding model using [FastEmbed](https://github.com/Anush008/fastembed-js). This model runs locally and does not require API keys or network requests.
-
-To use it, first install the package:
-
-```bash npm2yarn copy
-npm install @mastra/fastembed
-```
+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.
 
-Then, configure it in your `Memory` instance:
+## Usage example
 
-```typescript {2,7}
+```typescript filename="src/mastra/agents/test-agent.ts" showLineNumbers copy
 import { Memory } from "@mastra/memory";
-import { fastembed } from "@mastra/fastembed";
 import { Agent } from "@mastra/core/agent";
-
-const agent = new Agent({
-  memory: new Memory({
-    embedder: fastembed,
-    // ... other memory config
-  }),
-});
-```
-
-Note that, depending on where you're deploying your project, your project may not deploy due to FastEmbeds large internal dependencies.
-
-Alternatively, you can use an API-based embedder like OpenAI (which doesn't have this problem):
-
-```typescript {2,7}
-import { Memory } from "@mastra/memory";
 import { openai } from "@ai-sdk/openai";
-import { Agent } from "@mastra/core/agent";
 
-const agent = new Agent({
+export const agent = new Agent({
+  name: "test-agent",
+  instructions: "You are an agent with memory.",
+  model: openai("gpt-4o"),
   memory: new Memory({
-    embedder: openai.embedding("text-embedding-3-small"),
-  }),
+    options: {
+      workingMemory: {
+        enabled: true
+      }
+    }
+  })
 });
 ```
 
-Mastra supports many embedding models through the [Vercel AI SDK](https://sdk.vercel.ai/docs/ai-sdk-core/embeddings), including options from OpenAI, Google, Mistral, and Cohere.
+> To enable `workingMemory` on an agent, you’ll need a storage provider configured on your main Mastra instance. See [Mastra class](../core/mastra-class.mdx) for more information.
 
-## Parameters
+## Constructor parameters
 
 <PropertiesTable
   content={[
     {
       name: "storage",
       type: "MastraStorage",
-      description: "Storage implementation for persisting memory data",
+      description: "Storage implementation for persisting memory data. Defaults to `new DefaultStorage({ config: { url: \"file:memory.db\" } })` if not provided.",
       isOptional: true,
     },
     {
       name: "vector",
-      type: "MastraVector",
-      description: "Vector store for semantic search capabilities",
+      type: "MastraVector | false",
+      description: "Vector store for semantic search capabilities. Set to `false` to disable vector operations.",
       isOptional: true,
     },
     {
       name: "embedder",
-      type: "EmbeddingModel",
-      description:
-        "Embedder instance for vector embeddings. Required when semantic recall is enabled",
+      type: "EmbeddingModel<string> | EmbeddingModelV2<string>",
+      description: "Embedder instance for vector embeddings. Required when semantic recall is enabled.",
       isOptional: true,
     },
     {
       name: "options",
       type: "MemoryConfig",
-      description: "General memory configuration options",
+      description: "Memory configuration options.",
+      isOptional: true,
+    },
+    {
+      name: "processors",
+      type: "MemoryProcessor[]",
+      description: "Array of memory processors that can filter or transform messages before they're sent to the LLM.",
       isOptional: true,
     },
   ]}
 />
 
-### options
+### Options parameters
 
 <PropertiesTable
   content={[
     {
       name: "lastMessages",
       type: "number | false",
-      description:
-        "Number of most recent messages to retrieve. Set to false to disable.",
+      description: "Number of most recent messages to retrieve. Set to false to disable.",
       isOptional: true,
       defaultValue: "10",
     },
     {
       name: "semanticRecall",
-      type: "boolean | SemanticRecallConfig",
-      description:
-        "Enable semantic search in message history. Automatically enabled when vector store is provided.",
+      type: "boolean | { topK: number; messageRange: number | { before: number; after: number }; scope?: 'thread' | 'resource' }",
+      description: "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.",
       isOptional: true,
       defaultValue: "false",
     },
-    {
-      name: "topK",
-      type: "number",
-      description:
-        "Number of similar messages to retrieve when using semantic search",
-      isOptional: true,
-      defaultValue: "2",
-    },
-    {
-      name: "messageRange",
-      type: "number | { before: number; after: number }",
-      description:
-        "Range of messages to include around semantic search results",
-      isOptional: true,
-      defaultValue: "2",
-    },
-    {
-      name: "scope",
-      type: "'thread' | 'resource'",
-      description:
-        "Scope for semantic search. 'thread' searches within the current thread only (default). 'resource' searches across all threads for a given resourceId, allowing agents to recall information from any of the user's past conversations. The 'resource' scope is currently supported by LibSQL, Postgres, and Upstash storage adapters.",
-      isOptional: true,
-      defaultValue: "'thread'",
-    },
     {
       name: "workingMemory",
-      type: "{ enabled: boolean; template?: string }",
-      description:
-        "Configuration for working memory feature that allows persistent storage of user information across conversations. Working memory uses Markdown format to structure and store continuously relevant information.",
+      type: "WorkingMemory",
+      description: "Configuration for working memory feature. Can be `{ enabled: boolean; template?: string; schema?: ZodObject<any> | JSONSchema7; scope?: 'thread' | 'resource' }` or `{ enabled: boolean }` to disable.",
       isOptional: true,
-      defaultValue:
-        "{ enabled: false, template: '# User Information\\n- **First Name**:\\n- **Last Name**:\\n...' }",
+      defaultValue: "{ enabled: false, template: '# User Information\\n- **First Name**:\\n- **Last Name**:\\n...' }",
     },
     {
       name: "threads",
-      type: "{ generateTitle?: boolean | { model: MastraLanguageModel | ((ctx: RuntimeContext) => MastraLanguageModel | Promise<MastraLanguageModel>), instructions?: string | ((ctx: RuntimeContext) => string | Promise<string>) } }",
-      description:
-        "Settings related to memory thread creation. `generateTitle` controls automatic thread title generation from the user's first message. Can be a boolean to enable/disable using the agent's model, or an object specifying a custom model or custom instructions for title generation (useful for cost optimization or title customization). Example: { generateTitle: { model: openai('gpt-4.1-nano'), instructions: 'Concise title based on the initial user message.' } }",
+      type: "{ generateTitle?: boolean | { model: DynamicArgument<MastraLanguageModel>; instructions?: DynamicArgument<string> } }",
+      description: "Settings related to memory thread creation. `generateTitle` controls automatic thread title generation from the user's first message. Can be a boolean or an object with custom model and instructions.",
       isOptional: true,
       defaultValue: "{ generateTitle: false }",
     },
   ]}
 />
 
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "memory",
+      type: "Memory",
+      description: "A new Memory instance with the specified configuration.",
+    },
+  ]}
+/>
+
+
+## Extended usage example
+
+```typescript filename="src/mastra/agents/test-agent.ts" showLineNumbers copy
+import { Memory } from "@mastra/memory";
+import { Agent } from "@mastra/core/agent";
+import { openai } from "@ai-sdk/openai";
+import { LibSQLStore, LibSQLVector } from "@mastra/libsql";
+
+export const agent = new Agent({
+  name: "test-agent",
+  instructions: "You are an agent with memory.",
+  model: openai("gpt-4o"),
+  memory: new Memory({
+    storage: new LibSQLStore({
+      url: "file:./working-memory.db"
+    }),
+    vector: new LibSQLVector({
+      connectionUrl: "file:./vector-memory.db"
+    }),
+    options: {
+      lastMessages: 10,
+      semanticRecall: {
+        topK: 3,
+        messageRange: 2,
+        scope: 'resource'
+      },
+      workingMemory: {
+        enabled: true
+      },
+      threads: {
+        generateTitle: true
+      }
+    }
+  })
+});
+```
+
 ### Related
 
 - [Getting Started with Memory](/docs/memory/overview.mdx)

package/.docs/raw/reference/memory/createThread.mdx

@@ -1,23 +1,16 @@
-# createThread
+---
+title: "Reference: Memory.createThread() | Memory | Mastra Docs"
+description: "Documentation for the `Memory.createThread()` method in Mastra, which creates a new conversation thread in the memory system."
+---
 
-Creates a new conversation thread in the memory system. Each thread represents a distinct conversation or context and can contain multiple messages.
+# Memory.createThread()
 
-## Usage Example
+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.
 
-```typescript
-import { Memory } from "@mastra/memory";
+## Usage Example
 
-const memory = new Memory({
-  /* config */
-});
-const thread = await memory.createThread({
-  resourceId: "user-123",
-  title: "Support Conversation",
-  metadata: {
-    category: "support",
-    priority: "high",
-  },
-});
+```typescript copy
+await memory?.createThread({ resourceId: "user-123" });
 ```
 
 ## Parameters
@@ -90,6 +83,33 @@ const thread = await memory.createThread({
   ]}
 />
 
+## Extended usage example
+
+```typescript filename="src/test-memory.ts" showLineNumbers copy
+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](/reference/memory/Memory.mdx)

package/.docs/raw/reference/memory/deleteMessages.mdx

@@ -1,95 +1,60 @@
 ---
-section: Memory
-title: deleteMessages
-slug: reference/memory/deleteMessages
-categorySlug: reference
-layout: guide
+title: "Reference: Memory.deleteMessages() | Memory | Mastra Docs"
+description: "Documentation for the `Memory.deleteMessages()` method in Mastra, which deletes multiple messages by their IDs."
 ---
 
-# `deleteMessages`
+# Memory.deleteMessages()
 
-Deletes one or more messages from the memory storage. This method accepts arrays to delete multiple messages in a single operation.
+The `.deleteMessages()` method deletes multiple messages by their IDs.
 
-## Syntax
+## Usage Example
 
-```typescript
-memory.deleteMessages(input: MessageDeleteInput): Promise<void>
-
-type MessageDeleteInput = 
-  | string[]                  // Array of message IDs
-  | { id: string }[]         // Array of message objects
+```typescript copy
+await memory?.deleteMessages(["671ae63f-3a91-4082-a907-fe7de78e10ec"]);
 ```
 
 ## Parameters
 
-- `input` (required): An array of messages to delete. Must be either:
-  - An array of message IDs (strings)
-  - An array of message objects with `id` properties
+<PropertiesTable
+  content={[
+    {
+      name: "messageIds",
+      type: "string[]",
+      description: "Array of message IDs to delete",
+      isOptional: false,
+    },
+  ]}
+/>
 
 ## Returns
 
-A Promise that resolves when all messages have been successfully deleted.
-
-## Examples
+<PropertiesTable
+  content={[
+    {
+      name: "void",
+      type: "Promise<void>",
+      description: "A promise that resolves when all messages are deleted",
+    },
+  ]}
+/>
 
-### Delete a single message
+## Extended usage example
 
-```typescript
-// Using an array with a single string ID
-await memory.deleteMessages(['msg-123']);
-
-// Using an array with a single message object
-await memory.deleteMessages([{ id: 'msg-123' }]);
-```
+```typescript filename="src/test-memory.ts" showLineNumbers copy
+import { mastra } from "./mastra";
+import { UIMessageWithMetadata } from "@mastra/core/agent";
 
-### Delete multiple messages
-
-```typescript
-// Using an array of string IDs
-await memory.deleteMessages(['msg-1', 'msg-2', 'msg-3']);
-
-// Using an array of message objects
-await memory.deleteMessages([
-  { id: 'msg-1' },
-  { id: 'msg-2' },
-  { id: 'msg-3' }
-]);
-```
-
-### Using with client SDK
-
-```typescript
-// Get a thread instance
-const thread = client.getAgent('my-agent').getThread('thread-123');
-
-// Delete a single message
-await thread.deleteMessages(['msg-123']);
-
-// Delete multiple messages
-await thread.deleteMessages(['msg-1', 'msg-2', 'msg-3']);
-
-// Delete using message objects (useful when you have message data)
-const messagesToDelete = messages.map(msg => ({ id: msg.id }));
-await thread.deleteMessages(messagesToDelete);
-```
+const agent = mastra.getAgent("agent");
+const memory = await agent.getMemory();
 
-### Error handling
+const { uiMessages } = await memory!.query({ threadId: "thread-123" });
 
-```typescript
-try {
-  await memory.deleteMessages(['msg-1', 'msg-2', 'msg-3']);
-  console.log('Messages deleted successfully');
-} catch (error) {
-  console.error('Failed to delete messages:', error);
-}
+const messageIds = uiMessages.map((message: UIMessageWithMetadata) => message.id);
+await memory?.deleteMessages([...messageIds]);
 ```
 
-## Notes
+## Related
 
-- This method requires an array as input, even when deleting a single message
-- Thread timestamps are automatically updated when messages are deleted
-- The method automatically extracts message IDs from message objects
-- All message IDs must be non-empty strings
-- An empty array will result in no operation (no error thrown)
-- Messages from different threads can be deleted in the same operation
-- When using message objects, only the `id` property is required
+- [Memory Class Reference](/reference/memory/Memory.mdx)
+- [query](/reference/memory/query.mdx)
+- [Getting Started with Memory](/docs/memory/overview.mdx)

package/.docs/raw/reference/memory/getThreadById.mdx

@@ -1,15 +1,16 @@
-# getThreadById Reference
+---
+title: "Reference: Memory.getThreadById() | Memory | Mastra Docs"
+description: "Documentation for the `Memory.getThreadById()` method in Mastra, which retrieves a specific thread by its ID."
+---
 
-The `getThreadById` function retrieves a specific thread by its ID from storage.
+# Memory.getThreadById()
+
+The `.getThreadById()` method retrieves a specific thread by its ID.
 
 ## Usage Example
 
 ```typescript
-import { Memory } from "@mastra/core/memory";
-
-const memory = new Memory(config);
-
-const thread = await memory.getThreadById({ threadId: "thread-123" });
+await memory?.getThreadById({ threadId: "thread-123" });
 ```
 
 ## Parameters
@@ -30,10 +31,9 @@ const thread = await memory.getThreadById({ threadId: "thread-123" });
 <PropertiesTable
   content={[
     {
-      name: "StorageThreadType | null",
-      type: "Promise",
-      description:
-        "A promise that resolves to the thread associated with the given ID, or null if not found.",
+      name: "thread",
+      type: "Promise<StorageThreadType | null>",
+      description: "A promise that resolves to the thread associated with the given ID, or null if not found.",
     },
   ]}
 />