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

package/.docs/docs/getting-started/develop.md

@@ -0,0 +1,196 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Develop
+
+Once you have a Mastra project, you're ready to develop, run, and test your agent.
+
+## Run Mastra locally
+
+The fastest way to see your agent working is in [Mastra Studio](https://mastra.ai/docs/studio/overview). From your project root, start Studio and the local development server with [`mastra dev`](https://mastra.ai/reference/cli/mastra):
+
+**npm**:
+
+```bash
+npx mastra dev
+```
+
+**pnpm**:
+
+```bash
+pnpm dlx mastra dev
+```
+
+**Yarn**:
+
+```bash
+yarn dlx mastra dev
+```
+
+**Bun**:
+
+```bash
+bun x mastra dev
+```
+
+Open Studio at [`http://localhost:4111`](http://localhost:4111) to test your agent and inspect its runs.
+
+The development server also exposes APIs for your agents, tools, and workflows. Open [`http://localhost:4111/api`](http://localhost:4111/api) to browse what's available, then connect your frontend using the [Mastra Client](https://mastra.ai/docs/server/mastra-client).
+
+Changes in your `src/mastra/` directory automatically restart the development server, so you don't need to restart it manually as you build.
+
+## Build with AI
+
+Mastra provides a skill and a CLI to help your coding agent write high-quality Mastra code.
+
+### Mastra skill
+
+AI models may not have up-to-date knowledge of Mastra's APIs. Use the [Mastra skill](https://github.com/mastra-ai/skills) to give your coding agent implementation guidance, best practices, and instructions for fetching the latest Mastra documentation.
+
+Install the skill manually with:
+
+**npm**:
+
+```bash
+npx skills add mastra-ai/skills
+```
+
+**pnpm**:
+
+```bash
+pnpm dlx skills add mastra-ai/skills
+```
+
+**Yarn**:
+
+```bash
+yarn dlx skills add mastra-ai/skills
+```
+
+**Bun**:
+
+```bash
+bun x skills add mastra-ai/skills
+```
+
+Periodically update the skill to get the latest guidance:
+
+**npm**:
+
+```bash
+npx skills update mastra
+```
+
+**pnpm**:
+
+```bash
+pnpm dlx skills update mastra
+```
+
+**Yarn**:
+
+```bash
+yarn dlx skills update mastra
+```
+
+**Bun**:
+
+```bash
+bun x skills update mastra
+```
+
+> **Note:** When you create a project with [create mastra](https://mastra.ai/docs), the command automatically installs the Mastra skill so your coding agent can discover and use it.
+
+### Mastra CLI
+
+Use the [`mastra` CLI](https://mastra.ai/reference/cli/mastra) to give your coding agent a feedback loop for testing updates and inspecting results. The CLI gives it access to agents, workflows, tools, memory, evals, traces, and logs.
+
+For example, your coding agent can run an agent, then pull traces to inspect the results:
+
+```bash
+npx mastra api --url http://localhost:4111 agent run agent '{"messages":"Hello"}'
+npx mastra api --url http://localhost:4111 trace list
+```
+
+Remember to install the [Mastra skill](#mastra-skill) to teach your coding agent how to use the CLI.
+
+## Project structure
+
+One of the first decisions when adopting a framework is how to structure the project. We recommend keeping framework code under `src/mastra/`, with related primitives grouped into their own files or folders. Use `src/mastra/index.ts` as the central place to configure and register them.
+
+A minimal project can look like this:
+
+```text
+src/
+  mastra/
+    agents/
+      agent.ts
+    tools/
+      tool.ts
+    workflows/
+      workflow.ts
+    scorers/
+      scorer.ts
+    skills.ts
+    index.ts
+```
+
+See the [project structure reference](https://mastra.ai/reference/project-structure) for the default layout and recommended conventions.
+
+## File-based agents
+
+> **Beta:** File-based agents are in beta and may change before they're stable.
+
+> **📹 Watch:** [How to create your first file-based agent](https://www.youtube.com/watch?v=5Kfn-oYkJNg\&t=18s)
+
+With file-based agents, Mastra automatically [discovers](https://mastra.ai/reference/file-based-agents/config) agents and related primitives from supported files under `src/mastra/`. You organize those files by convention instead of importing and registering each primitive on your [`Mastra`](https://mastra.ai/reference/core/mastra-class) instance.
+
+The file system becomes a direct representation of your project structure, so you and your coding agent can understand how the project fits together without tracing how everything is wired together in code.
+
+You can use file-based agents throughout your project or adopt them incrementally alongside primitives defined in code. Not every Mastra feature or use case is supported yet.
+
+### Create your first agent
+
+A file-based agent lives in its own directory under `src/mastra/agents/`. To create a working agent, add a `config.ts` file for its model and runtime options and an `instructions.md` file for its always-on prompt:
+
+```text
+src/mastra/agents/
+  writing-assistant/
+    config.ts
+    instructions.md
+```
+
+The directory name becomes the agent's default `id` and `name`. In this example, Mastra registers the agent as `writing-assistant`.
+
+```typescript
+import { agentConfig } from '@mastra/core/agent'
+
+export default agentConfig({
+  model: 'openai/gpt-5.6-sol',
+})
+```
+
+```markdown
+Rewrite text clearly and concisely.
+```
+
+Run `npx mastra dev`, open Studio, and select `writing-assistant` to test it.
+
+### How discovery works
+
+Mastra uses paths to discover and name file-based capabilities. An agent directory supplies the default agent `id` and `name`. For example, `tools/search_docs.ts` registers a tool as `search_docs`, while `skills/style-guide.md` registers a skill as `style-guide`. See the extension paths below.
+
+### Extend your agent
+
+Add files or directories when your agent needs more functionality:
+
+| Path                                                                                       | What it adds                                      |
+| ------------------------------------------------------------------------------------------ | ------------------------------------------------- |
+| [`tools/<tool-name>.ts`](https://mastra.ai/reference/file-based-agents/tools)              | Functions the model can call                      |
+| [`skills/<skill-name>.md`](https://mastra.ai/reference/file-based-agents/skills)           | Detailed guidance the agent loads when relevant   |
+| [`memory.ts`](https://mastra.ai/reference/file-based-agents/memory)                        | Conversation history and working context          |
+| [`workspace.ts` and `workspace/`](https://mastra.ai/reference/file-based-agents/workspace) | Filesystem and shell access                       |
+| [`subagents/<agent-id>/`](https://mastra.ai/reference/file-based-agents/subagents)         | Specialist agents that the parent can delegate to |
+
+Keep each capability next to the agent that uses it. Mastra discovers and registers these files when the development server starts or restarts.
+
+Browse the [file-based agents reference](https://mastra.ai/reference/file-based-agents/config) for all supported file conventions and configuration options.

package/.docs/docs/index.md

@@ -166,4 +166,81 @@ 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.
+## Use cases
+
+<details>
+**Embed agents in your product**
+
+Add AI capabilities to your platform so your users can build or interact with agents.
+
+Used by [Replit](https://mastra.ai/blog/replitagent3), [Fireworks](https://mastra.ai/blog/fireworks-xml-prompting), [Medusa](https://mastra.ai/blog/medusa-ecommerce)
+
+</details>
+
+<details>
+**Customer-facing assistants**
+
+Build agents that handle inquiries, schedule appointments, send reminders, and answer questions via chat, WhatsApp, or voice.
+
+Used by [Vetnio](https://mastra.ai/blog/vetnio), [Lua](https://mastra.ai/blog/lua-scaling)
+
+Templates: [Docs Chatbot](https://mastra.ai/templates/docs-chatbot), [Slack Agent](https://mastra.ai/templates/slack-agent)
+
+</details>
+
+<details>
+**Internal copilots**
+
+Help employees work faster with AI that understands your domain, such as HR queries, clinical documentation, sales prep, or document generation.
+
+Used by [Factorial](https://mastra.ai/blog/factorial-case-study), [Counsel Health](https://mastra.ai/blog/counsel-health), [Cedar](https://mastra.ai/blog/cedar-case-study), [SoftBank](https://mastra.ai/blog/softbank-productivity-mastra-2025-08-20)
+
+Templates: [Chat with PDF](https://mastra.ai/templates/chat-with-pdf), [Google Sheet Analysis](https://mastra.ai/templates/google-sheets-analysis)
+
+</details>
+
+<details>
+**Data analysis agents**
+
+Let users query databases and dashboards in natural language. Connect to your data sources and return answers, charts, or reports.
+
+Used by [Index](https://mastra.ai/blog/index-case-study), [PLAID Japan](https://mastra.ai/blog/plaid-jpn-gcp-agents)
+
+Templates: [Chat with Database](https://mastra.ai/templates/text-to-sql), [CSV to Questions](https://mastra.ai/templates/csv-to-questions)
+
+</details>
+
+<details>
+**Content automation**
+
+Generate, transform, and manage structured content at scale for a content management system, knowledge base, or documentation system.
+
+Used by [Sanity](https://mastra.ai/blog/sanity)
+
+Templates: [Chat with YouTube](https://mastra.ai/templates/chat-with-youtube), [Flash Cards from PDF](https://mastra.ai/templates/flash-cards-from-pdf)
+
+</details>
+
+<details>
+**DevOps and engineering automation**
+
+Automate deployments, debug production issues, manage infrastructure, and handle on-call workflows.
+
+Used by [StarSling](https://mastra.ai/blog/starsling)
+
+Templates: [GitHub PR Code Review](https://mastra.ai/templates/github-pr-code-review-agent), [Browser Agent](https://mastra.ai/templates/browsing-agent)
+
+</details>
+
+<details>
+**Sales and go-to-market workflows**
+
+Turn customer conversations into structured tasks, generate investment memos, or automate outreach sequences.
+
+Used by [Kestral](https://mastra.ai/blog/kestral), [Orange Collective](https://mastra.ai/blog/orange-collective-vc-operating-system), [WorkOS](https://mastra.ai/blog/workos-teaching-mastra)
+
+Templates: [Customer Feedback Summarization](https://mastra.ai/templates/customer-feedback-summarization)
+
+</details>
+
+> **Video:** [A quick tour of the Mastra platform](https://www.youtube.com/watch?v=NosES9aJxCc) shows how the pieces fit together.

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/workspaces.md

@@ -0,0 +1,152 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Workspaces
+
+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.
+
+Every workspace exposes two capabilities:
+
+- 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, authentication, and idle cleanup.
+
+## When workspaces are provisioned
+
+New projects have workspaces enabled by default. When you create an environment, the platform provisions a bucket for it automatically. The sandbox base image is warmed in the background so the first `PlatformSandbox` call starts quickly.
+
+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 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
+
+Install the provider package:
+
+**npm**:
+
+```bash
+npm install @mastra/platform-workspace
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/platform-workspace
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/platform-workspace
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/platform-workspace
+```
+
+Compose the providers into a workspace and register it with Mastra:
+
+```typescript
+import { Workspace } from '@mastra/core/workspace'
+import { PlatformFilesystem, PlatformSandbox } from '@mastra/platform-workspace'
+
+export const workspace = new Workspace({
+  filesystem: new PlatformFilesystem(),
+  sandbox: new PlatformSandbox(),
+})
+```
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { workspace } from './workspace'
+
+export const mastra = new Mastra({
+  workspace,
+})
+```
+
+`PlatformFilesystem` and `PlatformSandbox` read their configuration from environment variables, so you don't pass any options on the platform. The platform injects them at deploy time. See [Environment variables](#environment-variables).
+
+## One bucket, many sandboxes
+
+`PlatformFilesystem` and `PlatformSandbox` have different lifecycles, which 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.
+
+## Environment variables
+
+Every deploy that runs on a platform environment with a workspace receives these variables automatically:
+
+| Variable                       | Contents                                                                                                                                        |
+| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `MASTRA_PLATFORM_ACCESS_TOKEN` | Platform-issued JSON Web Token (JWT) the workspace providers use to authenticate. The token is scoped to the deploy's organization and project. |
+| `MASTRA_PROJECT_ID`            | Project the deploy belongs to.                                                                                                                  |
+| `MASTRA_ENVIRONMENT_ID`        | Environment the deploy belongs to. Selects which sandbox pool the platform uses.                                                                |
+| `MASTRA_PLATFORM_BUCKET_NAME`  | Bucket name attached to the environment. Selects which bucket `PlatformFilesystem` reads and writes.                                            |
+
+These names are reserved. If your project sets any of them explicitly, the platform-managed values take precedence.
+
+## Local development
+
+Reuse the same providers locally by putting the four variables in your `.env` file. Get the project, environment, and bucket values from your project's **Workspaces** tab. For `MASTRA_PLATFORM_ACCESS_TOKEN`, create an `sk_` API token on your organization's settings page under **API Tokens**. Platform deploys use an injected JWT instead.
+
+```bash
+MASTRA_PLATFORM_ACCESS_TOKEN=sk_your-api-token
+MASTRA_PROJECT_ID=your-project-id
+MASTRA_ENVIRONMENT_ID=your-environment-id
+MASTRA_PLATFORM_BUCKET_NAME=your-bucket-name
+```
+
+`PlatformFilesystem` and `PlatformSandbox` behave the same locally as on the platform, they connect to the same bucket and sandbox pool for that environment. Use a `staging` or `preview` environment's variables for local runs if you want to keep production data isolated.
+
+For a purely offline loop that never touches the platform, swap the providers for [`LocalFilesystem`](https://mastra.ai/reference/workspace/local-filesystem) and [`LocalSandbox`](https://mastra.ai/reference/workspace/local-sandbox) in a local build.
+
+## Inspect the workspace
+
+The Workspaces tab in your platform project shows, per environment:
+
+- Bucket status and its contents, with upload, download, and delete actions.
+- Recent sandbox sessions with their command, exit code, and duration.
+- Provisioning failures with a **Retry** action.
+
+## 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, 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.
@@ -459,6 +476,29 @@ const memory = new Memory({
 })
 ```
 
+#### Custom recall guidance
+
+Mastra injects scope-aware instructions that teach the agent when to search, list threads, or read a specific thread. Use `instructions` to append application-specific guidance after those built-in instructions. The built-in instructions are never replaced:
+
+```typescript
+const memory = new Memory({
+  options: {
+    observationalMemory: {
+      model: 'google/gemini-2.5-flash',
+      retrieval: {
+        vector: true,
+        instructions: `
+          Prefer the current conversation when it already contains the answer.
+          For an initial scan, use a small limit with detail="low".
+        `,
+      },
+    },
+  },
+})
+```
+
+This keeps recall-specific guidance attached to the recall tool instead of the agent's global instructions, so it doesn't affect unrelated tasks.
+
 #### What retrieval enables
 
 With retrieval mode enabled, OM:
@@ -684,7 +724,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 +736,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