@mastra/mcp-docs-server 1.0.0-beta.13 → 1.0.0-beta.15

package/.docs/raw/reference/storage/mssql.mdx

@@ -9,13 +9,13 @@ The MSSQL storage implementation provides a production-ready storage solution us
 
 ## Installation
 
-```bash copy
+```bash
 npm install @mastra/mssql@beta
 ```
 
 ## Usage
 
-```typescript copy showLineNumbers
+```typescript
 import { MSSQLStore } from "@mastra/mssql";
 
 const storage = new MSSQLStore({
@@ -105,7 +105,7 @@ The storage implementation handles schema creation and updates automatically. It
 
 When you pass storage to the Mastra class, `init()` is called automatically before any storage operation:
 
-```typescript copy
+```typescript
 import { Mastra } from "@mastra/core";
 import { MSSQLStore } from "@mastra/mssql";
 
@@ -120,18 +120,20 @@ const mastra = new Mastra({
 
 If you're using storage directly without Mastra, you must call `init()` explicitly to create the tables:
 
-```typescript copy
+```typescript
 import { MSSQLStore } from "@mastra/mssql";
 
 const storage = new MSSQLStore({
+  id: 'mssql-storage',
   connectionString: process.env.DATABASE_URL,
 });
 
 // Required when using storage directly
 await storage.init();
 
-// Now you can use the storage
-await storage.getThread({ threadId: "..." });
+// Access domain-specific stores via getStore()
+const memoryStore = await storage.getStore('memory');
+const thread = await memoryStore?.getThreadById({ threadId: "..." });
 ```
 
 :::warning

package/.docs/raw/{memory → reference}/storage/overview.mdx

@@ -1,58 +1,22 @@
 ---
-title: "MastraStorage | Storage"
-description: Overview of Mastra's storage system and data persistence capabilities.
+title: "Reference: Storage Overview | Storage"
+description: Core data schema and table structure for Mastra's storage system.
 ---
 
-import PropertiesTable from "@site/src/components/PropertiesTable";
 import { SchemaTable } from "@site/src/components/SchemaTable";
-import { StorageOverviewImage } from "@site/src/components/StorageOverviewImage";
 import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
 
 # Storage Overview
 
-`MastraStorage` provides a unified interface for managing:
+Mastra requires the following tables to be present in the database.
 
-- **Suspended Workflows**: the serialized state of suspended workflows (so they can be resumed later)
-- **Memory**: threads and messages per `resourceId` in your application
-- **Traces**: OpenTelemetry traces from all components of Mastra
-- **Eval Datasets**: scores and scoring reasons from eval runs
-
-<br />
-
-<br />
-
-<StorageOverviewImage />
-
-Mastra provides different storage providers, but you can treat them as interchangeable. Eg, you could use libsql in development but postgres in production, and your code will work the same both ways.
-
-## Configuration
-
-Mastra can be configured with a default storage option:
-
-```typescript copy
-import { Mastra } from "@mastra/core";
-import { LibSQLStore } from "@mastra/libsql";
-
-const mastra = new Mastra({
-  storage: new LibSQLStore({
-    id: 'mastra-storage',
-    url: "file:./mastra.db",
-  }),
-});
-```
-
-If you do not specify any `storage` configuration, Mastra will not persist 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()`.
-
-## Data Schema
+## Core Schema
 
 <Tabs>
   <TabItem value="messages" label="Messages">
 Stores conversation messages and their metadata. Each message belongs to a thread and contains the actual content along with metadata about the sender role and message type.
 
-<br />
 <SchemaTable
   columns={[
     {
@@ -152,10 +116,9 @@ The message `content` column contains a JSON object conforming to the `MastraMes
 
 </TabItem>
 
-  <TabItem value="threads" label="Threads">
+<TabItem value="threads" label="Threads">
 Groups related messages together and associates them with a resource. Contains metadata about the conversation.
 
