@mastra/mcp-docs-server 1.1.17-alpha.9 → 1.1.17

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

@@ -95,27 +95,72 @@ The result is a three-tier system:
 
 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.
 
+#### Browsing only
+
+Set `retrieval: true` to enable the recall tool for browsing raw messages. No vector store needed. By default, the recall tool can browse across all threads for the current resource.
+
 ```typescript
 const memory = new Memory({
   options: {
     observationalMemory: {
       model: 'google/gemini-2.5-flash',
-      scope: 'thread',
       retrieval: true,
     },
   },
 })
 ```
 
+#### With semantic search
+
+Set `retrieval: { vector: true }` to also enable semantic search. This reuses the vector store and embedder already configured on your Memory instance:
+
+```typescript
+const memory = new Memory({
+  storage,
+  vector: myVectorStore,
+  embedder: myEmbedder,
+  options: {
+    observationalMemory: {
+      model: 'google/gemini-2.5-flash',
+      retrieval: { vector: true },
+    },
+  },
+})
+```
+
+When vector search is configured, new observation groups are automatically indexed at buffer time and during synchronous observation (fire-and-forget, non-blocking). Semantic search returns observation-group matches with their raw source message ID ranges, so the recall tool can show the summarized memory alongside where it came from.
+
+#### Restricting to the current thread
+
+By default, the recall tool scope is `'resource'` — the agent can list threads, browse other threads, and search across all conversations. Set `scope: 'thread'` to restrict the agent to only the current thread:
+
+```typescript
+const memory = new Memory({
+  options: {
+    observationalMemory: {
+      model: 'google/gemini-2.5-flash',
+      retrieval: { vector: true, scope: 'thread' },
+    },
+  },
+})
+```
+
+#### What retrieval enables
+
 With retrieval mode enabled, OM:
 
 - Stores a `range` (e.g. `startId:endId`) on each observation group pointing to the messages it was derived from
+
 - Keeps range metadata visible in the agent's context so the agent knows which observations map to which messages
-- Registers a `recall` tool the agent can call to page through the raw messages behind any range
 
-Retrieval mode is only active for thread-scoped OM. Setting `retrieval: true` with `scope: 'resource'` has no effect — OM keeps resource-scoped behavior but skips retrieval-mode context and does not register the `recall` tool.
+- Registers a `recall` tool the agent can call to:
+
+  - Page through the raw messages behind any observation group range
+  - Search by semantic similarity (`mode: "search"` with a `query` string) — requires `vector: true`
+  - List all threads (`mode: "threads"`), browse other threads (`threadId`), and search across all threads (default `scope: 'resource'`)
+  - When `scope: 'thread'`: restrict browsing and search to the current thread only
 
