@mastra/mcp-docs-server 0.13.24-alpha.0 → 0.13.24-alpha.3

package/.docs/raw/memory/overview.mdx

@@ -3,54 +3,25 @@ title: "Memory Overview | Memory | Mastra Docs"
 description: "Learn how Mastra's memory system works with working memory, conversation history, and semantic recall."
 ---
 
-import { Steps, Callout } from "nextra/components";
+import { Steps } from "nextra/components";
 
 # Memory overview
 
-Memory in Mastra helps agents manage context across conversations by condensing relevant information into the language model’s context window.
+Memory in Mastra helps agents manage context across conversations by condensing relevant information into the language model's context window.
 
-Mastra supports three complementary memory systems: [working memory](./working-memory.mdx), [conversation history](#conversation-history), and [semantic recall](./semantic-recall.mdx). Together, they allow agents to track preferences, maintain conversational flow, and retrieve relevant historical messages.
+Mastra supports three types of memory: working memory, conversation history, and semantic recall. It uses a two-tier scoping system where memory can be isolated per conversation thread (thread-scoped) or shared across all conversations for the same user (resource-scoped).
 
-To persist and recall information between conversations, memory requires a storage adapter.
-
-Supported options include:
-
-- [Memory with LibSQL](/examples/memory/memory-with-libsql)
-- [Memory with Postgres](/examples/memory/memory-with-pg)
-- [Memory with Upstash](/examples/memory/memory-with-upstash)
-
-## Types of memory
-
-All memory types are [thread-scoped](./working-memory.mdx#thread-scoped-memory-default) by default, meaning they apply only to a single conversation. [Resource-scoped](./working-memory.mdx#resource-scoped-memory) configuration allows working memory and semantic recall to persist across all threads that use the same user or entity.
-
-
-### Working memory
-
-Stores persistent user-specific details such as names, preferences, goals, and other structured data. Uses [Markdown templates](./working-memory.mdx) or [Zod schemas](./working-memory.mdx#structured-working-memory) to define structure.
-
-### Conversation history
-
-Captures recent messages from the current conversation, providing short-term continuity and maintaining dialogue flow.
-
-### Semantic recall
-
-Retrieves older messages from past conversations based on semantic relevance. Matches are retrieved using vector search and can include surrounding context for better comprehension.
-
-## How memory works together
-
-Mastra combines all memory types into a single context window. If the total exceeds the model’s token limit, use [memory processors](./memory-processors.mdx) to trim or filter messages before sending them to the model.
+Mastra's memory system uses [storage providers](#memory-storage-adapters) to persist conversation threads, messages, and working memory across application restarts.
 
 ## Getting started
 
-To use memory, install the required dependencies:
+First install the required dependencies:
 
 ```bash copy
 npm install @mastra/core @mastra/memory @mastra/libsql
 ```
 
-### Shared storage
-
-To share memory across agents, add a storage adapter to the main Mastra instance. Any agent with memory enabled will use this shared storage to store and recall interactions.
+Then add a storage adapter to the main Mastra instance. Any agent with memory enabled will use this shared storage to store and recall interactions.
 
 ```typescript {6-8} filename="src/mastra/index.ts" showLineNumbers copy
 import { Mastra } from "@mastra/core/mastra";
@@ -64,150 +35,65 @@ export const mastra = new Mastra({
 });
 ```
 
-### Adding working memory to agents
-
-Enable working memory by passing a `Memory` instance to the agent's `memory` parameter and setting `workingMemory.enabled` to `true`:
-
-```typescript {1,6-12} filename="src/mastra/agents/test-agent.ts" showLineNumbers copy
-import { Memory } from "@mastra/memory";
-import { Agent } from "@mastra/core/agent";
-
-export const testAgent = new Agent({
-  // ..
-  memory: new Memory({
-    options: {
-      workingMemory: {
-        enabled: true
-      }
-    }
-  })
-})
-```
-
-## Dedicated storage
-
-Agents can be configured with their own dedicated storage, keeping tasks, conversations, and recalled information separate across agents.
-
-### Adding storage to agents
+Now, enable memory by passing a `Memory` instance to the agent's `memory` parameter:
 
-To assign dedicated storage to an agent, install and import the required dependency and pass a `storage` instance to the `Memory` constructor:
-
-```typescript {3, 9-11} filename="src/mastra/agents/test-agent.ts" showLineNumbers copy
+```typescript {3-5} filename="src/mastra/agents/test-agent.ts" showLineNumbers copy
 import { Memory } from "@mastra/memory";
 import { Agent } from "@mastra/core/agent";
-import { LibSQLStore } from "@mastra/libsql";
 
 export const testAgent = new Agent({
   // ...
-  memory: new Memory({
-    // ...
-    storage: new LibSQLStore({
-      url: "file:agent-memory.db"
-    })
-  // ...
-  })
+  memory: new Memory()
 });
 ```
 
-## Memory threads
+That memory instance has options you can configure for working memory, conversation history, and semantic recall.
 
-Mastra organizes memory into threads, which are records that group related interactions, using two identifiers:
+## Different types of memory
 
-1. **`thread`**: A globally unique ID representing the conversation (e.g., `support_123`). Must be unique across all resources.
-2. **`resource`**: The user or entity that owns the thread (e.g., `user_123`, `org_456`).
+Mastra supports three types of memory: working memory, conversation history, and semantic recall. 
 
-The `resource` is especially important for [resource-scoped memory](./working-memory.mdx#resource-scoped-memory), which allows memory to persist across all threads associated with the same user or entity.
-
-```typescript {4} showLineNumbers
-const stream = await agent.stream("message for agent", {
-  memory: {
-    thread: "user-123",
-    resource: "test-123"
-  }
-});
-```
+[**Working memory**](./working-memory.mdx) stores persistent user-specific details such as names, preferences, goals, and other structured data. (Compare this to ChatGPT where you can ask it to tell you about yourself). This is implemented as a block of Markdown text that the agent is able to update over time (or alternately, as a Zod schema)
 
-<Callout type="warning">
-Even with memory configured, agents won’t store or recall information unless both `thread` and `resource` are provided.
-</Callout>
+[**Conversation history**](./conversation-history.mdx) captures recent messages from the current conversation, providing short-term continuity and maintaining dialogue flow.
 
-> Mastra Playground sets `thread` and `resource` IDs automatically. In your own application, you must provide them manually as part of each `.generate()` or `.stream()` call.
+[**Semantic recall**](./semantic-recall.mdx) retrieves older messages from past conversations based on semantic relevance. Matches are retrieved using vector search and can include surrounding context for better comprehension.
 
-### Thread title generation
+Mastra combines all memory types into a single context window. If the total exceeds the model’s token limit, use [memory processors](./memory-processors.mdx) to trim or filter messages before sending them to the model.
 
-Mastra can automatically generate descriptive thread titles based on the user's first message. Enable this by setting `generateTitle` to `true`. This improves organization and makes it easier to display conversations in your UI.
+## Scoping memory with threads and resources
 
-```typescript {3-7} showLineNumbers
-export const testAgent = new Agent({
-  memory: new Memory({
-    options: {
-      threads: {
-        generateTitle: true,
-      }
-    },
-  })
-});
-```
+All memory types are [thread-scoped](./working-memory.mdx#thread-scoped-memory-default) by default, meaning they apply only to a single conversation. [Resource-scoped](./working-memory.mdx#resource-scoped-memory) configuration allows working memory and semantic recall to persist across all threads that use the same user or entity.
 
-> Title generation runs asynchronously after the agent responds and does not affect response time. See the [full configuration reference](../../reference/memory/Memory.mdx#thread-title-generation) for details and examples.
+## Memory Storage Adapters
 
-#### Optimizing title generation
+To persist and recall information between conversations, memory requires a storage adapter.
 
-Titles are generated using your agent's model by default. To optimize cost or behavior, provide a smaller `model` and custom `instructions`. This keeps title generation separate from main conversation logic.
+Supported options include [LibSQL](/examples/memory/memory-with-libsql), [Postgres](/examples/memory/memory-with-pg), and [Upstash](/examples/memory/memory-with-upstash)
 
-```typescript {5-9} showLineNumbers
-export const testAgent = new Agent({
-  // ...
-  memory: new Memory({
-    options: {
-      threads: {
-        generateTitle: {
-          model: openai("gpt-4.1-nano"),
-          instructions: "Generate a concise title based on the user's first message",
-        },
-      },
-    }
-  })
-});
-```
+We use LibSQL out of the box because it is file-based or in-memory, so it is easy to install and works well with the playground.
 
-#### Dynamic model selection and instructions
+## Dedicated storage
 
-You can configure thread title generation dynamically by passing functions to `model` and `instructions`. These functions receive the `runtimeContext` object, allowing you to adapt title generation based on user-specific values.
+Agents can be configured with their own dedicated storage, keeping tasks, conversations, and recalled information separate across agents.
 
-```typescript {7-16} showLineNumbers
-export const testAgent = new Agent({
-  // ...
-  memory: new Memory({
-    options: {
-      threads: {
-        generateTitle: {
-          model: ({ runtimeContext }) => {
-            const userTier = runtimeContext.get("userTier");
-            return userTier === "premium" ? openai("gpt-4.1") : openai("gpt-4.1-nano");
-          },
-          instructions: ({ runtimeContext }) => {
-            const language = runtimeContext.get("userLanguage") || "English";
-            return `Generate a concise, engaging title in ${language} based on the user's first message.`;
-          }
-        }
-      }
-    }
-  })
-});
-```
+### Adding storage to agents
 
-## Increasing conversation history
+To assign dedicated storage to an agent, install and import the required dependency and pass a `storage` instance to the `Memory` constructor:
 
-By default, each request includes the last 10 messages from the current memory thread, giving the agent short-term conversational context. This limit can be increased using the `lastMessages` parameter.
+```typescript {3, 9-11} filename="src/mastra/agents/test-agent.ts" showLineNumbers copy
+import { Memory } from "@mastra/memory";
+import { Agent } from "@mastra/core/agent";
+import { LibSQLStore } from "@mastra/libsql";
 
-```typescript {3-7} showLineNumbers
 export const testAgent = new Agent({
   // ...
   memory: new Memory({
-    options: {
-      lastMessages: 100
-    },
+    // ...
+    storage: new LibSQLStore({
+      url: "file:agent-memory.db"
+    })
+  // ...
   })
 });
 ```
@@ -226,7 +112,6 @@ For local development with `LibSQLStore`, you can inspect stored memory using th
 
 ![SQLite Viewer](/image/memory/memory-sqlite-viewer.jpg)
 
-
 ## Next Steps
 
 Now that you understand the core concepts, continue to [semantic recall](./semantic-recall.mdx) to learn how to add RAG memory to your Mastra agents.

package/.docs/raw/memory/semantic-recall.mdx

@@ -136,6 +136,42 @@ const agent = new Agent({
 });
 ```
 
+### PostgreSQL Index Optimization
+
+When using PostgreSQL as your vector store, you can optimize semantic recall performance by configuring the vector index. This is particularly important for large-scale deployments with thousands of messages.
+
+PostgreSQL supports both IVFFlat and HNSW indexes. By default, Mastra creates an IVFFlat index, but HNSW indexes typically provide better performance, especially with OpenAI embeddings which use inner product distance.
+
+```typescript {9-18}
+import { Memory } from "@mastra/memory";
+import { PgStore, PgVector } from "@mastra/pg";
+
+const agent = new Agent({
+  memory: new Memory({
+    storage: new PgStore({
+      connectionString: process.env.DATABASE_URL,
+    }),
+    vector: new PgVector({
+      connectionString: process.env.DATABASE_URL,
+    }),
+    options: {
+      semanticRecall: {
+        topK: 5,
+        messageRange: 2,
+        indexConfig: {
+          type: 'hnsw',           // Use HNSW for better performance
+          metric: 'dotproduct',   // Best for OpenAI embeddings  
+          m: 16,                  // Number of bi-directional links (default: 16)
+          efConstruction: 64,    // Size of candidate list during construction (default: 64)
+        },
+      },
+    },
+  }),
+});
+```
+
+For detailed information about index configuration options and performance tuning, see the [PgVector configuration guide](/reference/rag/pg#index-configuration-guide).
+
 ### Disabling
 
 There is a performance impact to using semantic recall. New messages are converted into embeddings and used to query a vector database before new messages are sent to the LLM.

package/.docs/raw/memory/threads-and-resources.mdx

@@ -0,0 +1,94 @@
+---
+title: "Memory Threads and Resources | Memory | Mastra Docs"
+description: "Learn how Mastra's memory system works with working memory, conversation history, and semantic recall."
+---
+
+import { Callout } from "nextra/components";
+
+# Memory threads and resources
+
+Mastra organizes memory into threads, which are records that group related interactions, using two identifiers:
+
+1. **`thread`**: A globally unique ID representing the conversation (e.g., `support_123`). Must be unique across all resources.
+2. **`resource`**: The user or entity that owns the thread (e.g., `user_123`, `org_456`).
+
+The `resource` is especially important for [resource-scoped memory](./working-memory.mdx#resource-scoped-memory), which allows memory to persist across all threads associated with the same user or entity.
+
+```typescript {4} showLineNumbers
+const stream = await agent.stream("message for agent", {
+  memory: {
+    thread: "user-123",
+    resource: "test-123"
+  }
+});
+```
+
+<Callout type="warning">
+Even with memory configured, agents won’t store or recall information unless both `thread` and `resource` are provided.
+</Callout>
+
+> Mastra Playground sets `thread` and `resource` IDs automatically. In your own application, you must provide them manually as part of each `.generate()` or `.stream()` call.
+
+### Thread title generation
+
+Mastra can automatically generate descriptive thread titles based on the user's first message. Enable this by setting `generateTitle` to `true`. This improves organization and makes it easier to display conversations in your UI.
+
+```typescript {3-7} showLineNumbers
+export const testAgent = new Agent({
+  memory: new Memory({
+    options: {
+      threads: {
+        generateTitle: true,
+      }
+    },
+  })
+});
+```
+
+> Title generation runs asynchronously after the agent responds and does not affect response time. See the [full configuration reference](../../reference/memory/Memory.mdx#thread-title-generation) for details and examples.
+
+#### Optimizing title generation
+
+Titles are generated using your agent's model by default. To optimize cost or behavior, provide a smaller `model` and custom `instructions`. This keeps title generation separate from main conversation logic.
+
+```typescript {5-9} showLineNumbers
+export const testAgent = new Agent({
+  // ...
+  memory: new Memory({
+    options: {
+      threads: {
+        generateTitle: {
+          model: openai("gpt-4.1-nano"),
+          instructions: "Generate a concise title based on the user's first message",
+        },
+      },
+    }
+  })
+});
+```
+
+#### Dynamic model selection and instructions
+
+You can configure thread title generation dynamically by passing functions to `model` and `instructions`. These functions receive the `runtimeContext` object, allowing you to adapt title generation based on user-specific values.
+
+```typescript {7-16} showLineNumbers
+export const testAgent = new Agent({
+  // ...
+  memory: new Memory({
+    options: {
+      threads: {
+        generateTitle: {
+          model: ({ runtimeContext }) => {
+            const userTier = runtimeContext.get("userTier");
+            return userTier === "premium" ? openai("gpt-4.1") : openai("gpt-4.1-nano");
+          },
+          instructions: ({ runtimeContext }) => {
+            const language = runtimeContext.get("userLanguage") || "English";
+            return `Generate a concise, engaging title in ${language} based on the user's first message.`;
+          }
+        }
+      }
+    }
+  })
+});
+```

package/.docs/raw/reference/agents/agent.mdx

@@ -7,19 +7,94 @@ description: "Documentation for the `Agent` class in Mastra, which provides the
 
 The `Agent` class is the foundation for creating AI agents in Mastra. It provides methods for generating responses, streaming interactions, and handling voice capabilities.
 
-## Usage example
+## Usage examples
 
-```typescript filename="src/mastra/agents/test-agent.ts" showLineNumbers copy
+### Basic string instructions
+
+```typescript filename="src/mastra/agents/string-agent.ts" showLineNumbers copy
 import { openai } from "@ai-sdk/openai";
 import { Agent } from "@mastra/core/agent";
 
+// String instructions
 export const agent = new Agent({
   name: "test-agent",
-  instructions: 'message for agent',
+  instructions: 'You are a helpful assistant that provides concise answers.',
+  model: openai("gpt-4o")
+});
+
+// System message object
+export const agent2 = new Agent({
+  name: "test-agent-2",
+  instructions: { 
+    role: "system", 
+    content: "You are an expert programmer" 
+  },
+  model: openai("gpt-4o")
+});
+
+// Array of system messages
+export const agent3 = new Agent({
+  name: "test-agent-3",
+  instructions: [
+    { role: "system", content: "You are a helpful assistant" },
+    { role: "system", content: "You have expertise in TypeScript" }
+  ],
   model: openai("gpt-4o")
 });
 ```
 
+### Single CoreSystemMessage
+
+Use CoreSystemMessage format to access additional properties like `providerOptions` for provider-specific configurations:
+
+```typescript filename="src/mastra/agents/core-message-agent.ts" showLineNumbers copy
+import { openai } from "@ai-sdk/openai";
+import { Agent } from "@mastra/core/agent";
+
+export const agent = new Agent({
+  name: "core-message-agent",
+  instructions: {
+    role: 'system',
+    content: 'You are a helpful assistant specialized in technical documentation.',
+    providerOptions: {
+      openai: { 
+        reasoningEffort: 'low'
+      }
+    }
+  },
+  model: openai("gpt-5")
+});
+```
+
+### Multiple CoreSystemMessages
+
+```typescript filename="src/mastra/agents/multi-message-agent.ts" showLineNumbers copy
+import { anthropic } from "@ai-sdk/anthropic";
+import { Agent } from "@mastra/core/agent";
+
+// This could be customizable based on the user
+const preferredTone = { 
+  role: 'system', 
+  content: 'Always maintain a professional and empathetic tone.',
+};
+
+export const agent = new Agent({
+  name: "multi-message-agent",
+  instructions: [
+    { role: 'system', content: 'You are a customer service representative.' },
+    preferredTone,
+    { 
+      role: 'system', 
+      content: 'Escalate complex issues to human agents when needed.',
+      providerOptions: {
+        anthropic: { cacheControl: { type: 'ephemeral' } },
+      },
+    },
+  ],
+  model: anthropic('claude-sonnet-4-20250514'),
+});
+```
+
 ## Constructor parameters
 
 <PropertiesTable
@@ -44,9 +119,11 @@ export const agent = new Agent({
     },
     {
       name: "instructions",
-      type: "string | ({ runtimeContext: RuntimeContext }) => string | Promise<string>",
+      type: "SystemMessage | ({ runtimeContext: RuntimeContext }) => SystemMessage | Promise<SystemMessage>",
       isOptional: false,
-      description: "Instructions that guide the agent's behavior. Can be a static string or a function that returns a string dynamically.",
+      description: `Instructions that guide the agent's behavior. Can be a string, array of strings, system message object, 
+        array of system messages, or a function that returns any of these types dynamically. 
+        SystemMessage types: string | string[] | CoreSystemMessage | CoreSystemMessage[] | SystemModelMessage | SystemModelMessage[]`,
     },
     {
       name: "model",

package/.docs/raw/reference/agents/getInstructions.mdx

@@ -33,8 +33,8 @@ await agent.getInstructions();
   content={[
     {
       name: "instructions",
-      type: "string | Promise<string>",
-      description: "The instructions configured for the agent, either as a direct string or a promise that resolves to the instructions.",
+      type: "SystemMessage | Promise<SystemMessage>",
+      description: "The instructions configured for the agent. SystemMessage can be: string | string[] | CoreSystemMessage | CoreSystemMessage[] | SystemModelMessage | SystemModelMessage[]. Returns either directly or as a promise that resolves to the instructions.",
     },
   ]}
 />

package/.docs/raw/reference/auth/auth0.mdx

@@ -0,0 +1,117 @@
+---
+title: "MastraAuthAuth0 Class"
+description: "API reference for the MastraAuthAuth0 class, which authenticates Mastra applications using Auth0 authentication."
+---
+
+# MastraAuthAuth0 Class
+
+The `MastraAuthAuth0` class provides authentication for Mastra using Auth0. It verifies incoming requests using Auth0-issued JWT tokens and integrates with the Mastra server using the `experimental_auth` option.
+
+## Usage example
+
+```typescript filename="src/mastra/index.ts" showLineNumbers copy
+import { Mastra } from "@mastra/core/mastra";
+import { MastraAuthAuth0 } from '@mastra/auth-auth0';
+
+export const mastra = new Mastra({
+  // ..
+  server: {
+    experimental_auth: new MastraAuthAuth0({
+      domain: process.env.AUTH0_DOMAIN,
+      audience: process.env.AUTH0_AUDIENCE
+    }),
+  },
+});
+```
+
+> **Note:** You can omit the constructor parameters if you have the appropriately named environment variables (`AUTH0_DOMAIN` and `AUTH0_AUDIENCE`) set. In that case, simply use `new MastraAuthAuth0()` without any arguments.
+
+## Constructor parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "domain",
+      type: "string",
+      description: "Your Auth0 domain (e.g., your-tenant.auth0.com). This is used to verify JWT tokens issued by your Auth0 tenant.",
+      isOptional: true,
+      defaultValue: "process.env.AUTH0_DOMAIN"
+    },
+    {
+      name: "audience",
+      type: "string",
+      description: "Your Auth0 API identifier/audience. This ensures tokens are intended for your specific API.",
+      isOptional: true,
+      defaultValue: "process.env.AUTH0_AUDIENCE"
+    },
+    {
+      name: "name",
+      type: "string",
+      description: "Custom name for the auth provider instance.",
+      isOptional: true,
+      defaultValue: '"auth0"'
+    },
+    {
+      name: "authorizeUser",
+      type: "(user: Auth0User) => Promise<boolean> | boolean",
+      description: "Custom authorization function to determine if a user should be granted access. Called after token verification. By default, allows all authenticated users with valid tokens.",
+      isOptional: true,
+    },
+  ]}
+/>
+
+## Environment Variables
+
+The following environment variables are automatically used when constructor options are not provided:
+
+<PropertiesTable
+  content={[
+    {
+      name: "AUTH0_DOMAIN",
+      type: "string",
+      description: "Your Auth0 domain. Can be found in your Auth0 Dashboard under Applications > Settings.",
+      isOptional: true,
+    },
+    {
+      name: "AUTH0_AUDIENCE",
+      type: "string",
+      description: "Your Auth0 API identifier. This is the identifier you set when creating an API in your Auth0 Dashboard.",
+      isOptional: true,
+    },
+  ]}
+/>
+
+## Default Authorization Behavior
+
+By default, `MastraAuthAuth0` validates Auth0 JWT tokens and allows access to all authenticated users:
+
+1. **Token Verification**: The JWT token is verified using Auth0's public keys (JWKS)
+2. **Signature Validation**: Ensures the token was signed by your Auth0 tenant
+3. **Expiration Check**: Verifies the token has not expired
+4. **Audience Validation**: Confirms the token was issued for your specific API (audience)
+5. **Issuer Validation**: Ensures the token was issued by your Auth0 domain
+
+If all validations pass, the user is considered authorized. To implement custom authorization logic (e.g., role-based access control), provide a custom `authorizeUser` function.
+
+## Auth0 User Type
+
+The `Auth0User` type used in the `authorizeUser` function corresponds to the decoded JWT token payload, which typically includes:
+
+- `sub`: The user's unique identifier (subject)
+- `email`: The user's email address (if included in token)
+- `email_verified`: Whether the email is verified
+- `name`: The user's display name (if available)
+- `picture`: URL to the user's profile picture (if available)
+- `iss`: Token issuer (your Auth0 domain)
+- `aud`: Token audience (your API identifier)
+- `iat`: Token issued at timestamp
+- `exp`: Token expiration timestamp
+- `scope`: Granted scopes for the token
+- Custom claims and app metadata configured in your Auth0 tenant
+
+The exact properties available depend on your Auth0 configuration, scopes requested, and any custom claims you've configured.
+
+## Related
+
+[MastraAuthAuth0 Class](/docs/auth/auth0.mdx)
+