-<br />
 <SchemaTable
   columns={[
     {
@@ -202,10 +165,9 @@ Groups related messages together and associates them with a resource. Contains m
 />
 
 </TabItem>
-  <TabItem value="resources" label="Resources">
+<TabItem value="resources" label="Resources">
 Stores user-specific data for resource-scoped working memory. Each resource represents a user or entity, allowing working memory to persist across all conversation threads for that user.
 
-<br />
 <SchemaTable
   columns={[
     {
@@ -248,10 +210,9 @@ Stores user-specific data for resource-scoped working memory. Each resource repr
 />
 
 </TabItem>
-  <TabItem value="workflows" label="Workflows">
+<TabItem value="workflows" label="Workflows">
 When `suspend` is called on a workflow, its state is saved in the following format. When `resume` is called, that state is rehydrated.
 
-<br />
 <SchemaTable
   columns={[
     {
@@ -296,11 +257,10 @@ When `suspend` is called on a workflow, its state is saved in the following form
     }
   ]}
 />
-  </TabItem>
-  <TabItem value="evals" label="Evals">
+</TabItem>
+<TabItem value="evals" label="Evals">
 Stores eval results from running metrics against agent outputs.
 
-<br />
 <SchemaTable
   columns={[
     {
@@ -370,11 +330,10 @@ Stores eval results from running metrics against agent outputs.
     }
   ]}
 />
-  </TabItem>
-  <TabItem value="traces" label="Traces">
+</TabItem>
+<TabItem value="traces" label="Traces">
 Captures OpenTelemetry traces for monitoring and debugging.
 
-<br />
 <SchemaTable
   columns={[
     {
@@ -468,62 +427,5 @@ Captures OpenTelemetry traces for monitoring and debugging.
     }
   ]}
 />
-  </TabItem>
+</TabItem>
 </Tabs>
-
-### Querying Messages
-
-Messages are stored in the `MastraDBMessage` format, which provides a consistent structure across the entire Mastra system:
-
-```typescript copy
-// Get messages for a thread with pagination
-const result = await mastra
-  .getStorage()
-  .listMessages({
-    threadId: "your-thread-id",
-    page: 0,
-    perPage: 50
-  });
-
-console.log(result.messages); // MastraDBMessage[]
-console.log(result.total); // Total count
-console.log(result.hasMore); // Whether more pages exist
-
-// Get messages from multiple threads at once
-const multiThreadResult = await mastra
-  .getStorage()
-  .listMessages({
-    threadId: ["thread-1", "thread-2", "thread-3"],
-    page: 0,
-    perPage: 100
-  });
-
-// Get messages by their IDs
-const messages = await mastra
-  .getStorage()
-  .listMessagesById({ messageIds: messageIdArr });
-```
-
-The `threadId` parameter accepts either a single thread ID string or an array of thread IDs to query messages from multiple threads in a single request.
-
-All message queries return `MastraDBMessage[]` format. If you need to convert messages to AI SDK formats for UI rendering, use the conversion utilities from `@mastra/ai-sdk/ui`:
-
-```typescript copy
-import { toAISdkV5Messages } from '@mastra/ai-sdk/ui';
-
-const result = await mastra
-  .getStorage()
-  .listMessages({ threadId: "your-thread-id" });
-
-// Convert to AI SDK v5 UIMessage format for UI rendering
-const uiMessages = toAISdkV5Messages(result.messages);
-```
-
-## Storage Providers
-
-Mastra supports the following providers:
-
-- For local development, check out [LibSQL Storage](/reference/v1/storage/libsql)
-- For production, check out [PostgreSQL Storage](/reference/v1/storage/postgresql)
-- For serverless deployments, check out [Upstash Storage](/reference/v1/storage/upstash)
-- For document-based storage, check out [MongoDB Storage](/reference/v1/storage/mongodb)

package/.docs/raw/reference/storage/postgresql.mdx

@@ -9,13 +9,13 @@ The PostgreSQL storage implementation provides a production-ready storage soluti
 
 ## Installation
 
-```bash copy
+```bash
 npm install @mastra/pg@beta
 ```
 
 ## Usage
 
-```typescript copy showLineNumbers
+```typescript
 import { PostgresStore } from "@mastra/pg";
 
 const storage = new PostgresStore({
@@ -105,7 +105,7 @@ The storage implementation handles schema creation and updates automatically. It
 
 When you pass storage to the Mastra class, `init()` is called automatically before any storage operation:
 
-```typescript copy
+```typescript
 import { Mastra } from "@mastra/core";
 import { PostgresStore } from "@mastra/pg";
 
@@ -120,18 +120,20 @@ const mastra = new Mastra({
 
 If you're using storage directly without Mastra, you must call `init()` explicitly to create the tables:
 
-```typescript copy
+```typescript
 import { PostgresStore } from "@mastra/pg";
 
 const storage = new PostgresStore({
+  id: 'pg-storage',
   connectionString: process.env.DATABASE_URL,
 });
 
 // Required when using storage directly
 await storage.init();
 
-// Now you can use the storage
-await storage.getThread({ threadId: "..." });
+// Access domain-specific stores via getStore()
+const memoryStore = await storage.getStore('memory');
+const thread = await memoryStore?.getThreadById({ threadId: "..." });
 ```
 
 :::warning
@@ -155,6 +157,77 @@ This enables direct queries and custom transaction management. When using these
 
 This approach is intended for advanced scenarios where low-level access is required.
 
+## Usage Example
+
+### Adding memory to an agent
+
+To add PostgreSQL memory to an agent use the `Memory` class and create a new `storage` key using `PostgresStore`. The `connectionString` can either be a remote location, or a local database connection.
+
+```typescript title="src/mastra/agents/example-pg-agent.ts"
+import { Memory } from "@mastra/memory";
+import { Agent } from "@mastra/core/agent";
+import { PostgresStore } from "@mastra/pg";
+
+export const pgAgent = new Agent({
+  id: "pg-agent",
+  name: "PG Agent",
+  instructions:
+    "You are an AI agent with the ability to automatically recall memories from previous interactions.",
+  model: "openai/gpt-5.1",
+  memory: new Memory({
+    storage: new PostgresStore({
+      id: 'pg-agent-storage',
+      connectionString: process.env.DATABASE_URL!,
+    }),
+    options: {
+      generateTitle: true, // Explicitly enable automatic title generation
+    },
+  }),
+});
+```
+
+### Using the agent
+
+Use `memoryOptions` to scope recall for this request. Set `lastMessages: 5` to limit recency-based recall, and use `semanticRecall` to fetch the `topK: 3` most relevant messages, including `messageRange: 2` neighboring messages for context around each match.
+
+```typescript title="src/test-pg-agent.ts" 
+import "dotenv/config";
+
+import { mastra } from "./mastra";
+
+const threadId = "123";
+const resourceId = "user-456";
+
+const agent = mastra.getAgent("pg-agent");
+
+const message = await agent.stream("My name is Mastra", {
+  memory: {
+    thread: threadId,
+    resource: resourceId,
+  },
+});
+
+await message.textStream.pipeTo(new WritableStream());
+
+const stream = await agent.stream("What's my name?", {
+  memory: {
+    thread: threadId,
+    resource: resourceId,
+  },
+  memoryOptions: {
+    lastMessages: 5,
+    semanticRecall: {
+      topK: 3,
+      messageRange: 2,
+    },
+  },
+});
+
+for await (const chunk of stream.textStream) {
+  process.stdout.write(chunk);
+}
+```
+
 ## Index Management
 
 PostgreSQL storage provides comprehensive index management capabilities to optimize query performance.
@@ -174,7 +247,7 @@ These indexes significantly improve performance for filtered queries with sortin
 
 Create additional indexes to optimize specific query patterns:
 
-```typescript copy
+```typescript
 // Basic index for common queries
 await storage.createIndex({
   name: "idx_threads_resource",
@@ -278,7 +351,7 @@ For more advanced use cases, you can also use:
 
 List and monitor existing indexes:
 
-```typescript copy
+```typescript
 // List all indexes
 const allIndexes = await storage.listIndexes();
 console.log(allIndexes);
@@ -321,7 +394,7 @@ await storage.dropIndex("idx_threads_status");
 
 When using custom schemas, indexes are created with schema prefixes:
 
-```typescript copy
+```typescript
 const storage = new PostgresStore({
   id: 'pg-storage',
   connectionString: process.env.DATABASE_URL,

package/.docs/raw/reference/storage/upstash.mdx

@@ -15,13 +15,13 @@ The Upstash storage implementation provides a serverless-friendly storage soluti
 
 ## Installation
 
-```bash copy
+```bash
 npm install @mastra/upstash@beta
 ```
 
 ## Usage
 
-```typescript copy showLineNumbers
+```typescript
 import { UpstashStore } from "@mastra/upstash";
 
 const storage = new UpstashStore({
@@ -91,3 +91,75 @@ For optimal performance:
 - Use appropriate key prefixes to organize data
 - Monitor Redis memory usage
 - Consider data expiration policies if needed
+
+## Usage Example
+
+### Adding memory to an agent
+
+To add Upstash memory to an agent use the `Memory` class and create a new `storage` key using `UpstashStore` and a new `vector` key using `UpstashVector`. The configuration can point to either a remote service or a local setup.
+
+```typescript title="src/mastra/agents/example-upstash-agent.ts"
+import { Memory } from "@mastra/memory";
+import { Agent } from "@mastra/core/agent";
+import { UpstashStore } from "@mastra/upstash";
+
+export const upstashAgent = new Agent({
+  id: "upstash-agent",
+  name: "Upstash Agent",
+  instructions:
+    "You are an AI agent with the ability to automatically recall memories from previous interactions.",
+  model: "openai/gpt-5.1",
+  memory: new Memory({
+    storage: new UpstashStore({
+      id: 'upstash-agent-storage',
+      url: process.env.UPSTASH_REDIS_REST_URL!,
+      token: process.env.UPSTASH_REDIS_REST_TOKEN!,
+    }),
+    options: {
+      generateTitle: true, // Explicitly enable automatic title generation
+    },
+  }),
+});
+```
+
+### Using the agent
+
+Use `memoryOptions` to scope recall for this request. Set `lastMessages: 5` to limit recency-based recall, and use `semanticRecall` to fetch the `topK: 3` most relevant messages, including `messageRange: 2` neighboring messages for context around each match.
+
+```typescript title="src/test-upstash-agent.ts"
+import "dotenv/config";
+
+import { mastra } from "./mastra";
+
+const threadId = "123";
+const resourceId = "user-456";
+
+const agent = mastra.getAgent("upstashAgent");
+
+const message = await agent.stream("My name is Mastra", {
+  memory: {
+    thread: threadId,
+    resource: resourceId,
+  },
+});
+
+await message.textStream.pipeTo(new WritableStream());
+
+const stream = await agent.stream("What's my name?", {
+  memory: {
+    thread: threadId,
+    resource: resourceId,
+  },
+  memoryOptions: {
+    lastMessages: 5,
+    semanticRecall: {
+      topK: 3,
+      messageRange: 2,
+    },
+  },
+});
+
+for await (const chunk of stream.textStream) {
+  process.stdout.write(chunk);
+}
+```

package/.docs/raw/reference/streaming/agents/stream.mdx

@@ -11,7 +11,7 @@ The `.stream()` method enables real-time streaming of responses from an agent wi
 
 ## Usage example
 
-```ts title="index.ts" copy
+```ts title="index.ts"
 const stream = await agent.stream("message for agent");
 ```
 
@@ -675,7 +675,7 @@ const stream = await agent.stream("message for agent");
 
 ### Mastra Format (Default)
 
-```ts title="index.ts" showLineNumbers copy
+```ts title="index.ts"
 import { stepCountIs } from "ai-v5";
 
 const stream = await agent.stream("Tell me a story", {
@@ -703,7 +703,7 @@ const fullText = await stream.text;
 
 To use the stream with AI SDK v5, you can convert it using our utility function `toAISdkStream`.
 
-```ts title="index.ts" showLineNumbers copy
+```ts title="index.ts"
 import { stepCountIs, createUIMessageStreamResponse } from "ai";
 import { toAISdkStream } from "@mastra/ai-sdk";
 
@@ -724,7 +724,7 @@ return createUIMessageStreamResponse({
 
 All callback functions are now available as top-level properties for a cleaner API experience.
 
-```ts title="index.ts" showLineNumbers copy
+```ts title="index.ts"
 const stream = await agent.stream("Tell me a story", {
   onFinish: (result) => {
     console.log("Streaming finished:", result);
@@ -751,7 +751,7 @@ for await (const chunk of stream.textStream) {
 
 ### Advanced Example with Options
 
-```ts title="index.ts" showLineNumbers copy
+```ts title="index.ts"
 import { z } from "zod";
 import { stepCountIs } from "ai";
 

package/.docs/raw/reference/streaming/agents/streamLegacy.mdx

@@ -15,7 +15,7 @@ The `.streamLegacy()` method is the legacy version of the agent streaming API, u
 
 ## Usage example
 
-```typescript copy
+```typescript
 await agent.streamLegacy("message for agent");
 ```
 
@@ -534,7 +534,7 @@ await agent.streamLegacy("message for agent");
 
 ## Extended usage example
 
-```typescript showLineNumbers copy
+```typescript
 await agent.streamLegacy("message for agent", {
   temperature: 0.7,
   maxSteps: 3,

package/.docs/raw/reference/streaming/workflows/observeStream.mdx

@@ -9,7 +9,7 @@ The `.observeStream()` method opens a new `ReadableStream` to a workflow run tha
 
 ## Usage example
 
-```typescript showLineNumbers copy
+```typescript
 const run = await workflow.createRun();
 
 run.stream({

package/.docs/raw/reference/streaming/workflows/resumeStream.mdx

@@ -9,7 +9,7 @@ The `.resumeStream()` method resumes a suspended workflow run with new data, all
 
 ## Usage example
 
-```typescript showLineNumbers copy
+```typescript
 const run = await workflow.createRun();
 
 const stream = run.stream({

package/.docs/raw/reference/streaming/workflows/stream.mdx

@@ -9,7 +9,7 @@ The `.stream()` method enables real-time streaming of responses from a workflow.
 
 ## Usage example
 
-```typescript showLineNumbers copy
+```typescript
 const run = await workflow.createRun();
 
 const stream = await run.stream({
@@ -163,7 +163,7 @@ Returns a `WorkflowRunOutput` object that implements the async iterable interfac
 
 ## Extended usage example
 
-```typescript showLineNumbers copy
+```typescript
 const run = await workflow.createRun();
 
 const stream = run.stream({

package/.docs/raw/reference/streaming/workflows/timeTravelStream.mdx

@@ -9,7 +9,7 @@ The `.timeTravelStream()` method re-executes a workflow starting from any specif
 
 ## Usage example
 
-```typescript showLineNumbers copy
+```typescript
 const run = await workflow.createRun();
 
 const output = run.timeTravelStream({
@@ -76,7 +76,7 @@ The stream emits various workflow events during execution:
 
 ### Processing events during time travel
 
-```typescript showLineNumbers copy
+```typescript
 const run = await workflow.createRun();
 
 const output = run.timeTravelStream({
@@ -104,7 +104,7 @@ console.log("Time travel completed:", result);
 
 ### Time travel stream with context
 
-```typescript showLineNumbers copy
+```typescript
 const output = run.timeTravelStream({
   step: "step2",
   context: {
@@ -128,7 +128,7 @@ const result = await output.result;
 
 ### Time travel stream with nested workflows
 
-```typescript showLineNumbers copy
+```typescript
 const output = run.timeTravelStream({
   step: ["nestedWorkflow", "step3"],
   inputData: { value: 10 },

package/.docs/raw/reference/templates/overview.mdx

@@ -20,7 +20,7 @@ Mastra templates are pre-built project structures that demonstrate specific use
 
 Install a template using the `create-mastra` command:
 
-```bash copy
+```bash
 npx create-mastra@beta --template template-name
 ```
 
@@ -123,7 +123,6 @@ const agent = new Agent({
   name: "example-agent",
   model: "openai/gpt-5.1", // or other provider strings
   instructions: "Your agent instructions here",
-  // ... other configuration
 });
 ```
 

package/.docs/raw/reference/tools/create-tool.mdx

@@ -9,7 +9,7 @@ The `createTool()` function is used to define custom tools that your Mastra agen
 
 ## Usage example
 
-```typescript title="src/mastra/tools/reverse-tool.ts" showLineNumbers copy
+```typescript title="src/mastra/tools/reverse-tool.ts"
 import { createTool } from "@mastra/core/tools";
 import { z } from "zod";
 
@@ -215,7 +215,6 @@ export const tool = createTool({
   onInputStart: ({ toolCallId, messages, abortSignal }) => {
     console.log(`Tool ${toolCallId} input streaming started`);
   },
-  // ... other properties
 });
 ```
 
@@ -230,7 +229,6 @@ export const tool = createTool({
   onInputDelta: ({ inputTextDelta, toolCallId, messages, abortSignal }) => {
     console.log(`Received input chunk: ${inputTextDelta}`);
   },
-  // ... other properties
 });
 ```
 
@@ -249,7 +247,6 @@ export const tool = createTool({
     console.log(`Tool received complete input:`, input);
     // input is fully typed based on inputSchema
   },
-  // ... other properties
 });
 ```
 

package/.docs/raw/reference/tools/vector-query-tool.mdx

@@ -574,7 +574,7 @@ For more information on request context, please see:
 
 The tool can be used by itself to retrieve documents matching a query:
 
-```typescript copy showLineNumbers title="src/index.ts"
+```typescript title="src/index.ts"
 import { RequestContext } from "@mastra/core/request-context";
 import { createVectorQueryTool } from "@mastra/rag";
 import { PgVector } from "@mastra/pg";