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

package/.docs/docs/index.md

@@ -54,7 +54,7 @@ export const weatherTool = createTool({
 })
 ```
 
-If you need to create an agent, create a new file and use `import { Agent } from "@mastra/core/agent"`. The constructor takes `{ id, name, instructions, model }`. The `model` property is a string in Mastra's model router format: `provider/model`, for example `openai/gpt-5.5`. For OpenAI models, use `openai/<model>`, not `openai:<model>`, and don't pass a provider object. No provider import is needed for this format. Do not install any AI SDK package unless Mastra's documentation says otherwise.
+If you need to create an agent, create a new file and use `import { Agent } from "@mastra/core/agent"`. The constructor takes `{ id, name, instructions, model }`. The `model` property is a string in Mastra's model router format: `provider/model`, for example `openai/gpt-5.5`. For OpenAI models, use `openai/<model>`, not `openai:<model>`, and don't pass a provider object. No provider import is needed for this format. Don't install any AI SDK package unless Mastra's documentation says otherwise.
 
 Add a tool an agent by importing the tool and passing it to the agent constructor as a tools object.
 

package/.docs/docs/long-running-agents/background-tasks.md

@@ -16,7 +16,7 @@ Use background tasks when a tool call may take long enough that the user shouldn
 
 For tool calls that return quickly, foreground execution using `agent.stream()` and `agent.generate()` is simpler.
 
-> **Note:** Background tasks require a configured [storage](https://mastra.ai/docs/memory/storage) backend on the Mastra instance. Tasks are persisted so they survive process restarts.
+> **Note:** Background tasks require a configured [storage](https://mastra.ai/docs/storage/overview) backend on the Mastra instance. Tasks are persisted so they survive process restarts.
 
 ## Quickstart
 
@@ -168,7 +168,7 @@ const stream = await agent.stream('Research solana for me', {
 })
 ```
 
