@mastra/mcp-docs-server 1.0.0-beta.0 → 1.0.0-beta.10

package/.docs/raw/memory/storage/memory-with-libsql.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Memory with LibSQL | Memory | Mastra Docs"
+title: "Memory with LibSQL | Memory"
 description: Example for how to use Mastra's memory system with LibSQL storage and vector database backend.
 ---
 
@@ -18,7 +18,7 @@ OPENAI_API_KEY=<your-api-key>
 And install the following package:
 
 ```bash copy
-npm install @mastra/libsql
+npm install @mastra/libsql@beta
 ```
 
 ## Adding memory to an agent
@@ -28,7 +28,6 @@ To add LibSQL memory to an agent use the `Memory` class and create a new `storag
 ```typescript title="src/mastra/agents/example-libsql-agent.ts" showLineNumbers copy
 import { Memory } from "@mastra/memory";
 import { Agent } from "@mastra/core/agent";
-import { openai } from "@ai-sdk/openai";
 import { LibSQLStore } from "@mastra/libsql";
 
 export const libsqlAgent = new Agent({
@@ -36,7 +35,7 @@ export const libsqlAgent = new Agent({
   name: "LibSQL Agent",
   instructions:
     "You are an AI agent with the ability to automatically recall memories from previous interactions.",
-  model: openai("gpt-4o"),
+  model: "openai/gpt-5.1",
   memory: new Memory({
     storage: new LibSQLStore({
       id: 'libsql-agent-storage',
@@ -56,7 +55,7 @@ Embeddings are numeric vectors used by memory’s `semanticRecall` to retrieve r
 Install `fastembed` to get started:
 
 ```bash copy
-npm install @mastra/fastembed
+npm install @mastra/fastembed@beta
 ```
 
 Add the following to your agent:
@@ -64,7 +63,6 @@ Add the following to your agent:
 ```typescript title="src/mastra/agents/example-libsql-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";
 import { fastembed } from "@mastra/fastembed";
 
@@ -73,7 +71,7 @@ export const libsqlAgent = new Agent({
   name: "LibSQL Agent",
   instructions:
     "You are an AI agent with the ability to automatically recall memories from previous interactions.",
-  model: openai("gpt-4o"),
+  model: "openai/gpt-5.1",
   memory: new Memory({
     storage: new LibSQLStore({
       id: 'libsql-agent-storage',
@@ -140,6 +138,3 @@ for await (const chunk of stream.textStream) {
 }
 ```
 
-## Related
-
-- [Calling Agents](/examples/v1/agents/calling-agents)

package/.docs/raw/memory/storage/memory-with-mongodb.mdx

@@ -0,0 +1,150 @@
+---
+title: "Example: Memory with MongoDB | Memory"
+description: Example for how to use Mastra's memory system with MongoDB storage and vector capabilities.
+---
+
+# Memory with MongoDB
+
+This example demonstrates how to use Mastra's memory system with MongoDB as the storage backend.
+
+## Prerequisites
+
+This example uses the `openai` model and requires a MongoDB database. Make sure to add the following to your `.env` file:
+
+```bash title=".env" copy
+OPENAI_API_KEY=<your-api-key>
+MONGODB_URI=<your-connection-string>
+MONGODB_DB_NAME=<your-db-name>
+```
+
+And install the following package:
+
+```bash copy
+npm install @mastra/mongodb@beta
+```
+
+## Adding memory to an agent
+
+To add MongoDB memory to an agent use the `Memory` class and create a new `storage` key using `MongoDBStore`. The configuration supports both local and remote MongoDB instances.
+
+```typescript title="src/mastra/agents/example-mongodb-agent.ts" showLineNumbers copy
+import { Memory } from "@mastra/memory";
+import { Agent } from "@mastra/core/agent";
+import { MongoDBStore } from "@mastra/mongodb";
+
+export const mongodbAgent = new Agent({
+  id: "mongodb-agent",
+  name: "mongodb-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 MongoDBStore({
+      url: process.env.MONGODB_URI!,
+      dbName: process.env.MONGODB_DB_NAME!,
+    }),
+    options: {
+      threads: {
+        generateTitle: true,
+      },
+    },
+  }),
+});
+```
+
+## Vector embeddings with MongoDB
+
+Embeddings are numeric vectors used by memory's `semanticRecall` to retrieve related messages by meaning (not keywords).
+
+> Note: You must use a deployment hosted on MongoDB Atlas to successfully use the MongoDB Vector database.
+
+This setup uses FastEmbed, a local embedding model, to generate vector embeddings.
+To use this, install `@mastra/fastembed`:
+
+```bash copy
+npm install @mastra/fastembed@beta
+```
+
+Add the following to your agent:
+
+```typescript title="src/mastra/agents/example-mongodb-agent.ts" showLineNumbers copy
+import { Memory } from "@mastra/memory";
+import { Agent } from "@mastra/core/agent";
+import { MongoDBStore, MongoDBVector } from "@mastra/mongodb";
+import { fastembed } from "@mastra/fastembed";
+
+export const mongodbAgent = new Agent({
+  id: "mongodb-agent",
+  name: "mongodb-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 MongoDBStore({
+      url: process.env.MONGODB_URI!,
+      dbName: process.env.MONGODB_DB_NAME!,
+    }),
+    vector: new MongoDBVector({
+      uri: process.env.MONGODB_URI!,
+      dbName: process.env.MONGODB_DB_NAME!,
+    }),
+    embedder: fastembed,
+    options: {
+      lastMessages: 10,
+      semanticRecall: {
+        topK: 3,
+        messageRange: 2,
+      },
+      threads: {
+        generateTitle: true, // generates descriptive thread titles automatically
+      },
+    },
+  }),
+});
+```
+
+## Usage example
+
+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-mongodb-agent.ts" showLineNumbers copy
+import "dotenv/config";
+
+import { mastra } from "./mastra";
+
+const threadId = "123";
+const resourceId = "user-456";
+
+const agent = mastra.getAgent("mongodbAgent");
+
+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);
+}
+```
+
+## Related
+
+- [Calling Agents](/docs/v1/agents/overview)

package/.docs/raw/memory/storage/memory-with-pg.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Memory with Postgres | Memory | Mastra Docs"
+title: "Memory with Postgres | Memory"
 description: Example for how to use Mastra's memory system with PostgreSQL storage and vector capabilities.
 ---
 
@@ -19,7 +19,7 @@ DATABASE_URL=<your-connection-string>
 And install the following package:
 
 ```bash copy
-npm install @mastra/pg
+npm install @mastra/pg@beta
 ```
 
 ## Adding memory to an agent
@@ -29,7 +29,6 @@ To add PostgreSQL memory to an agent use the `Memory` class and create a new `st
 ```typescript title="src/mastra/agents/example-pg-agent.ts" showLineNumbers copy
 import { Memory } from "@mastra/memory";
 import { Agent } from "@mastra/core/agent";
-import { openai } from "@ai-sdk/openai";
 import { PostgresStore } from "@mastra/pg";
 
 export const pgAgent = new Agent({
@@ -37,7 +36,7 @@ export const pgAgent = new Agent({
   name: "PG Agent",
   instructions:
     "You are an AI agent with the ability to automatically recall memories from previous interactions.",
-  model: openai("gpt-4o"),
+  model: "openai/gpt-5.1",
   memory: new Memory({
     storage: new PostgresStore({
       id: 'pg-agent-storage',
@@ -57,7 +56,7 @@ Embeddings are numeric vectors used by memory’s `semanticRecall` to retrieve r
 Install `fastembed` to get started:
 
 ```bash copy
-npm install @mastra/fastembed
+npm install @mastra/fastembed@beta
 ```
 
 Add the following to your agent:
@@ -65,7 +64,6 @@ Add the following to your agent:
 ```typescript title="src/mastra/agents/example-pg-agent.ts" showLineNumbers copy
 import { Memory } from "@mastra/memory";
 import { Agent } from "@mastra/core/agent";
-import { openai } from "@ai-sdk/openai";
 import { PostgresStore, PgVector } from "@mastra/pg";
 import { fastembed } from "@mastra/fastembed";
 
@@ -74,7 +72,7 @@ export const pgAgent = new Agent({
   name: "PG Agent",
   instructions:
     "You are an AI agent with the ability to automatically recall memories from previous interactions.",
-  model: openai("gpt-4o"),
+  model: "openai/gpt-5.1",
   memory: new Memory({
     storage: new PostgresStore({
       id: 'pg-agent-storage',
@@ -138,6 +136,3 @@ for await (const chunk of stream.textStream) {
 }
 ```
 
-## Related
-
-- [Calling Agents](/examples/v1/agents/calling-agents)

package/.docs/raw/memory/storage/memory-with-upstash.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Memory with Upstash | Memory | Mastra Docs"
+title: "Memory with Upstash | Memory"
 description: Example for how to use Mastra's memory system with Upstash Redis storage and vector capabilities.
 ---
 
@@ -24,7 +24,7 @@ You can get your Upstash credentials by signing up at [upstash.com](https://upst
 And install the following package:
 
 ```bash copy
-npm install @mastra/upstash
+npm install @mastra/upstash@beta
 ```
 
 ## Adding memory to an agent
@@ -34,7 +34,6 @@ To add Upstash memory to an agent use the `Memory` class and create a new `stora
 ```typescript title="src/mastra/agents/example-upstash-agent.ts" showLineNumbers copy
 import { Memory } from "@mastra/memory";
 import { Agent } from "@mastra/core/agent";
-import { openai } from "@ai-sdk/openai";
 import { UpstashStore } from "@mastra/upstash";
 
 export const upstashAgent = new Agent({
@@ -42,7 +41,7 @@ export const upstashAgent = new Agent({
   name: "Upstash Agent",
   instructions:
     "You are an AI agent with the ability to automatically recall memories from previous interactions.",
-  model: openai("gpt-4o"),
+  model: "openai/gpt-5.1",
   memory: new Memory({
     storage: new UpstashStore({
       id: 'upstash-agent-storage',
@@ -63,7 +62,7 @@ Embeddings are numeric vectors used by memory’s `semanticRecall` to retrieve r
 Install `fastembed` to get started:
 
 ```bash copy
-npm install @mastra/fastembed
+npm install @mastra/fastembed@beta
 ```
 
 Add the following to your agent:
@@ -71,7 +70,6 @@ Add the following to your agent:
 ```typescript title="src/mastra/agents/example-upstash-agent.ts" showLineNumbers copy
 import { Memory } from "@mastra/memory";
 import { Agent } from "@mastra/core/agent";
-import { openai } from "@ai-sdk/openai";
 import { UpstashStore, UpstashVector } from "@mastra/upstash";
 import { fastembed } from "@mastra/fastembed";
 
@@ -80,7 +78,7 @@ export const upstashAgent = new Agent({
   name: "Upstash Agent",
   instructions:
     "You are an AI agent with the ability to automatically recall memories from previous interactions.",
-  model: openai("gpt-4o"),
+  model: "openai/gpt-5.1",
   memory: new Memory({
     storage: new UpstashStore({
       id: 'upstash-agent-storage',
@@ -146,6 +144,3 @@ for await (const chunk of stream.textStream) {
 }
 ```
 
-## Related
-
-- [Calling Agents](/examples/v1/agents/calling-agents)

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

@@ -1,5 +1,5 @@
 ---
-title: "Memory threads and resources | Memory | Mastra Docs"
+title: "Memory threads and resources | Memory"
 description: "Learn how Mastra's memory system works with working memory, conversation history, and semantic recall."
 ---
 
@@ -56,7 +56,7 @@ export const testAgent = new Agent({
     options: {
       threads: {
         generateTitle: {
-          model: openai("gpt-4.1-nano"),
+          model: "openai/gpt-4.1-nano",
           instructions:
             "Generate a concise title based on the user's first message",
         },
@@ -80,8 +80,8 @@ export const testAgent = new Agent({
           model: ({ requestContext }) => {
             const userTier = requestContext.get("userTier");
             return userTier === "premium"
-              ? openai("gpt-4.1")
-              : openai("gpt-4.1-nano");
+              ? "openai/gpt-5.1"
+              : "openai/gpt-4.1-nano";
           },
           instructions: ({ requestContext }) => {
             const language = requestContext.get("userLanguage") || "English";

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

@@ -1,5 +1,5 @@
 ---
-title: "Working Memory | Memory | Mastra Docs"
+title: "Working Memory | Memory"
 description: "Learn how to configure working memory in Mastra to store persistent user data, preferences."
 ---
 
@@ -24,17 +24,16 @@ Working memory can persist at two different scopes:
 
 Here's a minimal example of setting up an agent with working memory:
 
-```typescript {12-15}
+```typescript {11-14}
 import { Agent } from "@mastra/core/agent";
 import { Memory } from "@mastra/memory";
-import { openai } from "@ai-sdk/openai";
 
 // Create agent with working memory enabled
 const agent = new Agent({
   id: "personal-assistant",
   name: "PersonalAssistant",
   instructions: "You are a helpful personal assistant.",
-  model: openai("gpt-4o"),
+  model: "openai/gpt-5.1",
   memory: new Memory({
     options: {
       workingMemory: {
@@ -132,6 +131,7 @@ Resource-scoped working memory requires specific storage adapters that support t
 - **LibSQL** (`@mastra/libsql`)
 - **PostgreSQL** (`@mastra/pg`)
 - **Upstash** (`@mastra/upstash`)
+- **MongoDB** (`@mastra/mongodb`)
 
 ## Custom Templates
 
@@ -268,10 +268,18 @@ When a schema is provided, the agent receives the working memory as a JSON objec
 }
 ```
 
+### Merge Semantics for Schema-Based Memory
+
+Schema-based working memory uses **merge semantics**, meaning the agent only needs to include fields it wants to add or update. Existing fields are preserved automatically.
+
+- **Object fields are deep merged:** Only provided fields are updated; others remain unchanged
+- **Set a field to `null` to delete it:** This explicitly removes the field from memory
+- **Arrays are replaced entirely:** When an array field is provided, it replaces the existing array (arrays are not merged element-by-element)
+
 ## Choosing Between Template and Schema
 
-- Use a **template** (Markdown) if you want the agent to maintain memory as a free-form text block, such as a user profile or scratchpad.
-- Use a **schema** if you need structured, type-safe data that can be validated and programmatically accessed as JSON.
+- Use a **template** (Markdown) if you want the agent to maintain memory as a free-form text block, such as a user profile or scratchpad. Templates use **replace semantics** — the agent must provide the complete memory content on each update.
+- Use a **schema** if you need structured, type-safe data that can be validated and programmatically accessed as JSON. Schemas use **merge semantics** — the agent only provides fields to update, and existing fields are preserved.
 - Only one mode can be active at a time: setting both `template` and `schema` is not supported.
 
 ## Example: Multi-step Retention
@@ -378,6 +386,6 @@ await memory.updateWorkingMemory({
 
 ## Examples
 
-- [Working memory with template](/examples/v1/memory/working-memory-template)
-- [Working memory with schema](/examples/v1/memory/working-memory-schema)
+- [Working memory with template](https://github.com/mastra-ai/mastra/tree/main/examples/memory-with-template)
+- [Working memory with schema](https://github.com/mastra-ai/mastra/tree/main/examples/memory-with-schema)
 - [Per-resource working memory](https://github.com/mastra-ai/mastra/tree/main/examples/memory-per-resource-example) - Complete example showing resource-scoped memory persistence

package/.docs/raw/{logging.mdx → observability/logging.mdx}

@@ -1,5 +1,5 @@
 ---
-title: "Logging | Observability | Mastra Docs"
+title: "Logging | Observability"
 description: Learn how to use logging in Mastra to monitor execution, capture application behavior, and improve the accuracy of AI applications.
 ---
 
@@ -7,14 +7,14 @@ description: Learn how to use logging in Mastra to monitor execution, capture ap
 
 Mastra's logging system captures function execution, input data, and output responses in a structured format.
 
-When deploying to Mastra Cloud, logs are shown on the [Logs]/docs/v1/mastra-cloud/observability) page. In self-hosted or custom environments, logs can be directed to files or external services depending on the configured transports.
+When deploying to Mastra Cloud, logs are shown on the [Logs](/docs/v1/deployment/mastra-cloud/observability) page. In self-hosted or custom environments, logs can be directed to files or external services depending on the configured transports.
 
-## PinoLogger
+## Configuring logs with PinoLogger
 
-When [initializing a new Mastra project]/docs/v1/getting-started/installation) using the CLI, `PinoLogger` is included by default.
+When [initializing a new Mastra project](/guides/v1/getting-started/quickstart) using the CLI, `PinoLogger` is included by default.
 
 ```typescript title="src/mastra/index.ts" showLineNumbers copy
-import { Mastra } from "@mastra/core";
+import { Mastra } from "@mastra/core/mastra";
 import { PinoLogger } from "@mastra/loggers";
 
 export const mastra = new Mastra({
@@ -26,9 +26,9 @@ export const mastra = new Mastra({
 });
 ```
 
-> See the [PinoLogger]/reference/v1/logging/pino-logger) API reference for all available configuration options.
+> See the [PinoLogger](/reference/v1/logging/pino-logger) API reference for all available configuration options.
 
-## Logging from workflows and tools
+## Customizing logs
 
 Mastra provides access to a logger instance via the `mastra.getLogger()` method, available inside both workflow steps and tools. The logger supports standard severity levels: `debug`, `info`, `warn`, and `error`.
 
@@ -79,7 +79,7 @@ export const testTool = createTool({
 });
 ```
 
-## Logging with additional data
+### Logging with additional data
 
 Logger methods accept an optional second argument for additional data. This can be any value, such as an object, string, or number.
 

package/.docs/raw/observability/overview.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Observability Overview | Observability | Mastra Docs"
+title: "Observability Overview | Observability"
 description: Monitor and debug applications with Mastra's Observability features.
 ---
 
@@ -43,11 +43,10 @@ export const mastra = new Mastra({
 
 With this basic setup, you will see Traces and Logs in both Studio and in Mastra Cloud.
 
-We also support various external tracing providers like Langfuse, Braintrust, and any OpenTelemetry-compatible platform (Datadog, New Relic, SigNoz, etc.). See more about this in the [Tracing]/docs/v1/observability/tracing/overview) documentation.
+We also support various external tracing providers like MLflow, Langfuse, Braintrust, and any OpenTelemetry-compatible platform (Datadog, New Relic, SigNoz, etc.). See more about this in the [Tracing](/docs/v1/observability/tracing/overview) documentation.
 
 ## What's Next?
 
-- **[Set up Tracing]/docs/v1/observability/tracing/overview)**: Configure tracing for your application
-- **[Configure Logging]/docs/v1/logging)**: Add structured logging
-- **[View Examples]/examples/v1/observability/basic-tracing)**: See observability in action
-- **[API Reference]/reference/v1/observability/tracing/instances)**: Detailed configuration options
+- **[Set up Tracing](/docs/v1/observability/tracing/overview)**: Configure tracing for your application
+- **[Configure Logging](/docs/v1/observability/logging)**: Add structured logging
+- **[API Reference](/reference/v1/observability/tracing/instances)**: Detailed configuration options