@mastra/mcp-docs-server 1.2.13-alpha.4 → 1.2.13-alpha.8

package/.docs/docs/agents/agent-approval.md

@@ -108,7 +108,7 @@ A tool's own `requireApproval` setting takes precedence over the function above.
 
 For sensitive tools, bind the approval to the exact tool name and arguments that were shown to the reviewer. If those arguments drift before execution, the tool shouldn't run under the old approval.
 
-The `tool-call-approval` chunk already includes `toolName`, `toolCallId`, and `args`. You can fingerprint those fields when the approval request is shown. The example below uses a simple JSON string as the fingerprint, but in production you should use a stable hash of the tool name and arguments:
+The `tool-call-approval` chunk already includes `toolName`, `toolCallId`, and `args`. You can fingerprint those fields when the approval request is shown. The example below uses a JSON string as the fingerprint, but in production you should use a stable hash of the tool name and arguments:
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
@@ -174,7 +174,7 @@ async function approveReviewedToolCall(runId: string, toolCallId: string, finger
 await consumeApprovalStream(stream)
 ```
 
-In production, store the approved fingerprint in durable storage scoped to the user, run, tool call, and policy version. The `Set` above is intentionally small so the boundary is easy to see: the approval is consumed once, and only for the same canonical tool arguments that were reviewed.
+In production, store the approved fingerprint in durable storage scoped to the user, run, tool call, and policy version. The `Set` above is intentionally small so the boundary is clear: the approval is consumed once, and only for the same canonical tool arguments that were reviewed.
 
 ### Runtime suspension with `suspend()`
 

package/.docs/docs/deployment/workers.md

@@ -17,7 +17,7 @@ Workers matter when any of these apply:
 - Different parts of the system need to scale independently (e.g., more orchestration capacity without more API instances)
 - Background tool calls should run on dedicated compute
 
-If your application handles light traffic and workflows complete quickly, the default in-process setup works fine. Skip the worker infrastructure until you need it.
+If your application handles light traffic and workflows complete fast, the default in-process setup works fine. Skip the worker infrastructure until you need it.
 
 ## Worker types
 
@@ -33,11 +33,11 @@ The orchestration worker requires a PubSub backend that supports pull mode (e.g.
 
 ### Scheduler worker
 
-Polls storage for due cron schedules and publishes `workflow.start` events. It is a producer only, meaning it creates work for the orchestration worker to pick up.
+Polls storage for due cron schedules and publishes `workflow.start` events. It's a producer only, meaning it creates work for the orchestration worker to pick up.
 
 The scheduler reads declarative `schedule` fields from your workflow definitions automatically. See [Scheduled workflows](https://mastra.ai/docs/workflows/scheduled-workflows) for how to declare schedules.
 
-**Do not run more than one scheduler instance.** Multiple schedulers polling the same storage would fire duplicate events for the same schedule.
+**Don't run more than one scheduler instance.** Multiple schedulers polling the same storage would fire duplicate events for the same schedule.
 
 ### Background task worker
 
@@ -47,7 +47,7 @@ The background task worker manages concurrency limits, task lifecycle, and resul
 
 ## How workers run
 
-### In-process (default)
+### In-process mode (default)
 
 With no configuration, Mastra creates and starts workers inside the API process. Events flow through an in-memory PubSub, and everything shares a single Node.js runtime.
 
@@ -64,7 +64,7 @@ This setup needs no external infrastructure beyond your storage adapter. It does
 
 ### Split processes
 
-To run workers separately, configure a distributed [PubSub](https://mastra.ai/docs/server/pubsub) backend and use the `MASTRA_WORKERS` environment variable to control which workers start in each process.
+To run workers in their own processes, configure a distributed [PubSub](https://mastra.ai/docs/server/pubsub) backend and use the `MASTRA_WORKERS` environment variable to control which workers start in each process.
 
 **Redis Streams + PostgreSQL**:
 
@@ -100,38 +100,38 @@ export const mastra = new Mastra({
 })
 ```
 
-Any [supported storage backend](https://mastra.ai/reference/workers/overview) works — swap the storage adapter for your preferred database.
+Any [supported storage backend](https://mastra.ai/reference/workers/overview) works. Swap the storage adapter for your preferred database.
 
 Run the same build artifact in multiple containers, each with a different [`MASTRA_WORKERS`](https://mastra.ai/reference/workers/overview) value to control which worker starts in each process.
 
 Split deployments require a distributed PubSub backend ([`RedisStreamsPubSub`](https://mastra.ai/reference/pubsub/redis-streams) or [`GoogleCloudPubSub`](https://mastra.ai/reference/pubsub/google-cloud-pubsub)), a shared [storage backend](https://mastra.ai/reference/workers/overview), and network connectivity between the orchestration worker and the API.
 
-The [worker deployment guide](https://mastra.ai/guides/deployment/mastra-workers) walks through this setup with a Docker Compose example.
+The [worker deployment guide](https://mastra.ai/guides/deployment/mastra-workers) walks through this setup with Docker Compose and Kubernetes examples.
 
 ## Network architecture
 
-Workers are internal infrastructure. They are not exposed to end users and do not need their own subdomain, public URL, or inbound HTTP route.
+Workers are internal infrastructure. They're not exposed to end users and don't need their own subdomain, public URL, or inbound HTTP route.
 
 In a split deployment:
 
-- **The API server is the only public-facing process.** It serves all client HTTP requests — REST endpoints, agent interactions, workflow triggers, and any custom routes.
-- **Workers connect outbound only.** They pull events from the distributed PubSub backend and read/write to the shared storage database. They do not accept inbound traffic from clients.
-- **The orchestration worker calls the API internally.** It sends step execution requests to the API over the container network using `MASTRA_STEP_EXECUTION_URL`. This is internal service-to-service communication, not a public endpoint.
+- **The API server is the only public-facing process**: It serves all client HTTP requests, including REST endpoints, agent interactions, workflow triggers, and any custom routes.
+- **Workers connect outbound only**: They pull events from the distributed PubSub backend and read/write to the shared storage database. They don't accept inbound traffic from clients.
+- **The orchestration worker calls the API internally**: It sends step execution requests to the API over the container network using `MASTRA_STEP_EXECUTION_URL`. This is internal service-to-service communication, not a public endpoint.
 
 All three worker types (orchestration, scheduler, background task) sit behind the API on a private network. They share access to the PubSub backend and storage database but never receive traffic directly from clients. If a worker-related feature needs an HTTP route (for example, token minting for a voice integration), that route runs on the API server, not on the worker process.
 
 ## Known limitations
 
-- **No dead-letter queue**: Failed events are nacked and retried, but there is no DLQ for events that repeatedly fail.
+- **No dead-letter queue**: Failed events are nacked and retried, but there's no DLQ for events that fail after all retries.
 - **No built-in health endpoint**: Workers don't expose an HTTP health check. Use container-level liveness probes or process monitoring.
 - **Scheduler is single-instance**: Running multiple scheduler processes causes duplicate schedule fires.
 - **Runs stuck in "running" after API crash**: If the API process crashes while executing a workflow step, the run remains in `running` status with no automatic retry. For [durable agents](https://mastra.ai/docs/long-running-agents/durable-agents), set `recovery.durableAgents` to `'auto'` in the Mastra config to automatically re-drive orphaned runs on server restart. See [Crash recovery](https://mastra.ai/docs/long-running-agents/durable-agents) for details.
 
 ## Related
 
-- [Worker deployment guide](https://mastra.ai/guides/deployment/mastra-workers): Docker Compose example and topology options
+- [Worker deployment guide](https://mastra.ai/guides/deployment/mastra-workers): Docker Compose and Kubernetes examples
 - [Worker authentication](https://mastra.ai/docs/server/auth/workers): Secure worker-to-API communication
-- [Workers reference](https://mastra.ai/reference/workers/overview): Environment variables, worker types, and storage backends
+- [Workers reference](https://mastra.ai/reference/workers/overview): Details about worker environment variables and types, with a list of supported storage backends
 - [CLI reference](https://mastra.ai/reference/cli/mastra): `mastra worker build` and `mastra worker start`
 - [PubSub](https://mastra.ai/docs/server/pubsub): Event delivery backends
 - [Scheduled workflows](https://mastra.ai/docs/workflows/scheduled-workflows): Declare cron schedules on workflows

package/.docs/docs/evals/datasets/running-experiments.md

@@ -133,7 +133,7 @@ Visit the [Scorers overview](https://mastra.ai/docs/evals/overview) for details
 
 ## Tool mocks
 
-When an experiment runs an agent that calls side-effecting tools, you can make the run deterministic by attaching static tool mocks to individual dataset items. During the experiment, a mocked tool returns its declared output instead of executing. By default, tools that have no mock on the item run live.
+When an experiment runs an agent that calls side-effecting tools, attach static tool mocks to individual dataset items to make the run deterministic. During the experiment, a mocked tool returns its declared output instead of executing. Tools without a mock on the item run live by default.
 
 Mocks live on the dataset item, so they version with the row and travel with the test case. Each mock declares a tool name, the arguments it expects, and the output to return:
 

package/.docs/docs/index.md

@@ -166,4 +166,4 @@ For other frameworks, see the [framework integration guides](https://mastra.ai/g
 
 Browse [templates](https://mastra.ai/templates) for complete Mastra projects you can clone and adapt.
 
-> **Note:** New to Mastra? Read [What is Mastra?](https://mastra.ai/docs/what-is-mastra) for an overview of the framework, its capabilities, and what you can build with it.
+> **Note:** New to Mastra? Read [What's Mastra?](https://mastra.ai/docs/what-is-mastra) for an overview of the framework, its capabilities, and what you can build with it.

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

@@ -245,7 +245,7 @@ On startup, this discovers every registered durable agent with runs stuck in `ru
 
 ### Manual recovery
 
-If you need finer control — for example gating recovery behind a leader election or running it on a schedule — call the methods directly:
+If you need finer control, such as gating recovery behind a leader election or running it on a schedule, call the methods directly:
 
 ```typescript
 // Recover all durable agents
@@ -261,7 +261,7 @@ await durableAgent.recoverActiveRuns({ runId: 'run-abc-123' })
 
 ### Multi-instance deployments
 
-There is no distributed lease or lock yet. In multi-replica deployments, every replica that starts with `recovery.durableAgents: 'auto'` will race to recover the same runs. For now, either gate recovery behind your own leader election or run it from a single replica.
+Mastra doesn't provide a distributed lease or lock yet. In multi-replica deployments, every replica that starts with `recovery.durableAgents: 'auto'` will race to recover the same runs. For now, either gate recovery behind your own leader election or run it from a single replica.
 
 ## Related
 

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

@@ -10,7 +10,7 @@ The [Mastra platform](https://projects.mastra.ai) provides three products for de
 
 Deploy with a single command, [`mastra deploy`](https://mastra.ai/docs/mastra-platform/deploy), or connect a GitHub repository for push-to-deploy. See the [GitHub integration](https://mastra.ai/docs/mastra-platform/github) for the repository-linked flow.
 
-Each project can run multiple [**Environments**](https://mastra.ai/docs/mastra-platform/environments) (for example `production` and `staging`), provision [**Hosted databases**](https://mastra.ai/docs/mastra-platform/database) from the CLI or project settings to persist application data, and get a managed [**Workspace**](https://mastra.ai/docs/mastra-platform/workspace) per environment that gives agents a filesystem and a sandbox with no manual configuration.
+Each project can run multiple [**Environments**](https://mastra.ai/docs/mastra-platform/environments) (for example `production` and `staging`), provision [**Hosted databases**](https://mastra.ai/docs/mastra-platform/database) from the CLI or project settings to persist application data, and get a managed [**Workspaces**](https://mastra.ai/docs/mastra-platform/workspaces) per environment that gives agents a filesystem and a sandbox with no manual configuration.
 
 [**Trace Intelligence**](https://mastra.ai/docs/mastra-platform/trace-intelligence) finds recurring goals, outcomes, behaviors, and sentiment across your agent traces. Trace Intelligence is available in private beta for selected projects.
 

package/.docs/docs/mastra-platform/{workspace.md → workspaces.md}

@@ -1,13 +1,15 @@
 > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
 
-# Workspace
+# Workspaces
 
-A workspace gives an environment two things your agents can use at runtime:
+A workspace is a set of runtime resources the Mastra platform provisions and hands to your agents at deploy time. Each environment gets its own workspace so `production` and `staging` stay isolated.
 
-- A **bucket** for filesystem storage, exposed to your code as [`PlatformFilesystem`](https://mastra.ai/reference/workspace/platform-filesystem).
-- A **sandbox** for executing commands, exposed as [`PlatformSandbox`](https://mastra.ai/reference/workspace/platform-sandbox).
+Every workspace exposes two capabilities:
 
-Workspaces are provisioned per [environment](https://mastra.ai/docs/mastra-platform/environments), so `production` and `staging` each get their own bucket and sandbox. The platform manages provisioning, credentials, and lifecycle. Your deploy code only needs to construct the providers.
+- One **bucket** for filesystem storage, wrapped by [`PlatformFilesystem`](https://mastra.ai/reference/workspace/platform-filesystem). The bucket is a durable, environment-scoped store agents read from and write to across runs.
+- A pool of **on-demand sandboxes** for command execution, wrapped by [`PlatformSandbox`](https://mastra.ai/reference/workspace/platform-sandbox). Each `PlatformSandbox` instance provisions its own remote sandbox on `start()` and destroys it on `destroy()`. Agents typically spin up many sandboxes per session, use them for a task, and let them go.
+
+Workspaces are scoped to a single [environment](https://mastra.ai/docs/mastra-platform/environments), so `production` and `staging` don't share buckets or sandbox pools. The platform manages provisioning, credentials, and idle cleanup. Your deploy only constructs the providers.
 
 ## When workspaces are provisioned
 
@@ -15,7 +17,7 @@ New projects have workspaces enabled by default. When you create an environment,
 
 Existing projects that haven't opted in show an **Enable workspaces** action in the Workspaces tab. Enabling provisions a bucket for every environment on the project.
 
-If provisioning fails for an environment, for example while Railway is under load, the Workspaces tab shows the failure and offers a retry. The environment itself is still created. Only the workspace is unavailable until you retry.
+If provisioning fails for an environment, for example while the sandbox provider is under load, the Workspaces tab shows the failure and offers a retry. The environment itself is still created. Only the workspace is unavailable until you retry.
 
 ## Use the workspace from your code
 
@@ -68,6 +70,45 @@ export const mastra = new Mastra({
 
 `PlatformFilesystem` and `PlatformSandbox` read their credentials from environment variables the platform injects at deploy time, so you don't pass any options on the platform.
 
+## One bucket, many sandboxes
+
+The two providers have different lifecycles, and the difference matters when you design agents.
+
+**`PlatformFilesystem` is a long-lived handle to the environment's bucket.** All requests, all agents, and all sandboxes in the environment read and write the same object storage. Anything an agent writes is visible on the next request unless you explicitly delete it.
+
+**`PlatformSandbox` is a client for provisioning ephemeral sandboxes.** Each `PlatformSandbox` instance owns one remote sandbox:
+
+- `start()` provisions a fresh sandbox (or reattaches when you passed `sandboxId`).
+- `executeCommand()` runs commands against it.
+- `destroy()` tears the sandbox down. `stop()` is an alias.
+
+The `sandbox` you pass to `Workspace` provides the tools an agent uses inside its own request. When your agent needs another isolated environment, for example a per-task workspace, a per-user tenant, or a background job that shouldn't touch the caller's shell state, construct another `PlatformSandbox`:
+
+```typescript
+import { PlatformSandbox } from '@mastra/platform-workspace'
+
+export async function runInFreshSandbox(command: string) {
+  const sandbox = new PlatformSandbox()
+  await sandbox.start()
+  try {
+    return await sandbox.executeCommand(command)
+  } finally {
+    await sandbox.destroy()
+  }
+}
+```
+
+Or clone a configured sandbox as the template for a fleet, so the clones inherit credentials, environment, network isolation, and defaults without repeating them:
+
+```typescript
+const template = new PlatformSandbox({ networkIsolation: 'PRIVATE' })
+
+const perProjectSandbox = template.clone({ id: `project-${projectId}` })
+await perProjectSandbox.start()
+```
+
+See [`PlatformSandbox` reference](https://mastra.ai/reference/workspace/platform-sandbox) for the full lifecycle, checkpoint recovery, reattachment, and clone options.
+
 ## Injected environment variables
 
 Every deploy that runs on a platform environment with a workspace receives these variables:
@@ -107,5 +148,5 @@ The Workspaces tab in your platform project shows, per environment:
 ## See also
 
 - [`PlatformFilesystem`](https://mastra.ai/reference/workspace/platform-filesystem): reference for the filesystem provider.
-- [`PlatformSandbox`](https://mastra.ai/reference/workspace/platform-sandbox): reference for the sandbox provider.
+- [`PlatformSandbox`](https://mastra.ai/reference/workspace/platform-sandbox): reference for the sandbox provider, including checkpoint recovery and cloning.
 - [Environments](https://mastra.ai/docs/mastra-platform/environments): how environments scope workspaces, variables, and databases.

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

@@ -94,7 +94,7 @@ See [configuration options](https://mastra.ai/reference/memory/observational-mem
 >
 > For an AI SDK example, see [Using Mastra Memory](https://mastra.ai/guides/build-your-ui/ai-sdk-ui).
 
-> **Note:** OM currently only supports `@mastra/pg`, `@mastra/libsql`, `@mastra/mongodb`, and `@mastra/convex` storage adapters. It uses background agents for managing memory. When no model is set, the default model is `google/gemini-2.5-flash`.
+> **Note:** OM currently only supports `@mastra/pg`, `@mastra/libsql`, `@mastra/mysql`, `@mastra/mongodb`, and `@mastra/convex` storage adapters. It uses background agents for managing memory. When no model is set, the default model is `google/gemini-2.5-flash`.
 
 ## Temporal gap markers
 
@@ -378,7 +378,7 @@ new Agent({
 })
 ```
 
-You can also pass an allowlist of mimeType globs (for example `['image/*']`) to forward only the kinds the Observer can handle.
+You can also pass an allowlist of mimeType globs (for example `['image/*']`) to forward only the kinds the Observer can handle. Alternatively, set `observeAttachments: 'auto'` to let Mastra decide from the provider capabilities registry: attachments are forwarded when the Observer model supports multimodal input and dropped otherwise, falling back to `true` when no capability data is available for the model.
 
 ```md
 Date: 2026-01-15
@@ -399,12 +399,29 @@ Example: An agent using Playwright MCP might see 50,000+ tokens per page snapsho
 
 When observations exceed their threshold (default: 40,000 tokens), the Reflector condenses them and combines related items, plus reflects on patterns.
 
+Reflections don't accumulate as a separate, ever-growing layer. Each reflection rewrites the entire observation log. The Reflector's output becomes the new log, and new observations append after it. When the log next hits the threshold, the Reflector re-processes everything, including earlier reflections. It condenses older information more aggressively while keeping recent detail. Memory stays bounded around the reflection threshold no matter how long the conversation runs.
+
 The result is a three-tier system:
 
 1. **Recent messages**: Exact conversation history for the current task
 2. **Observations**: A log of what the Observer has seen
 3. **Reflections**: Condensed observations when memory becomes too long
 
+### How context changes over time
+
+With default settings, the context window doesn't grow unbounded. It oscillates through an observe-and-shrink cycle:
+
+![Chart of context tokens over the course of a conversation with Observational Memory enabled: message history repeatedly grows toward the 30,000 token observation threshold, then shrinks back to around 6,000 tokens as observations activate, while the observation log steps up with each cycle until it reaches the 40,000 token reflection threshold and the Reflector condenses it into reflections](/img/memory/om-context-over-time-light.svg)
+
+1. **0 → 30k tokens**: Message history grows normally. In the background, the Observer buffers observations every \~6k tokens (`bufferTokens: 0.2`).
+2. **30k reached**: Buffered observations activate instantly. Observed messages are removed from the context window and only \~6k tokens of recent history remain (`bufferActivation: 0.8` retains 20% of the threshold). The \~24k tokens of removed messages become roughly 1-5k tokens of observations at typical 5-40x compression.
+3. **Repeat**: History grows from \~6k back toward 30k and shrinks again. Each cycle appends to the observation log, which grows much more slowly than raw history.
+4. **Observations reach 40k**: The Reflector creates a smaller log from the current observations and any earlier reflections.
+
+In the normal buffered cycle, raw history oscillates between roughly 6k and 30k tokens. The observation log stays around 40k tokens, however long the conversation runs. These are activation thresholds rather than hard caps. If background buffering doesn't keep pace, history can grow past the threshold until `blockAfter` (default `1.2`) forces a synchronous observation at \~36k tokens (\~48k for reflection) as a safety ceiling.
+
+With [`shareTokenBudget`](https://mastra.ai/reference/memory/observational-memory) enabled, the two budgets pool together. While the observation log is small, message history can expand into the unused observation space (up to \~70k tokens with the defaults) before observation triggers. It then shrinks as observations accumulate.
+
 ### Retrieval mode
 
 Normal OM compresses messages into observations, which is great for staying on task, but the original wording is gone. Retrieval mode fixes this by keeping each observation group linked to the raw messages that produced it. When the agent needs exact wording, tool output, or chronology that the summary compressed away, it can call a `recall` tool to page through the source messages.
@@ -684,7 +701,7 @@ Reflection works similarly, the Reflector runs in the background when observatio
 | ------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `observation.bufferTokens`            | `0.2`   | How often to buffer. `0.2` means every 20% of `messageTokens`. With the default 30k threshold, that's roughly every 6k tokens. Can also be an absolute token count (e.g. `5000`).                                                                                             |
 | `observation.bufferActivation`        | `0.8`   | How aggressively to clear the message window on activation. `0.8` means remove enough messages to keep only 20% of `messageTokens` remaining. Lower values keep more message history.                                                                                         |
-| `observation.blockAfter`              | `1.2`   | Safety threshold as a multiplier of `messageTokens`. At `1.2`, synchronous observation is forced at 36k tokens (1.2 × 30k). Only matters if buffering can't keep up.                                                                                                          |
+| `observation.blockAfter`              | `1.2`   | Safety net if buffering can't keep up. Values from 1 up to (but not including) 100 multiply `messageTokens`: at `1.2`, synchronous observation is forced at 36k tokens (1.2 × 30k). Values of 100 or more are absolute token counts (e.g. `50_000`).                          |
 | `activateAfterIdle`                   | none    | Forces buffered observations to activate after a period of inactivity, even before `observation.messageTokens` is reached. Accepts a numeric millisecond value such as `300_000`, duration strings like `"5m"` or `"1hr"`, or `"auto"` for a provider-aware prompt cache TTL. |
 | `activateOnProviderChange`            | `false` | Forces buffered observations to activate when the next step uses a different `provider/model` than the one that produced the latest assistant step. Use this when switching providers or models would invalidate prompt cache reuse.                                          |
 | `reflection.bufferActivation`         | `0.5`   | When to start background reflection. `0.5` means reflection begins when observations reach 50% of the `observationTokens` threshold.                                                                                                                                          |
@@ -696,16 +713,16 @@ If you're relying on prompt caching, set `activateAfterIdle` to `"auto"` or to a
 
 With `"auto"`, Mastra chooses an idle activation TTL from the active model provider:
 
-| Provider                                                                                | Auto TTL  |
-| --------------------------------------------------------------------------------------- | --------- |
-| Anthropic, OpenRouter, unknown providers, xAI                                           | 5 minutes |
-| DeepSeek                                                                                | 1 hour    |
-| Google Gemini                                                                           | 24 hours  |
-| Groq                                                                                    | 2 hours   |
-| OpenAI with `providerOptions.openai.promptCacheRetention: "24h"`                        | 1 hour    |
-| OpenAI with `providerOptions.openai.promptCacheRetention: "in_memory"`                  | 5 minutes |
-| OpenAI `gpt-4*`, `gpt-5`, `gpt-5-*`, `gpt-5.1*`, `gpt-5.2*`, `gpt-5.3*`, and `gpt-5.4*` | 5 minutes |
-| Other OpenAI models                                                                     | 1 hour    |
+| Provider                                                                                               | Auto TTL  |
+| ------------------------------------------------------------------------------------------------------ | --------- |
+| Anthropic, OpenRouter, unknown providers, xAI                                                          | 5 minutes |
+| DeepSeek                                                                                               | 1 hour    |
+| Google Gemini                                                                                          | 24 hours  |
+| Groq                                                                                                   | 2 hours   |
+| OpenAI with `providerOptions.openai.promptCacheRetention: "24h"`                                       | 1 hour    |
+| OpenAI with `providerOptions.openai.promptCacheRetention: "in_memory"`                                 | 5 minutes |
+| OpenAI `gpt-4*`, `gpt-5`, `gpt-5-*`, and `gpt-5.1` through `gpt-5.4` (including `-` suffixed variants) | 5 minutes |
+| Other OpenAI models                                                                                    | 1 hour    |
 
 ```typescript
 const memory = new Memory({

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

@@ -172,6 +172,20 @@ export const memoryAgent = new Agent({
 
 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.
 
+## What the model sees
+
+Each memory feature is added to either the system messages or the conversation messages in the request sent to the model. The layers depend on the features you've enabled. Working memory and semantic recall only appear when configured. The same applies to Observational Memory, while message history is on by default. The diagram shows where each enabled layer is placed in the request. The list below describes what each layer contributes:
+
+![Diagram showing how Mastra assembles the model context: system messages containing agent instructions, call-time system messages, working memory, cross-thread semantic recall, and Observational Memory, followed by conversation messages where message history and same-thread semantic recall interleave by timestamp, then call-time context messages, and finally the new user message](/img/memory/memory-context-window-light.svg)
+
+- [Working memory](https://mastra.ai/docs/memory/working-memory) is injected as a system message containing the template and the stored data. With `useStateSignals`, it's delivered as a state signal instead.
+- [Semantic recall](https://mastra.ai/docs/memory/semantic-recall) matches from the current thread are inserted as regular messages and interleave with message history by timestamp. Matches from other threads are formatted into a system message instead.
+- [Message history](https://mastra.ai/docs/memory/message-history) adds the last N messages in chronological order. Your new message always comes last.
+- [Observational Memory](https://mastra.ai/docs/memory/observational-memory) replaces old raw history: reflections and observations live in a system message, and only messages that haven't been observed yet remain in the conversation. A short continuation reminder is placed at the start of the conversation messages.
+- Context messages are the optional `context` array passed on a call, for example `agent.generate(msg, { context: [...] })`. Use them for one-off background such as app state or your own RAG results. They appear as regular conversation messages for that request only and are never saved to memory.
+
+Conversation messages are ordered by timestamp and deduplicated by message ID, so recalled older messages appear before recent history. Context messages passed at call time are stamped with the current time, which places them after history and recall but before your new message. To inspect the exact context for a real request, use [Tracing](https://mastra.ai/docs/observability/tracing/overview) and open the LLM call spans, see [Observability](#observability) below.
+
 ## Memory in multi-agent systems
 
 When a [supervisor agent](https://mastra.ai/docs/agents/supervisor-agents) delegates to a subagent, Mastra isolates subagent memory automatically. No flag enables this as it happens on every delegation. Understanding how this scoping works lets you decide what stays private and what to share intentionally.

package/.docs/docs/server/auth/workers.md

@@ -57,7 +57,7 @@ services:
   orchestration-worker:
     environment:
       MASTRA_WORKER_AUTH_TOKEN: ${WORKER_TOKEN}
-      MASTRA_STEP_EXECUTION_URL: http://api:4111/api
+      MASTRA_STEP_EXECUTION_URL: http://api:4111/api # Use HTTPS in production
       # ... other env vars
 ```
 
@@ -65,6 +65,8 @@ services:
 WORKER_TOKEN=sk-worker-secret-token
 ```
 
+These examples use `http://` for local development. In production, use HTTPS URLs and terminate TLS with a service mesh or ingress controller. See [Security recommendations](#security-recommendations).
+
 The orchestration worker reads `MASTRA_WORKER_AUTH_TOKEN` and sends it as a `Bearer` token in the `Authorization` header on every step execution request.
 
 ## Auth credential types
@@ -87,7 +89,7 @@ Send the credential as `x-worker-api-key` instead of `Authorization`:
 import { HttpRemoteStrategy } from '@mastra/core/worker'
 
 const strategy = new HttpRemoteStrategy({
-  serverUrl: 'http://api:4111/api',
+  serverUrl: 'http://api:4111/api', // Use HTTPS in production
   auth: { type: 'api-key', key: process.env.WORKER_API_KEY! },
 })
 ```
@@ -102,7 +104,7 @@ Use any header name and value:
 import { HttpRemoteStrategy } from '@mastra/core/worker'
 
 const strategy = new HttpRemoteStrategy({
-  serverUrl: 'http://api:4111/api',
+  serverUrl: 'http://api:4111/api', // Use HTTPS in production
   auth: {
     type: 'header',
     name: 'X-Internal-Service-Key',
@@ -111,7 +113,7 @@ const strategy = new HttpRemoteStrategy({
 })
 ```
 
-## Push-mode broker authentication
+## Push-mode broker auth
 
 When using a push-mode PubSub (like Google Cloud Pub/Sub), the broker POSTs events directly to the `/api/workflows/events` endpoint. The broker attaches its own credentials. For example, Google Cloud Pub/Sub sends a Google-signed OIDC token.
 
@@ -121,7 +123,7 @@ Your auth provider's `authenticateToken` callback must recognize whatever creden
 
 - **Use different tokens for different worker types.** This lets you revoke access to one worker without affecting others.
 - **Rotate tokens on a schedule.** Update the `WORKER_TOKEN` environment variable and restart the affected containers.
-- **Use TLS in production.** Worker-to-API communication should go over HTTPS to protect tokens in transit. Within a private network (Docker bridge, Kubernetes cluster), plain HTTP is acceptable.
+- **Use TLS in production.** Worker-to-API communication should go over HTTPS to protect tokens in transit. This applies to all environments, including Kubernetes clusters and Docker networks. Use a service mesh (e.g., Istio, Linkerd) or TLS-terminating ingress to encrypt internal traffic.
 - **Restrict network access.** The step execution and event endpoints are internal. If possible, keep them off the public internet using network policies or firewall rules.
 
 ## Related

package/.docs/docs/server/mastra-client.md

@@ -69,6 +69,66 @@ The Mastra Client SDK exposes all resources served by the Mastra Server.
 - **[Logs](https://mastra.ai/reference/client-js/logs)**: View logs and debug system behavior.
 - **[Telemetry](https://mastra.ai/reference/client-js/telemetry)**: View app performance and trace activity.
 
+## Create and run stored workflows
+
+Use `upsertStoredWorkflow()` to create or replace a persisted workflow definition. A successful upsert validates the complete definition, registers it with the running Mastra instance, and makes it available through the standard workflow execution API.
+
+The following example creates a mapping workflow, reads the stored definition, runs it, and then deletes it:
+
+```typescript
+import { MastraClient } from '@mastra/client-js'
+import type { UpsertStoredWorkflowParams } from '@mastra/client-js'
+
+const client = new MastraClient({
+  baseUrl: process.env.MASTRA_API_URL || 'http://localhost:4111',
+})
+
+const definition = {
+  id: 'greeting-workflow',
+  description: 'Returns a greeting for the supplied name',
+  inputSchema: {
+    type: 'object',
+    properties: { name: { type: 'string' } },
+    required: ['name'],
+  },
+  outputSchema: {
+    type: 'object',
+    properties: { message: { type: 'string' } },
+    required: ['message'],
+  },
+  graph: [
+    {
+      type: 'mapping',
+      id: 'create-greeting',
+      mapConfig: JSON.stringify({
+        message: { template: 'Hello, ${initData.name}!' },
+      }),
+    },
+  ],
+} satisfies UpsertStoredWorkflowParams
+
+await client.upsertStoredWorkflow(definition)
+
+const storedWorkflow = client.getStoredWorkflow(definition.id)
+const storedDefinition = await storedWorkflow.details()
+
+const workflow = client.getWorkflow(storedDefinition.id)
+const run = await workflow.createRun()
+const result = await run.startAsync({ inputData: { name: 'Ada' } })
+
+console.log(result)
+
+await storedWorkflow.delete()
+```
+
+Use `listStoredWorkflows()` to list persisted definitions. Calling `upsertStoredWorkflow()` again with the same `id` replaces the stored definition and live workflow registration.
+
+> **Warning:** Durable storage requires a configured storage adapter that supports the `workflowDefinitions` domain. Without that domain, Core can register a workflow in memory, but the server's stored-workflow API can't preserve it across restarts.
+>
+> Stored definitions support declarative agent, tool, mapping, nested workflow, parallel, foreach, sleep, sleep-until, conditional, and loop entries. They can't contain JavaScript closures. Conditional and loop logic must use the declarative predicate format, and referenced agents, tools, and nested workflows must already be registered.
+>
+> Authenticated servers require `stored-workflows:read` or `stored-workflows:write` for definition operations and `workflows:execute` to run the workflow.
+
 ## Generating responses
 
 Call `.generate()` with a string prompt:

package/.docs/docs/server/pubsub.md

@@ -124,6 +124,6 @@ Visit the [PubSub reference](https://mastra.ai/reference/pubsub/base) for the fu
 
 - [PubSub reference](https://mastra.ai/reference/pubsub/base)
 - [Mastra class](https://mastra.ai/reference/core/mastra-class)
+- [Workers](https://mastra.ai/docs/deployment/workers): Run workflow orchestration and background tasks in dedicated processes using PubSub
 - [Background task streaming](https://mastra.ai/docs/long-running-agents/background-tasks)
-- [Scheduled workflows](https://mastra.ai/docs/workflows/scheduled-workflows)
-- [Workers](https://mastra.ai/docs/deployment/workers): Run workflow orchestration and background tasks in dedicated processes using PubSub
+- [Scheduled workflows](https://mastra.ai/docs/workflows/scheduled-workflows)

package/.docs/docs/what-is-mastra.md

@@ -1,10 +1,10 @@
 > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
 
-# What is Mastra?
+# What's Mastra?
 
-Mastra is an open-source TypeScript framework for building AI applications and autonomous AI systems. Use it for anything from an AI feature inside an existing product to long-running agents that run entire processes on their own, such as a software factory that plans, builds, reviews, and ships code.
+Mastra is an open-source TypeScript framework for building AI applications and autonomous AI systems. Use it for anything from an AI feature inside an existing product to long-running agents that run entire processes on their own, such as a software factory that plans, builds, reviews, and releases code.
 
-Mastra gives you everything you need to build an agent harness out of the box. It's built on established patterns, so you make fewer integration decisions and spend more time on your product. And, as you'd expect from an AI framework, it includes a [skill and CLI](https://mastra.ai/docs/getting-started/build-with-ai) that help your coding agent write accurate, up-to-date Mastra code.
+Mastra gives you everything you need to build an agent harness out of the box. It's built on established patterns, so you make fewer integration decisions and spend more time on your product. It also includes a [skill and CLI](https://mastra.ai/docs/getting-started/build-with-ai) that help your coding agent write accurate, up-to-date Mastra code.
 
 Run Mastra standalone or inside your existing web server, and call your agents from your own code, over HTTP using the [Mastra client](https://mastra.ai/docs/server/mastra-client), or from channels (for example, Slack).
 
@@ -29,10 +29,10 @@ export const supportAgent = new Agent({
 
 Then add the capabilities your agent needs:
 
-- **Act in real environments**: Use [workspaces](https://mastra.ai/docs/workspace/overview) so agents can read and write files, run commands, and work inside a sandbox.
+- **Act in real environments**: Use [workspaces](https://mastra.ai/docs/workspace/overview) so agents can read and write files or run commands. They can also work inside a sandbox.
 - **Bring the right context**: Use tools, [memory](https://mastra.ai/docs/memory/observational-memory), [skills](https://mastra.ai/docs/agents/skills), and domain knowledge so agents remember what matters and stay within the context window.
 - **Coordinate complex work**: Run typed [workflows](https://mastra.ai/docs/workflows/overview), [tasks](https://mastra.ai/docs/agents/using-tools), and [subagents](https://mastra.ai/docs/agents/supervisor-agents) when work needs multiple steps or parallel execution.
-- **Control the agent loop**: [Suspend](https://mastra.ai/docs/agents/agent-approval) for human approval, steer an in-flight loop with [signals](https://mastra.ai/docs/long-running-agents/signals), or queue input for the next turn.
+- **Control the agent loop**: [Suspend](https://mastra.ai/docs/agents/agent-approval) for human approval or steer an in-flight loop with [signals](https://mastra.ai/docs/long-running-agents/signals). You can also queue input for the next turn.
 - **Meet users where they work**: Connect agents to Slack, Discord, GitHub, and other [channels](https://mastra.ai/docs/capabilities/channels/overview).
 - **Manage risk and cost**: Configure authentication, multi-tenant isolation, and [guardrails](https://mastra.ai/docs/agents/guardrails), including [`CostGuardProcessor`](https://mastra.ai/reference/processors/cost-guard-processor).
 
@@ -42,13 +42,13 @@ See the left-hand sidebar for the full menu of features.
 
 ![Agents page in Mastra Studio. A sidebar lists primitives like agents, workflows, and tools, a middle panel lists recent chats, and a chat panel shows the agent responding to a prompt with collapsible tool calls and a task list tracking progress. Below the chat is a message box with a model picker.](/assets/images/studio-agent-chat-e516834f26abd332aa54cbffa7553028.png)
 
-[Studio](https://mastra.ai/docs/studio/overview) is usually the first place you go after creating a Mastra app. It gives you a live environment for testing agents, inspecting runs, and iterating quickly.
+[Studio](https://mastra.ai/docs/studio/overview) is usually the first place you go after creating a Mastra app. It gives you a live environment where you can test agents and inspect runs as you iterate.
 
-Studio isn't just for engineers. Deploy it and share it with your team, so collaborators can try an agent before it ships. With the [Editor](https://mastra.ai/docs/editor/overview) and [Agent Builder](https://mastra.ai/docs/agent-builder/overview), non-technical teammates can create and iterate on agents themselves, with every change versioned in code.
+Studio isn't limited to engineers. Deploy it and share it with your team, so collaborators can try an agent before it goes to production. With the [Editor](https://mastra.ai/docs/editor/overview) and [Agent Builder](https://mastra.ai/docs/agent-builder/overview), non-technical teammates can create and iterate on agents themselves, with every change versioned in code.
 
 ## Observability and evals
 
-![Traces page in Mastra Studio. A table lists recent agent runs with timestamps and inputs. A details panel shows the selected trace as an expandable tree of model, tool, and workspace spans with per-span timings, plus actions to evaluate the trace or save it as a dataset item.](/assets/images/studio-traces-e061dbd62a9c7f2ac2d61ad172125be6.png)
+![Traces page in Mastra Studio. A table lists recent agent runs with timestamps and inputs. Beside it, a details panel shows the selected trace as an expandable tree of model, tool, and workspace spans with per-span timings, plus actions to evaluate the trace or save it as a dataset item.](/assets/images/studio-traces-e061dbd62a9c7f2ac2d61ad172125be6.png)
 
 Mastra has built-in logs, traces, and metrics, so you can understand every run in development and production. See [Observability](https://mastra.ai/docs/observability/overview).
 
@@ -59,9 +59,9 @@ Evals close the loop. Score outputs with rule-based or LLM-as-judge [scorers](ht
 Some agents finish in a single request. Others run for hours or days, like a sales agent that watches for signups or an SRE agent that handles incidents. Mastra supports [long-running agents](https://mastra.ai/docs/long-running-agents/durable-agents) with these capabilities:
 
 - **Survive restarts and disconnects**: [Durable agents](https://mastra.ai/docs/long-running-agents/durable-agents) persist run state so work resumes and clients reconnect.
-- **Wake and steer agents mid-run**: Send [messages and signals](https://mastra.ai/docs/long-running-agents/signals) to wake an agent, add context, or queue input.
+- **Wake and steer agents mid-run**: Send [messages and signals](https://mastra.ai/docs/long-running-agents/signals) to wake an agent or add context. You can also queue input.
 - **Keep working toward a goal**: [Goals](https://mastra.ai/docs/long-running-agents/goals) persist an objective until it's met or the run budget is spent.
-- **Run work outside the request**: Use [schedules](https://mastra.ai/docs/long-running-agents/schedules) and [background tasks](https://mastra.ai/docs/long-running-agents/background-tasks) for recurring jobs, slow tools, and work that shouldn't block the agent loop.
+- **Run work outside the request**: Use [schedules](https://mastra.ai/docs/long-running-agents/schedules) and [background tasks](https://mastra.ai/docs/long-running-agents/background-tasks) for recurring jobs or slow tools. They also handle work that shouldn't block the agent loop.
 
 For long-running interactive applications, [AgentController](https://mastra.ai/docs/agent-controller/overview) manages threads, modes, tool approvals, and model switching. It powers [Mastra Code](https://code.mastra.ai/) and lets you build a Claude Code-style experience for your own domain.
 

package/.docs/docs/workflows/overview.md

@@ -545,5 +545,5 @@ For a closer look at workflows, see our [Workflow Guide](https://mastra.ai/guide
 - [Control Flow](https://mastra.ai/docs/workflows/control-flow)
 - [Suspend and Resume](https://mastra.ai/docs/workflows/suspend-and-resume)
 - [Error Handling](https://mastra.ai/docs/workflows/error-handling)
-- [Workers](https://mastra.ai/docs/deployment/workers): Offload workflow orchestration to dedicated processes in production
+- [Workers](https://mastra.ai/docs/deployment/workers): Run workflow execution in dedicated background processes
 - 📹 [Agentic workflows with Mastra workshop](https://www.youtube.com/watch?v=HGt8pVPpX9g)

package/.docs/docs/workflows/scheduled-workflows.md

@@ -181,4 +181,5 @@ Manage Inngest schedules from the [Inngest dashboard](https://www.inngest.com/do
 
 - [Workflow overview](https://mastra.ai/docs/workflows/overview)
 - [Suspend and resume](https://mastra.ai/docs/workflows/suspend-and-resume)
+- [Workers](https://mastra.ai/docs/deployment/workers): The [scheduler worker](https://mastra.ai/docs/deployment/workers) runs cron schedules in a dedicated process
 - [Agent schedules](https://mastra.ai/docs/long-running-agents/schedules): Run an agent rather than a workflow on a cron schedule, and manage both schedule types at runtime through `mastra.schedules`.

package/.docs/guides/deployment/kubernetes.md

@@ -294,5 +294,7 @@ The pod that handles the approval loads the suspended run from Postgres. It then
 
 - [PubSub](https://mastra.ai/docs/server/pubsub)
 - [Durable agents](https://mastra.ai/docs/long-running-agents/durable-agents)
+- [Workers](https://mastra.ai/docs/deployment/workers): Split background processing into separate containers on Kubernetes
+- [Worker deployment guide](https://mastra.ai/guides/deployment/mastra-workers): Full Kubernetes manifests for orchestration, scheduler, and background task workers
 - [Mastra server](https://mastra.ai/docs/server/mastra-server)
 - [Deployment overview](https://mastra.ai/docs/deployment/overview)