@mastra/mcp-docs-server 1.2.17-alpha.7 → 1.2.17

package/.docs/reference/file-based-agents/skills.md

@@ -6,7 +6,7 @@
 
 A file-based agent discovers skills from its `skills/` directory and bundles them at build time. Skills are reusable procedures or reference material that the agent can load when relevant, instead of putting every detail into the always-on prompt.
 
-Use this page for the file-based convention. For code-defined skills, see [Agent skills](https://mastra.ai/docs/agents/skills). For the `SKILL.md` package format, see [Workspace skills](https://mastra.ai/docs/workspace/skills).
+Use this page for the file-based convention. For code-defined skills, see [Agent skills](https://mastra.ai/docs/skills). For the `SKILL.md` package format, see [Workspace skills](https://mastra.ai/docs/sandbox/skills).
 
 ## Quickstart
 

package/.docs/reference/file-based-agents/storage.md

@@ -4,9 +4,9 @@
 
 > **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
-Mastra sets the project's default [storage](https://mastra.ai/docs/storage/overview) from a `storage.ts` file directly under `src/mastra/`. The file default-exports a store, which replaces the built-in in-memory store used for memory, workflows, observability, and other storage domains.
+Mastra sets the project's default [storage](https://mastra.ai/docs/storage) from a `storage.ts` file directly under `src/mastra/`. The file default-exports a store, which replaces the built-in in-memory store used for memory, workflows, observability, and other storage domains.
 
-Use this page for the file-based convention. For backend choice, storage domains, retention, and provider details, see [storage overview](https://mastra.ai/docs/storage/overview).
+Use this page for the file-based convention. For backend choice, storage domains, retention, and provider details, see [storage overview](https://mastra.ai/docs/storage).
 
 ## Quickstart
 
@@ -25,7 +25,7 @@ Mastra registers the store before file-based agents and workflows, so storage-de
 
 ## Production backends
 
-`storage.ts` can export any Mastra storage adapter, such as LibSQL, PostgreSQL, or MongoDB. For setup patterns, provider support, and schema details, see [storage overview](https://mastra.ai/docs/storage/overview), [observability signal support](https://mastra.ai/docs/observability/overview), and the [storage reference](https://mastra.ai/reference/storage/overview).
+`storage.ts` can export any Mastra storage adapter, such as LibSQL, PostgreSQL, or MongoDB. For setup patterns, provider support, and schema details, see [storage overview](https://mastra.ai/docs/storage), [observability signal support](https://mastra.ai/docs/observability/overview), and the [storage reference](https://mastra.ai/reference/storage/overview).
 
 ## Precedence with code
 

package/.docs/reference/file-based-agents/subagents.md

@@ -6,7 +6,7 @@
 
 A file-based agent can declare **subagents**, specialist child agents it delegates to. The parent model sees each subagent as a delegation tool named after the subagent directory and calls that tool to hand off a task. The subagent's result returns to the parent conversation.
 
-Use this page for the file-based convention. For broader delegation patterns, hooks, memory isolation, tool approval propagation, and scoring, see [Supervisor agents](https://mastra.ai/docs/capabilities/subagents).
+Use this page for the file-based convention. For broader delegation patterns, hooks, memory isolation, tool approval propagation, and scoring, see [Supervisor agents](https://mastra.ai/docs/subagents).
 
 ## Quickstart
 

package/.docs/reference/file-based-agents/workspace.md

@@ -4,9 +4,9 @@
 
 > **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
-A [workspace](https://mastra.ai/docs/workspace/sandbox) assembles capabilities such as filesystem access and command execution. The configured backends determine which tools are available. File-based agents get a default workspace automatically when discovered through `mastra dev` or `mastra build`. This default includes filesystem access and command execution, so agents can read and write files and run shell commands without extra configuration.
+A [workspace](https://mastra.ai/docs/sandbox/overview) assembles capabilities such as filesystem access and command execution. The configured backends determine which tools are available. File-based agents get a default workspace automatically when discovered through `mastra dev` or `mastra build`. This default includes filesystem access and command execution, so agents can read and write files and run shell commands without extra configuration.
 
-Use this page for the file-based convention. For workspace providers, tools, search, lifecycle, and sandbox details, see [Sandbox](https://mastra.ai/docs/workspace/sandbox).
+Use this page for the file-based convention. For workspace providers, tools, search, lifecycle, and sandbox details, see [Sandbox](https://mastra.ai/docs/sandbox/overview).
 
 ## Default workspace
 
@@ -65,7 +65,7 @@ Customize the workspace when the default local directory isn't enough. Common re
 - Add workspace search with BM25 or vector search.
 - Share one workspace across multiple agents.
 
-For provider patterns and runtime behavior, see the [sandbox guide](https://mastra.ai/docs/workspace/sandbox) and [workspace search](https://mastra.ai/docs/workspace/search).
+For provider patterns and runtime behavior, see the [sandbox guide](https://mastra.ai/docs/sandbox/overview) and [workspace search](https://mastra.ai/docs/sandbox/search).
 
 ## Runtime boundary
 

package/.docs/reference/index.md

@@ -211,6 +211,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [.getThreadById()](https://mastra.ai/reference/memory/getThreadById)
 - [.listThreads()](https://mastra.ai/reference/memory/listThreads)
 - [.recall()](https://mastra.ai/reference/memory/recall)
+- [.settled()](https://mastra.ai/reference/memory/settled)
 - [.summarizeThread()](https://mastra.ai/reference/memory/summarizeThread)
 - [AgentNetwork to .network()](https://mastra.ai/reference/migrations/agentnetwork)
 - [AI SDK v4 to v5](https://mastra.ai/reference/migrations/ai-sdk-v4-to-v5)

package/.docs/reference/manual-install.md

@@ -157,7 +157,7 @@ If you prefer not to use our automatic CLI tool, you can set up your project you
    })
    ```
 
-   > **Note:** We've shortened and simplified the `weatherTool` example here. You can see the complete weather tool under [Giving an Agent a Tool](https://mastra.ai/docs/agents/using-tools).
+   > **Note:** We've shortened and simplified the `weatherTool` example here. You can see the complete weather tool under [Giving an Agent a Tool](https://mastra.ai/docs/agents/tools).
 
 5. Create a `weather-agent.ts` file:
 
@@ -244,7 +244,7 @@ If you prefer not to use our automatic CLI tool, you can set up your project you
 
 - [Review the project structure](https://mastra.ai/reference/project-structure): Understand how `src/mastra/` files map to agents, tools, workflows, storage, and configuration.
 - [Test your agent in Studio](https://mastra.ai/docs/studio/overview): Open the local Studio UI and run the weather agent.
-- [Use tools with agents](https://mastra.ai/docs/agents/using-tools): Replace the example weather tool with a real tool that calls an API or service.
+- [Use tools with agents](https://mastra.ai/docs/agents/tools): Replace the example weather tool with a real tool that calls an API or service.
 - [Add memory](https://mastra.ai/docs/memory/overview): Persist conversation history and user-specific context.
-- [Configure storage](https://mastra.ai/docs/storage/overview): Add a persistent storage adapter for memory, workflows, observability, and other runtime state.
+- [Configure storage](https://mastra.ai/docs/storage): Add a persistent storage adapter for memory, workflows, observability, and other runtime state.
 - [Build and deploy](https://mastra.ai/docs/deployment/overview): Build the Mastra server and deploy it to a hosting platform.

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

@@ -145,4 +145,5 @@ export const agent = new Agent({
 - [listThreads](https://mastra.ai/reference/memory/listThreads)
 - [deleteMessages](https://mastra.ai/reference/memory/deleteMessages)
 - [cloneThread](https://mastra.ai/reference/memory/cloneThread)
+- [settled](https://mastra.ai/reference/memory/settled)
 - [Clone Utility Methods](https://mastra.ai/reference/memory/clone-utilities)

package/.docs/reference/memory/settled.md

@@ -0,0 +1,57 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Memory.settled()
+
+The `.settled()` method resolves once all background work the `Memory` instance started has finished. Some memory work continues after an agent run returns:
+
+- Observational memory cycles (buffered observation and reflection, including the nested agent runs they spawn)
+- Vector cleanup started by `deleteThread()` and `deleteMessages()`
+
+Await this method before closing a storage connection you own. Without it, background statements can run against a closed connection.
+
+The method is declared on the base memory class, so it's also available on the `MastraMemory` instance returned by `agent.getMemory()`.
+
+## Usage example
+
+```typescript
+await agent.generate('Hello', {
+  memory: { thread: 'thread-123', resource: 'user-456' },
+})
+
+await memory.settled()
+await store.close()
+```
+
+## Parameters
+
+This method takes no parameters.
+
+## Returns
+
+**void** (`Promise<void>`): A promise that resolves when all background memory work has finished. Background work that fails does not reject this promise.
+
+## Extended usage example
+
+Test suites and short-lived processes are the most common places to need this, since they close the store immediately after a run finishes.
+
+```typescript
+import { Memory } from '@mastra/memory'
+import { PostgresStore } from '@mastra/pg'
+
+const store = new PostgresStore({ connectionString })
+const memory = new Memory({ storage: store })
+
+// ... run your agent ...
+
+// Wait for observational memory and vector cleanup to finish before closing.
+await memory.settled()
+await store.close()
+```
+
+> **Note:** `settled()` joins the work that had started by the time you called it, plus any work that work enqueues. It does not prevent new work from starting afterwards, so call it once the agent runs you care about have returned.
+
+## Related
+
+- [Memory Class Reference](https://mastra.ai/reference/memory/memory-class)
+- [Observational Memory](https://mastra.ai/docs/memory/observational-memory)
+- [deleteMessages](https://mastra.ai/reference/memory/deleteMessages)

package/.docs/reference/migrations/network-to-supervisor.md

@@ -255,9 +255,9 @@ const stream = await supervisorAgent.stream('Research AI in education', {
 
 ## See also
 
-- [Supervisor Agents](https://mastra.ai/docs/capabilities/subagents)
+- [Supervisor Agents](https://mastra.ai/docs/subagents)
 - [Agent Networks](https://mastra.ai/docs/agents/networks)
 - [Agent.stream() Reference](https://mastra.ai/reference/streaming/agents/stream)
 - [Agent.generate() Reference](https://mastra.ai/reference/agents/generate)
-- [Agent Approval](https://mastra.ai/docs/agents/agent-approval)
+- [Agent Approval](https://mastra.ai/docs/agents/human-in-the-loop)
 - [Guide: Research Coordinator](https://mastra.ai/blog/build-a-research-coordinator-with-supervisor-agents)

package/.docs/reference/processors/provider-history-compat.md

@@ -45,11 +45,12 @@ Mastra agents don't add this processor automatically. Add it explicitly when you
 
 `ProviderHistoryCompat` includes these built-in compatibility rules:
 
-| Rule                                        | Provider  | Timing                      | Behavior                                                                                                                          |
-| ------------------------------------------- | --------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| `anthropic-tool-id-format`                  | Anthropic | Reactive API error recovery | Rewrites tool call IDs that contain characters outside `[a-zA-Z0-9_-]` and retries the request.                                   |
-| `cerebras-strip-reasoning-content`          | Cerebras  | Preemptive prompt rewrite   | Removes assistant `reasoning` parts from the outbound prompt so they're not serialized as unsupported `reasoning_content` fields. |
-| `anthropic-strip-foreign-reasoning-content` | Anthropic | Preemptive prompt rewrite   | Removes non-Anthropic assistant `reasoning` parts from the outbound prompt. Anthropic-native thinking history is preserved.       |
+| Rule                                        | Provider     | Timing                      | Behavior                                                                                                                                                    |
+| ------------------------------------------- | ------------ | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `anthropic-tool-id-format`                  | Anthropic    | Reactive API error recovery | Rewrites tool call IDs that contain characters outside `[a-zA-Z0-9_-]` and retries the request.                                                             |
+| `cerebras-strip-reasoning-content`          | Cerebras     | Preemptive prompt rewrite   | Removes assistant `reasoning` parts from the outbound prompt so they're not serialized as unsupported `reasoning_content` fields.                           |
+| `anthropic-strip-foreign-reasoning-content` | Anthropic    | Preemptive prompt rewrite   | Removes non-Anthropic assistant `reasoning` parts from the outbound prompt. Anthropic-native thinking history is preserved.                                 |
+| `azure-system-reminder-transform`           | Azure OpenAI | Preemptive prompt rewrite   | Renames `<system-reminder>` wrappers in user text and system instructions to `<memory-context>` for the outbound request. Stored history remains unchanged. |
 
 Preemptive rules run through `processLLMRequest` after Mastra converts messages to the model prompt format and before the prompt is sent to the provider. These rewrites affect only the current provider call.
 

package/.docs/reference/processors/skill-search-processor.md

@@ -41,6 +41,8 @@ const skillSearch = new SkillSearchProcessor({
 
 **options.ttl** (`number`): Time-to-live for thread state in milliseconds. After this duration of inactivity, thread state will be cleaned up. Set to 0 to disable cleanup.
 
+**options.blockingRefresh** (`boolean`): When true, awaits the skills staleness check before the first step of each request so skill changes appear in the same turn. When false, the cached catalog is served and revalidated in the background, so skill changes can lag by one turn plus the staleness cooldown (up to 30 seconds).
+
 ## Returns
 
 **id** (`string`): Processor identifier set to 'skill-search'
@@ -112,4 +114,4 @@ Reserve workspace file tools such as `mastra_workspace_read_file` for explicit f
 
 - [ToolSearchProcessor](https://mastra.ai/reference/processors/tool-search-processor)
 - [Processors](https://mastra.ai/docs/agents/processors)
-- [Workspace Skills](https://mastra.ai/docs/workspace/skills)
+- [Workspace Skills](https://mastra.ai/docs/sandbox/skills)

package/.docs/reference/processors/token-limiter-processor.md

@@ -64,6 +64,10 @@ for await (const part of stream.fullStream) {
 }
 ```
 
+## Media token counting
+
+Images and file attachments are estimated rather than tokenized. This applies to `file` message parts and to tool results shaped like `{ data, mediaType }`. Images use a flat per-image estimate, other media is estimated from its decoded byte size, and remote URLs or provider file ids use a flat fallback because their size isn't known locally. Encoded payloads such as base64 data are never counted as text, which would otherwise inflate the count by an order of magnitude and truncate history unnecessarily.
+
 ## Error behavior
 
 When used as an input processor (both `processInput` and `processInputStep`), `TokenLimiterProcessor` throws a `TripWire` error in the following cases:

package/.docs/reference/processors/tool-call-filter.md

@@ -2,7 +2,9 @@
 
 # ToolCallFilter
 
-The `ToolCallFilter` is an **input processor** that filters out tool calls and their results from the message history before sending to the model. This is useful when you want to exclude specific tool interactions from context or remove all tool calls entirely.
+The `ToolCallFilter` is an **input processor** that filters out tool calls and their results from the prompt sent to the model. This is useful when you want to exclude specific tool interactions from context or remove all tool calls entirely.
+
+Filtering happens in the `processLLMRequest` hook, which runs after the message list is converted to a model prompt. Changes are transient: they affect only what's sent to the model on that call. Stored messages, memory, and UI history keep their original tool calls and results.
 
 ## Usage example
 
@@ -44,13 +46,11 @@ const filterWithCompactToolHistory = new ToolCallFilter({
 
 **name** (`string`): Processor display name set to 'ToolCallFilter'
 
-**processInput** (`(args: { messages: MastraDBMessage[]; messageList: MessageList; abort: (reason?: string) => never; requestContext?: RequestContext }) => Promise<MessageList | MastraDBMessage[]>`): Processes input messages to filter out tool calls and their results based on configuration
-
-**processInputStep** (`(args: ProcessInputStepArgs) => Promise<ProcessInputStepResult>`): Processes agent loop step input when filterAfterToolSteps is configured. Returns no changes when step filtering is disabled
+**processLLMRequest** (`(args: ProcessLLMRequestArgs) => Promise<ProcessLLMRequestResult | undefined>`): Filters tool calls and results out of the model prompt before it is sent to the provider. Returns undefined when nothing is filtered. Changes are transient and are not persisted to the message list or memory
 
 ## Step filtering
 
-By default, `ToolCallFilter` filters only the initial input before the agent loop starts. Set `filterAfterToolSteps` to also filter during each loop step.
+By default, `ToolCallFilter` filters tool calls from history but leaves tool calls made during the current agent loop in place. Set `filterAfterToolSteps` to also filter tool calls produced by the current loop.
 
 `filterAfterToolSteps` counts tool-producing steps. For example, `filterAfterToolSteps: 2` keeps tool calls and results from the two most recent tool-producing steps and filters older tool calls and results. Non-tool text remains in context.
 
@@ -64,9 +64,9 @@ const filter = new ToolCallFilter({
 
 ## Preserve compact model output
 
-Set `preserveModelOutput: true` to retain compact `toModelOutput` history for completed tool results that the filter removes. This keeps the model-facing output as text in the prompt while removing the raw `toolInvocation.args` and raw `toolInvocation.result` payloads.
+Set `preserveModelOutput: true` to retain compact `toModelOutput` history for tool results that the filter removes. The removed tool call and result are replaced with a single text part in the prompt, so the model still sees the output while the raw tool arguments are dropped.
 
-Only completed tool results with `providerMetadata.mastra.modelOutput` are preserved. Tool calls, incomplete results, and results without stored model output are still filtered.
+Tool results without model output that can be represented as text are removed entirely.
 
 ```typescript
 const filter = new ToolCallFilter({

package/.docs/reference/processors/tool-search-processor.md

@@ -277,4 +277,4 @@ const agent = new Agent({
 ## Related
 
 - [Processors](https://mastra.ai/docs/agents/processors)
-- [Using Tools](https://mastra.ai/docs/agents/using-tools)
+- [Using Tools](https://mastra.ai/docs/agents/tools)

package/.docs/reference/project-structure.md

@@ -44,7 +44,7 @@ Mastra recommends organizing your code into the following folders:
 
 Mastra has two special folder conventions:
 
-- `src/mastra/agents/<name>`: You can define an agent by file convention instead of constructing it in code. Learn more in the [File-based Agents](https://mastra.ai/docs/getting-started/develop) docs.
+- `src/mastra/agents/<name>`: You can define an agent by file convention instead of constructing it in code. Learn more in the [File-based Agents](https://mastra.ai/docs/develop) docs.
 - `src/mastra/public`: Contents are copied into the `.build/output` directory during the build process, making them available for serving at runtime.
 
 ### Top-level files

package/.docs/reference/pubsub/lease-provider.md

@@ -2,7 +2,7 @@
 
 # LeaseProvider
 
-`LeaseProvider` is the distributed leasing contract, separate from event delivery ([`PubSub`](https://mastra.ai/reference/pubsub/base)). Mastra's [signals layer](https://mastra.ai/docs/long-running-agents/signals) uses it to elect a single owner across multiple processes (for example, serverless invocations) for a resource, most commonly a thread key. The owner is the process that wakes and runs the agent stream, so other processes route follow-up work to it instead of starting a competing run.
+`LeaseProvider` is the distributed leasing contract, separate from event delivery ([`PubSub`](https://mastra.ai/reference/pubsub/base)). Mastra's [signals layer](https://mastra.ai/docs/harness/signals) uses it to elect a single owner across multiple processes (for example, serverless invocations) for a resource, most commonly a thread key. The owner is the process that wakes and runs the agent stream, so other processes route follow-up work to it instead of starting a competing run.
 
 Leasing is a distinct concern from pub/sub. A backend implements `LeaseProvider` only when it can actually coordinate a lock, such as Redis via atomic `SET`/Lua, or an in-memory map for single-process. Backends that can't lease omit it; the signals runtime feature-detects the capability and falls back to a no-op provider, preserving single-process behavior.
 
@@ -129,5 +129,5 @@ When the configured pub/sub backend doesn't implement `LeaseProvider`, the runti
 
 - [PubSub](https://mastra.ai/reference/pubsub/base): The event delivery contract, separate from leasing
 - [RedisStreamsPubSub](https://mastra.ai/reference/pubsub/redis-streams): The built-in backend that implements `LeaseProvider`
-- [Signals](https://mastra.ai/docs/long-running-agents/signals): The runtime that uses leasing to coordinate thread execution across processes
-- [Channels](https://mastra.ai/docs/capabilities/channels): Uses leasing to coordinate agent runs in serverless and multi-instance deployments
+- [Signals](https://mastra.ai/docs/harness/signals): The runtime that uses leasing to coordinate thread execution across processes
+- [Channels](https://mastra.ai/docs/channels): Uses leasing to coordinate agent runs in serverless and multi-instance deployments

package/.docs/reference/pubsub/redis-streams.md

@@ -131,7 +131,7 @@ When a subscriber calls `nack`, the event is republished with an incremented `de
 
 ## Distributed leasing
 
-`RedisStreamsPubSub` implements the [`LeaseProvider`](https://mastra.ai/reference/pubsub/lease-provider) contract on top of the same Redis connection. The [signals runtime](https://mastra.ai/docs/long-running-agents/signals) uses it to elect a single owner (usually per thread key) so that across instances only one process wakes and runs the agent, and others route follow-up work to the holder. This is what makes signals work on serverless and multi-instance deployments; without a shared lease, each instance would start its own competing run.
+`RedisStreamsPubSub` implements the [`LeaseProvider`](https://mastra.ai/reference/pubsub/lease-provider) contract on top of the same Redis connection. The [signals runtime](https://mastra.ai/docs/harness/signals) uses it to elect a single owner (usually per thread key) so that across instances only one process wakes and runs the agent, and others route follow-up work to the holder. This is what makes signals work on serverless and multi-instance deployments; without a shared lease, each instance would start its own competing run.
 
 Lease keys are namespaced under the same `keyPrefix` as topics, as `<keyPrefix>:lease:<key>`. All operations are atomic: `acquireLease` uses `SET NX PX` and refreshes its own TTL idempotently, while `releaseLease`, `renewLease`, and `transferLease` use Lua scripts that check ownership before mutating, so a concurrent renewal from another owner is never clobbered.
 

package/.docs/reference/rag/graph-rag.md

@@ -9,10 +9,7 @@ The `GraphRAG` class implements a graph-based approach to retrieval augmented ge
 ```typescript
 import { GraphRAG } from '@mastra/rag'
 
-const graphRag = new GraphRAG({
-  dimension: 1536,
-  threshold: 0.7,
-})
+const graphRag = new GraphRAG(1536, 0.7)
 
 // Create the graph from chunks and embeddings
 graphRag.createGraph(documentChunks, embeddings)
@@ -88,13 +85,79 @@ Returns an array of `RankedNode` objects, where each node contains:
 
 **score** (`number`): Combined relevance score from graph traversal
 
+### `serialize`
+
+Returns a JSON-safe snapshot of the graph so it can be persisted and restored later instead of rebuilt with `createGraph`.
+
+```typescript
+serialize(): GraphRAGSnapshot
+```
+
+#### Returns
+
+Returns a `GraphRAGSnapshot` object containing:
+
+**version** (`number`): Snapshot format version, used to reject snapshots this version of the class can't load
+
+**dimension** (`number`): Dimension of the embedding vectors the graph was built with
+
+**threshold** (`number`): Similarity threshold the graph was built with
+
+**nodes** (`GraphNode[]`): All nodes in the graph, each including its full embedding
+
+**edges** (`GraphEdge[]`): All edges in the graph
+
+The snapshot is a deep copy, so mutating it doesn't affect the graph it came from. Every node carries its full embedding, so snapshots are large: a 1,000-node graph built with 1536-dimension embeddings serializes to about 20 MB of JSON. Size your storage column accordingly.
+
+### `deserialize`
+
+Rebuilds a `GraphRAG` instance from a snapshot produced by `serialize`.
+
+```typescript
+static deserialize(snapshot: GraphRAGSnapshot): GraphRAG
+```
+
+#### Parameters
+
+**snapshot** (`GraphRAGSnapshot`): A snapshot previously returned by serialize
+
+Throws if the snapshot version is unsupported, if a node embedding doesn't match the snapshot dimension, or if an edge references a node that isn't in the snapshot. A bad snapshot therefore fails at load time instead of during a later query.
+
+## Persisting a graph
+
+Building a graph is O(n²) in the number of chunks, so rebuilding it on every process start is wasteful. Serialize the graph once and store the snapshot wherever you already keep state. A snapshot is plain JSON, so any store works (a file, a blob column, a key-value cache), and `GraphRAG` doesn't depend on a storage backend.
+
+```typescript
+import { readFile, writeFile } from 'node:fs/promises'
+import { GraphRAG } from '@mastra/rag'
+import type { GraphRAGSnapshot } from '@mastra/rag'
+
+const SNAPSHOT_PATH = './docs-graph.json'
+
+async function loadOrBuildGraph() {
+  try {
+    const snapshot = JSON.parse(await readFile(SNAPSHOT_PATH, 'utf8')) as GraphRAGSnapshot
+    return GraphRAG.deserialize(snapshot)
+  } catch {
+    // No usable snapshot yet, so build the graph from scratch
+  }
+
+  const graphRag = new GraphRAG(1536, 0.7)
+  graphRag.createGraph(documentChunks, embeddings)
+
+  await writeFile(SNAPSHOT_PATH, JSON.stringify(graphRag.serialize()))
+
+  return graphRag
+}
+```
+
+A snapshot reflects the chunks it was built from and isn't updated incrementally. When the underlying documents change, build the graph again and store a new snapshot.
+
 ## Advanced example
 
 ```typescript
-const graphRag = new GraphRAG({
-  dimension: 1536,
-  threshold: 0.8, // Stricter similarity threshold
-})
+// Stricter similarity threshold
+const graphRag = new GraphRAG(1536, 0.8)
 
 // Create graph from chunks and embeddings
 graphRag.createGraph(documentChunks, embeddings)

package/.docs/reference/rag/retrieval.md

@@ -266,6 +266,23 @@ For detailed configuration options and advanced usage, see the [Vector Query Too
 
 Vector store prompts define query patterns and filtering capabilities for each vector database implementation. When implementing filtering, these prompts are required in the agent's instructions to specify valid operators and syntax for each vector store implementation.
 
+**MongoDB**:
+
+```ts
+import { MONGODB_PROMPT } from '@mastra/mongodb'
+
+export const ragAgent = new Agent({
+  id: 'rag-agent',
+  name: 'RAG Agent',
+  model: 'openai/gpt-5.6-sol',
+  instructions: `
+  Process queries using the provided context. Structure responses to be concise and relevant.
+  ${MONGODB_PROMPT}
+  `,
+  tools: { vectorQueryTool },
+})
+```
+
 **pgVector**:
 
 ```ts
@@ -402,23 +419,6 @@ export const ragAgent = new Agent({
 })
 ```
 
-**MongoDB**:
-
-```ts
-import { MONGODB_PROMPT } from '@mastra/mongodb'
-
-export const ragAgent = new Agent({
-  id: 'rag-agent',
-  name: 'RAG Agent',
-  model: 'openai/gpt-5.6-sol',
-  instructions: `
-  Process queries using the provided context. Structure responses to be concise and relevant.
-  ${MONGODB_PROMPT}
-  `,
-  tools: { vectorQueryTool },
-})
-```
-
 **OpenSearch**:
 
 ```ts
@@ -520,7 +520,13 @@ The weights control how different factors influence the final ranking:
 
 > **Note:** For semantic scoring to work properly during re-ranking, each result must include the text content in its `metadata.text` field.
 
-You can also use other relevance score providers like Cohere or ZeroEntropy:
+You can also use other relevance score providers like Voyage AI, Cohere, or ZeroEntropy:
+
+```ts
+import { VoyageRelevanceScorer } from '@mastra/voyageai'
+
+const relevanceProvider = new VoyageRelevanceScorer({ model: 'rerank-2.5' })
+```
 
 ```ts
 const relevanceProvider = new CohereRelevanceScorer('rerank-v3.5')
@@ -530,6 +536,8 @@ const relevanceProvider = new CohereRelevanceScorer('rerank-v3.5')
 const relevanceProvider = new ZeroEntropyRelevanceScorer('zerank-1')
 ```
 
+Voyage AI provides dedicated reranking models: `rerank-2.5` and `rerank-2.5-lite` both allow up to 32,000 tokens for the query and any single document combined, and up to 600,000 tokens across a request. `VoyageRelevanceScorer` reads `VOYAGE_API_KEY` from the environment, or accepts an `apiKey` in its config.
+
 The re-ranked results combine vector similarity with semantic understanding to improve retrieval quality.
 
 For more details about re-ranking, see the [rerank()](https://mastra.ai/reference/rag/rerankWithScorer) method.

package/.docs/reference/schedules/overview.md

@@ -8,7 +8,7 @@
 
 `mastra.schedules` is the CRUD service for persisted cron schedules. Use it to create, list, update, pause, resume, manually run, and delete schedules for agents or workflows.
 
-For usage patterns and concepts, see [Schedules](https://mastra.ai/docs/long-running-agents/schedules).
+For usage patterns and concepts, see [Schedules](https://mastra.ai/docs/harness/schedules).
 
 ## Usage example
 

package/.docs/reference/streaming/ChunkType.md

@@ -402,7 +402,7 @@ Contains output from workflow step execution, used primarily for usage tracking
 
 ## Background task chunks
 
-Emitted when a tool call is dispatched as a [background task](https://mastra.ai/docs/long-running-agents/background-tasks) and `streamUntilIdle()` is used.
+Emitted when a tool call is dispatched as a [background task](https://mastra.ai/docs/harness/background-tasks) and `streamUntilIdle()` is used.
 
 ### background-task-started
 
@@ -614,7 +614,7 @@ Contains monitoring and observability data from agent execution. Can include wor
 
 ### goal
 
-Emitted on every evaluation of an agent [goal](https://mastra.ai/docs/long-running-agents/goals). Consumers use this to render judge progress and the result mid-run. A goal that has no judge model configured produces no `goal` chunk.
+Emitted on every evaluation of an agent [goal](https://mastra.ai/docs/harness/goals). Consumers use this to render judge progress and the result mid-run. A goal that has no judge model configured produces no `goal` chunk.
 
 **type** (`"goal"`): Chunk type identifier
 

package/.docs/reference/streaming/agents/stream.md

@@ -80,7 +80,7 @@ const stream = await agent.stream('message for agent')
 
 **options.onError** (`({ error }: { error: Error | string }) => Promise<void> | void`): Callback function called when an error occurs during streaming.
 
-**options.onAbort** (`(event: any) => Promise<void> | void`): Callback function called when the stream is aborted.
+**options.onAbort** (`(event: { steps: any[]; text?: string }) => Promise<void> | void`): Callback function called when the stream is aborted. steps contains the steps that completed before the abort, and text contains the assistant text streamed so far for the step that was in flight.
 
 **options.abortSignal** (`AbortSignal`): Signal object that allows you to abort the agent's execution. When the signal is aborted, all ongoing operations will be terminated, including any in-flight subagent runs the agent delegated to.
 
@@ -158,6 +158,8 @@ const stream = await agent.stream('message for agent')
 
 **options.modelSettings.frequencyPenalty** (`number`): Penalty for token frequency (-2 to 2). Reduces repetition of frequent tokens.
 
+**options.modelSettings.timeout** (`object`): Time-based execution budget for the run. Accepts totalMs, the maximum duration of the entire agent run across every loop iteration, tool call and retry, and stepMs, the maximum duration of a single model call including the time spent consuming its stream. Exceeding either budget fails with a MastraTimeoutError. A totalMs timeout ends the run and does not try fallback models, because it is a hard deadline for the whole run. A stepMs timeout is not retried against the same model but does advance to the next entry in models when fallback models are configured.
+
 **options.modelSettings.stopSequences** (`string[]`): Stop sequences. If set, the model will stop generating text when one of the stop sequences is generated.
 
 **options.toolChoice** (`'auto' | 'none' | 'required' | { type: 'tool'; toolName: string }`): Controls how the agent uses tools during streaming.
@@ -178,6 +180,8 @@ const stream = await agent.stream('message for agent')
 
 **options.savePerStep** (`boolean`): Save messages incrementally after each stream step completes (default: false).
 
+**options.persistPartialOnAbort** (`boolean`): Save the assistant text that was streamed before an abort to memory (default: false). Only text emitted before the abort is persisted; output a provider keeps producing after cancellation is discarded, and nothing is saved when no text was streamed.
+
 **options.requireToolApproval** (`boolean`): When true, all tool calls require explicit approval before execution. The stream will emit tool-call-approval chunks and pause until approveToolCall() or declineToolCall() is called.
 
 **options.autoResumeSuspendedTools** (`boolean`): When true, automatically resumes suspended tools when the user sends a new message on the same thread. The agent extracts resumeData from the user's message based on the tool's resumeSchema. Requires memory to be configured.
@@ -262,6 +266,26 @@ for await (const chunk of stream.fullStream) {
 const fullText = await stream.text
 ```
 
+### Limiting execution time
+
+Use `modelSettings.timeout` to bound how long a run may take. `totalMs` limits the entire run, including every loop iteration, tool call and retry. `stepMs` limits a single model call, covering both establishing the stream and consuming it.
+
+```ts
+const stream = await agent.stream('Tell me a story', {
+  modelSettings: {
+    timeout: {
+      totalMs: 30000, // fail the run if it takes longer than 30s
+      stepMs: 10000, // fail an individual model call after 10s
+    },
+  },
+})
+```
+
+Exceeding either budget fails with a `MastraTimeoutError`, which carries a `timeoutType` of `'total'` or `'step'`. Each budget behaves differently when the agent is configured with fallback [`models`](https://mastra.ai/reference/agents/agent):
+
+- A `totalMs` timeout ends the run immediately and doesn't try the next model, because it's a hard deadline for the run as a whole.
+- A `stepMs` timeout isn't retried against the same model, but does advance to the next model, which makes it a way to fail over from a slow provider.
+
 ### AI SDK v5+ Format
 
 To use the stream with AI SDK v5 (and later), you can convert it using our utility function `toAISdkStream`.
@@ -301,8 +325,9 @@ const stream = await agent.stream('Tell me a story', {
   onError: ({ error }) => {
     console.error('Streaming error:', error)
   },
-  onAbort: event => {
-    console.log('Stream aborted:', event)
+  onAbort: ({ steps, text }) => {
+    console.log('Stream aborted after', steps.length, 'steps')
+    console.log('Partial text:', text)
   },
 })
 
@@ -399,4 +424,4 @@ Responses WebSocket connections run one response at a time. Mastra rejects overl
 
 - [Generating responses](https://mastra.ai/docs/agents/overview)
 - [Streaming responses](https://mastra.ai/docs/agents/overview)
-- [Agent Approval](https://mastra.ai/docs/agents/agent-approval)
+- [Agent Approval](https://mastra.ai/docs/agents/human-in-the-loop)

package/.docs/reference/streaming/agents/streamUntilIdle.md

@@ -101,7 +101,7 @@ for await (const chunk of stream.fullStream) {
 
 ## Related
 
-- [Background tasks](https://mastra.ai/docs/long-running-agents/background-tasks)
+- [Background tasks](https://mastra.ai/docs/harness/background-tasks)
 - [`Agent.stream()` reference](https://mastra.ai/reference/streaming/agents/stream)
 - [backgroundTasks configuration reference](https://mastra.ai/reference/configuration)
 - [Stream chunk types](https://mastra.ai/reference/streaming/ChunkType)

package/.docs/reference/tools/ask-user-tool.md

@@ -4,7 +4,7 @@
 
 A built-in, agent-agnostic tool that asks the user a question and waits for their response. The tool supports free-text questions, single-select prompts, and multi-select prompts.
 
-The tool pauses through the native [tool suspension](https://mastra.ai/docs/agents/agent-approval) primitive: it calls `suspend()` with the question payload, which makes the agent emit a `tool-call-suspended` event and persist run state. Resume the run with `agent.resumeStream(answer, { runId })`.
+The tool pauses through the native [tool suspension](https://mastra.ai/docs/agents/human-in-the-loop) primitive: it calls `suspend()` with the question payload, which makes the agent emit a `tool-call-suspended` event and persist run state. Resume the run with `agent.resumeStream(answer, { runId })`.
 
 When executed outside an agent run (no `suspend` available), the tool returns a readable fallback string containing the question and choices.
 

package/.docs/reference/tools/create-code-mode.md

@@ -126,4 +126,4 @@ export const codeModeTool = createCodeModeTool({
 
 - [Code mode](https://mastra.ai/docs/agents/code-mode)
 - [createTool()](https://mastra.ai/reference/tools/create-tool)
-- [Sandbox](https://mastra.ai/docs/workspace/sandbox)
+- [Sandbox](https://mastra.ai/docs/sandbox/overview)

package/.docs/reference/tools/create-tool.md

@@ -519,8 +519,8 @@ These annotations follow the [MCP specification](https://spec.modelcontextprotoc
 
 ## Related
 
-- [MCP Overview](https://mastra.ai/docs/mcp/overview)
-- [Using Tools with Agents](https://mastra.ai/docs/agents/using-tools)
-- [Agent Approval](https://mastra.ai/docs/agents/agent-approval)
-- [Tool Streaming](https://mastra.ai/docs/agents/using-tools)
+- [MCP Overview](https://mastra.ai/docs/connections/mcp)
+- [Using Tools with Agents](https://mastra.ai/docs/agents/tools)
+- [Agent Approval](https://mastra.ai/docs/agents/human-in-the-loop)
+- [Tool Streaming](https://mastra.ai/docs/agents/tools)
 - [Request Context](https://mastra.ai/docs/server/request-context)