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

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

@@ -1,170 +1,218 @@
-import { Steps } from "nextra/components";
+---
+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";
 
 # Memory overview
 
-Memory is how agents manage the context that's available to them, it's a condensation of all chat messages into their 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.
+
+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
 
-## The Context Window
+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.
 
-The context window is the total information visible to the language model at any given time.
 
-In Mastra, context is broken up into three parts: system instructions and information about the user ([working memory](./working-memory.mdx)), recent messages ([message history](#conversation-history)), and older messages that are relevant to the user’s query ([semantic recall](./semantic-recall.mdx)).
+### Working memory
 
-Working memory can persist at different scopes - either per conversation thread (default) or across all threads for the same user (resource-scoped), enabling persistent user profiles that remember context across conversations.
+Stores persistent user-specific details such as names, preferences, goals, and other structured data. Uses [Markdown templates](./working-memory-template.mdx) or [Zod schemas](./working-memory-schema.mdx) to define structure.
 
-In addition, we provide [memory processors](./memory-processors.mdx) to trim context or remove information if the context is too long.
+### Conversation history
 
-## Quick Start
+Captures recent messages from the current conversation, providing short-term continuity and maintaining dialogue flow.
 
-The fastest way to see memory in action is using the built-in development playground.
+### Semantic recall
 
-If you haven't already, create a new Mastra project following the main [Getting Started guide](/docs/getting-started/installation).
+Retrieves older messages from past conversations based on semantic relevance. Matches are retrieved using vector search and can include surrounding context for better comprehension.
 
-<Steps>
+## How memory works together
 
-### Install the memory package
+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.
 
-```bash npm2yarn copy
-npm install @mastra/memory@latest
+## Getting started
+
+To use memory, install the required dependencies:
+
+```bash copy
+npm install @mastra/core @mastra/memory @mastra/libsql
 ```
 
-### Create an agent and attach a `Memory` instance
+### Shared storage
 
-```typescript filename="src/mastra/agents/index.ts" {6-18}
-import { Agent } from "@mastra/core/agent";
-import { Memory } from "@mastra/memory";
-import { openai } from "@ai-sdk/openai";
+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.
+
+```typescript {6-8} filename="src/mastra/index.ts" showLineNumbers copy
+import { Mastra } from "@mastra/core/mastra";
 import { LibSQLStore } from "@mastra/libsql";
 
-// Initialize memory with LibSQLStore for persistence
-const memory = new Memory({
+export const mastra = new Mastra({
+  // ...
   storage: new LibSQLStore({
-    url: "file:../mastra.db", // Or your database URL
-  }),
-});
-
-export const myMemoryAgent = new Agent({
-  name: "MemoryAgent",
-  instructions: "...",
-  model: openai("gpt-4o"),
-  memory,
+    url: ":memory:"
+  })
 });
 ```
 
-### Start the Development Server
-
-```bash npm2yarn copy
-npm run dev
-```
+### Adding working memory to agents
 
-### Open the playground and select your `MemoryAgent`
+Enable working memory by passing a `Memory` instance to the agent's `memory` parameter and setting `workingMemory.enabled` to `true`:
 
-Open the playground at [http://localhost:4111](http://localhost:4111). Send a few messages and notice that it remembers information across turns:
+```typescript {1,6-12} filename="src/mastra/agents/test-agent.ts" showLineNumbers copy
+import { Memory } from "@mastra/memory";
+import { Agent } from "@mastra/core/agent";
 
-```
-➡️ You: My favorite color is blue.
-⬅️ Agent: Got it! I'll remember that your favorite color is blue.
-➡️ You: What is my favorite color?
-⬅️ Agent: Your favorite color is blue.
+export const testAgent = new Agent({
+  // ..
+  memory: new Memory({
+    options: {
+      workingMemory: {
+        enabled: true
+      }
+    }
+  })
+})
 ```
 
-</Steps>
+## Dedicated storage
 
-## Memory Threads
+Agents can be configured with their own dedicated storage, keeping tasks, conversations, and recalled information separate across agents.
 
-Mastra organizes memory into threads, which are records that identify specific conversation histories, using two identifiers:
+### Adding storage to agents
 
-1.  **`threadId`**: A globally unique conversation id (e.g., `support_123`). Thread IDs must be unique across all resources.
-2.  **`resourceId`**: The user or entity id that owns each thread (e.g., `user_123`, `org_456`).
+To assign dedicated storage to an agent, install and import the required dependency and pass a `storage` instance to the `Memory` constructor:
 
-The `resourceId` is particularly important for [resource-scoped working memory](./working-memory.mdx#resource-scoped-memory), which allows memory to persist across all conversation threads for the same user.
+```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 {2,3}
-const response = await myMemoryAgent.stream("Hello, my name is Alice.", {
-  resourceId: "user_alice",
-  threadId: "conversation_123",
+export const testAgent = new Agent({
+  // ...
+  memory: new Memory({
+    // ...
+    storage: new LibSQLStore({
+      url: "file:agent-memory.db"
+    })
+  // ...
+  })
 });
 ```
 
-**Important:** without these ID's your agent will not use memory, even if memory is properly configured. The playground handles this for you, but you need to add ID's yourself when using memory in your application.
+## Memory threads
 
-> **Thread ID Uniqueness:** Each thread ID must be globally unique across all resources. A thread is permanently associated with the resource that created it. If you need to have similar thread names for different resources (e.g., a "general" thread for multiple users), include the resource ID in the thread ID: `${resourceId}-general` or `user_alice_general`.
+Mastra organizes memory into threads, which are records that group related interactions, using two identifiers:
 
-### Thread Title Generation
+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 can automatically generate meaningful titles for conversation threads based on the user's first message. This helps organize and identify conversations in your application UI.
+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 {3-7}
-const memory = new Memory({
-  options: {
-    threads: {
-      generateTitle: true, // Enable automatic title generation
-    },
-  },
+```typescript {4} showLineNumbers
+const stream = await agent.stream("message for agent", {
+  memory: {
+    thread: "user-123",
+    resource: "test-123"
+  }
 });
 ```
 
-By default, title generation uses the same model and default instructions as your agent. For customization or cost optimization, you can specify a different model or provide custom instructions specifically for title generation:
+<Callout type="warning">
+Even with memory configured, agents won’t store or recall information unless both `thread` and `resource` are provided.
+</Callout>
 
-```typescript {5-7}
-const memory = new Memory({
-  options: {
-    threads: {
-      generateTitle: {
-        model: openai("gpt-4.1-nano"), // Use cheaper model for titles
-        instructions: "Generate a concise title for this conversation based on the first user message.",
-      },
+> 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 happens asynchronously after the agent responds, so it doesn't impact response time. See the [full configuration reference](../../reference/memory/Memory.mdx#thread-title-generation) for more details and examples.
+> 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.
 
-## Conversation History
+#### Optimizing title generation
 
-By default, the `Memory` instance includes the [last 10 messages](../../reference/memory/Memory.mdx) from the current Memory thread in each new request. This provides the agent with immediate conversational context.
+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.
 
-```ts {3}
-const memory = new Memory({
-  options: {
-    lastMessages: 10,
-  },
+```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",
+        },
+      },
+    }
+  })
 });
 ```
 
-**Important:** Only send the newest user message in each agent call. Mastra handles retrieving and injecting the necessary history. Sending the full history yourself will cause duplication. See the [AI SDK Memory Example](../../docs/frameworks/agentic-uis/ai-sdk.mdx) for how to handle this with when using the `useChat` frontend hooks.
+#### Dynamic model selection and instructions
 
-### Storage Configuration
+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.
 
-Conversation history relies on a [storage adapter](/reference/memory/Memory#parameters) to store messages.
-By default it uses the same storage provided to the [main Mastra instance](https://mastra.ai/reference/core/mastra-class#initialization)
+```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.`;
+          }
+        }
+      }
+    }
+  })
+});
+```
 
-If neither the `Memory` instance nor the `Mastra` object specify a storage provider, Mastra will not persist memory data across application restarts or deployments. For any deployment beyond local testing you should provide your own storage configuration either on `Mastra` or directly within `new Memory()`.
+## Increasing conversation history
 
-When `storage` **is** given on the `Mastra` instance it will automatically be used by every `Memory` attached to agents. In that case you do not need to pass `storage` to `new Memory()` unless you want a per-agent override.
+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.
 
-```ts {7-9}
-import { Memory } from "@mastra/memory";
-import { Agent } from "@mastra/core/agent";
-import { LibSQLStore } from "@mastra/libsql";
-
-const agent = new Agent({
+```typescript {3-7} showLineNumbers
+export const testAgent = new Agent({
+  // ...
   memory: new Memory({
-    storage: new LibSQLStore({
-      url: "file:./local.db",
-    }),
-  }),
+    options: {
+      lastMessages: 100
+    },
+  })
 });
 ```
 
-**Storage code Examples**:
-
-- [LibSQL](/examples/memory/memory-with-libsql)
-- [Postgres](/examples/memory/memory-with-pg)
-- [Upstash](/examples/memory/memory-with-upstash)
-
-## Viewing Retrieved Messages
+## Viewing retrieved messages
 
 If tracing is enabled in your Mastra deployment and memory is configured either with `lastMessages` and/or `semanticRecall`, the agent’s trace output will show all messages retrieved for context—including both recent conversation history and messages recalled via semantic recall.
 
@@ -172,6 +220,13 @@ This is helpful for debugging, understanding agent decisions, and verifying that
 
 For more details on enabling and configuring tracing, see [Tracing](../observability/tracing).
 
+## Local development with LibSQL
+
+For local development with `LibSQLStore`, you can inspect stored memory using the [SQLite Viewer](https://marketplace.visualstudio.com/items?itemName=qwtel.sqlite-viewer) extension in VS Code.
+
+![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

@@ -1,3 +1,8 @@
+---
+title: "Semantic Recall | Memory | Mastra Docs"
+description: "Learn how to use semantic recall in Mastra to retrieve relevant messages from past conversations using vector search and embeddings."
+---
+
 # Semantic Recall
 
 If you ask your friend what they did last weekend, they will search in their memory for events associated with "last weekend" and then tell you what they did. That's sort of like how semantic recall works in Mastra.

package/.docs/raw/memory/working-memory.mdx

@@ -1,3 +1,8 @@
+---
+title: "Working Memory | Memory | Mastra Docs"
+description: "Learn how to configure working memory in Mastra to store persistent user data, preferences."
+---
+
 import YouTube from "@/components/youtube";
 
 # Working Memory

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

@@ -54,6 +54,12 @@ export const agent = new Agent({
       isOptional: false,
       description: "The language model used by the agent. Can be provided statically or resolved at runtime.",
     },
+    {
+      name: "agents",
+      type: "Record<string, Agent> | ({ runtimeContext: RuntimeContext }) => Record<string, Agent> | Promise<Record<string, Agent>>",
+      isOptional: true,
+      description: "Sub-Agents that the agent can access. Can be provided statically or resolved dynamically.",
+    },
     {
       name: "tools",
       type: "ToolsInput | ({ runtimeContext: RuntimeContext }) => ToolsInput | Promise<ToolsInput>",

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

@@ -224,7 +224,8 @@ const aiSdkResult = await agent.generateVNext("message for agent", {
       name: "output",
       type: "Zod schema | JsonSchema7",
       isOptional: true,
-      description: "Schema for structured output generation (Zod schema or JSON Schema).",
+      description: 
+        "**Deprecated.** Use structuredOutput with maxSteps:1 to achieve the same thing. Defines the expected structure of the output. Can be a JSON Schema object or a Zod schema.",
     },
     {
       name: "memory",

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

@@ -0,0 +1,68 @@
+---
+title: "Reference: Agent.listAgents() | Agents | Mastra Docs"
+description: "Documentation for the `Agent.listAgents()` method in Mastra agents, which retrieves the sub-agents that the agent can access."
+---
+
+# Agent.listAgents()
+
+The `.listAgents()` method retrieves the sub-agents configured for an agent, resolving them if they're a function. These sub-agents enable the agent to access other agents and perform complex actions.
+
+## Usage example
+
+```typescript copy
+await agent.listAgents();
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "options",
+      type: "{ runtimeContext?: RuntimeContext }",
+      isOptional: true,
+      defaultValue: "{}",
+      description: "Optional configuration object containing runtime context.",
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "agents",
+      type: "Promise<Record<string, Agent>>",
+      description: "A promise that resolves to a record of agent names to their corresponding Agent instances.",
+    },
+  ]}
+/>
+
+## Extended usage example
+
+```typescript copy
+import { RuntimeContext } from "@mastra/core/runtime-context";
+
+await agent.listAgents({
+  runtimeContext: new RuntimeContext()
+});
+```
+
+### Options parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "runtimeContext",
+      type: "RuntimeContext",
+      isOptional: true,
+      defaultValue: "new RuntimeContext()",
+      description: "Runtime context for dependency injection and contextual information.",
+    },
+  ]}
+/>
+
+## Related
+
+- [Agents overview](../../docs/agents/overview.mdx)

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

