@mastra/mcp-docs-server 1.1.18-alpha.1 → 1.1.18-alpha.4

package/.docs/docs/agents/overview.md

@@ -38,7 +38,7 @@ export const mastra = new Mastra({
 
 Once registered, it can be called from workflows, tools, or other agents, and has access to shared resources such as memory, logging, and observability features.
 
-> **Tip:** Use [Studio](https://mastra.ai/docs/getting-started/studio) to test your agent with different messages, inspect tool calls and responses, and debug agent behavior.
+> **Tip:** Use [Studio](https://mastra.ai/docs/studio/overview) to test your agent with different messages, inspect tool calls and responses, and debug agent behavior.
 
 > **Note:** Visit the [agent reference](https://mastra.ai/reference/agents/agent) for more information on available properties and configurations.
 
@@ -48,7 +48,7 @@ After registration, retrieve your agent with [`mastra.getAgentById()`](https://m
 
 When referencing an agent from your Mastra instance, use `mastra.getAgentById()` to ensure it has access to shared services such as instance-level storage, logging, and agent registry. A directly imported agent can still work with its own local configuration, but it won't have access to those shared services.
 
-**Generate**:
+**.generate()**:
 
 Returns the full response after all tool calls and steps complete. The result includes `text`, `toolCalls`, `toolResults`, `steps`, and token `usage` statistics.
 
@@ -58,7 +58,7 @@ const response = await agent.generate('Help me organize my day')
 console.log(response.text)
 ```
 
-**Stream**:
+**.stream()**:
 
 Returns a stream you can consume as tokens arrive. The result exposes `textStream` for incremental output and promises for `toolCalls`, `toolResults`, `steps`, and token `usage` that resolve when the stream finishes.
 
@@ -90,6 +90,6 @@ Once your agent is running, use this table to find the right page for what you w
 
 ## Multi-agent systems
 
-A multi-agent system uses multiple agents to solve a task that is too broad or too specialized for a single agent. Instead of building one agent with dozens of tools and a long instruction set, you split responsibilities across focused agents and let a coordinator bring results together.
+A multi-agent system uses multiple agents to solve a task that's too broad or too specialized for a single agent. Instead of building one agent with dozens of tools and a long instruction set, you split responsibilities across focused agents and let a coordinator bring results together.
 
 Read the [conceptual overview of multi-agent systems](https://mastra.ai/guides/concepts/multi-agent-systems) to learn how you can apply different patterns with Mastra.

package/.docs/docs/agents/processors.md

@@ -493,7 +493,7 @@ After a `.parallel()` step, each branch result is keyed by its processor ID (e.g
 
 If a branch uses a mutating strategy like `redact`, map to that branch so its transformed messages carry forward. If all branches only `block`, any branch works. Pick any one since none of them modify the messages.
 
-When an agent is registered with Mastra, processor workflows are automatically registered as workflows, allowing you to view and debug them in the [Studio](https://mastra.ai/docs/getting-started/studio).
+When an agent is registered with Mastra, processor workflows are automatically registered as workflows, allowing you to view and debug them in the [Studio](https://mastra.ai/docs/studio/overview).
 
 ### Retry mechanism
 

package/.docs/docs/community/licensing.md

@@ -1,10 +1,8 @@
 # License
 
-## Apache license 2.0
-
 Mastra is licensed under the Apache License 2.0, a permissive open-source license that provides users with broad rights to use, modify, and distribute the software.
 
-### What's Apache License 2.0?
+## What's Apache License 2.0?
 
 The Apache License 2.0 is a permissive open-source license that grants users extensive rights to use, modify, and distribute the software. It allows:
 
@@ -16,7 +14,7 @@ The Apache License 2.0 is a permissive open-source license that grants users ext
 
 The Apache License 2.0 is one of the most permissive and business-friendly open-source licenses available.
 
-### Why We Chose Apache License 2.0
+## Why We Chose Apache License 2.0
 
 We selected the Apache License 2.0 for several important reasons:
 
@@ -30,11 +28,11 @@ We selected the Apache License 2.0 for several important reasons:
 
 5. **Widely Adopted**: It's one of the most popular and well-understood open-source licenses in the industry.
 
-### Building Your Business with Mastra
+## Building Your Business with Mastra
 
 The Apache License 2.0 provides maximum flexibility for building businesses with Mastra:
 
-#### Allowed Business Models
+### Allowed Business Models
 
 - **Building Applications**: Create and sell applications built with Mastra
 - **Offering Consulting Services**: Provide expertise, implementation, and customization services
@@ -44,7 +42,7 @@ The Apache License 2.0 provides maximum flexibility for building businesses with
 - **Hosted Services**: Offer Mastra as a hosted or managed service
 - **SaaS Platforms**: Build SaaS platforms powered by Mastra
 
-#### Examples of Compliant Usage
+### Examples of Compliant Usage
 
 - A company builds an AI-powered customer service application using Mastra and sells it to clients
 - A consulting firm offers implementation and customization services for Mastra
@@ -53,7 +51,7 @@ The Apache License 2.0 provides maximum flexibility for building businesses with
 - A company offers Mastra as a hosted service to their customers
 - A SaaS platform integrates Mastra as their AI backend
 
-#### Compliance Requirements
+### Compliance Requirements
 
 The Apache License 2.0 has minimal requirements:
 
@@ -61,6 +59,6 @@ The Apache License 2.0 has minimal requirements:
 - **State Changes**: If you modify the software, state that you have made changes
 - **Include License**: Include a copy of the Apache License 2.0 when distributing
 
-### Questions About Licensing?
+## Questions About Licensing?
 
 If you have specific questions about how the Apache License 2.0 applies to your use case, please [contact us](https://discord.gg/BTYqqHKUrf) on Discord for clarification. We're committed to supporting all legitimate use cases while maintaining the open-source nature of the project.

package/.docs/docs/deployment/monorepo.md

@@ -105,12 +105,6 @@ When deploying to cloud providers, ensure the correct package is selected as the
 
 Most providers let you specify the root directory in their dashboard or configuration file.
 
-### Mastra Cloud
-
-The image below shows how to select `apps/api` as the project root when deploying to [Mastra Cloud](https://mastra.ai/docs/mastra-cloud/overview). While the interface may differ between providers, the configuration remains the same.
-
-![Deployment configuration](/assets/images/monorepo-mastra-cloud-6bd3d30cb0ef7c255c8d8bb43aeff4ec.jpg)
-
 ## Dependency management
 
 Keep dependencies consistent to avoid version conflicts and build errors:

package/.docs/docs/evals/built-in-scorers.md

@@ -28,7 +28,7 @@ These scorers evaluate the quality and relevance of context used in generating r
 - [`context-precision`](https://mastra.ai/reference/evals/context-precision): Evaluates context relevance and ranking using Mean Average Precision, rewarding early placement of relevant context (`0-1`, higher is better)
 - [`context-relevance`](https://mastra.ai/reference/evals/context-relevance): Measures context utility with nuanced relevance levels, usage tracking, and missing context detection (`0-1`, higher is better)
 
-> tip Context Scorer Selection
+> **Context Scorer Selection:**
 >
 > - Use **Context Precision** when context ordering matters and you need standard IR metrics (ideal for RAG ranking evaluation)
 > - Use **Context Relevance** when you need detailed relevance assessment and want to track context usage and identify gaps

package/.docs/docs/{observability → evals}/datasets/overview.md

@@ -41,6 +41,16 @@ const { datasets: all } = await datasets.list()
 
 > **Info:** Visit the [`DatasetsManager` reference](https://mastra.ai/reference/datasets/datasets-manager) for the full list of methods.
 
+## Studio
+
+You can also manage datasets in [Studio](https://mastra.ai/docs/studio/overview). After opening Studio, select **Datasets** from the sidebar to see all your available datasets or create a new one.
+
+To get started, select **Create Dataset** and set a name, description, and optional schemas. After confirming, you'll see the dataset details page with two tabs: **Items** and [**Experiments**](https://mastra.ai/docs/evals/datasets/running-experiments).
+
+In the **Items** view you can add, update, and delete items, and view version history. Select **Add Item** to insert a new item with JSON editors for input and ground truth. From this view you can also import items in bulk from a CSV or JSON file. When importing, map each column to the corresponding dataset field.
+
+Select **Versions** to see the full history of changes to the dataset. After selecting **Compare Versions**, choose any two versions and select **Compare** to see a side-by-side diff of all items that were added, changed, or removed between those versions.
+
 ## Creating a dataset
 
 Call [`create()`](https://mastra.ai/reference/datasets/create) with a name and optional description:
@@ -176,23 +186,13 @@ Fetch the exact items that existed at a past version:
 const items = await dataset.listItems({ version: 2 })
 ```
 
-You can also pin experiments to a version, see [running experiments](https://mastra.ai/docs/observability/datasets/running-experiments).
+You can also pin experiments to a version, see [running experiments](https://mastra.ai/docs/evals/datasets/running-experiments).
 
 > **Info:** Visit the [`Dataset` reference](https://mastra.ai/reference/datasets/dataset) for the full list of methods and parameters.
 
-## Studio
-
-You can also manage datasets in [Mastra Studio](https://mastra.ai/docs/getting-started/studio). After opening Studio, select **Datasets** from the sidebar to see all your available datasets or create a new one.
-
-To get started, select **Create Dataset** and set a name, description, and optional schemas. After confirming, you'll see the dataset details page with two tabs: **Items** and [**Experiments**](https://mastra.ai/docs/observability/datasets/running-experiments).
-
-In the **Items** view you can add, update, and delete items, and view version history. Select **Add Item** to insert a new item with JSON editors for input and ground truth. From this view you can also import items in bulk from a CSV or JSON file. When importing, map each column to the corresponding dataset field.
-
-Select **Versions** to see the full history of changes to the dataset. After selecting **Compare Versions**, choose any two versions and select **Compare** to see a side-by-side diff of all items that were added, changed, or removed between those versions.
-
 ## Related
 
-- [Running experiments](https://mastra.ai/docs/observability/datasets/running-experiments)
+- [Running experiments](https://mastra.ai/docs/evals/datasets/running-experiments)
 - [Scorers overview](https://mastra.ai/docs/evals/overview)
 - [DatasetsManager reference](https://mastra.ai/reference/datasets/datasets-manager)
 - [Dataset reference](https://mastra.ai/reference/datasets/dataset)

package/.docs/docs/{observability → evals}/datasets/running-experiments.md

@@ -27,6 +27,14 @@ console.log(summary.failedCount) // number of items that failed
 
 `startExperiment()` blocks until all items finish. For fire-and-forget execution, see [async experiments](#async-experiments).
 
+## Studio
+
+You can also run experiments in [Studio](https://mastra.ai/docs/studio/overview). After you've added a dataset item, open it and select **Run Experiment** and configure the target, scorers, and options.
+
+After running an experiment, the **Experiments** tab shows all runs for that dataset (with status, counts, and timestamps). Select an experiment to see per-item results, scores, and execution traces.
+
+In the **Experiments** tab, select **Compare** and choose two or more experiments to compare their scores and results side by side.
+
 ## Experiment targets
 
 You can point an experiment at a registered agent, workflow, or scorer.
@@ -258,17 +266,9 @@ for (const result of results) {
 
 > **Info:** Visit the [`startExperiment` reference](https://mastra.ai/reference/datasets/startExperiment) for the full parameter and return type documentation.
 
-## Studio
-
-You can also run experiments in [Mastra Studio](https://mastra.ai/docs/getting-started/studio). After you've added a dataset item, open it and select **Run Experiment** and configure the target, scorers, and options.
-
-After running an experiment, the **Experiments** tab shows all runs for that dataset (with status, counts, and timestamps). Select an experiment to see per-item results, scores, and execution traces.
-
-In the **Experiments** tab, select **Compare** and choose two or more experiments to compare their scores and results side by side.
-
 ## Related
 
-- [Datasets overview](https://mastra.ai/docs/observability/datasets/overview)
+- [Datasets overview](https://mastra.ai/docs/evals/datasets/overview)
 - [Scorers overview](https://mastra.ai/docs/evals/overview)
 - [`startExperiment` reference](https://mastra.ai/reference/datasets/startExperiment)
 - [`listExperimentResults` reference](https://mastra.ai/reference/datasets/listExperimentResults)

package/.docs/docs/evals/overview.md

@@ -111,9 +111,9 @@ export const contentWorkflow = createWorkflow({ ... })
 
 In addition to live evaluations, you can use scorers to evaluate historical traces from your agent interactions and workflows. This is particularly useful for analyzing past performance, debugging issues, or running batch evaluations.
 
-> **Observability Required:** To score traces, you must first configure observability in your Mastra instance to collect trace data. See [Tracing documentation](https://mastra.ai/docs/observability/tracing/overview) for setup instructions.
+> **Observability required:** To score traces, you must first configure observability in your Mastra instance to collect trace data. See [Tracing documentation](https://mastra.ai/docs/observability/tracing/overview) for setup instructions.
 
-### Scoring traces with Studio
+## Studio
 
 To score traces, you first need to register your scorers with your Mastra instance:
 
@@ -126,16 +126,15 @@ const mastra = new Mastra({
 })
 ```
 
-Once registered, you can score traces interactively within Studio under the Observability section. This provides a user-friendly interface for running scorers against historical traces.
+Once registered, you can score traces interactively within Studio under the **Observability** section. Open Studio to manage scorers, review scores, and run experiments.
 
-## Testing scorers locally
-
-Mastra provides a CLI command `mastra dev` to test your scorers. Studio includes a scorers section where you can run individual scorers against test inputs and view detailed results.
-
-For more details, see [Studio](https://mastra.ai/docs/getting-started/studio) docs.
+- **Scorers list**: Browse all registered scorers with their description, and the number of agents and workflows each scorer is attached to.
+- **Score results**: Select a scorer to see a paginated list of every score it has produced. Click a row to open the detail panel, which shows the score value, reason, input, output, and the prompts used by the judge. From this panel, save any result as a dataset item for future experiments.
+- **Agent Evaluate tab**: Open the Evaluate tab on any agent to attach or detach scorers, create or edit stored scorers inline, manage datasets, and run experiments. Experiment results display per-item scores alongside pass/fail status and version tags.
+- **Trace scoring**: In the Observability section, run a scorer against any historical trace or span to evaluate past interactions. Filter scores by agent or workflow.
 
 ## Next steps
 
 - Learn how to create your own scorers in the [Creating Custom Scorers](https://mastra.ai/docs/evals/custom-scorers) guide
 - Explore built-in scorers in the [Built-in Scorers](https://mastra.ai/docs/evals/built-in-scorers) section
-- Test scorers with [Studio](https://mastra.ai/docs/getting-started/studio)
+- Test scorers with [Studio](https://mastra.ai/docs/studio/overview)

package/.docs/docs/getting-started/manual-install.md

@@ -71,7 +71,6 @@ If you prefer not to use our automatic CLI tool, you can set up your project you
    ```json
    {
      "scripts": {
-       "test": "echo \"Error: no test specified\" && exit 1",
        "dev": "mastra dev",
        "build": "mastra build"
      }
@@ -199,7 +198,7 @@ If you prefer not to use our automatic CLI tool, you can set up your project you
    })
    ```
 
-7. You can now launch [Studio](https://mastra.ai/docs/getting-started/studio) and test your agent.
+7. You can now launch [Studio](https://mastra.ai/docs/studio/overview) and test your agent.
 
    **npm**:
 

package/.docs/docs/index.md

@@ -4,7 +4,7 @@ Build AI agents your users actually depend on. Mastra is a TypeScript framework
 
 ## Quickstart
 
-Run this command to create a new project you can test immediately in [Studio](https://mastra.ai/docs/getting-started/studio):
+Run this command to create a new project you can test immediately in [Studio](https://mastra.ai/docs/studio/overview):
 
 **npm**:
 

package/.docs/docs/mastra-cloud/deployment.md

@@ -73,5 +73,5 @@ After deployment, interact with your agents using the [Mastra Client](https://ma
 
 ## Next steps
 
-- [Studio](https://mastra.ai/docs/mastra-cloud/studio) - Test your agents in the cloud
-- [Observability](https://mastra.ai/docs/mastra-cloud/observability) - Monitor traces and logs
+- [Studio](https://mastra.ai/docs/mastra-cloud/overview): Test your agents in the cloud
+- [Observability](https://mastra.ai/docs/mastra-cloud/observability): Monitor traces and logs

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

@@ -10,7 +10,7 @@ Traces are available for both agents and workflows by enabling [observability](h
 
 ### Agents
 
-With observability enabled, you can view detailed outputs from your agents in the **Traces** section in [Studio](https://mastra.ai/docs/mastra-cloud/studio).
+With observability enabled, you can view detailed outputs from your agents in the **Traces** section in [Studio](https://mastra.ai/docs/mastra-cloud/overview).
 
 ![observability agents](/assets/images/mastra-cloud-observability-agents-a51e3bcac8589ba42fc5bd958a627187.jpg)
 
@@ -18,7 +18,7 @@ Agent traces break a run into clear steps: model calls, tool calls, and intermed
 
 ### Workflows
 
-With observability enabled, you can view detailed outputs from your workflows in the **Traces** section in [Studio](https://mastra.ai/docs/mastra-cloud/studio).
+With observability enabled, you can view detailed outputs from your workflows in the **Traces** section in [Studio](https://mastra.ai/docs/mastra-cloud/overview).
 
 ![observability workflows](/assets/images/mastra-cloud-observability-workflows-47baf49146575e665e3aad9f1fd65e5f.jpg)
 

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

@@ -4,7 +4,7 @@
 
 ## Studio
 
-Run [Studio](https://mastra.ai/docs/mastra-cloud/studio) in the cloud and share access with your team via a link. Team members can test agents and workflows, tweak system prompts, and give feedback without running the project locally.
+Run [Studio](https://mastra.ai/docs/studio/overview) in the cloud and share access with your team via a link. Team members can test agents and workflows, tweak system prompts, and give feedback without running the project locally.
 
 ## Deploy
 

package/.docs/docs/mastra-cloud/setup.md

@@ -1,6 +1,6 @@
 # Setup
 
-Import your Mastra project to [Mastra Cloud](https://cloud.mastra.ai) to use [Studio](https://mastra.ai/docs/mastra-cloud/studio) and optionally [deploy](https://mastra.ai/docs/mastra-cloud/deployment) your agent.
+Import your Mastra project to [Mastra Cloud](https://cloud.mastra.ai) to use [Studio](https://mastra.ai/docs/mastra-cloud/overview) and optionally [deploy](https://mastra.ai/docs/mastra-cloud/deployment) your agent.
 
 ## Before you begin
 
@@ -14,7 +14,7 @@ Import your Mastra project to [Mastra Cloud](https://cloud.mastra.ai) to use [St
 When you create a new project, you can choose from three options:
 
 1. **Create from GitHub** - Import a Mastra project from GitHub
-2. **Create from your server** - Connect a self-hosted Mastra instance to [Studio](https://mastra.ai/docs/mastra-cloud/studio)
+2. **Create from your server** - Connect a self-hosted Mastra instance to [Studio](https://mastra.ai/docs/mastra-cloud/overview)
 3. **Create from template** - Start from a [pre-built template](https://mastra.ai/templates)
 
 To create a project from GitHub, follow these steps:
@@ -37,6 +37,6 @@ To create a project from GitHub, follow these steps:
 
 ## Next steps
 
-Once your project is imported, [Studio](https://mastra.ai/docs/mastra-cloud/studio) automatically creates a sandbox where you can interact with your agents and share access with your team.
+Once your project is imported, [Studio](https://mastra.ai/docs/mastra-cloud/overview) automatically creates a sandbox where you can interact with your agents and share access with your team.
 
 When you're ready for production, enable [Deployment](https://mastra.ai/docs/mastra-cloud/deployment) settings and hit deploy!

package/.docs/docs/mcp/publishing-mcp-server.md

@@ -6,10 +6,30 @@ This example guides you through setting up a basic Mastra MCPServer using the st
 
 Install the necessary packages:
 
+**npm**:
+
+```bash
+npm install @mastra/mcp @mastra/core tsup
+```
+
+**pnpm**:
+
 ```bash
 pnpm add @mastra/mcp @mastra/core tsup
 ```
 
+**Yarn**:
+
+```bash
+yarn add @mastra/mcp @mastra/core tsup
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/mcp @mastra/core tsup
+```
+
 ## Setting up an MCP server
 
 1. Create a file for your stdio server, for example, `/src/mastra/stdio.ts`.

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

@@ -48,7 +48,7 @@ export const mastra = new Mastra({
 })
 ```
 
-Give your agent a `Memory`:
+Instantiate a [`Memory`](https://mastra.ai/reference/memory/memory-class) instance in your agent:
 
 ```typescript
 import { Memory } from '@mastra/memory'
@@ -66,7 +66,7 @@ export const agent = new Agent({
 
 When you call the agent, messages are automatically saved to the database. You can specify a `threadId`, `resourceId`, and optional `metadata`:
 
-**Generate**:
+**.generate()**:
 
 ```typescript
 await agent.generate('Hello', {
@@ -81,7 +81,7 @@ await agent.generate('Hello', {
 })
 ```
 
-**Stream**:
+**.stream()**:
 
 ```typescript
 await agent.stream('Hello', {
@@ -103,12 +103,14 @@ You can use this history in two ways:
 - **Automatic inclusion** - Mastra automatically fetches and includes recent messages in the context window. By default, it includes the last 10 messages, keeping agents grounded in the conversation. You can adjust this number with `lastMessages`, but in most cases you don't need to think about it.
 - [**Manual querying**](#querying) - For more control, use the `recall()` function to query threads and messages directly. This lets you choose exactly which memories are included in the context window, or fetch messages to render conversation history in your UI.
 
+> **Tip:** When memory is enabled, [Studio](https://mastra.ai/docs/studio/overview) uses message history to display past conversations in the chat sidebar.
+
 ## Accessing memory
 
 To access memory functions for querying, cloning, or deleting threads and messages, call `getMemory()` on an agent:
 
 ```typescript
-const agent = mastra.getAgent('weatherAgent')
+const agent = mastra.getAgentById('test-agent')
 const memory = await agent.getMemory()
 ```
 

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

@@ -42,7 +42,7 @@ See [configuration options](https://mastra.ai/reference/memory/observational-mem
 
 ## Benefits
 
-- **Prompt caching**: OM's context is stable — observations append over time rather than being dynamically retrieved each turn. This keeps the prompt prefix cacheable, which reduces costs.
+- **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.
 - **Compression**: Raw message history and tool results get compressed into a dense observation log. Smaller context means faster responses and longer coherent conversations.
 - **Zero context rot**: The agent sees relevant information instead of noisy tool calls and irrelevant tokens, so the agent stays on task over long sessions.
 
@@ -50,7 +50,7 @@ See [configuration options](https://mastra.ai/reference/memory/observational-mem
 
 You don't remember every word of every conversation you've ever had. You observe what happened subconsciously, then your brain reflects — reorganizing, combining, and condensing into long-term memory. OM works the same way.
 
-Every time an agent responds, it sees a context window containing its system prompt, recent message history, and any injected context. The context window is finite — even models with large token limits perform worse when the window is full. This causes two problems:
+Every time an agent responds, it sees a context window containing its system prompt, recent message history, and any injected context. The context window is finite; even models with large token limits perform worse when the window is full. This causes two problems:
 
 - **Context rot**: the more raw message history an agent carries, the worse it performs.
 - **Context waste**: most of that history contains tokens no longer needed to keep the agent on task.
@@ -59,14 +59,15 @@ OM solves both problems by compressing old context into dense observations.
 
 ### Observations
 
-When message history tokens exceed a threshold (default: 30,000), the Observer creates observations — concise notes about what happened:
+When message history tokens exceed a threshold (default: 30,000), the Observer creates observations which are concise notes about what happened:
 
 OM uses fast local token estimation for this thresholding work. Text is estimated with `tokenx`, while image parts use provider-aware heuristics so multimodal conversations still trigger observation at the right time. The same applies to image-like `file` parts when a transport normalizes an uploaded image as a file instead of an image part. For example, OpenAI image detail settings can materially change when OM decides to observe.
 
 The Observer can also see attachments in the history it reviews. OM keeps readable placeholders like `[Image #1: reference-board.png]` or `[File #1: floorplan.pdf]` in the transcript for readability, and forwards the actual attachment parts alongside the text. Image-like `file` parts are upgraded to image inputs for the Observer when possible, while non-image attachments are forwarded as file parts with normalized token counting. This applies to both normal thread observation and batched resource-scope observation.
 
-```text
+```md
 Date: 2026-01-15
+
 - 🔴 12:10 User is building a Next.js app with Supabase auth, due in 1 week (meaning January 22nd 2026)
   - 🔴 12:10 App uses server components with client-side hydration
   - 🟡 12:12 User asked about middleware configuration for protected routes
@@ -77,11 +78,11 @@ The compression is typically 5–40×. The Observer also tracks a **current task
 
 If you enable `observation.threadTitle`, the Observer can also suggest a short thread title when the conversation topic meaningfully changes. Thread title generation is opt-in and updates the thread metadata, so apps like Mastra Code can show the latest title in thread lists and status UI.
 
-Example: an agent using Playwright MCP might see 50,000+ tokens per page snapshot. With OM, the Observer watches the interaction and creates a few hundred tokens of observations about what was on the page and what actions were taken. The agent stays on task without carrying every raw snapshot.
+Example: An agent using Playwright MCP might see 50,000+ tokens per page snapshot. With OM, the Observer watches the interaction and creates a few hundred tokens of observations about what was on the page and what actions were taken. The agent stays on task without carrying every raw snapshot.
 
 ### Reflections
 
-When observations exceed their threshold (default: 40,000 tokens), the Reflector condenses them — combining related items and reflecting on patterns.
+When observations exceed their threshold (default: 40,000 tokens), the Reflector condenses them, combines related items, and reflects on patterns.
 
 The result is a three-tier system:
 
@@ -93,7 +94,7 @@ The result is a three-tier system:
 
 > **Note:** Retrieval mode is experimental. The API may change in future releases.
 
-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.
+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
 
@@ -162,6 +163,16 @@ With retrieval mode enabled, OM:
 
 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).
 
+## Studio
+
+To see how it works in practice, open [Studio](https://mastra.ai/docs/studio/overview) and navigate to an agent with OM enabled. The **Memory** tab displays:
+
+- **Token progress bars**: Current token counts for messages and observations, showing how close each is to its threshold. Hover over the info icon to see the model and threshold for the Observer and Reflector.
+- **Active observations**: The current observation log, rendered inline. When previous observation or reflection records exist, expand "Previous observations" to browse them.
+- **Background processing**: During a conversation, buffered observation chunks and reflection status appear as the agent processes in the background.
+
+The progress bars update live while the agent is observing or reflecting, showing elapsed time and a status badge.
+
 ## Models
 
 The Observer and Reflector run in the background. Any model that works with Mastra's [model routing](https://mastra.ai/models) (`provider/model`) can be used. When using `observationalMemory: true`, the default model is `google/gemini-2.5-flash`. When passing a config object, a `model` must be explicitly set.
@@ -184,6 +195,8 @@ See [model configuration](https://mastra.ai/reference/memory/observational-memor
 
 ### Token-tiered model selection
 
+**Added in:** `@mastra/memory@1.10.0`
+
 You can use `ModelByInputTokens` to specify different Observer or Reflector models based on input token count. OM selects the matching model tier at runtime from the configured `upTo` thresholds.
 
 ```typescript
@@ -373,10 +386,6 @@ No manual migration needed. OM reads existing messages and observes them lazily
 - **Thread scope**: The first time a thread exceeds `observation.messageTokens`, the Observer processes the backlog.
 - **Resource scope**: All unobserved messages across all threads for a resource are processed together. For users with many existing threads, this could take significant time.
 
-## Viewing in Mastra Studio
-
-Mastra Studio shows OM status in real time in the memory tab: token usage, which model is running, current observations, and reflection history.
-
 ## Comparing OM with other memory features
 
 - **[Message history](https://mastra.ai/docs/memory/message-history)**: High-fidelity record of the current conversation

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

@@ -107,7 +107,7 @@ Use memory when your agent needs to maintain multi-turn conversations that refer
 
    > **Note:** Visit [Memory Class](https://mastra.ai/reference/memory/memory-class) for a full list of configuration options.
 
-5. Call your agent, for example in [Mastra Studio](https://mastra.ai/docs/getting-started/studio). Inside Studio, start a new chat with your agent and take a look at the right sidebar. It'll now display various memory-related information.
+5. Call your agent, for example in [Studio](https://mastra.ai/docs/studio/overview). Inside Studio, start a new chat with your agent and take a look at the right sidebar. It'll now display various memory-related information.
 
 ## Message history
 
@@ -165,7 +165,7 @@ export const memoryAgent = new Agent({
 
 ## Memory in multi-agent systems
 
-When a [supervisor agent](https://mastra.ai/docs/agents/supervisor-agents) delegates to a subagent, Mastra isolates subagent memory automatically. There is no flag to enable this as it happens on every delegation. Understanding how this scoping works lets you decide what stays private and what to share intentionally.
+When a [supervisor agent](https://mastra.ai/docs/agents/supervisor-agents) delegates to a subagent, Mastra isolates subagent memory automatically. No flag enables this as it happens on every delegation. Understanding how this scoping works lets you decide what stays private and what to share intentionally.
 
 ### How delegation scopes memory
 
@@ -175,7 +175,7 @@ Each delegation creates a fresh `threadId` and a deterministic `resourceId` for
 - **Resource ID**: Derived as `{parentResourceId}-{agentName}`. Because the resource ID is stable across delegations, resource-scoped memory persists between calls. A subagent remembers facts from previous delegations by the same user.
 - **Memory instance**: If a subagent has no memory configured, it inherits the supervisor's `Memory` instance. If the subagent defines its own, that takes precedence.
 
-The supervisor forwards its conversation context to the subagent so it has enough background to complete the task. Only the delegation prompt and the subagent's response are saved — the full parent conversation is not stored. You can control which messages reach the subagent with the [`messageFilter`](https://mastra.ai/docs/agents/supervisor-agents) callback.
+The supervisor forwards its conversation context to the subagent so it has enough background to complete the task. Only the delegation prompt and the subagent's response are saved — the full parent conversation isn't stored. You can control which messages reach the subagent with the [`messageFilter`](https://mastra.ai/docs/agents/supervisor-agents) callback.
 
 > **Note:** Subagent resource IDs are always suffixed with the agent name (`{parentResourceId}-{agentName}`). Two different subagents under the same supervisor never share a resource ID through delegation.
 
@@ -206,7 +206,7 @@ Because both calls use `resource: 'project-42'`, the writer can access the resea
 
 Enable [Tracing](https://mastra.ai/docs/observability/tracing/overview) to monitor and debug memory in action. Traces show you exactly which messages and observations the agent included in its context for each request, helping you understand agent behavior and verify that memory retrieval is working as expected.
 
-Open [Mastra Studio](https://mastra.ai/docs/getting-started/studio) and select the **Observability** tab in the sidebar. Open the trace of a recent agent request, then look for spans of LLMs calls.
+Open [Studio](https://mastra.ai/docs/studio/overview) and select the **Observability** tab in the sidebar. Open the trace of a recent agent request, then look for spans of LLMs calls.
 
 ## Switch memory per request
 

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

@@ -18,18 +18,33 @@ After getting a response from the LLM, all new messages (user, assistant, and to
 
 ## Quickstart
 
-Semantic recall is enabled by default, so if you give your agent memory it will be included:
+Semantic recall is disabled by default. To enable it, set `semanticRecall: true` in `options` and provide a `vector` store and `embedder`:
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
 import { Memory } from '@mastra/memory'
+import { LibSQLStore, LibSQLVector } from '@mastra/libsql'
+import { ModelRouterEmbeddingModel } from '@mastra/core/llm'
 
 const agent = new Agent({
   id: 'support-agent',
   name: 'SupportAgent',
   instructions: 'You are a helpful support agent.',
   model: 'openai/gpt-5.4',
-  memory: new Memory(),
+  memory: new Memory({
+    storage: new LibSQLStore({
+      id: 'agent-storage',
+      url: 'file:./local.db',
+    }),
+    vector: new LibSQLVector({
+      id: 'agent-vector',
+      url: 'file:./local.db',
+    }),
+    embedder: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
+    options: {
+      semanticRecall: true,
+    },
+  }),
 })
 ```
 
@@ -77,6 +92,9 @@ const agent = new Agent({
       id: 'agent-vector',
       url: 'file:./local.db',
     }),
+    options: {
+      semanticRecall: true,
+    },
   }),
 })
 ```
@@ -139,6 +157,9 @@ import { ModelRouterEmbeddingModel } from '@mastra/core/llm'
 const agent = new Agent({
   memory: new Memory({
     embedder: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
+    options: {
+      semanticRecall: true,
+    },
   }),
 })
 ```
@@ -262,26 +283,14 @@ const agent = new Agent({
 
 For detailed information about index configuration options and performance tuning, see the [PgVector configuration guide](https://mastra.ai/reference/vectors/pg).
 
-## Disabling
+## Disable semantic recall
 
-Semantic recall has a performance impact. New messages are converted into embeddings and used to query a vector database before new messages are sent to the LLM.
-
-Semantic recall is enabled by default but can be disabled when not needed:
-
-```typescript
-const agent = new Agent({
-  memory: new Memory({
-    options: {
-      semanticRecall: false,
-    },
-  }),
-})
-```
+Semantic recall is disabled by default (`semanticRecall: false`). Each call adds latency because new messages are converted into embeddings and used to query a vector database before the LLM receives them.
 
-You might want to disable semantic recall in scenarios like:
+Keep semantic recall disabled when:
 
-- When message history provides sufficient context for the current conversation.
-- In performance-sensitive applications, like realtime two-way audio, where the added latency of creating embeddings and running vector queries is noticeable.
+- Message history provides sufficient context for the current conversation.
+- You're building performance-sensitive applications, like realtime two-way audio, where embedding and vector query latency is noticeable.
 
 ## Viewing recalled messages