-See the [recall tool reference](https://mastra.ai/reference/memory/observational-memory) for the full API (detail levels, part indexing, pagination, and token limiting).
+See the [recall tool reference](https://mastra.ai/reference/memory/observational-memory) for the full API (detail levels, part indexing, pagination, cross-thread browsing, and token limiting).
 
 ## Models
 

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

@@ -133,6 +133,23 @@ export const mastraClient = new MastraClient({
 
 > **Info:** Visit [MastraClient](https://mastra.ai/reference/client-js/mastra-client) for more configuration options.
 
+## Credentials and session cookies
+
+**Authenticate Mastra API calls with session cookies** when your UI and Mastra API are not on the same origin—different host, subdomain, or port (for example Mastra Studio on one port and a custom server on another). Add **`credentials: 'include'`** to `MastraClient` so each request carries the cookies the user already has after sign-in. Skip this and you will often get **`401`** responses from Mastra even though login succeeded in the browser.
+
+```typescript
+import { MastraClient } from '@mastra/client-js'
+
+export const mastraClient = new MastraClient({
+  baseUrl: process.env.MASTRA_API_URL || 'http://localhost:4111',
+  credentials: 'include',
+})
+```
+
+**Allow credentialed cross-origin requests on your server**—see [CORS: requests with credentials](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS#requests_with_credentials). You need a concrete `Access-Control-Allow-Origin` (not `*`) and `Access-Control-Allow-Credentials: true`, or the browser will block the call before it reaches Mastra.
+
+**Using `@mastra/react`?** Wrap your app with `MastraReactProvider`, set `baseUrl` and `apiPrefix` to match your server, and rely on the default `credentials: 'include'`. Change `credentials` only when you deliberately want `same-origin` or `omit` behavior.
+
 ## Adding request cancelling
 
 `MastraClient` supports request cancellation using the standard Node.js `AbortSignal` API. Useful for canceling in-flight requests, such as when users abort an operation or to clean up stale network calls.

package/.docs/docs/server/server-adapters.md

@@ -521,7 +521,21 @@ The adapter registers routes for both HTTP and SSE (Server-Sent Events) transpor
 
 ### Serverless mode
 
-For serverless environments like Cloudflare Workers or Vercel Edge, enable stateless mode via `mcpOptions`:
+For serverless environments like Cloudflare Workers or Vercel Edge, enable stateless mode via `mcpOptions`.
+
+When using the Mastra deployer (the standard `mastra dev` / `mastra build` path), set `mcpOptions` in your server config:
+
+```typescript
+const mastra = new Mastra({
+  server: {
+    mcpOptions: {
+      serverless: true,
+    },
+  },
+})
+```
+
+When manually creating a server adapter, pass `mcpOptions` directly:
 
 ```typescript
 const server = new MastraServer({

package/.docs/models/gateways/openrouter.md

@@ -117,7 +117,7 @@ ANTHROPIC_API_KEY=ant-...
 | `nousresearch/hermes-4-70b`                                     |
 | `nvidia/nemotron-3-nano-30b-a3b:free`                           |
 | `nvidia/nemotron-3-super-120b-a12b`                             |
-| `nvidia/nemotron-3-super-120b-a12b-free`                        |
+| `nvidia/nemotron-3-super-120b-a12b:free`                        |
 | `nvidia/nemotron-nano-12b-v2-vl:free`                           |
 | `nvidia/nemotron-nano-9b-v2`                                    |
 | `nvidia/nemotron-nano-9b-v2:free`                               |

package/.docs/models/index.md

@@ -1,6 +1,6 @@
 # Model Providers
 
-Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 3595 models from 95 providers through a single API.
+Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 3616 models from 95 providers through a single API.
 
 ## Features
 

package/.docs/models/providers/bailing.md

@@ -5,7 +5,7 @@ Access 2 Bailing models through Mastra's model router. Authentication is handled
 Learn more in the [Bailing documentation](https://alipaytbox.yuque.com/sxs0ba/ling/intro).
 
 ```bash
-BAILING_API_TOKEN=your-api-key
+BAILING_API_TOKEN=your-api-token
 ```
 
 ```typescript

package/.docs/models/providers/cloudflare-workers-ai.md

@@ -1,11 +1,12 @@
 # ![Cloudflare Workers AI logo](https://models.dev/logos/cloudflare-workers-ai.svg)Cloudflare Workers AI
 
-Access 42 Cloudflare Workers AI models through Mastra's model router. Authentication is handled automatically using the `CLOUDFLARE_ACCOUNT_ID` environment variable.
+Access 42 Cloudflare Workers AI models through Mastra's model router. Authentication is handled automatically using the `CLOUDFLARE_API_KEY` environment variable. Configure `CLOUDFLARE_ACCOUNT_ID` as well.
 
 Learn more in the [Cloudflare Workers AI documentation](https://developers.cloudflare.com/workers-ai/models/).
 
 ```bash
-CLOUDFLARE_ACCOUNT_ID=your-api-key
+CLOUDFLARE_ACCOUNT_ID=your-account-id
+CLOUDFLARE_API_KEY=your-api-key
 ```
 
 ```typescript
@@ -88,7 +89,7 @@ const agent = new Agent({
   model: {
     url: "https://api.cloudflare.com/client/v4/accounts/${CLOUDFLARE_ACCOUNT_ID}/ai/v1",
     id: "cloudflare-workers-ai/@cf/ai4bharat/indictrans2-en-indic-1B",
-    apiKey: process.env.CLOUDFLARE_ACCOUNT_ID,
+    apiKey: process.env.CLOUDFLARE_API_KEY,
     headers: {
       "X-Custom-Header": "value"
     }

package/.docs/models/providers/firmware.md

@@ -45,7 +45,6 @@ for await (const chunk of stream) {
 | `firmware/gemini-3-1-pro-preview`      | 1.0M    |       |           |       |       |       | $2         | $12         |
 | `firmware/gemini-3-flash-preview`      | 1.0M    |       |           |       |       |       | $0.50      | $3          |
 | `firmware/gemini-3-pro-preview`        | 1.0M    |       |           |       |       |       | $2         | $12         |
-| `firmware/glm-5`                       | 198K    |       |           |       |       |       | $1         | $3          |
 | `firmware/gpt-4o`                      | 128K    |       |           |       |       |       | $3         | $10         |
 | `firmware/gpt-5-3-codex`               | 400K    |       |           |       |       |       | $2         | $14         |
 | `firmware/gpt-5-4`                     | 272K    |       |           |       |       |       | $3         | $15         |
@@ -58,6 +57,7 @@ for await (const chunk of stream) {
 | `firmware/grok-code-fast-1`            | 256K    |       |           |       |       |       | $0.20      | $2          |
 | `firmware/kimi-k2.5`                   | 256K    |       |           |       |       |       | $0.60      | $3          |
 | `firmware/minimax-m2-5`                | 192K    |       |           |       |       |       | $0.30      | $1          |
+| `firmware/zai-glm-5`                   | 198K    |       |           |       |       |       | $1         | $3          |
 
 ## Advanced configuration
 
@@ -87,7 +87,7 @@ const agent = new Agent({
   model: ({ requestContext }) => {
     const useAdvanced = requestContext.task === "complex";
     return useAdvanced
-      ? "firmware/minimax-m2-5"
+      ? "firmware/zai-glm-5"
       : "firmware/claude-haiku-4-5";
   }
 });

package/.docs/models/providers/friendli.md

@@ -5,7 +5,7 @@ Access 7 Friendli models through Mastra's model router. Authentication is handle
 Learn more in the [Friendli documentation](https://friendli.ai/docs/guides/serverless_endpoints/introduction).
 
 ```bash
-FRIENDLI_TOKEN=your-api-key
+FRIENDLI_TOKEN=your-api-token
 ```
 
 ```typescript

package/.docs/models/providers/github-models.md

@@ -5,7 +5,7 @@ Access 55 GitHub Models models through Mastra's model router. Authentication is
 Learn more in the [GitHub Models documentation](https://docs.github.com/en/github-models).
 
 ```bash
-GITHUB_TOKEN=your-api-key
+GITHUB_TOKEN=your-api-token
 ```
 
 ```typescript

package/.docs/models/providers/google.md

@@ -1,6 +1,6 @@
 # ![Google logo](https://models.dev/logos/google.svg)Google
 
-Access 30 Google models through Mastra's model router. Authentication is handled automatically using the `GOOGLE_GENERATIVE_AI_API_KEY` environment variable.
+Access 35 Google models through Mastra's model router. Authentication is handled automatically using the `GOOGLE_GENERATIVE_AI_API_KEY` environment variable.
 
 Learn more in the [Google documentation](https://ai.google.dev/gemini-api/docs/pricing).
 
@@ -62,6 +62,11 @@ for await (const chunk of stream) {
 | `google/gemini-flash-lite-latest`                   | 1.0M    |       |           |       |       |       | $0.10      | $0.40       |
 | `google/gemini-live-2.5-flash`                      | 128K    |       |           |       |       |       | $0.50      | $2          |
 | `google/gemini-live-2.5-flash-preview-native-audio` | 131K    |       |           |       |       |       | $0.50      | $2          |
+| `google/gemma-3-12b-it`                             | 33K     |       |           |       |       |       | —          | —           |
+| `google/gemma-3-27b-it`                             | 131K    |       |           |       |       |       | —          | —           |
+| `google/gemma-3-4b-it`                              | 33K     |       |           |       |       |       | —          | —           |
+| `google/gemma-3n-e2b-it`                            | 8K      |       |           |       |       |       | —          | —           |
+| `google/gemma-3n-e4b-it`                            | 8K      |       |           |       |       |       | —          | —           |
 
 ## Advanced configuration
 
@@ -90,7 +95,7 @@ const agent = new Agent({
   model: ({ requestContext }) => {
     const useAdvanced = requestContext.task === "complex";
     return useAdvanced
-      ? "google/gemini-live-2.5-flash-preview-native-audio"
+      ? "google/gemma-3n-e4b-it"
       : "google/gemini-1.5-flash";
   }
 });

package/.docs/models/providers/groq.md

@@ -1,6 +1,6 @@
 # ![Groq logo](https://models.dev/logos/groq.svg)Groq
 
-Access 9 Groq models through Mastra's model router. Authentication is handled automatically using the `GROQ_API_KEY` environment variable.
+Access 17 Groq models through Mastra's model router. Authentication is handled automatically using the `GROQ_API_KEY` environment variable.
 
 Learn more in the [Groq documentation](https://console.groq.com/docs/models).
 
@@ -15,7 +15,7 @@ const agent = new Agent({
   id: "my-agent",
   name: "My Agent",
   instructions: "You are a helpful assistant",
-  model: "groq/llama-3.1-8b-instant"
+  model: "groq/allam-2-7b"
 });
 
 // Generate a response
@@ -30,17 +30,25 @@ for await (const chunk of stream) {
 
 ## Models
 
-| Model                                                | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
-| ---------------------------------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
-| `groq/llama-3.1-8b-instant`                          | 131K    |       |           |       |       |       | $0.05      | $0.08       |
-| `groq/llama-3.3-70b-versatile`                       | 131K    |       |           |       |       |       | $0.59      | $0.79       |
-| `groq/meta-llama/llama-4-maverick-17b-128e-instruct` | 131K    |       |           |       |       |       | $0.20      | $0.60       |
-| `groq/meta-llama/llama-4-scout-17b-16e-instruct`     | 131K    |       |           |       |       |       | $0.11      | $0.34       |
-| `groq/meta-llama/llama-guard-4-12b`                  | 131K    |       |           |       |       |       | $0.20      | $0.20       |
-| `groq/moonshotai/kimi-k2-instruct-0905`              | 262K    |       |           |       |       |       | $1         | $3          |
-| `groq/openai/gpt-oss-120b`                           | 131K    |       |           |       |       |       | $0.15      | $0.60       |
-| `groq/openai/gpt-oss-20b`                            | 131K    |       |           |       |       |       | $0.07      | $0.30       |
-| `groq/qwen/qwen3-32b`                                | 131K    |       |           |       |       |       | $0.29      | $0.59       |
+| Model                                            | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
+| ------------------------------------------------ | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
+| `groq/allam-2-7b`                                | 4K      |       |           |       |       |       | —          | —           |
+| `groq/canopylabs/orpheus-arabic-saudi`           | 4K      |       |           |       |       |       | $40        | —           |
+| `groq/canopylabs/orpheus-v1-english`             | 4K      |       |           |       |       |       | —          | —           |
+| `groq/groq/compound`                             | 131K    |       |           |       |       |       | —          | —           |
+| `groq/groq/compound-mini`                        | 131K    |       |           |       |       |       | —          | —           |
+| `groq/llama-3.1-8b-instant`                      | 131K    |       |           |       |       |       | $0.05      | $0.08       |
+| `groq/llama-3.3-70b-versatile`                   | 131K    |       |           |       |       |       | $0.59      | $0.79       |
+| `groq/meta-llama/llama-4-scout-17b-16e-instruct` | 131K    |       |           |       |       |       | $0.11      | $0.34       |
+| `groq/meta-llama/llama-prompt-guard-2-22m`       | 512     |       |           |       |       |       | $0.03      | $0.03       |
+| `groq/meta-llama/llama-prompt-guard-2-86m`       | 512     |       |           |       |       |       | $0.04      | $0.04       |
+| `groq/moonshotai/kimi-k2-instruct-0905`          | 262K    |       |           |       |       |       | $1         | $3          |
+| `groq/openai/gpt-oss-120b`                       | 131K    |       |           |       |       |       | $0.15      | $0.60       |
+| `groq/openai/gpt-oss-20b`                        | 131K    |       |           |       |       |       | $0.07      | $0.30       |
+| `groq/openai/gpt-oss-safeguard-20b`              | 131K    |       |           |       |       |       | $0.07      | $0.30       |
+| `groq/qwen/qwen3-32b`                            | 131K    |       |           |       |       |       | $0.29      | $0.59       |
+| `groq/whisper-large-v3`                          | 448     |       |           |       |       |       | —          | —           |
+| `groq/whisper-large-v3-turbo`                    | 448     |       |           |       |       |       | —          | —           |
 
 ## Advanced configuration
 
@@ -52,7 +60,7 @@ const agent = new Agent({
   name: "custom-agent",
   model: {
     url: "https://api.groq.com/openai/v1",
-    id: "groq/llama-3.1-8b-instant",
+    id: "groq/allam-2-7b",
     apiKey: process.env.GROQ_API_KEY,
     headers: {
       "X-Custom-Header": "value"
@@ -70,8 +78,8 @@ const agent = new Agent({
   model: ({ requestContext }) => {
     const useAdvanced = requestContext.task === "complex";
     return useAdvanced
-      ? "groq/qwen/qwen3-32b"
-      : "groq/llama-3.1-8b-instant";
+      ? "groq/whisper-large-v3-turbo"
+      : "groq/allam-2-7b";
   }
 });
 ```

package/.docs/models/providers/huggingface.md

@@ -5,7 +5,7 @@ Access 20 Hugging Face models through Mastra's model router. Authentication is h
 Learn more in the [Hugging Face documentation](https://huggingface.co).
 
 ```bash
-HF_TOKEN=your-api-key
+HF_TOKEN=your-api-token
 ```
 
 ```typescript

package/.docs/models/providers/mistral.md

@@ -1,6 +1,6 @@
 # ![Mistral logo](https://models.dev/logos/mistral.svg)Mistral
 
-Access 26 Mistral models through Mastra's model router. Authentication is handled automatically using the `MISTRAL_API_KEY` environment variable.
+Access 27 Mistral models through Mastra's model router. Authentication is handled automatically using the `MISTRAL_API_KEY` environment variable.
 
 Learn more in the [Mistral documentation](https://docs.mistral.ai/getting-started/models/).
 
@@ -52,7 +52,8 @@ for await (const chunk of stream) {
 | `mistral/mistral-medium-latest`    | 128K    |       |           |       |       |       | $0.40      | $2          |
 | `mistral/mistral-nemo`             | 128K    |       |           |       |       |       | $0.15      | $0.15       |
 | `mistral/mistral-small-2506`       | 128K    |       |           |       |       |       | $0.10      | $0.30       |
-| `mistral/mistral-small-latest`     | 128K    |       |           |       |       |       | $0.10      | $0.30       |
+| `mistral/mistral-small-2603`       | 256K    |       |           |       |       |       | $0.15      | $0.60       |
+| `mistral/mistral-small-latest`     | 256K    |       |           |       |       |       | $0.15      | $0.60       |
 | `mistral/open-mistral-7b`          | 8K      |       |           |       |       |       | $0.25      | $0.25       |
 | `mistral/open-mixtral-8x22b`       | 64K     |       |           |       |       |       | $2         | $6          |
 | `mistral/open-mixtral-8x7b`        | 32K     |       |           |       |       |       | $0.70      | $0.70       |

package/.docs/models/providers/nano-gpt.md

@@ -1,6 +1,6 @@
 # ![NanoGPT logo](https://models.dev/logos/nano-gpt.svg)NanoGPT
 
-Access 517 NanoGPT models through Mastra's model router. Authentication is handled automatically using the `NANO_GPT_API_KEY` environment variable.
+Access 519 NanoGPT models through Mastra's model router. Authentication is handled automatically using the `NANO_GPT_API_KEY` environment variable.
 
 Learn more in the [NanoGPT documentation](https://docs.nano-gpt.com).
 
@@ -551,6 +551,8 @@ for await (const chunk of stream) {
 | `nano-gpt/zai-org/glm-4.7-flash`                                    | 200K    |       |           |       |       |       | $0.07      | $0.40       |
 | `nano-gpt/zai-org/glm-5`                                            | 200K    |       |           |       |       |       | $0.30      | $3          |
 | `nano-gpt/zai-org/glm-5:thinking`                                   | 200K    |       |           |       |       |       | $0.30      | $3          |
+| `nano-gpt/zai-org/glm-5.1`                                          | 200K    |       |           |       |       |       | $0.30      | $3          |
+| `nano-gpt/zai-org/glm-5.1:thinking`                                 | 200K    |       |           |       |       |       | $0.30      | $3          |
 
 ## Advanced configuration
 

package/.docs/models/providers/openai.md

@@ -1,6 +1,6 @@
 # ![OpenAI logo](https://models.dev/logos/openai.svg)OpenAI
 
-Access 46 OpenAI models through Mastra's model router. Authentication is handled automatically using the `OPENAI_API_KEY` environment variable.
+Access 47 OpenAI models through Mastra's model router. Authentication is handled automatically using the `OPENAI_API_KEY` environment variable.
 
 Learn more in the [OpenAI documentation](https://platform.openai.com/docs/models).
 
@@ -59,6 +59,7 @@ for await (const chunk of stream) {
 | `openai/gpt-5.2-chat-latest`    | 128K    |       |           |       |       |       | $2         | $14         |
 | `openai/gpt-5.2-codex`          | 400K    |       |           |       |       |       | $2         | $14         |
 | `openai/gpt-5.2-pro`            | 400K    |       |           |       |       |       | $21        | $168        |
+| `openai/gpt-5.3-chat-latest`    | 128K    |       |           |       |       |       | $2         | $14         |
 | `openai/gpt-5.3-codex`          | 400K    |       |           |       |       |       | $2         | $14         |
 | `openai/gpt-5.3-codex-spark`    | 128K    |       |           |       |       |       | $2         | $14         |
 | `openai/gpt-5.4`                | 1.1M    |       |           |       |       |       | $3         | $15         |

package/.docs/models/providers/poe.md

@@ -1,6 +1,6 @@
 # ![Poe logo](https://models.dev/logos/poe.svg)Poe
 
-Access 122 Poe models through Mastra's model router. Authentication is handled automatically using the `POE_API_KEY` environment variable.
+Access 124 Poe models through Mastra's model router. Authentication is handled automatically using the `POE_API_KEY` environment variable.
 
 Learn more in the [Poe documentation](https://creator.poe.com/docs/external-applications/openai-compatible-api).
 
@@ -83,6 +83,7 @@ for await (const chunk of stream) {
 | `poe/ideogramai/ideogram-v2a`          | 150     |       |           |       |       |       | —          | —           |
 | `poe/ideogramai/ideogram-v2a-turbo`    | 150     |       |           |       |       |       | —          | —           |
 | `poe/lumalabs/ray2`                    | 5K      |       |           |       |       |       | —          | —           |
+| `poe/novita/deepseek-v3.2`             | 128K    |       |           |       |       |       | $0.27      | $0.40       |
 | `poe/novita/glm-4.6`                   | —       |       |           |       |       |       | —          | —           |
 | `poe/novita/glm-4.6v`                  | 131K    |       |           |       |       |       | —          | —           |
 | `poe/novita/glm-4.7`                   | 205K    |       |           |       |       |       | —          | —           |
@@ -155,6 +156,7 @@ for await (const chunk of stream) {
 | `poe/xai/grok-4-fast-reasoning`        | 2.0M    |       |           |       |       |       | $0.20      | $0.50       |
 | `poe/xai/grok-4.1-fast-non-reasoning`  | 2.0M    |       |           |       |       |       | —          | —           |
 | `poe/xai/grok-4.1-fast-reasoning`      | 2.0M    |       |           |       |       |       | —          | —           |
+| `poe/xai/grok-4.20-multi-agent`        | 128K    |       |           |       |       |       | $2         | $6          |
 | `poe/xai/grok-code-fast-1`             | 256K    |       |           |       |       |       | $0.20      | $2          |
 
 ## Advanced configuration

package/.docs/models/providers/zai-coding-plan.md

@@ -1,6 +1,6 @@
 # ![Z.AI Coding Plan logo](https://models.dev/logos/zai-coding-plan.svg)Z.AI Coding Plan
 
-Access 11 Z.AI Coding Plan models through Mastra's model router. Authentication is handled automatically using the `ZHIPU_API_KEY` environment variable.
+Access 12 Z.AI Coding Plan models through Mastra's model router. Authentication is handled automatically using the `ZHIPU_API_KEY` environment variable.
 
 Learn more in the [Z.AI Coding Plan documentation](https://docs.z.ai/devpack/overview).
 
@@ -45,6 +45,7 @@ for await (const chunk of stream) {
 | `zai-coding-plan/glm-4.7-flashx` | 200K    |       |           |       |       |       | $0.07      | $0.40       |
 | `zai-coding-plan/glm-5`          | 205K    |       |           |       |       |       | —          | —           |
 | `zai-coding-plan/glm-5-turbo`    | 200K    |       |           |       |       |       | —          | —           |
+| `zai-coding-plan/glm-5.1`        | 200K    |       |           |       |       |       | —          | —           |
 
 ## Advanced configuration
 
@@ -74,7 +75,7 @@ const agent = new Agent({
   model: ({ requestContext }) => {
     const useAdvanced = requestContext.task === "complex";
     return useAdvanced
-      ? "zai-coding-plan/glm-5-turbo"
+      ? "zai-coding-plan/glm-5.1"
       : "zai-coding-plan/glm-4.5";
   }
 });

package/.docs/models/providers/zhipuai-coding-plan.md

@@ -1,6 +1,6 @@
 # ![Zhipu AI Coding Plan logo](https://models.dev/logos/zhipuai-coding-plan.svg)Zhipu AI Coding Plan
 
-Access 12 Zhipu AI Coding Plan models through Mastra's model router. Authentication is handled automatically using the `ZHIPU_API_KEY` environment variable.
+Access 13 Zhipu AI Coding Plan models through Mastra's model router. Authentication is handled automatically using the `ZHIPU_API_KEY` environment variable.
 
 Learn more in the [Zhipu AI Coding Plan documentation](https://docs.bigmodel.cn/cn/coding-plan/overview).
 
@@ -46,6 +46,7 @@ for await (const chunk of stream) {
 | `zhipuai-coding-plan/glm-4.7-flashx` | 200K    |       |           |       |       |       | $0.07      | $0.40       |
 | `zhipuai-coding-plan/glm-5`          | 205K    |       |           |       |       |       | —          | —           |
 | `zhipuai-coding-plan/glm-5-turbo`    | 200K    |       |           |       |       |       | —          | —           |
+| `zhipuai-coding-plan/glm-5.1`        | 200K    |       |           |       |       |       | —          | —           |
 
 ## Advanced configuration
 
@@ -75,7 +76,7 @@ const agent = new Agent({
   model: ({ requestContext }) => {
     const useAdvanced = requestContext.task === "complex";
     return useAdvanced
-      ? "zhipuai-coding-plan/glm-5-turbo"
+      ? "zhipuai-coding-plan/glm-5.1"
       : "zhipuai-coding-plan/glm-4.5";
   }
 });

package/.docs/reference/ai-sdk/handle-chat-stream.md

@@ -59,4 +59,6 @@ export async function POST(req: Request) {
 
 **sendSources** (`boolean`): Whether to include source citations in the stream. (Default: `false`)
 
+**onError** (`(error: unknown) => string`): Called when the stream encounters an error. Return the string that will be sent to the client as the error message. Use this to sanitize errors before they reach the client — for example, to prevent internal infrastructure details from leaking to end users.
+
 **messageMetadata** (`(options: { part: UIMessageStreamPart }) => Record<string, unknown> | undefined`): A function that receives the current stream part and returns metadata to attach to start and finish chunks. See the \[AI SDK message metadata docs]\(https\://ai-sdk.dev/docs/ai-sdk-ui/message-metadata) for details.

package/.docs/reference/client-js/agents.md

@@ -308,7 +308,7 @@ response.processDataStream({
 
 ## Stored agents
 
-Stored agents are agent configurations stored in a database that can be created, updated, and deleted at runtime. They reference primitives (tools, workflows, other agents, memory, scorers) by key, which are resolved from the Mastra registry when the agent is instantiated.
+Stored agents are agent configurations stored in a database that can be created, updated, and deleted at runtime. They reference primitives (tools, workflows, other agents, scorers) by key, which are resolved from the Mastra registry when the agent is instantiated. Memory is configured inline as a `SerializedMemoryConfig` object with options such as `lastMessages` and `semanticRecall`.
 
 ### `listStoredAgents()`
 
@@ -361,10 +361,15 @@ const agent = await mastraClient.createStoredAgent({
     provider: 'openai',
     name: 'gpt-5.4',
   },
-  tools: ['calculator', 'weather'],
-  workflows: ['data-processing'],
-  agents: ['subagent-1'],
-  memory: 'my-memory',
+  tools: { calculator: {}, weather: {} },
+  workflows: { 'data-processing': {} },
+  agents: { 'subagent-1': {} },
+  memory: {
+    options: {
+      lastMessages: 20,
+      semanticRecall: false,
+    },
+  },
   scorers: {
     'quality-scorer': {
       sampling: { type: 'ratio', rate: 0.1 },
@@ -415,7 +420,7 @@ const updated = await storedAgent.update({
 ```typescript
 // Update just the tools
 await storedAgent.update({
-  tools: ['new-tool-1', 'new-tool-2'],
+  tools: { 'new-tool-1': {}, 'new-tool-2': {} },
 })
 
 // Update metadata

package/.docs/reference/client-js/mastra-client.md

@@ -32,7 +32,7 @@ export const mastraClient = new MastraClient({
 
 **getAgent(agentId)** (`Agent`): Retrieves a specific agent instance by ID.
 
-**getMemoryThreads(params)** (`Promise<StorageThreadType[]>`): Retrieves memory threads for the specified resource and agent. Requires a \`resourceId\` and an \`agentId\`.
+**listMemoryThreads(params)** (`Promise<StorageThreadType[]>`): Retrieves memory threads for the specified resource and agent. Requires a \`resourceId\` and an \`agentId\`.
 
 **createMemoryThread(params)** (`Promise<MemoryThread>`): Creates a new memory thread with the given parameters.
 

package/.docs/reference/client-js/memory.md

@@ -7,7 +7,7 @@ The Memory API provides methods to manage conversation threads and message histo
 Retrieve all memory threads for a specific resource:
 
 ```typescript
-const threads = await mastraClient.getMemoryThreads({
+const threads = await mastraClient.listMemoryThreads({
   resourceId: 'resource-1',
   agentId: 'agent-1', // Optional - can be omitted if storage is configured
 })

package/.docs/reference/configuration.md

@@ -566,6 +566,30 @@ export const mastra = new Mastra({
 })
 ```
 
+### server.mcpOptions
+
+**Type:** `object`\
+**Default:** `undefined`
+
+MCP transport options applied to all MCP HTTP and SSE routes. Use this to enable stateless mode for serverless environments (Cloudflare Workers, Vercel Edge, AWS Lambda, etc.) where persistent connections and in-memory session state are not available.
+
+| Property             | Type           | Default     | Description                                          |
+| -------------------- | -------------- | ----------- | ---------------------------------------------------- |
+| `serverless`         | `boolean`      | `false`     | Run MCP in stateless mode without session management |
+| `sessionIdGenerator` | `() => string` | `undefined` | Custom session ID generator function                 |
+
+```typescript
+import { Mastra } from '@mastra/core'
+
+export const mastra = new Mastra({
+  server: {
+    mcpOptions: {
+      serverless: true,
+    },
+  },
+})
+```
+
 ### server.build
 
 Build-time configuration for server features. These options control development tools like Swagger UI and request logging, which are enabled during local development but disabled in production by default.

package/.docs/reference/core/mastra-model-gateway.md

@@ -87,6 +87,8 @@ Fetches provider configurations from the gateway.
 
 Builds the API URL for a specific model/provider combination.
 
+If your provider URL contains placeholders such as `${ACCOUNT_ID}`, resolve them inside `buildUrl()` from `envVars` or `process.env` before returning the final URL.
+
 **Parameters:**
 
 **modelId** (`string`): Full model ID (e.g., "custom/my-provider/model-1")

package/.docs/reference/deployer/cloudflare.md

@@ -87,4 +87,34 @@ Use `vars` in the `CloudflareDeployer` constructor only for non-sensitive config
 
 ## Build output
 
-After running `mastra build`, the deployer generates a `wrangler.jsonc` file conforming to Cloudflare's [wrangler configuration](https://developers.cloudflare.com/workers/wrangler/configuration/). It points to files inside `.mastra/output` so you need to run `mastra build` before deploying with Wrangler.
+After running `mastra build`, the deployer generates a `wrangler.jsonc` file conforming to Cloudflare's [wrangler configuration](https://developers.cloudflare.com/workers/wrangler/configuration/). It points to files inside `.mastra/output` so you need to run `mastra build` before deploying with Wrangler.
+
+## Cloudflare bindings
+
+When you use the Cloudflare deployer, you can import runtime bindings from `cloudflare:workers` in your Mastra config file. Mastra automatically preserves protocol-based runtime imports like `cloudflare:workers` during `mastra build` without trying to install them as npm dependencies.
+
+```typescript
+import { env } from 'cloudflare:workers'
+import { Mastra } from '@mastra/core'
+import { registerApiRoute } from '@mastra/core/server'
+import { CloudflareDeployer } from '@mastra/deployer-cloudflare'
+
+export const mastra = new Mastra({
+  deployer: new CloudflareDeployer({
+    name: 'my-worker',
+    kv_namespaces: [{ binding: 'CACHE', id: 'your-kv-namespace-id' }],
+  }),
+  server: {
+    apiRoutes: [
+      registerApiRoute('/bindings', {
+        method: 'GET',
+        requiresAuth: false,
+        handler: async c => {
+          await env.CACHE.put('status', 'ok')
+          return c.json({ status: await env.CACHE.get('status') })
+        },
+      }),
+    ],
+  },
+})
+```

package/.docs/reference/evals/scorer-utils.md

@@ -367,10 +367,11 @@ The `expected` parameter accepts either a `Trajectory` (actual trajectory) or `{
 import { compareTrajectories } from '@mastra/evals/scorers/utils'
 
 // Using ExpectedStep[] (recommended for expectations)
+// Data fields (e.g. toolArgs) are auto-compared when present on expected steps
 const result = compareTrajectories(
   actualTrajectory,
   { steps: [{ name: 'search' }, { name: 'summarize', stepType: 'tool_call' }] },
-  { compareStepData: false, allowRepeatedSteps: true },
+  { allowRepeatedSteps: true },
 )
 // result.score — 0.0 to 1.0
 // result.missingSteps — step names not found
@@ -412,7 +413,9 @@ const result = checkTrajectoryEfficiency(trajectory, {
 })
 // result.score — 1.0 if within all budgets, lower with penalties
 // result.redundantCalls — duplicate tool+args combos
-// result.overBudget — which budgets were exceeded
+// result.overStepBudget — true if maxSteps exceeded
+// result.overTokenBudget — true if maxTotalTokens exceeded
+// result.overDurationBudget — true if maxTotalDurationMs exceeded
 ```
 
 **Returns:** `TrajectoryEfficiencyResult`
@@ -428,8 +431,9 @@ const result = checkTrajectoryBlacklist(trajectory, {
   blacklistedTools: ['deleteAll', 'admin-override'],
   blacklistedSequences: [['escalate', 'admin-override']],
 })
-// result.passed — true if no violations
-// result.violations — list of violations with type and details
+// result.score — 1.0 if no violations, 0.0 if any found
+// result.violatedTools — blacklisted tools that were called
+// result.violatedSequences — blacklisted sequences that were detected
 ```
 
 **Returns:** `TrajectoryBlacklistResult`
@@ -442,7 +446,7 @@ Detects tool failure patterns including retries, fallbacks, and argument correct
 import { analyzeToolFailures } from '@mastra/evals/scorers/utils'
 
 const result = analyzeToolFailures(trajectory, {
-  maxRetriesPerTool: 3,
+  maxRetriesPerTool: 2,
 })
 // result.score — 1.0 if no failure patterns, lower if patterns detected
 // result.patterns — detected patterns (retry, fallback, arg_correction)

package/.docs/reference/evals/trajectory-accuracy.md

@@ -103,13 +103,15 @@ All step types share the base properties `name`, `durationMs`, `metadata`, and `
 
 ## Expected steps
 
-When defining expected trajectories, use `ExpectedStep` instead of the full `TrajectoryStep` discriminated union. `ExpectedStep` is a simpler type designed for expectations:
+When defining expected trajectories, use `ExpectedStep` instead of the full `TrajectoryStep` discriminated union. `ExpectedStep` is a discriminated union that mirrors `TrajectoryStep` — when you specify a `stepType`, you get autocomplete for that variant's fields (e.g., `toolArgs` for `tool_call`, `modelId` for `model_generation`). All variant-specific fields are optional, so you only assert against what you care about.
+
+Omit `stepType` entirely to match any step by name only.
 
 **name** (`string`): Step name to match (tool name, agent ID, workflow step name, etc.).
 
-**stepType** (`TrajectoryStepType`): Step type to match. If omitted, matches any step type with the given name.
+**stepType** (`TrajectoryStepType`): Step type discriminant. When set, enables autocomplete for that variant's fields. If omitted, matches any step type with the given name.
 
-**data** (`Record<string, unknown>`): Expected step data. Compared against the actual step's type-specific data (toolArgs for tool\_call, output for workflow\_step, etc.).
+**(variant fields)** (`varies`): Type-specific fields from the corresponding TrajectoryStep variant. For example, \`toolArgs\` and \`toolResult\` for \`tool\_call\`, \`modelId\` for \`model\_generation\`, \`output\` for \`workflow\_step\`. All optional — only specified fields are compared.
 
 **children** (`TrajectoryExpectation`): Nested expectation config for this step's children. Overrides the parent config for evaluating children of this step.
 
@@ -120,11 +122,14 @@ const steps: ExpectedStep[] = [
   // Match by name only (any step type)
   { name: 'search' },
 
-  // Match by name and step type
+  // Match by name and step type (autocomplete for tool_call fields)
   { name: 'search', stepType: 'tool_call' },
 
-  // Match with expected data
-  { name: 'search', stepType: 'tool_call', data: { input: { query: 'weather' } } },
+  // Match with specific toolArgs (auto-compared when present)
+  { name: 'search', stepType: 'tool_call', toolArgs: { query: 'weather' } },
+
+  // Match a model generation step by model ID
+  { name: 'gpt-4o', stepType: 'model_generation', modelId: 'gpt-4o' },
 ]
 ```
 
@@ -182,7 +187,7 @@ The `createTrajectoryAccuracyScorerCode()` function from `@mastra/evals/scorers/
 
 ### Parameters
 
-**expectedTrajectory** (`TrajectoryExpectation`): Static expected trajectory to compare against. When provided, all dataset items use this trajectory. When omitted, the scorer reads expectedTrajectory from each dataset item at runtime.
+**expectedTrajectory** (`Trajectory | ExpectedStep[]`): Static expected trajectory to compare against. Accepts a full Trajectory or an array of ExpectedStep matchers. When omitted, the scorer reads expectedTrajectory from each dataset item at runtime.
 
 **comparisonOptions** (`TrajectoryComparisonOptions`): Controls how the comparison is performed.
 
@@ -368,8 +373,8 @@ const scorer = createTrajectoryAccuracyScorerCode({
       },
     ],
   },
-  comparisonOptions: { compareStepData: true },
 })
+// Data fields like toolArgs are auto-compared when present on expected steps
 ```
 
 ## LLM-based trajectory accuracy scorer
@@ -380,7 +385,7 @@ The `createTrajectoryAccuracyScorerLLM()` function from `@mastra/evals/scorers/p
 
 **model** (`MastraModelConfig`): The LLM model to use for evaluating trajectory quality.
 
-**expectedTrajectory** (`TrajectoryExpectation`): Optional static expected trajectory to compare against. When omitted, the LLM evaluates the trajectory based on the task requirements alone. Can also come from dataset items at runtime.
+**expectedTrajectory** (`Trajectory | ExpectedStep[]`): Optional static expected trajectory to compare against. Accepts a full Trajectory or an array of ExpectedStep matchers. When omitted, the LLM evaluates the trajectory based on the task requirements alone. Can also come from dataset items at runtime.
 
 ### Features
 
@@ -461,7 +466,7 @@ The `createTrajectoryScorerCode()` function from `@mastra/evals/scorers/prebuilt
 
 **defaults** (`TrajectoryExpectation`): Default expectations applied to all dataset items. Per-item expectedTrajectory values override these defaults.
 
-**weights** (`object`): Weights for combining dimension scores into the final score.
+**weights** (`TrajectoryScoreWeights`): Custom weights for combining dimension scores. Weights are normalized to sum to 1.0.
 
 ### Scoring behavior
 
@@ -472,7 +477,7 @@ The unified scorer evaluates four dimensions:
 3. **Blacklist** — Checks for forbidden tools or sequences. Any violation immediately results in a score of **0.0** regardless of other dimensions.
 4. **Tool failures** — Detects retry patterns, fallback patterns, and argument correction patterns.
 
-The final score is a weighted average of accuracy, efficiency, and tool failures. Blacklist violations override everything to 0.
+The final score is a weighted combination of active dimensions, normalized by which dimensions are active. Default weights are accuracy 0.4, efficiency 0.3, tool failures 0.2, blacklist 0.1, but you can customize them via the `weights` option. Blacklist violations override everything to 0. When nested evaluations are present, the score is 70% top-level and 30% nested average.
 
 ### Unified scorer results
 
@@ -481,11 +486,13 @@ The final score is a weighted average of accuracy, efficiency, and tool failures
   runId: string,
   preprocessStepResult: {
     accuracy?: TrajectoryComparisonResult,
-    efficiency: TrajectoryEfficiencyResult,
-    blacklist: TrajectoryBlacklistResult,
-    toolFailures: ToolFailureAnalysisResult,
+    efficiency?: TrajectoryEfficiencyResult,
+    blacklist?: TrajectoryBlacklistResult,
+    toolFailures?: ToolFailureAnalysisResult,
+    nested?: NestedEvaluationResult[],
   },
-  score: number
+  score: number,
+  reason: string
 }
 ```
 
@@ -542,6 +549,13 @@ const scorer = createTrajectoryScorerCode({
     noRedundantCalls: true,
     maxRetriesPerTool: 2,
   },
+  // Customize how dimensions contribute to the final score
+  weights: {
+    accuracy: 0.5, // prioritize step accuracy
+    efficiency: 0.3,
+    toolFailures: 0.1,
+    blacklist: 0.1,
+  },
 })
 ```
 

package/.docs/reference/index.md

@@ -66,7 +66,6 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [.getScorerById()](https://mastra.ai/reference/core/getScorerById)
 - [.getServer()](https://mastra.ai/reference/core/getServer)
 - [.getStorage()](https://mastra.ai/reference/core/getStorage)
-- [.getStoredAgentById()](https://mastra.ai/reference/core/getStoredAgentById)
 - [.getTelemetry()](https://mastra.ai/reference/core/getTelemetry)
 - [.getVector()](https://mastra.ai/reference/core/getVector)
 - [.getWorkflow()](https://mastra.ai/reference/core/getWorkflow)
@@ -77,7 +76,6 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [.listMCPServers()](https://mastra.ai/reference/core/listMCPServers)
 - [.listMemory()](https://mastra.ai/reference/core/listMemory)
 - [.listScorers()](https://mastra.ai/reference/core/listScorers)
-- [.listStoredAgents()](https://mastra.ai/reference/core/listStoredAgents)
 - [.listVectors()](https://mastra.ai/reference/core/listVectors)
 - [.listWorkflows()](https://mastra.ai/reference/core/listWorkflows)
 - [.setLogger()](https://mastra.ai/reference/core/setLogger)

package/.docs/reference/logging/pino-logger.md

@@ -30,6 +30,64 @@ export const mastra = new Mastra({
 
 **formatters** (`pino.LoggerOptions['formatters']`): Custom Pino formatters for log serialization.
 
+**redact** (`pino.LoggerOptions['redact']`): Paths or options for redacting sensitive fields from log output (Pino \`redact\`).
+
+**prettyPrint** (`boolean`): When false, disables \`pino-pretty\` and writes raw JSON lines (useful for log aggregators). (Default: `true`)
+
+**mixin** (`pino.MixinFn`): Pino mixin function merged into every log object (for example request-scoped \`traceId\` or other shared metadata).
+
+**customLevels** (`Record<string, number>`): Custom log levels and numeric values, forwarded to Pino. Standard severity is still logged via \`debug\`, \`info\`, \`warn\`, and \`error\`; extra levels follow Pino’s custom-level behavior.
+
+## Log enrichment with `mixin`
+
+Use `mixin` when you want the same structured fields on every line (for correlation with the rest of your services):
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { PinoLogger } from '@mastra/loggers'
+
+function getTraceContext() {
+  return { traceId: 'abc-123' }
+}
+
+export const mastra = new Mastra({
+  logger: new PinoLogger({
+    name: 'Mastra',
+    level: 'info',
+    mixin() {
+      return getTraceContext()
+    },
+  }),
+})
+```
+
+## Custom levels
+
+`customLevels` is passed through to Pino. `PinoLogger` only exposes `debug`, `info`, `warn`, and `error`; for any extra level name (for example `audit`), subclass and forward to the underlying Pino instance:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { PinoLogger } from '@mastra/loggers'
+
+type AuditLevel = 'audit'
+
+class MastraPinoWithAudit extends PinoLogger<AuditLevel> {
+  audit(message: string, meta: Record<string, unknown> = {}) {
+    this.logger.audit(meta, message)
+  }
+}
+
+const logger = new MastraPinoWithAudit({
+  name: 'Mastra',
+  level: 'info',
+  customLevels: { audit: 35 },
+})
+
+export const mastra = new Mastra({ logger })
+```
+
+Numeric values follow Pino’s ordering (built-in levels use 10–60). A level of `35` sits between `info` (30) and `warn` (40), so with `level: 'info'` both `info` and `audit` lines are emitted.
+
 ## File transport (structured logs)
 
 Writes structured logs to a file using the `FileTransport`. The logger accepts a plain message as the first argument and structured metadata as the second argument. These are internally converted to a `BaseLogMessage` and persisted to the configured file path.

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

@@ -38,7 +38,7 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
 
 **shareTokenBudget** (`boolean`): Share the token budget between messages and observations. When enabled, the total budget is \`observation.messageTokens + reflection.observationTokens\`. Messages can use more space when observations are small, and vice versa. This maximizes context usage through flexible allocation. \`shareTokenBudget\` is not yet compatible with async buffering. You must set \`observation: { bufferTokens: false }\` when using this option (this is a temporary limitation). (Default: `false`)
 
-**retrieval** (`boolean`): \*\*Experimental.\*\* Enable retrieval-mode observation groups as durable pointers to raw message history. Retrieval mode is only active when \`scope\` is \`'thread'\`. If you set \`retrieval: true\` with \`scope: 'resource'\`, OM keeps resource-scoped memory behavior but skips retrieval-mode context and does not register the \`recall\` tool. (Default: `false`)
+**retrieval** (`boolean | { vector?: boolean; scope?: 'thread' | 'resource' }`): \*\*Experimental.\*\* Enable retrieval-mode observation groups as durable pointers to raw message history. \`true\` enables cross-thread browsing by default. \`{ vector: true }\` also enables semantic search using Memory's vector store and embedder. \`{ scope: 'thread' }\` restricts the recall tool to the current thread only. Default scope is \`'resource'\`. (Default: `false`)
 
 **observation** (`ObservationalMemoryObservationConfig`): Configuration for the observation step. Controls when the Observer agent runs and how it behaves.
 
@@ -578,21 +578,31 @@ The standalone `ObservationalMemory` class accepts all the same options as the `
 
 ## Recall tool
 
-When `retrieval: true` is set with `scope: 'thread'`, OM registers a `recall` tool that the agent can call to page through the raw messages behind an observation group's `_range`. The tool is automatically added to the agent's tool list — no manual registration is needed.
+When `retrieval` is set (any truthy value), a `recall` tool is registered so the agent can page through raw messages behind observation group ranges. By default (scope `'resource'`), the tool supports listing threads (`mode: "threads"`), browsing other threads (`threadId`), and cross-thread search. With `retrieval: { vector: true }`, semantic search is available (`mode: "search"`). Set `scope: 'thread'` to restrict the tool to the current thread only. The tool is automatically added to the agent's tool list — no manual registration is needed.
 
 ### Parameters
 
-**cursor** (`string`): A message ID to anchor the recall query. Extract the start or end ID from an observation group range (e.g. from \`\_range: \\\`startId:endId\\\`\_\`, use either \`startId\` or \`endId\`). If a range string is passed directly, the tool returns a hint explaining how to extract the correct ID.
+**mode** (`'messages' | 'threads' | 'search'`): What to retrieve. \`"messages"\` (default) pages through message history. \`"threads"\` lists all threads for the current user. \`"search"\` finds messages by semantic similarity across all threads (requires vector store and embedder). (Default: `'messages'`)
 
-**page** (`number`): Pagination offset from the cursor. Positive values page forward (messages after the cursor), negative values page backward (messages before the cursor). \`0\` is treated as \`1\`. (Default: `1`)
+**query** (`string`): Search query for \`mode: "search"\`. Finds messages semantically similar to this text across all threads for the current user.
 
-**limit** (`number`): Maximum number of messages per page. (Default: `20`)
+**cursor** (`string`): A message ID to anchor the recall query. Required for \`mode: "messages"\` when browsing the current thread. Extract the start or end ID from an observation group range (e.g. from \`\_range: \\\`startId:endId\\\`\_\`, use either \`startId\` or \`endId\`). If a range string is passed directly, the tool returns a hint explaining how to extract the correct ID. Can be omitted when \`threadId\` is provided to start reading from the beginning of that thread.
+
+**threadId** (`string`): Browse a different thread by its ID. Use \`mode: "threads"\` first to discover thread IDs. When provided without a \`cursor\`, reading starts from the beginning of the thread.
+
+**page** (`number`): Pagination offset. For messages: positive values page forward from cursor, negative values page backward. For threads: page number (0-indexed). \`0\` is treated as \`1\` for messages. (Default: `1`)
+
+**limit** (`number`): Maximum number of items to return per page. (Default: `20`)
 
 **detail** (`'low' | 'high'`): Controls how much content is shown per message part. \`'low'\` shows truncated text and tool names with positional indices (\`\[p0]\`, \`\[p1]\`). \`'high'\` shows full content including tool arguments and results, clamped to one part per call with continuation hints. (Default: `'low'`)
 
 **partIndex** (`number`): Fetch a single message part at full detail by its positional index. Use this when a low-detail recall shows an interesting part at \`\[p1]\` — call again with \`partIndex: 1\` to see the full content without loading every part.
 
-### Returns
+**before** (`string`): For \`mode: "threads"\` only. Filter to threads created before this date. Accepts ISO 8601 format (e.g. \`"2026-03-15"\`, \`"2026-03-10T00:00:00Z"\`).
+
+**after** (`string`): For \`mode: "threads"\` only. Filter to threads created after this date. Accepts ISO 8601 format (e.g. \`"2026-03-01"\`, \`"2026-03-10T00:00:00Z"\`).
+
+### Returns (messages mode)
 
 **messages** (`string`): Formatted message content. Format depends on the \`detail\` level.
 
@@ -612,6 +622,22 @@ When `retrieval: true` is set with `scope: 'thread'`, OM registers a `recall` to
 
 **tokenOffset** (`number`): Approximate number of tokens that were trimmed when \`truncated\` is true.
 
+### Returns (threads mode)
+
+**threads** (`string`): Formatted thread listing. Each thread shows its title, ID, and dates. The current thread is marked with \`← current\`.
+
+**count** (`number`): Number of threads returned.
+
+**page** (`number`): The page number returned.
+
+**hasMore** (`boolean`): Whether more threads exist on the next page.
+
+### Returns (search mode)
+
+**results** (`string`): Formatted search results grouped by thread. Each result shows the thread title, thread ID, relevance score, message preview, and a cursor ID for browsing into that thread.
+
+**count** (`number`): Number of matching messages found.
+
 ### ModelByInputTokens
 
 `ModelByInputTokens` selects a model based on the input token count. It chooses the model for the smallest threshold that covers the actual input size.

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # @mastra/mcp-docs-server
 
+## 1.1.17
+
+### Patch Changes
+
+- Updated dependencies [[`dc514a8`](https://github.com/mastra-ai/mastra/commit/dc514a83dba5f719172dddfd2c7b858e4943d067), [`e333b77`](https://github.com/mastra-ai/mastra/commit/e333b77e2d76ba57ccec1818e08cebc1993469ff), [`dc9fc19`](https://github.com/mastra-ai/mastra/commit/dc9fc19da4437f6b508cc355f346a8856746a76b), [`60a224d`](https://github.com/mastra-ai/mastra/commit/60a224dd497240e83698cfa5bfd02e3d1d854844), [`fbf22a7`](https://github.com/mastra-ai/mastra/commit/fbf22a7ad86bcb50dcf30459f0d075e51ddeb468), [`f16d92c`](https://github.com/mastra-ai/mastra/commit/f16d92c677a119a135cebcf7e2b9f51ada7a9df4), [`949b7bf`](https://github.com/mastra-ai/mastra/commit/949b7bfd4e40f2b2cba7fef5eb3f108a02cfe938), [`404fea1`](https://github.com/mastra-ai/mastra/commit/404fea13042181f0b0c73a101392ac87c79ceae2), [`ebf5047`](https://github.com/mastra-ai/mastra/commit/ebf5047e825c38a1a356f10b214c1d4260dfcd8d), [`12c647c`](https://github.com/mastra-ai/mastra/commit/12c647cf3a26826eb72d40b42e3c8356ceae16ed), [`d084b66`](https://github.com/mastra-ai/mastra/commit/d084b6692396057e83c086b954c1857d20b58a14), [`79c699a`](https://github.com/mastra-ai/mastra/commit/79c699acf3cd8a77e11c55530431f48eb48456e9), [`62757b6`](https://github.com/mastra-ai/mastra/commit/62757b6db6e8bb86569d23ad0b514178f57053f8), [`675f15b`](https://github.com/mastra-ai/mastra/commit/675f15b7eaeea649158d228ea635be40480c584d), [`b174c63`](https://github.com/mastra-ai/mastra/commit/b174c63a093108d4e53b9bc89a078d9f66202b3f), [`819f03c`](https://github.com/mastra-ai/mastra/commit/819f03c25823373b32476413bd76be28a5d8705a), [`04160ee`](https://github.com/mastra-ai/mastra/commit/04160eedf3130003cf842ad08428c8ff69af4cc1), [`2c27503`](https://github.com/mastra-ai/mastra/commit/2c275032510d131d2cde47f99953abf0fe02c081), [`424a1df`](https://github.com/mastra-ai/mastra/commit/424a1df7bee59abb5c83717a54807fdd674a6224), [`3d70b0b`](https://github.com/mastra-ai/mastra/commit/3d70b0b3524d817173ad870768f259c06d61bd23), [`eef7cb2`](https://github.com/mastra-ai/mastra/commit/eef7cb2abe7ef15951e2fdf792a5095c6c643333), [`43595bf`](https://github.com/mastra-ai/mastra/commit/43595bf7b8df1a6edce7a23b445b5124d2a0b473), [`260fe12`](https://github.com/mastra-ai/mastra/commit/260fe1295fe7354e39d6def2775e0797a7a277f0), [`12c88a6`](https://github.com/mastra-ai/mastra/commit/12c88a6e32bf982c2fe0c6af62e65a3414519a75), [`43595bf`](https://github.com/mastra-ai/mastra/commit/43595bf7b8df1a6edce7a23b445b5124d2a0b473), [`78670e9`](https://github.com/mastra-ai/mastra/commit/78670e97e76d7422cf7025faf371b2aeafed860d), [`e8a5b0b`](https://github.com/mastra-ai/mastra/commit/e8a5b0b9bc94d12dee4150095512ca27a288d778), [`3b45a13`](https://github.com/mastra-ai/mastra/commit/3b45a138d09d040779c0aba1edbbfc1b57442d23), [`d400e7c`](https://github.com/mastra-ai/mastra/commit/d400e7c8b8d7afa6ba2c71769eace4048e3cef8e), [`f58d1a7`](https://github.com/mastra-ai/mastra/commit/f58d1a7a457588a996c3ecb53201a68f3d28c432), [`a49a929`](https://github.com/mastra-ai/mastra/commit/a49a92904968b4fc67e01effee8c7c8d0464ba85), [`8127d96`](https://github.com/mastra-ai/mastra/commit/8127d96280492e335d49b244501088dfdd59a8f1)]:
+  - @mastra/core@1.18.0
+  - @mastra/mcp@1.3.2
+
+## 1.1.17-alpha.17
+
+### Patch Changes
+
+- Updated dependencies [[`12c647c`](https://github.com/mastra-ai/mastra/commit/12c647cf3a26826eb72d40b42e3c8356ceae16ed), [`819f03c`](https://github.com/mastra-ai/mastra/commit/819f03c25823373b32476413bd76be28a5d8705a)]:
+  - @mastra/core@1.18.0-alpha.5
+
+## 1.1.17-alpha.15
+
+### Patch Changes
+
+- Updated dependencies [[`fbf22a7`](https://github.com/mastra-ai/mastra/commit/fbf22a7ad86bcb50dcf30459f0d075e51ddeb468), [`04160ee`](https://github.com/mastra-ai/mastra/commit/04160eedf3130003cf842ad08428c8ff69af4cc1), [`2c27503`](https://github.com/mastra-ai/mastra/commit/2c275032510d131d2cde47f99953abf0fe02c081), [`424a1df`](https://github.com/mastra-ai/mastra/commit/424a1df7bee59abb5c83717a54807fdd674a6224), [`43595bf`](https://github.com/mastra-ai/mastra/commit/43595bf7b8df1a6edce7a23b445b5124d2a0b473), [`12c88a6`](https://github.com/mastra-ai/mastra/commit/12c88a6e32bf982c2fe0c6af62e65a3414519a75), [`43595bf`](https://github.com/mastra-ai/mastra/commit/43595bf7b8df1a6edce7a23b445b5124d2a0b473), [`78670e9`](https://github.com/mastra-ai/mastra/commit/78670e97e76d7422cf7025faf371b2aeafed860d), [`d400e7c`](https://github.com/mastra-ai/mastra/commit/d400e7c8b8d7afa6ba2c71769eace4048e3cef8e), [`f58d1a7`](https://github.com/mastra-ai/mastra/commit/f58d1a7a457588a996c3ecb53201a68f3d28c432), [`a49a929`](https://github.com/mastra-ai/mastra/commit/a49a92904968b4fc67e01effee8c7c8d0464ba85)]:
+  - @mastra/core@1.18.0-alpha.4
+  - @mastra/mcp@1.3.2-alpha.0
+
+## 1.1.17-alpha.12
+
+### Patch Changes
+
+- Updated dependencies [[`e333b77`](https://github.com/mastra-ai/mastra/commit/e333b77e2d76ba57ccec1818e08cebc1993469ff), [`60a224d`](https://github.com/mastra-ai/mastra/commit/60a224dd497240e83698cfa5bfd02e3d1d854844), [`949b7bf`](https://github.com/mastra-ai/mastra/commit/949b7bfd4e40f2b2cba7fef5eb3f108a02cfe938), [`d084b66`](https://github.com/mastra-ai/mastra/commit/d084b6692396057e83c086b954c1857d20b58a14), [`79c699a`](https://github.com/mastra-ai/mastra/commit/79c699acf3cd8a77e11c55530431f48eb48456e9), [`62757b6`](https://github.com/mastra-ai/mastra/commit/62757b6db6e8bb86569d23ad0b514178f57053f8), [`3d70b0b`](https://github.com/mastra-ai/mastra/commit/3d70b0b3524d817173ad870768f259c06d61bd23), [`3b45a13`](https://github.com/mastra-ai/mastra/commit/3b45a138d09d040779c0aba1edbbfc1b57442d23), [`8127d96`](https://github.com/mastra-ai/mastra/commit/8127d96280492e335d49b244501088dfdd59a8f1)]:
+  - @mastra/core@1.18.0-alpha.3
+
+## 1.1.17-alpha.10
+
+### Patch Changes
+
+- Updated dependencies [[`f16d92c`](https://github.com/mastra-ai/mastra/commit/f16d92c677a119a135cebcf7e2b9f51ada7a9df4)]:
+  - @mastra/core@1.18.0-alpha.2
+
 ## 1.1.17-alpha.8
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.1.17-alpha.9",
+  "version": "1.1.17",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -29,8 +29,8 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.3.6",
-    "@mastra/core": "1.18.0-alpha.1",
-    "@mastra/mcp": "^1.3.1"
+    "@mastra/core": "1.18.0",
+    "@mastra/mcp": "^1.3.2"
   },
   "devDependencies": {
     "@hono/node-server": "^1.19.11",
@@ -46,9 +46,9 @@
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "4.0.18",
-    "@internal/lint": "0.0.74",
-    "@internal/types-builder": "0.0.49",
-    "@mastra/core": "1.18.0-alpha.1"
+    "@internal/types-builder": "0.0.50",
+    "@mastra/core": "1.18.0",
+    "@internal/lint": "0.0.75"
   },
   "homepage": "https://mastra.ai",
   "repository": {

package/.docs/reference/core/getStoredAgentById.md

@@ -1,87 +0,0 @@
-# Mastra.getStoredAgentById()
-
-The `.getStoredAgentById()` method retrieves an agent configuration from storage by its ID and creates an executable `Agent` instance. Stored agents allow you to persist agent configurations in a database and dynamically load them at runtime.
-
-## Usage example
-
-```typescript
-// Get an Agent instance from storage
-const agent = await mastra.getStoredAgentById('my-stored-agent')
-
-if (agent) {
-  const response = await agent.generate('Hello')
-  console.log(response.text)
-}
-```
-
-```typescript
-// Get the raw storage data instead of an Agent instance
-const storedConfig = await mastra.getStoredAgentById('my-stored-agent', { raw: true })
-
-if (storedConfig) {
-  console.log(storedConfig.instructions)
-  console.log(storedConfig.createdAt)
-}
-```
-
-## Parameters
-
-**id** (`string`): The unique identifier of the stored agent to retrieve.
-
-**options** (`{ raw?: boolean }`): Optional configuration object.
-
-**options.raw** (`boolean`): When \`true\`, returns the raw \`StorageAgentType\` object from storage instead of creating an \`Agent\` instance. Useful for inspecting stored configuration or metadata.
-
-## Returns
-
-**result** (`Agent | StorageAgentType | null`): Returns an \`Agent\` instance by default, or \`StorageAgentType\` when \`raw: true\`. Returns \`null\` if no agent with the given ID exists.
-
-## Primitive resolution
-
-When creating an `Agent` instance from stored configuration, the method resolves references to registered primitives:
-
-- **Tools**: Resolved from `tools` registered in Mastra config
-- **Workflows**: Resolved from `workflows` registered in Mastra config
-- **Subagents**: Resolved from `agents` registered in Mastra config
-- **Memory**: Resolved from `memory` registered in Mastra config
-- **Scorers**: Resolved from `scorers` registered in Mastra config, including sampling configuration
-
-If a referenced primitive isn't found in the registry, a warning is logged but the agent is still created.
-
-## `StorageAgentType`
-
-When using `raw: true`, the returned object has the following structure:
-
-**id** (`string`): Unique identifier for the agent.
-
-**name** (`string`): Display name of the agent.
-
-**description** (`string`): Optional description of the agent.
-
-**instructions** (`string`): System instructions for the agent.
-
-**model** (`Record<string, unknown>`): Model configuration with provider and name.
-
-**tools** (`Record<string, unknown>`): Tool references to resolve from registry.
-
-**workflows** (`Record<string, unknown>`): Workflow references to resolve from registry.
-
-**agents** (`Record<string, unknown>`): Subagent references to resolve from registry.
-
-**memory** (`Record<string, unknown>`): Memory reference to resolve from registry.
-
-**scorers** (`Record<string, unknown>`): Scorer references with optional sampling config.
-
-**defaultOptions** (`Record<string, unknown>`): Default options passed to agent execution.
-
-**metadata** (`Record<string, unknown>`): Custom metadata stored with the agent.
-
-**createdAt** (`Date`): Timestamp when the agent was created.
-
-**updatedAt** (`Date`): Timestamp when the agent was last updated.
-
-## Related
-
-- [Mastra.listStoredAgents()](https://mastra.ai/reference/core/listStoredAgents)
-- [Storage overview](https://mastra.ai/reference/storage/overview)
-- [Agents overview](https://mastra.ai/docs/agents/overview)

package/.docs/reference/core/listStoredAgents.md

@@ -1,91 +0,0 @@
-# Mastra.listStoredAgents()
-
-The `.listStoredAgents()` method retrieves a paginated list of agent configurations from storage. By default, it returns executable `Agent` instances, but can also return raw storage data.
-
-## Usage example
-
-```typescript
-// Get Agent instances from storage
-const { agents, total, hasMore } = await mastra.listStoredAgents()
-
-for (const agent of agents) {
-  console.log(agent.id, agent.name)
-  // Each agent is ready to use
-  // const response = await agent.generate("Hello");
-}
-```
-
-```typescript
-// Get paginated results with raw storage data
-const result = await mastra.listStoredAgents({
-  page: 0,
-  perPage: 10,
-  raw: true,
-})
-
-console.log(`Showing ${result.agents.length} of ${result.total} agents`)
-console.log(`Has more: ${result.hasMore}`)
-
-for (const config of result.agents) {
-  console.log(config.id, config.name, config.createdAt)
-}
-```
-
-## Parameters
-
-**args** (`object`): Optional configuration object for pagination and output format.
-
-**args.page** (`number`): Zero-indexed page number for pagination.
-
-**args.perPage** (`number | false`): Number of items per page. Set to \`false\` to fetch all records without pagination.
-
-**args.raw** (`boolean`): When \`true\`, returns raw \`StorageAgentType\` objects instead of \`Agent\` instances.
-
-## Returns
-
-**agents** (`Agent[] | StorageAgentType[]`): Array of \`Agent\` instances by default, or \`StorageAgentType\` objects when \`raw: true\`.
-
-**total** (`number`): Total number of stored agents across all pages.
-
-**page** (`number`): Current page number (zero-indexed).
-
-**perPage** (`number | false`): Number of items per page, or \`false\` if fetching all.
-
-**hasMore** (`boolean`): Whether there are more pages available.
-
-## Primitive resolution
-
-When creating `Agent` instances (default behavior), each stored agent's configuration is resolved against registered primitives:
-
-- **Tools**: Resolved from `tools` registered in Mastra config
-- **Workflows**: Resolved from `workflows` registered in Mastra config
-- **Subagents**: Resolved from `agents` registered in Mastra config
-- **Memory**: Resolved from `memory` registered in Mastra config
-- **Scorers**: Resolved from `scorers` registered in Mastra config
-
-If a referenced primitive isn't found, a warning is logged but the agent is still created.
-
-## Example: Iterating through all stored agents
-
-```typescript
-async function getAllStoredAgents(mastra: Mastra) {
-  const allAgents: Agent[] = []
-  let page = 0
-  let hasMore = true
-
-  while (hasMore) {
-    const result = await mastra.listStoredAgents({ page, perPage: 50 })
-    allAgents.push(...result.agents)
-    hasMore = result.hasMore
-    page++
-  }
-
-  return allAgents
-}
-```
-
-## Related
-
-- [Mastra.getStoredAgentById()](https://mastra.ai/reference/core/getStoredAgentById)
-- [Storage overview](https://mastra.ai/reference/storage/overview)
-- [Agents overview](https://mastra.ai/docs/agents/overview)