@@ -226,7 +226,7 @@ const aiSdkStream = await agent.streamVNext("message for agent", {
       type: "Zod schema | JsonSchema7",
       isOptional: true,
       description:
-        "Defines the expected structure of the output. Can be a JSON Schema object or a Zod schema.",
+        "**Deprecated.** Use structuredOutput with maxSteps:1 to achieve the same thing. Defines the expected structure of the output. Can be a JSON Schema object or a Zod schema.",
     },
     {
       name: "memory",

package/.docs/raw/reference/client-js/agents.mdx

@@ -2,6 +2,7 @@
 title: Mastra Client Agents API
 description: Learn how to interact with Mastra AI agents, including generating responses, streaming interactions, and managing agent tools using the client-js SDK.
 ---
+import { StreamVNextCallout } from "@/components/streamVNext-callout.tsx"
 
 # Agents API
 
@@ -105,7 +106,7 @@ Client-side tools allow you to execute custom functions on the client side when
 #### Basic Usage
 
 ```typescript
-import { createTool } from '@mastra/core/tools';
+import { createTool } from '@mastra/client-js';
 import { z } from 'zod';
 
 const colorChangeTool = createTool({
@@ -158,3 +159,55 @@ const evals = await agent.evals();
 // Get live evaluations
 const liveEvals = await agent.liveEvals();
 ```
+
+
+### Stream VNext (Experimental)
+
+<StreamVNextCallout />
+
+Stream responses using the enhanced VNext API with improved method signatures. This method provides enhanced capabilities and format flexibility, with support for both Mastra's native format and AI SDK v5 compatibility:
+
+```typescript
+const response = await agent.streamVNext(
+  "Tell me a story",
+  {
+    format: 'mastra', // Default: Mastra's native format
+    threadId: "thread-1",
+    clientTools: { colorChangeTool },
+  }
+);
+
+// AI SDK v5 compatible format
+const response = await agent.streamVNext(
+  "Tell me a story",
+  {
+    format: 'aisdk', // Enable AI SDK v5 compatibility
+    threadId: "thread-1",
+  }
+);
+
+// Process the stream
+response.processDataStream({
+  onChunk: (chunk) => {
+    console.log(chunk);
+  },
+});
+```
+
+The `format` parameter determines the output stream format:
+- `'mastra'` (default): Returns Mastra's native format
+- `'aisdk'`: Returns AI SDK v5 compatible format for frontend integration
+
+### Generate VNext (Experimental)
+
+Generate a response using the enhanced VNext API with improved method signatures and AI SDK v5 compatibility:
+
+```typescript
+const response = await agent.generateVNext(
+  "Hello, how are you?",
+  {
+    threadId: "thread-1",
+    resourceid: "resource-1",
+  }
+);
+```

package/.docs/raw/reference/client-js/workflows.mdx

@@ -44,10 +44,9 @@ const details = await workflow.details();
 Start a workflow run with inputData and await full run results:
 
 ```typescript
-const run = await workflow.createRun();
+const run = await workflow.createRunAsync();
 
-const result = await workflow.startAsync({
-  runId: run.runId,
+const result = await run.startAsync({
   inputData: {
     city: "New York",
   },
@@ -59,10 +58,9 @@ const result = await workflow.startAsync({
 Resume a suspended workflow step and await full run result:
 
 ```typescript
-const run = await workflow.createRun();
+const run = await workflow.createRunAsync();
 
-const result = await workflow.resumeAsync({
-  runId: run.runId,
+const result = await run.resumeAsync({
   step: "step-id",
   resumeData: { key: "value" },
 });
@@ -76,14 +74,13 @@ Watch workflow transitions:
 try {
   const workflow = mastraClient.getWorkflow("testWorkflow");
 
-  const run = await workflow.createRun();
+  const run = await workflow.createRunAsync();
 
-  workflow.watch({ runId: run.runId }, (record) => {
+  run.watch((record) => {
     console.log(record);
   });
 
-  const result = await workflow.start({
-    runId: run.runId,
+  const result = await run.start({
     inputData: {
       city: "New York",
     },
@@ -101,14 +98,13 @@ Resume workflow run and watch workflow step transitions:
 try {
   const workflow = mastraClient.getWorkflow("testWorkflow");
 
-  const run = await workflow.createRun({ runId: prevRunId });
+  const run = await workflow.createRunAsync({ runId: prevRunId });
 
-  workflow.watch({ runId: run.runId }, (record) => {
+  run.watch((record) => {
     console.log(record);
   });
 
-  workflow.resume({
-    runId: run.runId,
+  run.resume({
     step: "step-id",
     resumeData: { key: "value" },
   });
@@ -117,6 +113,30 @@ try {
 }
 ```
 
+### Stream Workflow
+
+Stream workflow execution for real-time updates:
+
+```typescript
+try {
+  const workflow = mastraClient.getWorkflow("testWorkflow");
+
+  const run = await workflow.createRunAsync();
+
+  const stream = await run.stream({
+    inputData: {
+      city: 'New York',
+    },
+  });
+
+  for await (const chunk of stream) {
+    console.log(JSON.stringify(chunk, null, 2));
+  }
+} catch (e) {
+  console.error('Workflow error:', e);
+}
+```
+
 ### Get Workflow Run result
 
 Get the result of a workflow run:
@@ -125,11 +145,10 @@ Get the result of a workflow run:
 try  {
   const workflow = mastraClient.getWorkflow("testWorkflow");
 
-  const run = await workflow.createRun();
+  const run = await workflow.createRunAsync();
 
   // start the workflow run
-  const startResult = await workflow.start({
-    runId: run.runId,
+  const startResult = await run.start({
     inputData: {
       city: "New York",
     },

package/.docs/raw/reference/core/mastra-class.mdx

@@ -1,6 +1,6 @@
 ---
-title: "Mastra Core"
-description: Documentation for the Mastra Class, the core entry point for managing agents, workflows, MCP servers, and server endpoints.
+title: "Reference: Mastra Class | Core | Mastra Docs"
+description: "Documentation for the `Mastra` class in Mastra, the core entry point for managing agents, workflows, MCP servers, and server endpoints."
 ---
 
 # Mastra Class