@mastra/mcp-docs-server 1.2.7-alpha.1 → 1.2.7-alpha.10

package/.docs/reference/memory/serialized-memory-config.md

@@ -38,7 +38,7 @@ new MastraEditor({
 
 **options.readOnly** (`boolean`): Treat memory as read-only — no new messages are stored.
 
-**options.lastMessages** (`number | false`): Number of recent messages to include in context, or false to disable.
+**options.lastMessages** (`number | false`): Number of recent messages to include in context, or false to disable message history entirely (messages are not loaded or saved).
 
 **options.semanticRecall** (`boolean | SemanticRecall`): Semantic recall configuration. See the Memory class reference for the full shape.
 

package/.docs/reference/memory/summarizeConversation.md

@@ -0,0 +1,99 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# summarizeConversation()
+
+The standalone `summarizeConversation()` function summarizes a conversation in one shot. It distills the messages you pass in with the same Observer plumbing that powers [Observational Memory](https://mastra.ai/reference/memory/observational-memory) — without Observational Memory attached to an agent, and without reading from or writing to storage.
+
+Nothing is written back to memory. The summary and extracted values are returned to you (and to each extractor's `onExtracted` hook), so you decide where they go — for example your own database.
+
+Use this when you already have the messages in hand and want explicit control over what gets summarized. To summarize a stored thread by ID instead, use [`Memory.summarizeThread()`](https://mastra.ai/reference/memory/summarizeThread), which loads the messages for you.
+
+## Usage example
+
+```typescript
+import { summarizeConversation } from '@mastra/memory'
+
+const result = await summarizeConversation({
+  model: 'openai/gpt-5-mini',
+  messages,
+  instructions: 'Summarize this voicemail call for the business owner.',
+})
+```
+
+## Parameters
+
+**model** (`string | LanguageModel | DynamicModel`): Model that runs the summarization, such as a router string like '\_\_GATEWAY\_OPENAI\_MODEL\_MINI\_\_'.
+
+**messages** (`MastraDBMessage[]`): The conversation to summarize. When empty, the function returns an empty result without calling the model.
+
+**instructions** (`string`): Extra guidance appended to the summarizer's system prompt, such as what to focus on or who the summary is for.
+
+**extract** (`Extractor[]`): Extractors to run over the conversation. Extractors with a Zod schema run as a follow-up structured output call; schema-less extractors are extracted inline. Each extractor's onExtracted hook fires with the extracted value.
+
+**threadId** (`string`): Thread the conversation belongs to. Defaults to the first threadId found on messages. Passed to extractor contexts.
+
+**resourceId** (`string`): Resource (user) the conversation belongs to. Defaults to the first resourceId found on messages. Passed to extractor contexts.
+
+**memory** (`Memory`): Memory instance forwarded to extractor contexts. Set automatically when called through Memory.summarizeThread().
+
+**mastra** (`Mastra`): Mastra instance used to resolve custom gateway models. Set automatically when called through Memory.summarizeThread().
+
+**requestContext** (`RequestContext`): Request context forwarded to the summarizer model and extractor hooks.
+
+**abortSignal** (`AbortSignal`): Signal to cancel the summarization call.
+
+## Returns
+
+**summary** (`string`): The distilled observations produced from the conversation, in dense bullet form.
+
+**extracted** (`Record<string, unknown>`): Values produced by extract extractors, keyed by extractor slug.
+
+**extractionFailures** (`{ slug: string; error: string }[]`): Extractors that failed to produce a valid value, with the reason. Only present when at least one extractor failed.
+
+**usage** (`{ inputTokens?: number; outputTokens?: number; totalTokens?: number }`): Token usage of the summarization call.
+
+## Extended usage example
+
+The following example summarizes an in-flight voice session from messages the application already holds, and extracts a structured record:
+
+```typescript
+import { summarizeConversation, Extractor } from '@mastra/memory'
+import type { MastraDBMessage } from '@mastra/core/agent'
+import { z } from 'zod'
+import { sessionRecords } from './db'
+
+const sessionSummary = new Extractor({
+  name: 'session-summary',
+  instructions: 'Return a concise summary of the session.',
+  schema: z.object({
+    summary: z.string(),
+    sentiment: z.enum(['positive', 'neutral', 'negative']),
+    followUps: z.array(z.string()),
+  }),
+  metadataKeyPath: false, // don't persist into memory metadata — the hook owns storage
+  onExtracted: async ({ current, threadId }) => {
+    await sessionRecords.upsert({ sessionId: threadId, record: current })
+  },
+})
+
+export async function onSessionEnd(messages: MastraDBMessage[]) {
+  const { summary, extracted, extractionFailures } = await summarizeConversation({
+    model: 'openai/gpt-5-mini',
+    messages,
+    instructions: 'Summarize this support session for the account manager.',
+    extract: [sessionSummary],
+  })
+
+  if (extractionFailures?.length) {
+    console.warn('Some extractors failed', extractionFailures)
+  }
+
+  return { summary, extracted }
+}
+```
+
+### Related
+
+- [.summarizeThread()](https://mastra.ai/reference/memory/summarizeThread)
+- [Memory Class Reference](https://mastra.ai/reference/memory/memory-class)
+- [Observational Memory](https://mastra.ai/reference/memory/observational-memory)

package/.docs/reference/memory/summarizeThread.md

@@ -0,0 +1,93 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Memory.summarizeThread()
+
+The `.summarizeThread()` method summarizes a thread's conversation in one shot. It loads the thread's messages from storage and distills them with the same Observer plumbing that powers [Observational Memory](https://mastra.ai/reference/memory/observational-memory) — as a standalone call, without Observational Memory attached to an agent.
+
+Messages load page-by-page starting from the newest, bounded by `lastMessages` and `maxInputTokens`, so summarizing a long thread doesn't read its entire history from storage.
+
+Nothing is written back to memory. The summary and extracted values are returned to you (and to each extractor's `onExtracted` hook), so you decide where they go — for example your own database.
+
+Use this when a session ends and you want a summary or structured extraction of the whole conversation, such as a voice call at hang-up. To summarize messages you already have in hand (without loading them from a thread), use the standalone [`summarizeConversation()`](https://mastra.ai/reference/memory/summarizeConversation) function instead — it takes the same options with `messages` in place of `threadId`.
+
+## Usage example
+
+```typescript
+const result = await memory.summarizeThread({
+  model: 'openai/gpt-5-mini',
+  threadId: 'thread-123',
+  instructions: 'Summarize this voicemail call for the business owner.',
+})
+```
+
+## Parameters
+
+**threadId** (`string`): The unique identifier of the thread to summarize.
+
+**model** (`string | LanguageModel | DynamicModel`): Model that runs the summarization, such as a router string like '\_\_GATEWAY\_OPENAI\_MODEL\_MINI\_\_'.
+
+**resourceId** (`string`): ID of the resource that owns the thread. If provided, validates thread ownership. Also passed to extractor contexts.
+
+**lastMessages** (`number`): Only summarize the last N messages of the thread. By default the whole thread is loaded, bounded by maxInputTokens.
+
+**maxInputTokens** (`number`): Stop loading older messages once the collected messages exceed this estimated token count. The newest message is always included. (Default: `1000000`)
+
+**instructions** (`string`): Extra guidance appended to the summarizer's system prompt, such as what to focus on or who the summary is for.
+
+**extract** (`Extractor[]`): Extractors to run over the conversation. Extractors with a Zod schema run as a follow-up structured output call; schema-less extractors are extracted inline. Each extractor's onExtracted hook fires with the extracted value.
+
+**requestContext** (`RequestContext`): Request context forwarded to the summarizer model and extractor hooks.
+
+**abortSignal** (`AbortSignal`): Signal to cancel the summarization call.
+
+## Returns
+
+**summary** (`string`): The distilled observations produced from the conversation, in dense bullet form.
+
+**extracted** (`Record<string, unknown>`): Values produced by extract extractors, keyed by extractor slug.
+
+**extractionFailures** (`{ slug: string; error: string }[]`): Extractors that failed to produce a valid value, with the reason. Only present when at least one extractor failed.
+
+**usage** (`{ inputTokens?: number; outputTokens?: number; totalTokens?: number }`): Token usage of the summarization call.
+
+## Extended usage example
+
+The following example summarizes a finished voice call and stores a structured record in the application's own database:
+
+```typescript
+import { Extractor } from '@mastra/memory'
+import { z } from 'zod'
+import { memory } from './mastra/memory'
+import { callRecords } from './db'
+
+const callSummary = new Extractor({
+  name: 'call-summary',
+  instructions: 'Return a concise summary of the call.',
+  schema: z.object({
+    summary: z.string(),
+    sentiment: z.enum(['positive', 'neutral', 'negative']),
+    requestedServices: z.array(z.string()),
+  }),
+  metadataKeyPath: false, // don't persist into memory metadata — the hook owns storage
+  onExtracted: async ({ current, threadId, resourceId }) => {
+    await callRecords.upsert({ callId: threadId, callerId: resourceId, record: current })
+  },
+})
+
+export async function onCallEnd(threadId: string, resourceId: string) {
+  await memory.summarizeThread({
+    model: 'openai/gpt-5-mini',
+    threadId,
+    resourceId,
+    instructions: 'Summarize this voicemail call for the business owner.',
+    extract: [callSummary],
+  })
+}
+```
+
+### Related
+
+- [summarizeConversation()](https://mastra.ai/reference/memory/summarizeConversation)
+- [Memory Class Reference](https://mastra.ai/reference/memory/memory-class)
+- [Observational Memory](https://mastra.ai/reference/memory/observational-memory)
+- [.recall()](https://mastra.ai/reference/memory/recall)

package/.docs/{docs/getting-started → reference}/project-structure.md

@@ -42,9 +42,9 @@ Mastra recommends organizing your code into the following folders:
 | `src/mastra/mcp`       | Implement custom MCP servers to share your tools with external agents   |
 | `src/mastra/scorers`   | Define scorers for evaluating agent performance over time               |
 
-There are two special folder conventions in Mastra:
+Mastra has two special folder conventions:
 
-- `src/mastra/agents/<name>`: You can define an agent by file convention instead of constructing it in code. Learn more in the [file-based agents](https://mastra.ai/docs/agents/file-based-agents) guide.
+- `src/mastra/agents/<name>`: You can define an agent by file convention instead of constructing it in code. Learn more in the [File-based Agents](https://mastra.ai/docs/getting-started/file-based-agents) docs.
 - `src/mastra/public`: Contents are copied into the `.build/output` directory during the build process, making them available for serving at runtime.
 
 ### Top-level files
@@ -56,11 +56,4 @@ Top-level files define how your Mastra project is configured, built, and connect
 | `src/mastra/index.ts` | Central entry point where you configure and initialize Mastra.                                                                     |
 | `.env.example`        | Template for environment variables - copy and rename to `.env` to add your secret [model provider](https://mastra.ai/models) keys. |
 | `package.json`        | Defines project metadata, dependencies, and available npm scripts.                                                                 |
-| `tsconfig.json`       | Configures TypeScript options such as path aliases, compiler settings, and build output.                                           |
-
-## Next steps
-
-- Read more about [Mastra's features](https://mastra.ai/docs).
-- Integrate Mastra with your frontend framework: [Next.js](https://mastra.ai/guides/getting-started/next-js), [React](https://mastra.ai/guides/getting-started/vite-react), or [Astro](https://mastra.ai/guides/getting-started/astro).
-- Build an agent from scratch following one of our [guides](https://mastra.ai/guides).
-- Watch conceptual guides on our [YouTube channel](https://www.youtube.com/@mastra-ai) and [subscribe](https://www.youtube.com/@mastra-ai?sub_confirmation=1)!
+| `tsconfig.json`       | Configures TypeScript options such as path aliases, compiler settings, and build output.                                           |

package/.docs/reference/pubsub/lease-provider.md

@@ -4,7 +4,7 @@
 
 `LeaseProvider` is the distributed leasing contract, separate from event delivery ([`PubSub`](https://mastra.ai/reference/pubsub/base)). Mastra's [signals layer](https://mastra.ai/docs/long-running-agents/signals) uses it to elect a single owner across multiple processes (for example, serverless invocations) for a given resource, most commonly a thread key. The owner is the process that wakes and runs the agent stream, so other processes route follow-up work to it instead of starting a competing run.
 
-Leasing is a distinct concern from pub/sub. A backend implements `LeaseProvider` only when it can genuinely coordinate a lock, such as Redis via atomic `SET`/Lua, or an in-memory map for single-process. Backends that cannot lease omit it; the signals runtime feature-detects the capability and falls back to a no-op provider, preserving single-process behavior.
+Leasing is a distinct concern from pub/sub. A backend implements `LeaseProvider` only when it can genuinely coordinate a lock, such as Redis via atomic `SET`/Lua, or an in-memory map for single-process. Backends that can't lease omit it; the signals runtime feature-detects the capability and falls back to a no-op provider, preserving single-process behavior.
 
 The built-in [`RedisStreamsPubSub`](https://mastra.ai/reference/pubsub/redis-streams) implements `LeaseProvider`, which is what enables signals to coordinate across instances in distributed and serverless deployments.
 
@@ -78,7 +78,7 @@ Returns: `Promise<string | undefined>`
 
 #### `releaseLease(key, owner)`
 
-Releases a lease. This is a no-op if the caller is not the current owner: implementations check ownership atomically before releasing, so a concurrent renewal by another owner is never clobbered.
+Releases a lease. This is a no-op if the caller isn't the current owner: implementations check ownership atomically before releasing, so a concurrent renewal by another owner is never clobbered.
 
 ```typescript
 await pubsub.releaseLease('thread:abc', runId)
@@ -117,17 +117,17 @@ if (!transferred) {
 
 Returns: `Promise<boolean>`
 
-> **Warning:** Backends that cannot perform the transfer atomically must still implement it as a best-effort `releaseLease(fromOwner)` followed by `acquireLease(toOwner)`, and document that the swap is non-atomic, since a racing process can win the key in the gap. Keeping the method required means callers have a single code path and atomicity is an explicit per-backend decision.
+> **Warning:** Backends that can't perform the transfer atomically must still implement it as a best-effort `releaseLease(fromOwner)` followed by `acquireLease(toOwner)`, and document that the swap is non-atomic, since a racing process can win the key in the gap. Keeping the method required means callers have a single code path and atomicity is an explicit per-backend decision.
 
 ## Capability detection
 
 The signals runtime detects `LeaseProvider` structurally rather than with `instanceof`, so detection works even when a separately published backend resolves a different copy of `@mastra/core`. A value is treated as a `LeaseProvider` when it exposes all five methods (`acquireLease`, `getLeaseOwner`, `releaseLease`, `renewLease`, `transferLease`).
 
-When the configured pub/sub backend does not implement `LeaseProvider`, the runtime falls back to an always-win no-op provider. Every caller wins its own lease race, and release, renew, and transfer are inert, which preserves the expected single-process behavior.
+When the configured pub/sub backend doesn't implement `LeaseProvider`, the runtime falls back to an always-win no-op provider. Every caller wins its own lease race, and release, renew, and transfer are inert, which preserves the expected single-process behavior.
 
 ## Related
 
 - [PubSub](https://mastra.ai/reference/pubsub/base): The event delivery contract, separate from leasing
 - [RedisStreamsPubSub](https://mastra.ai/reference/pubsub/redis-streams): The built-in backend that implements `LeaseProvider`
 - [Signals](https://mastra.ai/docs/long-running-agents/signals): The runtime that uses leasing to coordinate thread runs across processes
-- [Channels](https://mastra.ai/docs/agents/channels): Uses leasing to coordinate agent runs in serverless and multi-instance deployments
+- [Channels](https://mastra.ai/docs/capabilities/channels/overview): Uses leasing to coordinate agent runs in serverless and multi-instance deployments

package/.docs/reference/server/express-adapter.md

@@ -2,9 +2,7 @@
 
 # Express adapter
 
-The `@mastra/express` package provides a server adapter for running Mastra with [Express](https://expressjs.com).
-
-> **Info:** For general adapter concepts (constructor options, initialization flow, etc.), see [Server Adapters](https://mastra.ai/docs/server/server-adapters).
+The `@mastra/express` package provides a server adapter for running Mastra with [Express](https://expressjs.com). For general adapter concepts (constructor options, initialization flow, etc.), see [Server Adapters](https://mastra.ai/docs/server/server-adapters).
 
 ## Installation
 

package/.docs/reference/server/fastify-adapter.md

@@ -2,9 +2,7 @@
 
 # Fastify adapter
 
-The `@mastra/fastify` package provides a server adapter for running Mastra with [Fastify](https://fastify.dev).
-
-> **Info:** For general adapter concepts (constructor options, initialization flow, etc.), see [Server Adapters](https://mastra.ai/docs/server/server-adapters).
+The `@mastra/fastify` package provides a server adapter for running Mastra with [Fastify](https://fastify.dev). For general adapter concepts (constructor options, initialization flow, etc.), see [Server Adapters](https://mastra.ai/docs/server/server-adapters).
 
 ## Installation
 

package/.docs/reference/server/hono-adapter.md

@@ -2,9 +2,7 @@
 
 # Hono adapter
 
-The `@mastra/hono` package provides a server adapter for running Mastra with [Hono](https://hono.dev).
-
-> **Info:** For general adapter concepts (constructor options, initialization flow, etc.), see [Server Adapters](https://mastra.ai/docs/server/server-adapters).
+The `@mastra/hono` package provides a server adapter for running Mastra with [Hono](https://hono.dev). For general adapter concepts (constructor options, initialization flow, etc.), see [Server Adapters](https://mastra.ai/docs/server/server-adapters).
 
 ## Installation
 

package/.docs/reference/server/koa-adapter.md

@@ -2,9 +2,7 @@
 
 # Koa adapter
 
-The `@mastra/koa` package provides a server adapter for running Mastra with [Koa](https://koajs.com).
-
-> **Info:** For general adapter concepts (constructor options, initialization flow, etc.), see [Server Adapters](https://mastra.ai/docs/server/server-adapters).
+The `@mastra/koa` package provides a server adapter for running Mastra with [Koa](https://koajs.com). For general adapter concepts (constructor options, initialization flow, etc.), see [Server Adapters](https://mastra.ai/docs/server/server-adapters).
 
 ## Installation
 

package/.docs/reference/server/nestjs-adapter.md

@@ -4,9 +4,7 @@
 
 The `@mastra/nestjs` package provides a NestJS module for running Mastra with the Express-based NestJS platform.
 
-It's intentionally Express-only for v1. If Nest is bootstrapped with a different HTTP adapter, `MastraModule` throws during startup instead of attempting a partial integration.
-
-> **Info:** For general adapter concepts, see [Server Adapters](https://mastra.ai/docs/server/server-adapters).
+It's intentionally Express-only for v1. If Nest is bootstrapped with a different HTTP adapter, `MastraModule` throws during startup instead of attempting a partial integration. For general adapter concepts, see [Server Adapters](https://mastra.ai/docs/server/server-adapters).
 
 ## Installation
 

package/.docs/reference/signals/task-signal-provider.md

@@ -40,7 +40,7 @@ Task tracking requires a memory-backed thread (`threadId` + `resourceId`). Witho
 
 ### Agent integration
 
-These methods are called automatically by the Agent when the provider is passed to `signals`. You normally do not call them directly.
+These methods are called automatically by the Agent when the provider is passed to `signals`. You normally don't call them directly.
 
 #### `getTools()`
 

package/.docs/reference/storage/clickhouse.md

@@ -101,6 +101,38 @@ const observabilityStore = new ObservabilityStorageClickhouse({
 
 New projects should use `ObservabilityStorageClickhouseVNext` instead.
 
+### Migrating from legacy to vNext
+
+To migrate historical spans from the legacy `mastra_ai_spans` table to the vNext schema, run:
+
+**npm**:
+
+```bash
+npx mastra migrate
+```
+
+**pnpm**:
+
+```bash
+pnpm dlx mastra migrate
+```
+
+**Yarn**:
+
+```bash
+yarn dlx mastra migrate
+```
+
+**Bun**:
+
+```bash
+bun x mastra migrate
+```
+
+The migration copies span data from `mastra_ai_spans` into `mastra_span_events` in day-sized batches. It handles column mapping, deduplicates legacy rows, and preserves the original table as a backup. After migration, traces appear in Studio through the vNext adapter.
+
+> **Note:** The legacy table is not deleted. Drop it manually after verifying the migration.
+
 ### ClickHouse for every domain
 
 `ClickhouseStoreVNext` backs the `memory`, `workflows`, and `observability` domains with ClickHouse and uses the vNext observability adapter automatically. Use it when you want ClickHouse to back the entire application without wiring a composite store manually.
@@ -211,7 +243,7 @@ When `replication` is set, Mastra rewrites its `MergeTree` and `ReplacingMergeTr
 - `zookeeperPath`: `'/clickhouse/tables/{shard}/{database}/{table}'`
 - `replicaName`: `'{replica}'`
 
-The defaults match the most common self-managed convention. If your cluster's existing tables use a different layout (for example `/clickhouse/tables/{shard}/{table}` without the `{database}` segment), set `zookeeperPath` explicitly to match. Mastra does not read your cluster's convention from Keeper, so a mismatched default writes Mastra's metadata to a separate branch from the rest of the cluster.
+The defaults match the most common self-managed convention. If your cluster's existing tables use a different layout (for example `/clickhouse/tables/{shard}/{table}` without the `{database}` segment), set `zookeeperPath` explicitly to match. Mastra doesn't read your cluster's convention from Keeper, so a mismatched default writes Mastra's metadata to a separate branch from the rest of the cluster.
 
 ```typescript
 new ClickhouseStoreVNext({
@@ -231,7 +263,7 @@ Manual maintenance such as `optimizeTable()` and `materializeTtl()` runs on ever
 
 If existing Mastra tables use local `MergeTree` or `ReplacingMergeTree` engines, initialization fails while `replication` is enabled. Mastra refuses to silently convert local tables because copy-and-swap is unsafe across replicas. To migrate, recreate the affected tables as `Replicated*` before enabling replication. The typical sequence is: rename the local table, run `CREATE TABLE ... ENGINE = ReplicatedMergeTree(...) ON CLUSTER ...`, run `INSERT INTO ... SELECT * FROM <renamed_local>`, then drop the renamed local table.
 
-Do not set `replication` on ClickHouse Cloud. Cloud rewrites `MergeTree` to `SharedMergeTree` server-side, and explicit `ReplicatedMergeTree` engines produce incorrect DDL. `replication` is only for self-managed multi-replica clusters.
+Don't set `replication` on ClickHouse Cloud. Cloud rewrites `MergeTree` to `SharedMergeTree` server-side, and explicit `ReplicatedMergeTree` engines produce incorrect DDL. `replication` is only for self-managed multi-replica clusters.
 
 ### Observability domain options
 

package/.docs/reference/storage/cloudflare-d1.md

@@ -6,7 +6,7 @@ The Cloudflare D1 storage implementation provides a serverless SQL database solu
 
 > **Observability Not Supported:** Cloudflare D1 storage **doesn't support the observability domain**. Traces from the `MastraStorageExporter` can't be persisted to D1, and [Studio's](https://mastra.ai/docs/studio/overview) observability features won't work with D1 as your only storage provider. To enable observability, use [composite storage](https://mastra.ai/reference/storage/composite) to route observability data to a supported provider like ClickHouse.
 
-> **Row Size Limit:** Cloudflare D1 enforces a **1 MiB maximum row size**. This limit can be exceeded when storing messages with base64-encoded attachments such as images. See [Handling large attachments](https://mastra.ai/docs/memory/storage) for workarounds including uploading attachments to external storage.
+> **Row Size Limit:** Cloudflare D1 enforces a **1 MiB maximum row size**. This limit can be exceeded when storing messages with base64-encoded attachments such as images. See [Handling large attachments](https://mastra.ai/docs/memory/memory-processors) for workarounds including uploading attachments to external storage.
 
 ## Installation
 

package/.docs/reference/storage/composite.md

@@ -37,25 +37,25 @@ You'll also need to install the storage providers you want to compose:
 **npm**:
 
 ```bash
-npm install @mastra/pg@latest @mastra/libsql@latest
+npm install @mastra/pg@latest @mastra/libsql@latest @mastra/mongodb@latest
 ```
 
 **pnpm**:
 
 ```bash
-pnpm add @mastra/pg@latest @mastra/libsql@latest
+pnpm add @mastra/pg@latest @mastra/libsql@latest @mastra/mongodb@latest
 ```
 
 **Yarn**:
 
 ```bash
-yarn add @mastra/pg@latest @mastra/libsql@latest
+yarn add @mastra/pg@latest @mastra/libsql@latest @mastra/mongodb@latest
 ```
 
 **Bun**:
 
 ```bash
-bun add @mastra/pg@latest @mastra/libsql@latest
+bun add @mastra/pg@latest @mastra/libsql@latest @mastra/mongodb@latest
 ```
 
 ## Storage domains
@@ -124,6 +124,64 @@ export const mastra = new Mastra({
 })
 ```
 
+### Mixed backends
+
+Use domain classes from each storage package to route different domains to different backends. The following example stores memory and workflow state in MongoDB, then routes observability to ClickHouse:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraCompositeStore } from '@mastra/core/storage'
+import { ObservabilityStorageClickhouse } from '@mastra/clickhouse'
+import { MemoryStorageMongoDB, WorkflowsStorageMongoDB } from '@mastra/mongodb'
+
+export const mastra = new Mastra({
+  storage: new MastraCompositeStore({
+    id: 'composite',
+    domains: {
+      memory: new MemoryStorageMongoDB({
+        uri: process.env.MONGODB_URI,
+        dbName: 'mastra_memory',
+      }),
+      workflows: new WorkflowsStorageMongoDB({
+        uri: process.env.MONGODB_URI,
+        dbName: 'mastra_workflows',
+      }),
+      observability: new ObservabilityStorageClickhouse({
+        url: process.env.CLICKHOUSE_URL,
+        username: process.env.CLICKHOUSE_USERNAME,
+        password: process.env.CLICKHOUSE_PASSWORD,
+      }),
+    },
+  }),
+})
+```
+
+### Disabling a domain
+
+Set a domain to `false` to disable it. A disabled domain doesn't fall back to `default`, so data for that domain isn't persisted:
+
+```typescript
+import { MastraCompositeStore } from '@mastra/core/storage'
+import { PostgresStore } from '@mastra/pg'
+import { Mastra } from '@mastra/core'
+
+const pgStore = new PostgresStore({
+  id: 'pg',
+  connectionString: process.env.DATABASE_URL,
+})
+
+export const mastra = new Mastra({
+  storage: new MastraCompositeStore({
+    id: 'composite',
+    default: pgStore,
+    domains: {
+      // don't persist traces and spans
+      observability: false,
+    },
+  }),
+})
+```
+
 ## Options
 
 **id** (`string`): Unique identifier for this storage instance.
@@ -132,7 +190,7 @@ export const mastra = new Mastra({
 
 **disableInit** (`boolean`): When true, automatic initialization is disabled. You must call init() explicitly.
 
-**domains** (`object`): Individual domain overrides. Each domain can come from a different storage adapter. These take precedence over both editor and default storage.
+**domains** (`object`): Individual domain overrides. Each domain can come from a different storage adapter. These take precedence over both editor and default storage. Set a domain to false to disable it entirely; a disabled domain does not fall back to editor or default.
 
 **domains.memory** (`MemoryStorage`): Storage for threads, messages, and resources.
 
@@ -274,6 +332,6 @@ const storage = new MastraCompositeStore({
 })
 ```
 
-Do not set `replication` on ClickHouse Cloud. Cloud rewrites `MergeTree` to `SharedMergeTree` server-side. See the [ClickHouse storage reference](https://mastra.ai/reference/storage/clickhouse) for the full config shape and operator notes.
+Don't set `replication` on ClickHouse Cloud. Cloud rewrites `MergeTree` to `SharedMergeTree` server-side. See the [ClickHouse storage reference](https://mastra.ai/reference/storage/clickhouse) for the full config shape and operator notes.
 
 > **Info:** This approach is also required when using storage providers that don't support observability (like Convex, DynamoDB, or Cloudflare). See the [MastraStorageExporter documentation](https://mastra.ai/docs/observability/integrations/exporters/mastra-storage) for the full list of supported providers.

package/.docs/reference/storage/convex.md

@@ -6,7 +6,7 @@ The Convex storage implementation provides a serverless storage solution using [
 
 > **Observability Not Supported:** Convex storage **doesn't support the observability domain**. Traces from the `MastraStorageExporter` can't be persisted to Convex, and [Studio's](https://mastra.ai/docs/studio/overview) observability features won't work with Convex as your only storage provider. To enable observability, use [composite storage](https://mastra.ai/reference/storage/composite) to route observability data to a supported provider like ClickHouse.
 
-> **Record Size Limit:** Convex enforces a **1 MiB maximum record size**. This limit can be exceeded when storing messages with base64-encoded attachments such as images. See [Handling large attachments](https://mastra.ai/docs/memory/storage) for workarounds including uploading attachments to external storage like S3, Cloudflare R2, or [Convex file storage](https://docs.convex.dev/file-storage).
+> **Record Size Limit:** Convex enforces a **1 MiB maximum record size**. This limit can be exceeded when storing messages with base64-encoded attachments such as images. See [Handling large attachments](https://mastra.ai/docs/memory/memory-processors) for workarounds including uploading attachments to external storage like S3, Cloudflare R2, or [Convex file storage](https://docs.convex.dev/file-storage).
 
 ## Installation
 

package/.docs/reference/storage/dynamodb.md

@@ -6,7 +6,7 @@ The DynamoDB storage implementation provides a scalable and performant NoSQL dat
 
 > **Observability Not Supported:** DynamoDB storage **doesn't support the observability domain**. Traces from the `MastraStorageExporter` can't be persisted to DynamoDB, and [Studio's](https://mastra.ai/docs/studio/overview) observability features won't work with DynamoDB as your only storage provider. To enable observability, use [composite storage](https://mastra.ai/reference/storage/composite) to route observability data to a supported provider like ClickHouse.
 
-> **Item Size Limit:** DynamoDB enforces a **400 KB maximum item size**. This limit can be exceeded when storing messages with base64-encoded attachments such as images. See [Handling large attachments](https://mastra.ai/docs/memory/storage) for workarounds including uploading attachments to external storage.
+> **Item Size Limit:** DynamoDB enforces a **400 KB maximum item size**. This limit can be exceeded when storing messages with base64-encoded attachments such as images. See [Handling large attachments](https://mastra.ai/docs/memory/memory-processors) for workarounds including uploading attachments to external storage.
 
 ## Features