-> **Note:** Visit [`Agent.stream()`](https://mastra.ai/reference/streaming/agents/stream) for the full API.
+Visit [`Agent.stream()`](https://mastra.ai/reference/streaming/agents/stream) for the full API.
 
 ### Aggregate properties
 
@@ -379,4 +379,4 @@ These read from storage rather than the pubsub stream, so they're suitable for p
 - [Durable agents](https://mastra.ai/docs/long-running-agents/durable-agents)
 - [Supervisor agents](https://mastra.ai/docs/agents/supervisor-agents)
 - [Stream chunk types](https://mastra.ai/reference/streaming/ChunkType)
-- [Storage](https://mastra.ai/docs/memory/storage)
+- [Storage](https://mastra.ai/docs/storage/overview)

package/.docs/docs/long-running-agents/durable-agents.md

@@ -60,9 +60,7 @@ for await (const chunk of output.fullStream) {
 cleanup()
 ```
 
-The returned `runId` identifies the execution. Pass it to `observe()` to reconnect from a different client.
-
-> **Note:** Visit the [DurableAgent reference](https://mastra.ai/reference/agents/durable-agent) for the full configuration and method API.
+The returned `runId` identifies the execution. Pass it to `observe()` to reconnect from a different client. Visit the [DurableAgent reference](https://mastra.ai/reference/agents/durable-agent) for the full configuration and method API.
 
 ## How it works
 
@@ -105,7 +103,7 @@ export const durableHelper = createDurableAgent({ agent })
 
 ### Fire-and-forget with `createEventedAgent()`
 
-The workflow starts in the background without blocking the caller. You still receive chunks through PubSub, so `stream()` returns a result you can consume. The HTTP handler that triggered the run does not need to wait for the workflow to finish:
+The workflow starts in the background without blocking the caller. You still receive chunks through PubSub, so `stream()` returns a result you can consume. The HTTP handler that triggered the run doesn't need to wait for the workflow to finish:
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
@@ -140,7 +138,7 @@ const agent = new Agent({
 export const inngestAnalyst = createInngestAgent({ agent, inngest })
 ```
 
-> **Note:** Visit the [`createInngestAgent()` reference](https://mastra.ai/reference/agents/inngest-agent) for the full API, including Inngest-specific options like PubSub and cache configuration.
+Visit the [`createInngestAgent()` reference](https://mastra.ai/reference/agents/inngest-agent) for the full API, including Inngest-specific options like PubSub and cache configuration.
 
 ## Resumable streams
 
@@ -170,7 +168,7 @@ export const durableAgent = createDurableAgent({
 })
 ```
 
-`createInngestAgent()` does not enable caching by default. Pass a `cache` option or register the agent with a `Mastra` instance that has a `serverCache` configured to enable resumable streams.
+`createInngestAgent()` doesn't enable caching by default. Pass a `cache` option or register the agent with a `Mastra` instance that has a `serverCache` configured to enable resumable streams.
 
 ## Streaming with background tasks
 
@@ -199,7 +197,7 @@ await durableAgent.stream('Research topic', {
 })
 ```
 
-> **Note:** Visit [Background tasks](https://mastra.ai/docs/long-running-agents/background-tasks) for the full background task guide, including configuration, subagents, and suspend/resume.
+Visit [Background tasks](https://mastra.ai/docs/long-running-agents/background-tasks) for the full background task guide, including configuration, subagents, and suspend/resume.
 
 ## Cleanup
 

package/.docs/docs/long-running-agents/goals.md

@@ -6,7 +6,7 @@
 
 > **Beta:** The Goals feature is in beta stage and subject to breaking changes in minor versions until it graduates from its beta status.
 
-A goal is a durable, thread-scoped objective: a standing instruction the agent keeps working toward across loop iterations until a judge model decides it is satisfied or a run budget is exhausted. The objective is persisted in thread state, so it survives reloads and is evaluated in-loop — even when a new message arrives in the middle of an already-running turn.
+A goal is a durable, thread-scoped objective: a standing instruction the agent keeps working toward across loop iterations until a judge model decides it's satisfied or a run budget is exhausted. The objective is persisted in thread state, so it survives reloads and is evaluated in-loop — even when a new message arrives in the middle of an already-running turn.
 
 Goals build on the same machinery as [`isTaskComplete`](https://mastra.ai/docs/agents/supervisor-agents): an LLM-as-judge scores the agent's output each iteration and gates the loop. The difference is that a goal is **durable** (stored in thread state, not passed per call) and is set and updated through `Agent` methods rather than per-`stream()` options.
 
@@ -22,7 +22,7 @@ For a one-off completion check within a single `stream()` call, use [`isTaskComp
 
 ## Quickstart
 
-Goals require a configured [storage](https://mastra.ai/docs/memory/storage) backend and a memory-backed thread. Add a `goal` config to the agent — a judge model is required for the goal to do anything — then set an objective for a thread:
+Goals require a configured [storage](https://mastra.ai/docs/storage/overview) backend and a memory-backed thread. Add a `goal` config to the agent — a judge model is required for the goal to do anything — then set an objective for a thread:
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
@@ -89,7 +89,7 @@ Each evaluation emits a typed `goal` stream chunk (`GoalEvaluationPayload`: `obj
 
 ## Managing the objective
 
-Control the objective for a thread with `Agent` methods. All of them no-op when the run is not memory-backed (they require storage and a `threadId`):
+Control the objective for a thread with `Agent` methods. All of them no-op when the run isn't memory-backed (they require storage and a `threadId`):
 
 ```typescript
 // Read the current objective record.
@@ -103,12 +103,10 @@ await worker.updateObjectiveOptions({ threadId, maxRuns: 100 })
 await worker.clearObjective({ threadId })
 ```
 
-Per-objective values written by `setObjective` / `updateObjectiveOptions` take precedence over the agent's `goal` config, and that precedence is remembered in thread state.
-
-> **Note:** See the [`GoalEvaluationPayload` in the ChunkType reference](https://mastra.ai/reference/streaming/ChunkType) for the full goal chunk shape.
+Per-objective values written by `setObjective` / `updateObjectiveOptions` take precedence over the agent's `goal` config, and that precedence is remembered in thread state. See the [`GoalEvaluationPayload` in the ChunkType reference](https://mastra.ai/reference/streaming/ChunkType) for the full goal chunk shape.
 
 ## Related
 
 - [Supervisor agents](https://mastra.ai/docs/agents/supervisor-agents) — `isTaskComplete` and the rubric scorer
 - [Signal providers](https://mastra.ai/docs/long-running-agents/signal-providers) — how the objective is projected into context
-- [Memory storage](https://mastra.ai/docs/memory/storage) — the storage backend goals require
+- [Memory storage](https://mastra.ai/docs/storage/overview) — the storage backend goals require

package/.docs/docs/long-running-agents/schedules.md

@@ -10,7 +10,7 @@ A schedule runs an agent on a cron cadence. On each fire, Mastra sends a prompt
 
 Schedules are persisted, so they survive restarts and redeploys. Manage them at runtime through [`mastra.schedules`](https://mastra.ai/reference/schedules/overview), the canonical create, read, update, and delete (CRUD) surface. The same surface also manages [workflow schedules](https://mastra.ai/docs/workflows/scheduled-workflows) (pass `workflowId` instead of `agentId` to schedule a workflow).
 
-> **Note:** Schedules require a [storage](https://mastra.ai/docs/memory/storage) adapter that implements the schedules domain. See the [`mastra.schedules` reference](https://mastra.ai/reference/schedules/overview) for supported adapters and API behavior.
+> **Note:** Schedules require a [storage](https://mastra.ai/docs/storage/overview) adapter that implements the schedules domain. See the [`mastra.schedules` reference](https://mastra.ai/reference/schedules/overview) for supported adapters and API behavior.
 
 ## Quickstart
 

package/.docs/docs/long-running-agents/signal-providers.md

@@ -157,9 +157,7 @@ export class CiSignals extends SignalProvider<'ci-signals'> {
 }
 ```
 
-`handleWebhook()` is a provider method, not an auto-mounted HTTP route. Invoke it from your own endpoint, passing the request body, headers, and any route params.
-
-> **Note:** Visit [`SignalProvider` reference](https://mastra.ai/reference/signals/signal-provider) for subscription, polling, lifecycle, and `notify()` details. For the complete notification payload shape, including deduplication and coalescing fields, visit [`Agent.sendNotificationSignal()` reference](https://mastra.ai/reference/agents/agent).
+`handleWebhook()` is a provider method, not an auto-mounted HTTP route. Invoke it from your own endpoint, passing the request body, headers, and any route params. Visit [`SignalProvider` reference](https://mastra.ai/reference/signals/signal-provider) for subscription, polling, lifecycle, and `notify()` details. For the complete notification payload shape, including deduplication and coalescing fields, visit [`Agent.sendNotificationSignal()` reference](https://mastra.ai/reference/agents/agent).
 
 ## Built-in webhook provider
 

package/.docs/docs/long-running-agents/signals.md

@@ -10,6 +10,8 @@ Signals are a way to interact with an agent through a thread. Instead of startin
 
 Use message APIs for user-authored input. Use `sendSignal()` for lower-level system context, such as background task notifications, policy reminders, or processor-generated context.
 
+> **📹 Watch:** Watch [Mastra signals overview](https://www.youtube.com/watch?v=7It2y89TVP4) to see how signals wake and steer long-running agents.
+
 ## When to use signals
 
 Use signals when an agent thread needs new input or context outside the original `stream()` call. Signals are useful when users send follow-up messages while a run is active, when background systems need to add context to a thread, or when external events should wake, update, or notify the agent.
@@ -110,9 +112,7 @@ const result = agent.sendSignal(
 await result.persisted
 ```
 
-Pass `ifIdle.streamOptions` when the idle wake-up stream needs options such as model settings, tools, or runtime context.
-
-> **Note:** Visit [`Agent.sendSignal()` reference](https://mastra.ai/reference/agents/agent) for `ifActive`, `ifIdle`, branch attributes, and `streamOptions`.
+Pass `ifIdle.streamOptions` when the idle wake-up stream needs options such as model settings, tools, or runtime context. Visit [`Agent.sendSignal()` reference](https://mastra.ai/reference/agents/agent) for `ifActive`, `ifIdle`, branch attributes, and `streamOptions`.
 
 ### Send notification context
 
@@ -197,9 +197,7 @@ Awaiting `sendSignal()` preserves stream echo ordering when a subscribed thread
 
 ### Conditional attributes
 
-Use `ifActive.attributes` and `ifIdle.attributes` to tag input with context that depends on whether the agent is active or idle at delivery time. Top-level `attributes` always apply, and Mastra merges the selected branch's `attributes` into them when the input is accepted.
-
-> **Note:** Visit [`Agent.sendMessage()` reference](https://mastra.ai/reference/agents/agent) and [`Agent.sendSignal()` reference](https://mastra.ai/reference/agents/agent) for branch-specific attributes.
+Use `ifActive.attributes` and `ifIdle.attributes` to tag input with context that depends on whether the agent is active or idle at delivery time. Top-level `attributes` always apply, and Mastra merges the selected branch's `attributes` into them when the input is accepted. Visit [`Agent.sendMessage()` reference](https://mastra.ai/reference/agents/agent) and [`Agent.sendSignal()` reference](https://mastra.ai/reference/agents/agent) for branch-specific attributes.
 
 ## State and notification signals
 
@@ -274,9 +272,7 @@ Notification signals represent external events such as GitHub activity, email, S
 
 Notification delivery has two phases. During ingress, `agent.sendNotificationSignal()` stores a notification record and resolves the agent's delivery policy. During dispatch, Mastra consumes due records and emits full notification or summary signals.
 
-The default delivery policy is priority-aware. Urgent notifications deliver immediately, while lower-priority notifications may be batched into summaries or wait until the thread is idle.
-
-> **Note:** Visit [`Agent.sendNotificationSignal()` reference](https://mastra.ai/reference/agents/agent) for notification fields, [`Agent` constructor reference](https://mastra.ai/reference/agents/agent) for `notifications.deliveryPolicy` configuration, and [`createNotificationInboxTool()` reference](https://mastra.ai/reference/signals/create-notification-inbox-tool) for inbox tool actions.
+The default delivery policy is priority-aware. Urgent notifications deliver immediately, while lower-priority notifications may be batched into summaries or wait until the thread is idle. Visit [`Agent.sendNotificationSignal()` reference](https://mastra.ai/reference/agents/agent) for notification fields, [`Agent` constructor reference](https://mastra.ai/reference/agents/agent) for `notifications.deliveryPolicy` configuration, and [`createNotificationInboxTool()` reference](https://mastra.ai/reference/signals/create-notification-inbox-tool) for inbox tool actions.
 
 ```typescript
 await agent.sendNotificationSignal(
@@ -312,15 +308,11 @@ Notification summaries tell the model that inbox records are waiting:
 
 When Mastra emits a summary, it clears `summaryAt` and sets `summarySignalId` on each summarized record. The records stay pending and readable. When Mastra emits a full notification, it sets `deliveredSignalId` and marks the record `delivered`. If the inbox tool reads a notification first, it can inject the full notification signal and mark the record `seen`, which prevents duplicate full delivery.
 
-Configure a delivery policy on the agent when some notifications should wait for a different dispatch window or summary rollup. Enable scheduled dispatch at the Mastra level when deferred notifications and summary rollups should be delivered automatically.
-
-> **Note:** Visit [`Agent` constructor reference](https://mastra.ai/reference/agents/agent) for `notifications.deliveryPolicy` and [`Mastra` class reference](https://mastra.ai/reference/core/mastra-class) for runtime notification dispatch configuration.
+Configure a delivery policy on the agent when some notifications should wait for a different dispatch window or summary rollup. Enable scheduled dispatch at the Mastra level when deferred notifications and summary rollups should be delivered automatically. Visit [`Agent` constructor reference](https://mastra.ai/reference/agents/agent) for `notifications.deliveryPolicy` and [`Mastra` class reference](https://mastra.ai/reference/core/mastra-class) for runtime notification dispatch configuration.
 
 #### Notification inbox tool
 
-Use `createNotificationInboxTool()` to give agents one tool for inbox actions instead of many CRUD tools. Use `read` after a `<notification-summary>` signal when the agent needs the full records behind the summary. The notification contents are delivered as signals, not as normal tool output.
-
-> **Note:** Visit [`createNotificationInboxTool()` reference](https://mastra.ai/reference/signals/create-notification-inbox-tool) for the setup example, input schema, and action behavior.
+Use `createNotificationInboxTool()` to give agents one tool for inbox actions instead of many CRUD tools. Use `read` after a `<notification-summary>` signal when the agent needs the full records behind the summary. The notification contents are delivered as signals, not as normal tool output. Visit [`createNotificationInboxTool()` reference](https://mastra.ai/reference/signals/create-notification-inbox-tool) for the setup example, input schema, and action behavior.
 
 `sendNotificationSignal()` requires a storage domain with `notifications` support. Use `sendSignal({ type: 'notification' })` only for lower-level notification-shaped context that should bypass inbox storage.
 
@@ -345,7 +337,7 @@ export const mastra = new Mastra({
 })
 ```
 
-`RedisStreamsPubSub` implements both the event delivery contract and distributed leasing, so a single backend handles cross-instance signal delivery and lease ownership. Vercel's one-click Redis integration and Upstash Redis both work well. For more on when a distributed pub/sub is needed, see the [PubSub guide](https://mastra.ai/docs/server/pubsub) and the [`RedisStreamsPubSub` reference](https://mastra.ai/reference/pubsub/redis-streams).
+`RedisStreamsPubSub` implements both the event delivery contract and distributed leasing, so a single backend handles cross-instance signal delivery and lease ownership. Vercel's managed Redis integration and Upstash Redis both work well. For more on when a distributed pub/sub is needed, see the [PubSub guide](https://mastra.ai/docs/server/pubsub) and the [`RedisStreamsPubSub` reference](https://mastra.ai/reference/pubsub/redis-streams).
 
 ## Compatibility and APIs
 
@@ -356,15 +348,11 @@ Mastra still accepts legacy signal payloads such as `type: 'user-message'` and `
 - `type: 'user-message'`: Normalizes to `type: 'user'` and `tagName: 'user'`
 - `type: 'system-reminder'`: Normalizes to `type: 'reactive'` and `tagName: 'system-reminder'`
 
-Existing stored signal rows and older clients continue to load through the compatibility layer. New clients call the message routes when the server supports them; React's thread signal path falls back to the legacy `/signals` route when it detects an older server.
-
-> **Note:** Visit [Agent signals reference](https://mastra.ai/reference/agents/agent) for the full message, signal, and subscription types.
+Existing stored signal rows and older clients continue to load through the compatibility layer. New clients call the message routes when the server supports them; React's thread signal path falls back to the legacy `/signals` route when it detects an older server. Visit [Agent signals reference](https://mastra.ai/reference/agents/agent) for the full message, signal, and subscription types.
 
 ### Approve tool calls
 
-When a subscribed run pauses for tool approval, approve or decline the tool call with the subscription-native methods. The resumed chunks arrive through the existing thread subscription.
-
-> **Note:** Visit [`client.getAgent().sendToolApproval()` reference](https://mastra.ai/reference/client-js/agents) and [server agent routes](https://mastra.ai/reference/server/routes) for request and response shapes.
+When a subscribed run pauses for tool approval, approve or decline the tool call with the subscription-native methods. The resumed chunks arrive through the existing thread subscription. Visit [`client.getAgent().sendToolApproval()` reference](https://mastra.ai/reference/client-js/agents) and [server agent routes](https://mastra.ai/reference/server/routes) for request and response shapes.
 
 ### Use HTTP routes
 
@@ -430,4 +418,5 @@ Use heartbeats together with client-side reconnect logic. Heartbeats reduce idle
 - [Server agent routes](https://mastra.ai/reference/server/routes)
 - [`client.getAgent().subscribeToThread()`](https://mastra.ai/reference/client-js/agents)
 - [`client.getAgent().sendToolApproval()`](https://mastra.ai/reference/client-js/agents)
-- [`RedisStreamsPubSub`](https://mastra.ai/reference/pubsub/redis-streams)
+- [`RedisStreamsPubSub`](https://mastra.ai/reference/pubsub/redis-streams)
+- 📹 [Mastra signals workshop](https://www.youtube.com/watch?v=KLg6uFKz9aw\&t=3020s)

package/.docs/docs/mastra-platform/database.md

@@ -10,7 +10,7 @@ Use a hosted database when your project needs durable storage that's managed by
 
 - **Agent memory**: Persist conversation history, working memory, and semantic recall across sessions.
 - **Application data**: Store and retrieve relational or structured data your project needs at runtime.
-- **Vector search**: Store embeddings for retrieval-augmented generation and semantic search.
+- **Vector search**: Store embeddings for Retrieval-Augmented Generation and semantic search.
 
 ## Providers
 
@@ -41,7 +41,7 @@ For most agent-focused projects, **Turso** is the simplest starting point. It pr
 
 5. Select **Attach database**. Provisioning runs in the background. The database starts in a `provisioning` state and moves to `ready` once the provider finishes setup. Connection details are injected into your project as server runtime environment variables automatically.
 
-> **Note:** Hosted databases are created from your platform project settings. There is currently no CLI or public API for provisioning them.
+> **Note:** Hosted databases are created from your platform project settings. No CLI or public API currently provisions them.
 
 ## Connect from your code
 

package/.docs/docs/mastra-platform/github.md

@@ -4,7 +4,7 @@
 
 The GitHub integration links a Mastra platform project to a GitHub repository. When you push changes to your repository Studio and Server will automatically be deployed.
 
-> **Note:** The integration only works with repositories hosted on GitHub.com. Self-hosted GitHub Enterprise instances are not currently supported.
+> **Note:** The integration only works with repositories hosted on GitHub.com. Self-hosted GitHub Enterprise instances aren't currently supported.
 
 After a repository is linked, the platform:
 

package/.docs/docs/mastra-platform/observability.md

@@ -128,4 +128,8 @@ yarn dlx mastra api trace list
 bun x mastra api trace list
 ```
 
-For observability commands, the CLI targets the hosted observability API and can infer credentials from your project environment. See the [`mastra api` CLI reference](https://mastra.ai/reference/cli/mastra) for available observability commands, filtering, pagination, credential resolution, and direct `curl` examples.
+For observability commands, the CLI targets the hosted observability API and can infer credentials from your project environment. See the [`mastra api` CLI reference](https://mastra.ai/reference/cli/mastra) for available observability commands, filtering, pagination, credential resolution, and direct `curl` examples.
+
+## Related
+
+- 📹 [Mastra observability and Studio workshop](https://www.youtube.com/watch?v=dKO_a3RPra0)

package/.docs/docs/mcp/mcp-apps.md

@@ -81,7 +81,7 @@ calculatorTool._meta = {
 }
 ```
 
-> **Note:** Visit [MCPServer reference](https://mastra.ai/reference/tools/mcp-server) for the full `appResources` configuration.
+Visit [MCPServer reference](https://mastra.ai/reference/tools/mcp-server) for the full `appResources` configuration.
 
 ## Connecting MCP Apps to agents
 
@@ -249,7 +249,7 @@ Establishes the connection to the host. Call this after registering all event ha
 await app.connect()
 ```
 
-> **Note:** See the [`App` class API reference](https://apps.extensions.modelcontextprotocol.io/api/classes/app.App.html) for the full list of methods, callbacks, and lifecycle hooks.
+See the [`App` class API reference](https://apps.extensions.modelcontextprotocol.io/api/classes/app.App.html) for the full list of methods, callbacks, and lifecycle hooks.
 
 ## Using external MCP servers with apps
 
@@ -284,7 +284,7 @@ export const mastra = new Mastra({
 })
 ```
 
-> **Note:** Visit [MCPClient reference](https://mastra.ai/reference/tools/mcp-client) for more details on proxying external servers.
+Visit [MCPClient reference](https://mastra.ai/reference/tools/mcp-client) for more details on proxying external servers.
 
 ## Sandbox security
 

package/.docs/docs/mcp/overview.md

@@ -62,7 +62,7 @@ export const testMcpClient = new MCPClient({
 })
 ```
 
-> **Info:** Visit [MCPClient](https://mastra.ai/reference/tools/mcp-client) for a full list of configuration options.
+Visit [MCPClient](https://mastra.ai/reference/tools/mcp-client) for a full list of configuration options.
 
 > **Authentication:** For connecting to OAuth-protected MCP servers, see the [OAuth Authentication](https://mastra.ai/reference/tools/mcp-client) section.
 
@@ -89,7 +89,7 @@ export const testAgent = new Agent({
 })
 ```
 
-> **Info:** Visit [Agent Class](https://mastra.ai/reference/agents/agent) for a full list of configuration options.
+Visit [Agent Class](https://mastra.ai/reference/agents/agent) for a full list of configuration options.
 
 ## Tool approval
 
@@ -129,7 +129,7 @@ export const testMcpServer = new MCPServer({
 })
 ```
 
-> **Info:** Visit [MCPServer](https://mastra.ai/reference/tools/mcp-server) for a full list of configuration options.
+Visit [MCPServer](https://mastra.ai/reference/tools/mcp-server) for a full list of configuration options.
 
 > **Authentication:** To protect your MCP server with OAuth, see the [OAuth Protection](https://mastra.ai/reference/tools/mcp-server) section.
 
@@ -160,9 +160,7 @@ export const mastra = new Mastra({
 
 ### Static tools
 
-Use the `.listTools()` method to fetch tools from all configured MCP servers. This is suitable when configuration (such as API keys) is static and consistent across users or requests. Call it once and pass the result to the `tools` property when defining your agent.
-
-> **Info:** Visit [listTools()](https://mastra.ai/reference/tools/mcp-client) for more information.
+Use the `.listTools()` method to fetch tools from all configured MCP servers. This is suitable when configuration (such as API keys) is static and consistent across users or requests. Call it once and pass the result to the `tools` property when defining your agent. Visit [listTools()](https://mastra.ai/reference/tools/mcp-client) for more information.
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
@@ -211,7 +209,7 @@ async function handleRequest(userPrompt: string, userApiKey: string) {
 }
 ```
 
-> **Info:** Visit [listToolsets()](https://mastra.ai/reference/tools/mcp-client) for more information.
+Visit [listToolsets()](https://mastra.ai/reference/tools/mcp-client) for more information.
 
 ## Connecting to an MCP registry
 
@@ -412,9 +410,7 @@ As an alternative to MCP, Ampersand's AI SDK also has an adapter for Mastra, so
 
 ## MCP Apps
 
-MCP servers can serve interactive HTML UIs via the MCP Apps extension. Tools with associated `ui://` resources render sandboxed iframes in Studio — both on tool detail pages and inline in agent chat. The app iframe can call server tools and inject messages into the conversation.
-
-> **Note:** Visit [MCP Apps](https://mastra.ai/docs/mcp/mcp-apps) for setup instructions and the app bridge API.
+MCP servers can serve interactive HTML UIs via the MCP Apps extension. Tools with associated `ui://` resources render sandboxed iframes in Studio — both on tool detail pages and inline in agent chat. The app iframe can call server tools and inject messages into the conversation. Visit [MCP Apps](https://mastra.ai/docs/mcp/mcp-apps) for setup instructions and the app bridge API.
 
 ## Related
 

package/.docs/docs/memory/memory-processors.md

@@ -309,6 +309,73 @@ const agent = new Agent({
 
 Both scenarios are safe - guardrails prevent inappropriate content from being persisted to memory
 
+## Handling large attachments
+
+Some storage providers enforce record size limits that base64-encoded file attachments can exceed:
+
+| Provider                                                           | Record size limit |
+| ------------------------------------------------------------------ | ----------------- |
+| [DynamoDB](https://mastra.ai/reference/storage/dynamodb)           | 400 KB            |
+| [Convex](https://mastra.ai/reference/storage/convex)               | 1 MiB             |
+| [Cloudflare D1](https://mastra.ai/reference/storage/cloudflare-d1) | 1 MiB             |
+
+PostgreSQL, MongoDB, and libSQL have higher limits and are usually unaffected.
+
+Use an input processor to upload attachments to external storage, then replace them with URL references before messages are persisted.
+
+```typescript
+import type { Processor } from '@mastra/core/processors'
+import type { MastraDBMessage } from '@mastra/core/memory'
+
+export class AttachmentUploader implements Processor {
+  id = 'attachment-uploader'
+
+  async processInput({ messages }: { messages: MastraDBMessage[] }) {
+    return Promise.all(messages.map(message => this.processMessage(message)))
+  }
+
+  async processMessage(message: MastraDBMessage) {
+    const attachments = message.content.experimental_attachments
+    if (!attachments?.length) return message
+
+    const uploaded = await Promise.all(
+      attachments.map(async attachment => {
+        if (!attachment.url?.startsWith('data:')) return attachment
+
+        const url = await this.upload(attachment.url, attachment.contentType)
+        return { ...attachment, url }
+      }),
+    )
+
+    return { ...message, content: { ...message.content, experimental_attachments: uploaded } }
+  }
+
+  async upload(dataUri: string, contentType?: string): Promise<string> {
+    const base64 = dataUri.split(',')[1]
+    const buffer = Buffer.from(base64, 'base64')
+
+    throw new Error('Implement upload() with your storage provider')
+  }
+}
+```
+
+Use the processor with your agent:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+import { AttachmentUploader } from '../processors/attachment-uploader'
+
+export const supportAgent = new Agent({
+  id: 'support-agent',
+  name: 'Support agent',
+  instructions: 'Answer customer support questions.',
+  model: 'openai/gpt-5.5',
+  memory: new Memory({ lastMessages: 10 }),
+  inputProcessors: [new AttachmentUploader()],
+})
+```
+
 ## Related documentation
 
 - [Processors](https://mastra.ai/docs/agents/processors): General processor concepts and custom processor creation

package/.docs/docs/memory/message-history.md

@@ -6,7 +6,7 @@ Message history is the most basic and important form of memory. It gives the LLM
 
 You can also retrieve message history to display past conversations in your UI.
 
-> **Info:** Each message belongs to a thread (the conversation) and a resource (the user or entity it's associated with). See [Threads and resources](https://mastra.ai/docs/memory/storage) for more detail.
+> **Info:** Each message belongs to a thread (the conversation) and a resource (the user or entity it's associated with). See [Threads and resources](#threads-and-resources) for more detail.
 
 > **Warning:** When you use memory with a client application, send **only the new message** from the client instead of the full conversation history.
 >
@@ -14,9 +14,18 @@ You can also retrieve message history to display past conversations in your UI.
 >
 > For an AI SDK example, see [Using Mastra Memory](https://mastra.ai/guides/build-your-ui/ai-sdk-ui).
 
+## Threads and resources
+
+Mastra organizes conversations using two identifiers:
+
+- **Thread**: A conversation session containing a sequence of messages.
+- **Resource**: The entity that owns the thread, such as a user, organization, project, or another domain entity in your application.
+
+Studio automatically generates a thread and resource ID for you. When calling `stream()` or `generate()` yourself, provide these identifiers explicitly.
+
 ## Getting started
 
-Install the Mastra memory module along with a [storage adapter](https://mastra.ai/docs/memory/storage) for your database. The examples below use `@mastra/libsql`, which stores data locally in a `mastra.db` file.
+Install the Mastra memory module along with a [storage adapter](https://mastra.ai/docs/storage/overview) for your database. The examples below use `@mastra/libsql`, which stores data locally in a `mastra.db` file.
 
 **npm**:
 
@@ -113,6 +122,51 @@ You can use this history in two ways:
 
 > **Tip:** When memory is enabled, [Studio](https://mastra.ai/docs/studio/overview) uses message history to display past conversations in the chat sidebar.
 
+## Thread title generation
+
+Mastra can automatically generate descriptive thread titles based on the user's first message when `generateTitle` is enabled. Use this option when you build a chat interface that renders conversation titles in a thread list or sidebar.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+
+export const supportAgent = new Agent({
+  id: 'support-agent',
+  name: 'Support agent',
+  instructions: 'Answer customer support questions.',
+  model: 'openai/gpt-5.5',
+  memory: new Memory({
+    options: {
+      generateTitle: true,
+    },
+  }),
+})
+```
+
+Title generation runs asynchronously after the agent responds and doesn't affect response time.
+
+To optimize cost or behavior, provide a smaller [`model`](https://mastra.ai/models) and custom `instructions`:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+
+export const supportAgent = new Agent({
+  id: 'support-agent',
+  name: 'Support agent',
+  instructions: 'Answer customer support questions.',
+  model: 'openai/gpt-5.5',
+  memory: new Memory({
+    options: {
+      generateTitle: {
+        model: 'openai/gpt-5-mini',
+        instructions: 'Generate a one-word title.',
+      },
+    },
+  }),
+})
+```
+
 ## Accessing memory
 
 To access memory functions for querying, cloning, or deleting threads and messages, call `getMemory()` on an agent:

package/.docs/docs/memory/observational-memory.md

@@ -217,7 +217,7 @@ new Extractor({
 })
 ```
 
-By default, OM shows the last extracted value to the extractor on later runs. Set `includePreviousExtraction: false` when the Observer should not see the previous value.
+By default, OM shows the last extracted value to the extractor on later runs. Set `includePreviousExtraction: false` when the Observer shouldn't see the previous value.
 
 ```typescript
 new Extractor({
@@ -263,7 +263,7 @@ const memory = new Memory({
 
 This setting adds `WorkingMemoryExtractor`, defaults `workingMemory.agentManaged` to `false`, and defaults `workingMemory.useStateSignals` to `true`. Set `workingMemory.agentManaged: true` if the main agent should still receive working memory tool and instruction injection.
 
-Use `onExtracted` to normalize or react to custom extracted values before they are persisted:
+Use `onExtracted` to normalize or react to custom extracted values before they're persisted:
 
 ```typescript
 new Extractor({
@@ -280,7 +280,7 @@ new Extractor({
 })
 ```
 
-Extractor failures are reported in OM markers and do not block other successful extractor values. See [the API reference](https://mastra.ai/reference/memory/observational-memory) for the full `Extractor` shape.
+Extractor failures are reported in OM markers and don't block other successful extractor values. See [the API reference](https://mastra.ai/reference/memory/observational-memory) for the full `Extractor` shape.
 
 If your Observer model is text-only or its API rejects multimodal input, set `observation.observeAttachments` to `false` to drop attachments before they reach the Observer. The readable placeholders (`[Image #1: ...]`, `[File #1: ...]`) are kept in the transcript so the Observer can still reason about what was shared without receiving the binary payload. The same filter applies to tool results that contain image or file parts:
 
@@ -714,4 +714,5 @@ In practical terms, OM replaces both working memory and message history, and has
 - [Memory Overview](https://mastra.ai/docs/memory/overview)
 - [Message History](https://mastra.ai/docs/memory/message-history)
 - [Memory Processors](https://mastra.ai/docs/memory/memory-processors)
-- [Mastra Code](https://code.mastra.ai/): A coding agent using Observational Memory
+- [Mastra Code](https://code.mastra.ai/): A coding agent using Observational Memory
+- 📹 [Mastra processors and Observational Memory workshop](https://www.youtube.com/watch?v=4Vpp7xQYvl0)

package/.docs/docs/memory/overview.md

@@ -13,7 +13,9 @@ Mastra agents can be configured to store [message history](https://mastra.ai/doc
 
 If the combined memory exceeds the model's context limit, [memory processors](https://mastra.ai/docs/memory/memory-processors) can filter, trim, or prioritize content so the most relevant information is preserved.
 
-Memory results will be stored in one or more of your configured [storage providers](https://mastra.ai/docs/memory/storage).
+Memory results will be stored in one or more of your configured [storage providers](https://mastra.ai/docs/storage/overview).
+
+> **📹 Watch:** Watch [Mastra memory concepts](https://www.youtube.com/watch?v=18iIHQtIPmc) for a conceptual overview of the memory layers agents can use.
 
 ## When to use memory
 
@@ -75,7 +77,7 @@ Use memory when your agent needs to maintain multi-turn conversations that refer
    bun add @mastra/libsql@latest
    ```
 
-   > **Note:** For more details on available providers and how storage works in Mastra, visit the [storage](https://mastra.ai/docs/memory/storage) documentation.
+   For more details on available providers and how storage works in Mastra, visit the [storage](https://mastra.ai/docs/storage/overview) documentation.
 
 3. Add the storage provider to your main Mastra instance to enable memory across all configured agents.
 
@@ -108,7 +110,7 @@ Use memory when your agent needs to maintain multi-turn conversations that refer
    })
    ```
 
-   > **Note:** Visit [Memory Class](https://mastra.ai/reference/memory/memory-class) for a full list of configuration options.
+   Visit [Memory Class](https://mastra.ai/reference/memory/memory-class) for a full list of configuration options.
 
 5. Call your agent, for example in [Studio](https://mastra.ai/docs/studio/overview). Inside Studio, start a new chat with your agent and take a look at the right sidebar. It'll now display various memory-related information.
 
@@ -164,7 +166,7 @@ export const memoryAgent = new Agent({
 })
 ```
 
-> **Note:** See [Observational Memory](https://mastra.ai/docs/memory/observational-memory) for details on how observations and reflections work, and [the reference](https://mastra.ai/reference/memory/observational-memory) for all configuration options.
+See [Observational Memory](https://mastra.ai/docs/memory/observational-memory) for details on how observations and reflections work, and [the reference](https://mastra.ai/reference/memory/observational-memory) for all configuration options.
 
 ## Memory in multi-agent systems
 
@@ -178,7 +180,7 @@ Each delegation creates a fresh `threadId` and a deterministic `resourceId` for
 - **Resource ID**: Derived as `{parentResourceId}-{agentName}`. Because the resource ID is stable across delegations, resource-scoped memory persists between calls. A subagent remembers facts from previous delegations by the same user.
 - **Memory instance**: If a subagent has no memory configured, it inherits the supervisor's `Memory` instance, including all of its options. If the subagent defines its own, that takes precedence.
 
-> **Note:** Title generation (`generateTitle`) is a top-level thread concern and is **not** applied to inherited subagent threads. Because each delegation creates an ephemeral thread that no one sees, running title generation for it would waste an LLM call per delegation. To generate titles for a subagent's own threads, give that subagent its own memory configuration.
+> **Note:** Title generation (`generateTitle`) is a top-level thread concern and **isn't** applied to inherited subagent threads. Because each delegation creates an ephemeral thread that no one sees, running title generation for it would waste an LLM call per delegation. To generate titles for a subagent's own threads, give that subagent its own memory configuration.
 
 The supervisor forwards its conversation context to the subagent so it has enough background to complete the task. Only the delegation prompt and the subagent's response are saved — the full parent conversation isn't stored. You can control which messages reach the subagent with the [`messageFilter`](https://mastra.ai/docs/agents/supervisor-agents) callback.
 
@@ -236,7 +238,7 @@ export const memoryAgent = new Agent({
 })
 ```
 
-> **Note:** Visit [Request Context](https://mastra.ai/docs/server/request-context) for more information.
+Visit [Request Context](https://mastra.ai/docs/server/request-context) for more information.
 
 ## Related