@mastra/mcp-docs-server 1.1.35-alpha.8 → 1.1.36-alpha.1

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

@@ -0,0 +1,99 @@
+# Observability on Mastra platform
+
+Observability on Mastra platform is a standalone hosted product for searchable traces, logs, and metrics across Mastra projects and deploys. Use it when you want observability without deploying Studio first or setting up local storage.
+
+Mastra can configure platform observability during project setup. The CLI provisions a platform project, writes the required environment variables, and registers observability exporters in your Mastra config.
+
+## Quickstart
+
+Choose the setup path that matches your project. New and existing projects can use the CLI to provision Observability automatically, while manual setup is available when you already manage platform projects and environment variables yourself.
+
+### New project
+
+Create a new Mastra project:
+
+**npm**:
+
+```bash
+npm create mastra@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm create mastra
+```
+
+**Yarn**:
+
+```bash
+yarn create mastra
+```
+
+**Bun**:
+
+```bash
+bunx create-mastra
+```
+
+When prompted, enable Mastra Observability:
+
+```bash
+Enable Mastra Observability? (will open auth flow)
+
+> Yes
+```
+
+The CLI authenticates with Mastra platform, creates a platform project, writes the required environment variables, and configures the observability exporters.
+
+### Existing non-Mastra projects
+
+If you already have an application, such as a Next.js app, but have not added Mastra yet, run `mastra init` and enable Mastra Observability when prompted:
+
+**npm**:
+
+```bash
+npx mastra init
+```
+
+**pnpm**:
+
+```bash
+pnpm dlx mastra init
+```
+
+**Yarn**:
+
+```bash
+yarn dlx mastra init
+```
+
+**Bun**:
+
+```bash
+bun x mastra init
+```
+
+The CLI can select an existing platform project or create a new one.
+
+### Manual setup
+
+Create a project in [Mastra Platform](https://projects.mastra.ai), add `MASTRA_PLATFORM_ACCESS_TOKEN` and `MASTRA_PROJECT_ID` to `.env`, then register `MastraPlatformExporter` in your Mastra config. Add `MastraStorageExporter` if you also want to persist observability events to your configured Mastra Storage:
+
+```ts
+import { Mastra } from '@mastra/core/mastra'
+import { Observability, MastraPlatformExporter } from '@mastra/observability'
+
+export const mastra = new Mastra({
+  observability: new Observability({
+    configs: {
+      default: {
+        serviceName: 'mastra',
+        exporters: [new MastraPlatformExporter()],
+      },
+    },
+  }),
+})
+```
+
+See [Mastra platform configuration](https://mastra.ai/docs/mastra-platform/configuration) for the environment variables used by platform observability.

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

@@ -1,65 +1,22 @@
 # Mastra platform
 
-The [Mastra platform](https://projects.mastra.ai) provides two products for deploying and managing AI applications built with the Mastra framework:
+The [Mastra platform](https://projects.mastra.ai) provides three products for deploying, monitoring, and managing AI applications built with the Mastra framework:
 
-- **Studio**: A hosted visual environment for testing agents, running workflows, and inspecting traces
-- **Server**: A production deployment target that runs your Mastra application as an API server
+- [**Observability**](https://mastra.ai/docs/mastra-platform/observability): The baseline product for every platform project, with searchable traces, logs, and metrics across Mastra projects and deploys
+- [**Studio**](https://mastra.ai/docs/mastra-platform/studio): A hosted visual environment for testing agents, running workflows, and inspecting traces. Starting with Studio also gives you Observability.
+- [**Server**](https://mastra.ai/docs/mastra-platform/server): A production deployment target that runs your Mastra application as an API server. Starting with Server also gives you Observability.
 
-## Quickstart
+## Get started
 
-Before you begin, ensure you have Node.js 22.13.0 or later installed.
+Choose the path that matches what you want to do:
 
-1. Follow the [get started guide](https://mastra.ai/docs) to create your first Mastra project.
-
-2. Install the `mastra` CLI globally:
-
-   **npm**:
-
-   ```bash
-   npm install -g mastra
-   ```
-
-   **pnpm**:
-
-   ```bash
-   pnpm add -g mastra
-   ```
-
-   **Yarn**:
-
-   ```bash
-   yarn global add mastra
-   ```
-
-   **Bun**:
-
-   ```bash
-   bun add --global mastra
-   ```
-
-3. Deploy Studio with a single command:
-
-   ```bash
-   mastra studio deploy
-   ```
-
-   On a successful deploy, the CLI will output the URL of your deployed Studio instance.
-
-4. Deploy Server with a single command:
-
-   ```bash
-   mastra server deploy
-   ```
-
-   On a successful deploy, the CLI will output the URL of your deployed Server instance.
-
-You have now successfully deployed both Studio and Server instances of your Mastra application. The CLI created a `.mastra-project.json` file in your project directory.
-
-This file links your local project to a platform project. It's auto-generated on your first deploy and contains the `projectId`, `projectName`, and `organizationId`. Commit this file to your repository so CI/CD knows which project to deploy to.
+- **Add hosted observability**: Use [Observability](https://mastra.ai/docs/mastra-platform/observability) to collect searchable traces, logs, and metrics across projects and deploys. Start here if you want monitoring without deploying Studio or Server first.
+- **Deploy Studio**: Use [Studio](https://mastra.ai/docs/mastra-platform/studio) to host the visual development environment for your team. Start here if you want a shared UI for testing agents, running workflows, and inspecting traces.
+- **Deploy Server**: Use [Server](https://mastra.ai/docs/mastra-platform/server) to run your Mastra application as a production API server. Start here when you’re ready to serve agents, tools, and workflows from the cloud.
 
 ## Key Concepts
 
-**Projects** are the shared parent entity across all products. A single project can have a Studio deployment and a Server deployment. Projects belong to an **Organization**, which is the multi-tenant container for your team.
+**Projects** are the shared parent entity across all products. A single project can have Observability, a Studio deployment, and a Server deployment. Projects belong to an **Organization**, which is the multi-tenant container for your team.
 
 Your Mastra application is built from three building blocks:
 
@@ -73,6 +30,6 @@ Develop your project locally with [`mastra dev`](https://mastra.ai/reference/cli
 
 Once you're ready to deploy your application to production, use [`mastra studio deploy`](https://mastra.ai/reference/cli/mastra) and [`mastra server deploy`](https://mastra.ai/reference/cli/mastra) to push your application to the cloud.
 
-Follow the [Studio deployment guide](https://mastra.ai/docs/studio/deployment) and [Server deployment guide](https://mastra.ai/guides/deployment/mastra-platform) for step-by-step instructions.
+Follow the [Studio on Mastra platform](https://mastra.ai/docs/mastra-platform/studio) and [Server on Mastra platform](https://mastra.ai/docs/mastra-platform/server) docs for step-by-step instructions.
 
-If you host your Mastra application on your own infrastructure, you can still send observability data to Studio using the [CloudExporter](https://mastra.ai/docs/observability/tracing/exporters/cloud).
+If you host your Mastra application on your own infrastructure, you can still send observability data to Mastra platform using the [MastraPlatformExporter](https://mastra.ai/docs/observability/tracing/exporters/mastra-platform).

package/.docs/{guides/deployment/mastra-platform.md → docs/mastra-platform/server.md}

@@ -1,46 +1,42 @@
-# Deploy to Mastra platform
+# Server on Mastra platform
 
-Mastra Server deploys your application as a production API server on cloud infrastructure. You get a stable API endpoint, environment variable management, custom domain support, and deploy history out of the box.
+Server on Mastra platform is a production deployment target that runs your Mastra application as an API server. Use it when you want the platform to build, deploy, host, and manage your Mastra server.
 
-> **Tip:** This guide covers deploying the standalone server generated by `mastra build`. If you need to deploy Studio to the Mastra platform, see [Studio deployment](https://mastra.ai/docs/studio/deployment) instead.
+You get a stable API endpoint, environment variable management, custom domain support, and deploy history out of the box.
 
-## Before you begin
+> **Note:** Server deploy provisions hosted storage automatically. If you override storage with [LibSQLStore](https://mastra.ai/reference/storage/libsql) and a file URL, switch to a remotely hosted database because Mastra platform uses an ephemeral filesystem.
 
-You'll need a [Mastra application](https://mastra.ai/guides/getting-started/quickstart) and a [Mastra platform](https://projects.mastra.ai) account.
+## Quickstart
 
-> **Warning:** Mastra platform uses an ephemeral filesystem, so any storage you configure (including observability storage) must be hosted externally. If you're using [LibSQLStore](https://mastra.ai/reference/storage/libsql) with a file URL, switch to a remotely hosted database.
+1. Follow the [get started guide](https://mastra.ai/docs) to create your first Mastra project.
 
-## Installation
+2. Install the `mastra` CLI globally:
 
-Install the `mastra` CLI globally:
+   **npm**:
 
-**npm**:
-
-```bash
-npm install -g mastra
-```
-
-**pnpm**:
+   ```bash
+   npm install -g mastra
+   ```
 
-```bash
-pnpm add -g mastra
-```
+   **pnpm**:
 
-**Yarn**:
+   ```bash
+   pnpm add -g mastra
+   ```
 
-```bash
-yarn global add mastra
-```
+   **Yarn**:
 
-**Bun**:
+   ```bash
+   yarn global add mastra
+   ```
 
-```bash
-bun add --global mastra
-```
+   **Bun**:
 
-## Deploy
+   ```bash
+   bun add --global mastra
+   ```
 
-1. Deploy your project:
+3. Deploy your project:
 
    ```bash
    mastra server deploy
@@ -54,7 +50,7 @@ bun add --global mastra
 
    See the [CLI reference](https://mastra.ai/reference/cli/mastra) for the full list of flags.
 
-2. Verify your deployment at the URL printed by the CLI. Append `/api/agents` to confirm it returns a JSON list of your agents.
+4. Verify your deployment at the URL printed by the CLI. Append `/api/agents` to confirm it returns a JSON list of your agents.
 
    > **Warning:** Set up [authentication](https://mastra.ai/docs/server/auth) before exposing your endpoints publicly.
 
@@ -181,11 +177,8 @@ The CLI reads `organizationId` and `projectId` from `.mastra-project.json` by de
 
 ## Related
 
-- [CLI reference: `mastra server deploy`](https://mastra.ai/reference/cli/mastra)
-- [CLI reference: `mastra server pause`](https://mastra.ai/reference/cli/mastra)
-- [CLI reference: `mastra server restart`](https://mastra.ai/reference/cli/mastra)
-- [CLI reference: `mastra studio deploy`](https://mastra.ai/reference/cli/mastra)
-- [CLI reference: `mastra auth tokens`](https://mastra.ai/reference/cli/mastra)
-- [Mastra platform overview](https://mastra.ai/docs/mastra-platform/overview)
-- [Studio deployment](https://mastra.ai/docs/studio/deployment)
-- [Deployment overview](https://mastra.ai/docs/deployment/overview)
+- [`mastra server deploy`](https://mastra.ai/reference/cli/mastra)
+- [`mastra server pause`](https://mastra.ai/reference/cli/mastra)
+- [`mastra server restart`](https://mastra.ai/reference/cli/mastra)
+- [`mastra studio deploy`](https://mastra.ai/reference/cli/mastra)
+- [`mastra auth tokens`](https://mastra.ai/reference/cli/mastra)

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

@@ -0,0 +1,81 @@
+# Studio on Mastra platform
+
+Studio on Mastra platform is a hosted visual environment for testing agents, running workflows, and inspecting traces. Use it when you want to share Studio with your team without hosting the Studio UI yourself.
+
+## Quickstart
+
+1. Follow the [get started guide](https://mastra.ai/docs) to create your first Mastra project.
+
+2. Install the `mastra` CLI globally:
+
+   **npm**:
+
+   ```bash
+   npm install -g mastra
+   ```
+
+   **pnpm**:
+
+   ```bash
+   pnpm add -g mastra
+   ```
+
+   **Yarn**:
+
+   ```bash
+   yarn global add mastra
+   ```
+
+   **Bun**:
+
+   ```bash
+   bun add --global mastra
+   ```
+
+3. Deploy Studio with a single command:
+
+   ```bash
+   mastra studio deploy
+   ```
+
+   On a successful deploy, the CLI outputs the URL of your deployed Studio instance.
+
+On your first deploy, the CLI prompts you to create a new project or select an existing one. It then creates a `.mastra-project.json` file in your project directory. This file links your local project to a platform project. It contains the `projectId`, `projectName`, and `organizationId`. Commit this file to your repository so CI/CD knows which project to deploy to.
+
+## How deploy works
+
+The `mastra studio deploy` command builds your project, compiles `src/mastra/` into `.mastra/output`, packages the output as an artifact ZIP, uploads it, and deploys it to a cloud sandbox.
+
+A deploy transitions through **queued → uploading → starting → running** or **failed** if something goes wrong. If a sandbox is already running for your project, the platform updates it in place with no downtime. Otherwise, it creates a fresh sandbox. Your instance URL is assigned per project slug and remains stable across deploys.
+
+See the [`mastra studio deploy` CLI reference](https://mastra.ai/reference/cli/mastra) for the full list of flags and CI/CD usage.
+
+## Environment files
+
+The deploy bundles environment variables from a `.env` or `.env.*` file in the project directory. If no env file is present, the deploy errors with `No env file found for deploy.` after the build step. Add at least an empty `.env` file before running the command.
+
+When multiple env files are present, the CLI prompts you to pick one. To select non-interactively, pass `--env-file`:
+
+```bash
+mastra studio deploy --env-file .env.production --yes
+```
+
+This is also how you target multiple environments from a single codebase: maintain one env file per environment, such as `.env.staging` and `.env.production`, and pass the right one to each deploy. Each environment still requires its own Mastra platform project. See [Configuration](https://mastra.ai/docs/mastra-platform/configuration) for the multi-environment pattern.
+
+## Create a new project non-interactively
+
+`mastra studio deploy` can create a project on first run. If `--project <name>` doesn't match an existing project, the CLI uses the value as the new project name and creates it after confirmation. Combined with `--yes`, this is fully scriptable:
+
+```bash
+mastra studio deploy --project "my-new-project" --yes
+```
+
+Use this from CI or AI coding agents instead of `mastra studio projects create`, which is interactive only.
+
+## Self-host Studio
+
+To deploy Studio on your own infrastructure, see [Studio deployment](https://mastra.ai/docs/studio/deployment).
+
+## Related
+
+- [`mastra studio deploy`](https://mastra.ai/reference/cli/mastra)

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

@@ -77,6 +77,48 @@ The observer also sees these markers when it processes the thread, so the observ
 
 See [the API reference](https://mastra.ai/reference/memory/observational-memory) for the full configuration shape.
 
+## Early activation
+
+OM can activate buffered observations before the token threshold is reached. This is useful when a prompt cache is likely to expire, or when the agent changes model providers.
+
+Top-level early activation settings apply to observations by default:
+
+```typescript
+const memory = new Memory({
+  options: {
+    observationalMemory: {
+      model: 'google/gemini-2.5-flash',
+      activateAfterIdle: '5m',
+      activateOnProviderChange: true,
+    },
+  },
+})
+```
+
+Use nested `observation` and `reflection` settings for per-phase control. Reflection early activation is opt-in, so top-level settings affect only observations.
+
+```typescript
+const memory = new Memory({
+  options: {
+    observationalMemory: {
+      model: 'google/gemini-2.5-flash',
+      activateAfterIdle: '5m',
+      observation: {
+        activateAfterIdle: false,
+      },
+      reflection: {
+        activateAfterIdle: '10m',
+        activateOnProviderChange: true,
+      },
+    },
+  },
+})
+```
+
+In this example, the top-level idle setting is disabled for observations, while reflections opt into idle and provider-change activation.
+
+See [the API reference](https://mastra.ai/reference/memory/observational-memory) for the full configuration shape.
+
 ## Benefits
 
 - **Prompt caching**: OM's context is stable and observations append over time rather than being dynamically retrieved each turn. This keeps the prompt prefix cacheable, which reduces costs.
@@ -216,7 +258,7 @@ The Observer and Reflector run in the background. Any model that works with Mast
 
 Generally speaking, we recommend using a model that has a large context window (128K+ tokens) and is fast enough to run in the background without slowing down your actions.
 
-If you're unsure which model to use, start with the default `google/gemini-2.5-flash`. We've also successfully tested `openai/gpt-5-mini`, `anthropic/claude-haiku-4-5`, `deepseek/deepseek-reasoner`, `qwen3`, and `glm-4.7`.
+If you're unsure which model to use, start with the default `google/gemini-2.5-flash`. We've also successfully tested `openai/gpt-5-mini`, `anthropic/claude-haiku-4-5`, `deepseek/deepseek-reasoner`, `deepseek/deepseek-v4-pro`, `deepseek/deepseek-v4-flash`, `xai/grok-4-1-fast`, `qwen3`, and `glm-4.7`.
 
 ```typescript
 const memory = new Memory({
@@ -230,6 +272,10 @@ const memory = new Memory({
 
 See [model configuration](https://mastra.ai/reference/memory/observational-memory) for using different models per agent.
 
+> **Note:** `google/gemini-2.5-flash` is unusually good at preserving detail in long output. As a result, the Reflector can produce reflections that stay above the configured `reflection.observationTokens` threshold even after the maximum compression retry. When this happens, the Reflector returns the smallest non-degenerate candidate produced during retries so the loop terminates instead of running forever.
+>
+> If you'd rather have more aggressive compression on the Reflector, swap to a model that condenses more readily, such as `xai/grok-4-1-fast`, `deepseek/deepseek-v4-pro`, or `deepseek/deepseek-v4-flash`. You can keep `google/gemini-2.5-flash` for the Observer and use a different model for the Reflector — see [different models per agent](https://mastra.ai/reference/memory/observational-memory).
+
 ### Token-tiered model selection
 
 **Added in:** `@mastra/memory@1.10.0`
@@ -364,17 +410,19 @@ Reflection works similarly — the Reflector runs in the background when observa
 
 ### Settings
 
-| Setting                        | Default | What it controls                                                                                                                                                                                                                                                                                                                       |
-| ------------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `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.                                                                                                                                                                   |
-| `activateAfterIdle`            | none    | Forces buffered observations and buffered reflections to activate after a period of inactivity, even if their token thresholds have not been reached yet. Accepts milliseconds or duration strings like `300_000`, `"5m"`, or `"1hr"`. Set this to your prompt cache TTL if you want activation to happen before the next cold prompt. |
-| `activateOnProviderChange`     | `false` | Forces buffered observations and reflections 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.                                                                                                                                                                                                   |
-| `reflection.blockAfter`        | `1.2`   | Safety threshold for reflection, same logic as observation.                                                                                                                                                                                                                                                                            |
+| Setting                               | Default | What it controls                                                                                                                                                                                                                                                                                                              |
+| ------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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.                                                                                                                                                          |
+| `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`, or duration strings like `"5m"` or `"1hr"`. Set this to your prompt cache TTL if you want activation to happen before the next cold prompt. |
+| `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.                                                                                                                                                                                          |
+| `reflection.activateAfterIdle`        | none    | Opts buffered reflections into idle activation. Reflections don't inherit top-level `activateAfterIdle`.                                                                                                                                                                                                                      |
+| `reflection.activateOnProviderChange` | `false` | Opts buffered reflections into provider-change activation. Reflections don't inherit top-level `activateOnProviderChange`.                                                                                                                                                                                                    |
+| `reflection.blockAfter`               | `1.2`   | Safety threshold for reflection, same logic as observation.                                                                                                                                                                                                                                                                   |
 
-If you're relying on prompt caching, set `activateAfterIdle` to match your cache TTL. That way, once a thread has been idle long enough for the cache to expire, the next request can activate buffered observations or reflections first and send a smaller compressed context window.
+If you're relying on prompt caching, set `activateAfterIdle` to match your cache TTL. That way, once a thread has been idle long enough for the cache to expire, the next request can activate buffered observations first and send a smaller compressed context window.
 
 ```typescript
 const memory = new Memory({
@@ -388,9 +436,9 @@ const memory = new Memory({
 })
 ```
 
-With a 5-minute prompt cache TTL, this activates buffered context after 5 minutes of inactivity so the next uncached prompt uses observations and reflections instead of a larger raw message window. If you prefer, `300_000` works the same way.
+With a 5-minute prompt cache TTL, this activates buffered observations after 5 minutes of inactivity so the next uncached prompt uses compressed observations instead of a larger raw message window. If you prefer, `300_000` works the same way.
 
-Changing model or providers mid-thread will invalidate the prompt cache. If your agent can switch between providers or models mid-thread, `activateOnProviderChange: true` forces buffered context to activate before the new provider runs. That avoids sending a large raw window to a provider that cannot reuse the previous prompt cache.
+Changing model or providers mid-thread will invalidate the prompt cache. If your agent can switch between providers or models mid-thread, `activateOnProviderChange: true` forces buffered observations to activate before the new provider runs. That avoids sending a large raw window to a provider that can't reuse the previous prompt cache.
 
 ### Disabling
 

package/.docs/docs/memory/semantic-recall.md

@@ -121,26 +121,88 @@ Each vector store page below includes installation instructions, configuration p
 
 ## Recall configuration
 
-The three main parameters that control semantic recall behavior are:
+The following options control semantic recall behavior:
 
-1. **topK**: How many semantically similar messages to retrieve
-2. **messageRange**: How much surrounding context to include with each match
-3. **scope**: Whether to search within the current thread or across all threads owned by a resource (the default is resource scope).
+1. **topK**: The number of similar messages to retrieve
+2. **messageRange**: The surrounding messages to include with each match
+3. **scope**: Whether to search the current thread or all threads for a resource
+4. **filter**: Metadata criteria that restrict search results
 
 ```typescript
 const agent = new Agent({
   memory: new Memory({
     options: {
       semanticRecall: {
-        topK: 3, // Retrieve 3 most similar messages
+        topK: 3, // Retrieve 3 similar messages
         messageRange: 2, // Include 2 messages before and after each match
-        scope: 'resource', // Search across all threads for this user (default setting if omitted)
+        scope: 'resource', // Search all threads for this resource
+        filter: { projectId: { $eq: 'project-a' } },
       },
     },
   }),
 })
 ```
 
+> **Note:** `scope: 'resource'` is supported by the LibSQL, PostgreSQL, and Upstash storage adapters.
+
+### Metadata filtering
+
+The `filter` option restricts semantic recall results to messages with matching thread metadata.
+
+```typescript
+const agent = new Agent({
+  memory: new Memory({
+    options: {
+      semanticRecall: {
+        scope: 'resource',
+        filter: {
+          projectId: { $eq: 'project-a' },
+          category: { $in: ['work', 'personal'] },
+        },
+      },
+    },
+  }),
+})
+```
+
+Filters match metadata stored on message embeddings when messages are saved. If thread metadata changes later, existing embeddings keep their previous metadata until those messages are saved or indexed again.
+
+Supported filter operators:
+
+- `$and`: Logical AND
+- `$eq`: Equal to
+- `$gt`: Greater than
+- `$gte`: Greater than or equal
+- `$in`: In array
+- `$lt`: Less than
+- `$lte`: Less than or equal
+- `$ne`: Not equal to
+- `$nin`: Not in array
+- `$or`: Logical OR
+
+The following example demonstrates metadata filters for common use cases:
+
+```typescript
+// Filter by project
+const options = {
+  semanticRecall: { filter: { projectId: { $eq: 'my-project' } } },
+}
+
+// Filter by multiple categories
+const options = {
+  semanticRecall: { filter: { category: { $in: ['work', 'research'] } } },
+}
+
+// Filter by project and priority
+const options = {
+  semanticRecall: {
+    filter: {
+      $and: [{ projectId: { $eq: 'project-a' } }, { priority: { $gte: 3 } }],
+    },
+  },
+}
+```
+
 ## Embedder configuration
 
 Semantic recall relies on an [embedding model](https://mastra.ai/reference/memory/memory-class) to convert messages into embeddings. Mastra supports embedding models through the model router using `provider/model` strings, or you can use any [embedding model](https://sdk.vercel.ai/docs/ai-sdk-core/embeddings) compatible with the AI SDK.

package/.docs/docs/observability/logging.md

@@ -35,7 +35,7 @@ You can control which log levels reach observability storage independently from
 ```typescript
 import { Mastra } from '@mastra/core/mastra'
 import { PinoLogger } from '@mastra/loggers'
-import { Observability, DefaultExporter } from '@mastra/observability'
+import { Observability, MastraStorageExporter } from '@mastra/observability'
 
 export const mastra = new Mastra({
   logger: new PinoLogger({ name: 'Mastra', level: 'debug' }),
@@ -43,7 +43,7 @@ export const mastra = new Mastra({
     configs: {
       default: {
         serviceName: 'my-app',
-        exporters: [new DefaultExporter()],
+        exporters: [new MastraStorageExporter()],
         logging: {
           enabled: true, // set to false to disable log forwarding
           level: 'info', // minimum level: 'debug' | 'info' | 'warn' | 'error' | 'fatal'

package/.docs/docs/observability/metrics/overview.md

@@ -54,7 +54,7 @@ import { Mastra } from '@mastra/core/mastra'
 import { LibSQLStore } from '@mastra/libsql'
 import { DuckDBStore } from '@mastra/duckdb'
 import { MastraCompositeStore } from '@mastra/core/storage'
-import { Observability, DefaultExporter, SensitiveDataFilter } from '@mastra/observability'
+import { Observability, MastraStorageExporter, SensitiveDataFilter } from '@mastra/observability'
 
 export const mastra = new Mastra({
   storage: new MastraCompositeStore({
@@ -71,7 +71,7 @@ export const mastra = new Mastra({
     configs: {
       default: {
         serviceName: 'mastra',
-        exporters: [new DefaultExporter()],
+        exporters: [new MastraStorageExporter()],
         spanOutputProcessors: [new SensitiveDataFilter()],
       },
     },
@@ -103,7 +103,7 @@ Mastra auto-instruments agent runs, workflow steps, tool calls, and model genera
 2. **Token usage**: Extracted from the `usage` attribute on model generation spans.
 3. **Cost estimation**: Runs each token metric through an embedded pricing registry that matches by provider and model name.
 
-Before storage, all metric labels pass through a cardinality filter that blocks known high-cardinality values (such as trace IDs and UUIDs) to keep storage efficient. Metrics are then batched by an internal event buffer and flushed to storage by the `DefaultExporter`.
+Before storage, all metric labels pass through a cardinality filter that blocks known high-cardinality values (such as trace IDs and UUIDs) to keep storage efficient. Metrics are then batched by an internal event buffer and flushed to storage by the `MastraStorageExporter`.
 
 ## Next steps
 
@@ -111,4 +111,4 @@ Before storage, all metric labels pass through a cardinality filter that blocks
 - [Tracing overview](https://mastra.ai/docs/observability/tracing/overview)
 - [Studio observability](https://mastra.ai/docs/studio/observability)
 - [Observability overview](https://mastra.ai/docs/observability/overview)
-- [DefaultExporter reference](https://mastra.ai/docs/observability/tracing/exporters/default)
+- [MastraStorageExporter reference](https://mastra.ai/docs/observability/tracing/exporters/mastra-storage)