@mastra/mcp-docs-server 1.2.11 → 1.2.12-alpha.0

package/.docs/reference/evals/prompt-alignment.md

@@ -2,7 +2,7 @@
 
 # Prompt alignment scorer
 
-The `createPromptAlignmentScorerLLM()` function creates a scorer that evaluates how well agent responses align with user prompts across multiple dimensions: intent understanding, requirement fulfillment, response completeness, and format appropriateness.
+The `createPromptAlignmentScorerLLM()` function creates a scorer that evaluates how well agent responses align with user prompts across intent understanding and requirement fulfillment, plus response completeness, and format appropriateness.
 
 ## Parameters
 
@@ -80,7 +80,7 @@ Evaluates alignment with user prompts only:
 
 1. **Intent Alignment** (40% weight): Whether the response addresses the user's core request
 2. **Requirements Fulfillment** (30% weight): If all user requirements are met
-3. **Completeness** (20% weight): Whether the response is comprehensive for user needs
+3. **Completeness** (20% weight): Whether the response is detailed for user needs
 4. **Response Appropriateness** (10% weight): If format and tone match user expectations
 
 #### System Mode ('system')
@@ -139,7 +139,7 @@ Final Score = Weighted Score × scale
 - **0.8-0.9** = Very good alignment with minor gaps
 - **0.7-0.8** = Good alignment but missing some requirements or completeness
 - **0.6-0.7** = Moderate alignment with noticeable gaps
-- **0.4-0.6** = Poor alignment with significant issues
+- **0.4-0.6** = Poor alignment with substantial issues
 - **0.0-0.4** = Very poor alignment, response doesn't address the prompt effectively
 
 ### When to Use Each Mode
@@ -160,7 +160,7 @@ Final Score = Weighted Score × scale
 
 **Both Mode (`'both'`)** - Use when (default, recommended):
 
-- Comprehensive evaluation of overall AI agent performance
+- Comprehensive evaluation of AI agent performance
 - Balancing user satisfaction with system compliance
 - Production monitoring where both user and system requirements matter
 - Holistic assessment of prompt-response alignment
@@ -403,7 +403,7 @@ console.log(result)
 
 ### Excellent alignment output
 
-The output receives a high score because it perfectly addresses the intent, fulfills all requirements, and uses appropriate format.
+The output receives a high score because it perfectly addresses the intent and fulfills all requirements. It also uses the appropriate format.
 
 ```typescript
 {

package/.docs/reference/evals/rubric.md

@@ -106,7 +106,7 @@ The scorer runs in two phases:
 1. **Grade**: The judge model evaluates each criterion independently and returns a per-criterion verdict (`satisfied` / not) with reasoning.
 2. **Score**: The result is `1` only when every required criterion is `satisfied`, otherwise `0`. If no criteria are marked required, all criteria are treated as required.
 
-The `reason` summarizes the overall result and lists each criterion with its verdict, so a failing grade gives the agent targeted, actionable feedback rather than a generic "try again".
+The `reason` summarizes the result and lists each criterion with its verdict, so a failing grade gives the agent targeted, useful feedback rather than a generic "try again".
 
 ## Related
 

package/.docs/reference/evals/run-evals.md

@@ -371,9 +371,9 @@ const result = await runEvals({
 // result.verdict: 'passed' | 'scored' | 'failed'
 ```
 
-Each turn runs `agent.generate()` with the same `threadId`, so the agent sees the full conversation history. `runEvals` also injects a `resourceId` (Mastra memory scopes messages by resource + thread), defaulting it to the generated thread; pass `targetOptions.memory.resource` to pin a specific one. Cross-turn recall requires the agent to have a memory store configured; otherwise turns run in isolation. Mix single-turn (`input`) and multi-turn (`inputs`) items in the same `data` array. When using `inputs`, `input` can be omitted.
+Each turn runs `agent.generate()` with the same `threadId`, so the agent sees the full conversation history. `runEvals` also injects a `resourceId` (Mastra memory scopes messages by resource + thread), defaulting it to the generated thread. Pass `targetOptions.memory.resource` to pin a specific one. Cross-turn recall requires the agent to have a memory store configured. Otherwise turns run in isolation. Mix single-turn (`input`) and multi-turn (`inputs`) items in the same `data` array. When using `inputs`, `input` can be omitted.
 
-Scoring uses the accumulated output from all turns as `run.output`, but only the first turn as `run.input`. Prefer output-based scorers (`checks.includes`, `checks.calledTool`, `checks.similarity`) for multi-turn; input-relative scorers (e.g. faithfulness) only see the first turn's input. Trajectory scorers that read from the trace (`AgentScorerConfig.trajectory`) resolve against the last turn's span; tool-call checks that read `run.output` (like `checks.calledTool`) still see every turn.
+Scoring uses the accumulated output from all turns as `run.output`, but only the first turn as `run.input`. Prefer output-based scorers (`checks.includes`, `checks.calledTool`, `checks.similarity`) for multi-turn. Input-relative scorers (e.g. faithfulness) only see the first turn's input. Trajectory scorers that read from the trace (`AgentScorerConfig.trajectory`) resolve against the last turn's span. Tool-call checks that read `run.output` (like `checks.calledTool`) still see every turn.
 
 ### Per-turn assertions
 
@@ -403,7 +403,7 @@ result.verdict // folds in per-turn gate/threshold outcomes
 result.turnResults // [{ index, gateResults, thresholdResults, scores }]
 ```
 
-Per-turn gates/scorers evaluate only that turn (`run.input`/`run.output` are that turn's). A failing turn gate makes the verdict `failed`; a missed turn threshold (gates passing) makes it `scored`. Top-level `scorers`/`gates` still score the accumulated conversation holistically. `turns` is Agent-only and cannot be combined with `input` or `inputs`.
+Per-turn gates/scorers evaluate only that turn (`run.input`/`run.output` are that turn's). A failing turn gate makes the verdict `failed`. A missed turn threshold (gates passing) makes it `scored`. Top-level `scorers`/`gates` still score the accumulated conversation as a whole. `turns` is Agent-only and can't be combined with `input` or `inputs`.
 
 ## Related
 

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

@@ -284,7 +284,7 @@ const result = await myScorer.run({
 
 ### `extractTrajectory`
 
-Extracts a `Trajectory` from agent output messages (`MastraDBMessage[]`). Converts tool invocations into `ToolCallStep` objects. The `runEvals` pipeline calls this automatically for trajectory scorers — you only need it for direct testing.
+Extracts a `Trajectory` from agent output messages (`MastraDBMessage[]`). Converts tool invocations into `ToolCallStep` objects. The `runEvals` pipeline calls this automatically for trajectory scorers: you only need it for direct testing.
 
 Available from `@mastra/core/evals`.
 
@@ -296,7 +296,7 @@ const trajectory = extractTrajectory(agentOutputMessages)
 // trajectory.rawOutput — the original MastraDBMessage[] array
 ```
 
-**Returns:** `Trajectory` — Contains `steps: TrajectoryStep[]`, `totalDurationMs`, and `rawOutput`.
+**Returns:** `Trajectory`: Contains `steps: TrajectoryStep[]`, `totalDurationMs`, and `rawOutput`.
 
 ### `extractWorkflowTrajectory`
 
@@ -314,7 +314,7 @@ const trajectory = extractWorkflowTrajectory(
 // trajectory.steps — WorkflowStepStep[] in execution order
 ```
 
-**Returns:** `Trajectory` — Contains `steps: TrajectoryStep[]`, `totalDurationMs`, and `rawWorkflowResult`.
+**Returns:** `Trajectory`: Contains `steps: TrajectoryStep[]`, `totalDurationMs`, and `rawWorkflowResult`.
 
 ### `extractTrajectoryFromTrace`
 
@@ -363,7 +363,7 @@ Spans with types `GENERIC`, `MODEL_STEP`, `MODEL_CHUNK`, and `WORKFLOW_CONDITION
 
 Compares an actual trajectory against an expected trajectory and returns a detailed comparison result. Used internally by `createTrajectoryAccuracyScorerCode`.
 
-The `expected` parameter accepts either a `Trajectory` (actual trajectory) or `{ steps: ExpectedStep[] }`. When using `ExpectedStep[]`, you can match by name only, name + stepType, or include data for comparison. See [Expected steps](https://mastra.ai/reference/evals/trajectory-accuracy) for details.
+The `expected` parameter accepts either a `Trajectory` (actual trajectory) or `{ steps: ExpectedStep[] }`. When using `ExpectedStep[]`, you can match by name only or by name + stepType. You can also include data for comparison. See [Expected steps](https://mastra.ai/reference/evals/trajectory-accuracy) for details.
 
 ```typescript
 import { compareTrajectories } from '@mastra/evals/scorers/utils'

package/.docs/reference/evals/textual-difference.md

@@ -62,10 +62,10 @@ Final score: `(similarity_ratio * confidence) * scale`
 
 A textual difference score between 0 and 1:
 
-- **1.0**: Identical texts – no differences detected.
-- **0.7–0.9**: Minor differences – few changes needed.
-- **0.4–0.6**: Moderate differences – noticeable changes required.
-- **0.1–0.3**: Major differences – extensive changes needed.
+- **1.0**: The texts are identical.
+- **0.7 to 0.9**: Minor differences, few changes needed.
+- **0.4 to 0.6**: Moderate differences, noticeable changes required.
+- **0.1 to 0.3**: Major differences, extensive changes needed.
 - **0.0**: Completely different texts.
 
 ## Example

package/.docs/reference/evals/tool-call-accuracy.md

@@ -275,7 +275,7 @@ console.log(result.score) // 1 - auth-tool comes before fetch-tool
 
 ## LLM-based tool call accuracy scorer
 
-The `createToolCallAccuracyScorerLLM()` function from `@mastra/evals/scorers/prebuilt` uses an LLM to evaluate whether the tools called by an agent are appropriate for the given user request, providing semantic evaluation rather than exact matching.
+The `createToolCallAccuracyScorerLLM()` function from `@mastra/evals/scorers/prebuilt` uses an LLM to evaluate whether the tools called by an agent are appropriate for the user request, providing semantic evaluation rather than exact matching.
 
 ### Parameters
 

package/.docs/reference/evals/toxicity.md

@@ -2,7 +2,7 @@
 
 # Toxicity scorer
 
-The `createToxicityScorer()` function evaluates whether an LLM's output contains racist, biased, or toxic elements. It uses a judge-based system to analyze responses for various forms of toxicity including personal attacks, mockery, hate speech, dismissive statements, and threats.
+The `createToxicityScorer()` function evaluates whether an LLM's output contains racist, biased, or toxic elements. It uses a judge-based system to analyze responses for forms of toxicity including personal attacks, mockery, hate speech, dismissive statements, and threats.
 
 ## Parameters
 
@@ -74,9 +74,9 @@ Final score: `(toxicity_weighted_sum / max_toxicity) * scale`
 
 A toxicity score between 0 and 1:
 
-- **0.8–1.0**: Severe toxicity.
-- **0.4–0.7**: Moderate toxicity.
-- **0.1–0.3**: Mild toxicity.
+- **0.8 to 1.0**: Severe toxicity.
+- **0.4 to 0.7**: Moderate toxicity.
+- **0.1 to 0.3**: Mild toxicity.
 - **0.0**: No toxic elements detected.
 
 ## Example

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

@@ -15,7 +15,7 @@ The `runEvals` pipeline uses two extraction strategies, depending on whether obs
 
 ### Trace-based extraction (preferred)
 
-When the target's `Mastra` instance has storage configured, the pipeline fetches the full execution trace from the observability store and calls `extractTrajectoryFromTrace()`. This produces a hierarchical trajectory with nested `children`, capturing the complete execution tree — including nested agent runs, tool calls within workflow steps, and model generations.
+When the target's `Mastra` instance has storage configured, the pipeline fetches the full execution trace from the observability store and calls `extractTrajectoryFromTrace()`. This produces a hierarchical trajectory with nested `children` that captures the complete execution tree. The tree includes nested agent runs and tool calls within workflow steps. It also includes model generations.
 
 For example, a workflow that calls an agent, which in turn calls tools, produces:
 
@@ -35,8 +35,8 @@ workflow_run
 
 When storage isn't available, the pipeline falls back to:
 
-- **Agents:** `extractTrajectory()` — Extracts `ToolCallStep` entries from `toolInvocations` in the agent's message output. Produces a flat list of tool calls.
-- **Workflows:** `extractWorkflowTrajectory()` — Extracts `WorkflowStepStep` entries from `stepResults`. Produces a flat list of workflow steps.
+- **Agents:** `extractTrajectory()`, Extracts `ToolCallStep` entries from `toolInvocations` in the agent's message output. Produces a flat list of tool calls.
+- **Workflows:** `extractWorkflowTrajectory()`, Extracts `WorkflowStepStep` entries from `stepResults`. Produces a flat list of workflow steps.
 
 These fallbacks don't capture nested execution or non-tool-call spans.
 
@@ -105,7 +105,7 @@ All step types share the base properties `name`, `durationMs`, `metadata`, and `
 
 ## Expected steps
 
-When defining expected trajectories, use `ExpectedStep` instead of the full `TrajectoryStep` discriminated union. `ExpectedStep` is a discriminated union that mirrors `TrajectoryStep` — when you specify a `stepType`, you get autocomplete for that variant's fields (e.g., `toolArgs` for `tool_call`, `modelId` for `model_generation`). All variant-specific fields are optional, so you only assert against what you care about.
+When defining expected trajectories, use `ExpectedStep` instead of the full `TrajectoryStep` discriminated union. `ExpectedStep` is a discriminated union that mirrors `TrajectoryStep`: when you specify a `stepType`, you get autocomplete for that variant's fields (e.g., `toolArgs` for `tool_call`, `modelId` for `model_generation`). All variant-specific fields are optional, so you only assert against what you care about.
 
 Omit `stepType` entirely to match any step by name only.
 
@@ -199,8 +199,8 @@ This function returns an instance of the MastraScorer class. See the [MastraScor
 
 The code-based scorer resolves `expectedTrajectory` from two sources, in order of priority:
 
-1. **Constructor option** — A static trajectory passed when creating the scorer. Used for all dataset items.
-2. **Dataset item** — An `expectedTrajectory` field on the dataset item, passed through the `runEvals` pipeline. Allows different expected trajectories per item.
+1. **Constructor option**: A static trajectory passed when creating the scorer. Used for all dataset items.
+2. **Dataset item**: An `expectedTrajectory` field on the dataset item, passed through the `runEvals` pipeline. Allows different expected trajectories per item.
 
 ```typescript
 // Static: same expected trajectory for all items
@@ -474,10 +474,10 @@ The `createTrajectoryScorerCode()` function from `@mastra/evals/scorers/prebuilt
 
 The unified scorer evaluates four dimensions:
 
-1. **Accuracy** — Matches actual steps against expected steps (if `steps` is configured). Uses the `ordering` mode.
-2. **Efficiency** — Checks step budgets (`maxSteps`, `maxTotalTokens`, `maxTotalDurationMs`) and redundant calls (`noRedundantCalls`).
-3. **Blacklist** — Checks for forbidden tools or sequences. Any violation immediately results in a score of **0.0** regardless of other dimensions.
-4. **Tool failures** — Detects retry patterns, fallback patterns, and argument correction patterns.
+1. **Accuracy**: Matches actual steps against expected steps (if `steps` is configured). Uses the `ordering` mode.
+2. **Efficiency**: Checks step budgets (`maxSteps`, `maxTotalTokens`, `maxTotalDurationMs`) and redundant calls (`noRedundantCalls`).
+3. **Blacklist**: Checks for forbidden tools or sequences. Any violation immediately results in a score of **0.0** regardless of other dimensions.
+4. **Tool failures**: Detects retry and fallback patterns. It also detects argument correction patterns.
 
 The final score is a weighted combination of active dimensions, normalized by which dimensions are active. Default weights are accuracy 0.4, efficiency 0.3, tool failures 0.2, blacklist 0.1, but you can customize them via the `weights` option. Blacklist violations override everything to 0. When nested evaluations are present, the score is 70% top-level and 30% nested average.
 

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

@@ -27,7 +27,7 @@ Move conditional, large, or action-oriented guidance into [`tools/`](https://mas
 
 ## Dynamic instructions
 
-When the prompt needs to change per request, for example based on the current user or runtime context, set a dynamic `instructions` function in [`config.ts`](https://mastra.ai/reference/file-based-agents/config) instead of using `instructions.md`. A function `instructions` wins over `instructions.md`, so the static file is ignored when both are present.
+When the prompt needs to change per request, for example based on the current user or runtime context, set a runtime-defined `instructions` function in [`config.ts`](https://mastra.ai/reference/file-based-agents/config) instead of using `instructions.md`. A function `instructions` wins over `instructions.md`, so the static file is ignored when both are present.
 
 ```typescript
 import { agentConfig } from '@mastra/core/agent'
@@ -49,6 +49,6 @@ Mastra reads `instructions.md` and inlines its contents into the generated code
 
 Instructions can come from `instructions.md` or from the `instructions` field in [`config.ts`](https://mastra.ai/reference/file-based-agents/config):
 
-- A dynamic (function) `instructions` in `config.ts` wins over `instructions.md`.
+- A runtime-defined (function) `instructions` in `config.ts` wins over `instructions.md`.
 - Otherwise `instructions.md` wins over a static `instructions` string.
 - If neither is present, the build fails and names the agent directory.

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

@@ -23,4 +23,4 @@ Mastra registers the logger before storage, observability, and file-based agents
 
 ## Precedence with code
 
-Code-registered logging wins over `logger.ts`. If you pass `logger` to `new Mastra({ logger })` in `src/mastra/index.ts` (or set `logger: false` to disable logging), `logger.ts` is ignored with a warning. Use `logger.ts` when one project-wide logger is enough; use code registration when setup depends on runtime wiring.
+Code-registered logging wins over `logger.ts`. If you pass `logger` to `new Mastra({ logger })` in `src/mastra/index.ts` (or set `logger: false` to disable logging), `logger.ts` is ignored with a warning. Use `logger.ts` when one project-wide logger is enough. Use code registration when setup depends on runtime wiring.

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

@@ -29,4 +29,4 @@ export default new Observability({
 
 ## Precedence with code
 
-Code-registered observability wins over `observability.ts`. Use `observability.ts` when one project-wide configuration is enough; use code registration when setup depends on runtime wiring in `src/mastra/index.ts`.
+Code-registered observability wins over `observability.ts`. Use `observability.ts` when one project-wide configuration is enough. Use code registration when setup depends on runtime wiring in `src/mastra/index.ts`.

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

@@ -45,7 +45,7 @@ If `config.inputProcessors` or `config.outputProcessors` is a function, discover
 
 ## Precedence with config
 
-Use `config.ts` for processors that need to be created dynamically or shared across agents. Use file-based processors for static, per-agent processors that should be reviewed alongside the agent.
+Use `config.ts` for processors that need to be created at runtime or shared across agents. Use file-based processors for static, per-agent processors that should be reviewed alongside the agent.
 
 Precedence is:
 

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

@@ -40,7 +40,7 @@ For packaged skills, `description` is required in `SKILL.md` frontmatter. Flat m
 
 ## What gets loaded
 
-File-based Agents skills are read at build time and added to the generated bundle. The deployed agent doesn't need to read those skill files from disk at runtime.
+File-based Agent skills are added to the generated bundle at build time, so the deployed agent doesn't read them from disk.
 
 For packaged skills, Mastra reads:
 

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

@@ -27,4 +27,4 @@ Mastra registers the store before file-based agents and workflows, so storage-de
 
 ## Precedence with code
 
-Code-registered storage wins over `storage.ts`. Use `storage.ts` when one project-wide store is enough; use code registration when setup depends on runtime wiring in `src/mastra/index.ts`.
+Code-registered storage wins over `storage.ts`. Use `storage.ts` when one project-wide store is enough. Use code registration when setup depends on runtime wiring in `src/mastra/index.ts`.

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

@@ -53,4 +53,4 @@ The auth provider handles who the user is. For what the user can do after sign-i
 
 ## Precedence with code
 
-Code-registered Studio config wins over `studio.ts`. Use `studio.ts` when one project-wide Studio config is enough; use code registration when auth depends on runtime wiring in `src/mastra/index.ts`.
+Code-registered Studio config wins over `studio.ts`. Use `studio.ts` when one project-wide Studio config is enough. Use code registration when auth depends on runtime wiring in `src/mastra/index.ts`.

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

@@ -2,7 +2,7 @@
 
 # Subagents
 
-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, calls that tool to hand off a task, and receives the subagent's result back in the parent conversation.
+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/agents/supervisor-agents).
 

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

@@ -37,7 +37,7 @@ Use one file per tool. Name the file after the action the model should take:
 
 - Use `get_weather.ts`, `search_docs.ts`, or `create_ticket.ts`.
 - Avoid vague names like `helper.ts`, `api.ts`, or `utils.ts`.
-- Co-locate tests next to the tool as `*.test.ts` or `*.spec.ts`; discovery ignores those files.
+- Co-locate tests next to the tool as `*.test.ts` or `*.spec.ts`. Discovery ignores those files.
 - Keep shared helper code outside `tools/` or in files that don't match the discovered extensions under `tools/`.
 
 Because nested directories aren't discovered as tools, group related tools with clear filename prefixes instead of subfolders, such as `calendar_create_event.ts` and `calendar_list_events.ts`.

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

@@ -56,7 +56,7 @@ The workspace filesystem controls what file tools can read and write. The sandbo
 
 ## Seed files
 
-Add a `workspace/` directory to ship starting files with the agent. Mastra mirrors files under `workspace/` into the agent's default runtime workspace at build time, so the agent starts with those files on disk.
+Add a `workspace/` directory to include starting files with the agent. Mastra mirrors files under `workspace/` into the agent's default runtime workspace at build time, so the agent starts with those files on disk.
 
 ```text
 src/mastra/agents/weather/

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

@@ -2,7 +2,7 @@
 
 # PinoLogger
 
-A Logger instance is created using `new PinoLogger()` and provides methods to record events at various severity levels.
+A Logger instance is created using `new PinoLogger()` and provides methods to record events at severity levels.
 
 ## Usage example
 
@@ -86,7 +86,7 @@ const logger = new MastraPinoWithAudit({
 export const mastra = new Mastra({ logger })
 ```
 
-Numeric values follow Pino’s ordering (built-in levels use 10–60). A level of `35` sits between `info` (30) and `warn` (40), so with `level: 'info'` both `info` and `audit` lines are emitted.
+Numeric values follow Pino’s ordering (built-in levels use 10 to 60). A level of `35` sits between `info` (30) and `warn` (40), so with `level: 'info'` both `info` and `audit` lines are emitted.
 
 ## File transport (structured logs)
 
@@ -114,7 +114,7 @@ fileLogger.warn('Low disk space', {
 
 ## Upstash transport (remote log drain)
 
-Streams structured logs to a remote Redis list using the `UpstashTransport`. The logger accepts a string message and a structured metadata object. This enables centralized logging for distributed environments, supporting filtering by `destinationPath`, `type`, and `runId`.
+Streams structured logs to a remote Redis list using the `UpstashTransport`. The logger accepts a string message and a structured metadata object. It supports centralized logging for distributed environments, supporting filtering by `destinationPath`, `type`, and `runId`.
 
 ```typescript
 import { UpstashTransport } from '@mastra/loggers/upstash'

package/.docs/reference/memory/clone-utilities.md

@@ -2,7 +2,7 @@
 
 # Cloned thread utilities
 
-The Memory class provides utility methods for working with cloned threads. These methods help you check clone status, retrieve clone metadata, navigate clone relationships, and track clone history.
+The Memory class provides utility methods for working with cloned threads. These methods help you check clone status, retrieve clone metadata, traverse clone relationships, and track clone history.
 
 ## `isClone()`
 

package/.docs/reference/memory/cloneThread.md

@@ -2,7 +2,7 @@
 
 # Memory.cloneThread()
 
-The `.cloneThread()` method creates a copy of an existing conversation thread, including all its messages. This enables creating divergent conversation paths from a specific point in a conversation. When semantic recall is enabled, the method also creates vector embeddings for the cloned messages.
+The `.cloneThread()` method creates a copy of an existing conversation thread, including all its messages. It supports creating divergent conversation paths from a specific point in a conversation. When semantic recall is enabled, the method also creates vector embeddings for the cloned messages.
 
 ## Usage example
 
@@ -125,7 +125,7 @@ Pass the cloned `thread.id` and `thread.resourceId` to `agent.generate()` to con
 
 ## Vector embeddings
 
-When the Memory instance has semantic recall enabled with a vector store and embedder configured, `cloneThread()` automatically creates vector embeddings for all cloned messages. This ensures that semantic search works correctly on the cloned thread.
+When the Memory instance has semantic recall enabled with a vector store and embedder configured, `cloneThread()` automatically creates vector embeddings for all cloned messages. It ensures that semantic search works correctly on the cloned thread.
 
 In this example, `embeddingModel` is the embedding model configured for the project.
 
@@ -170,4 +170,4 @@ When [Observational Memory](https://mastra.ai/docs/memory/observational-memory)
 - **Resource-scoped OM (same `resourceId`)**: The OM record is shared between the source and cloned threads since they belong to the same resource. No duplication occurs.
 - **Resource-scoped OM (different `resourceId`)**: The OM record is cloned to the new resource. Message IDs are remapped and any thread-identifying tags within observations are updated to reference the cloned thread.
 
-Only the current (most recent) OM generation is cloned — older history generations aren't copied. Transient processing state (observation/reflection in-progress flags) is reset on the cloned record.
+Only the current (most recent) OM generation is cloned. Older history generations aren't copied. Transient processing state (observation/reflection in-progress flags) is reset on the cloned record.

package/.docs/reference/memory/listThreads.md

@@ -19,7 +19,7 @@ const result = await memory.listThreads({
 
 Use `perPage: false` to retrieve all matching threads at once.
 
-> **Warning:** Generally speaking it's recommended to use pagination, especially for large datasets. Use this option cautiously.
+> **Warning:** Use pagination, especially for large datasets. Use this option cautiously.
 
 ```typescript
 const result = await memory.listThreads({

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

@@ -2,7 +2,7 @@
 
 # Memory class
 
-The `Memory` class provides a robust system for managing conversation history and thread-based message storage in Mastra. It enables persistent storage of conversations, semantic search capabilities, and efficient message retrieval. You must configure a storage provider for conversation history, and if you enable semantic recall you will also need to provide a vector store and embedder.
+The `Memory` class provides a reliable system for managing conversation history and thread-based message storage in Mastra. It enables persistent storage of conversations, semantic search capabilities, and efficient message retrieval. You must configure a storage provider for conversation history, and if you enable semantic recall you will also need to provide a vector store and embedder.
 
 ## Usage example
 

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

@@ -4,7 +4,7 @@
 
 **Added in:** `@mastra/memory@1.1.0`
 
-Observational Memory (OM) is Mastra's memory system for long-context agentic memory. Two background agents — an **Observer** that watches conversations and creates observations, and a **Reflector** that restructures observations by combining related items, reflecting on overarching patterns, and condensing where possible — maintain an observation log that replaces raw message history as it grows.
+Observational Memory (OM) is Mastra's memory system for long-context agentic memory. An **Observer** watches conversations and creates observations. A **Reflector** restructures those observations by combining related items and condensing overarching patterns. Together, they maintain an observation log that replaces raw message history as it grows.
 
 ## Usage
 
@@ -27,7 +27,7 @@ export const agent = new Agent({
 
 ## Configuration
 
-The `observationalMemory` option accepts `true`, a configuration object, or `false`. Setting `true` enables OM with `google/gemini-2.5-flash` as the default model. When passing a config object, a `model` must be explicitly set — either at the top level, or on `observation.model` and/or `reflection.model`.
+The `observationalMemory` option accepts `true`, a configuration object, or `false`. Setting `true` enables OM with `google/gemini-2.5-flash` as the default model. When passing a config object, a `model` must be explicitly set: either at the top level or on `observation.model` and/or `reflection.model`.
 
 Observer input is multimodal-aware. OM keeps text placeholders like `[Image #1: screenshot.png]` in the transcript it builds for the Observer, and also sends the underlying image parts when possible. This applies to both single-thread observation and batched multi-thread observation. Non-image files appear as placeholders only.
 
@@ -170,7 +170,7 @@ const memory = new Memory({
 - Schema-less extractors are inline string extractors emitted directly in the Observer or Reflector output.
 - Dynamic extractor functions receive runtime context, including `source`, `threadId`, `resourceId`, `mainAgent`, `memory`, and `requestContext` when available.
 - `WorkingMemoryExtractor` uses the normal extractor pipeline to update working memory through the active `Memory` instance. It uses structured extraction when working memory has a JSON schema and skips OM metadata persistence, so the working memory payload isn't duplicated under OM extracted metadata.
-- `observationalMemory.observation.manageWorkingMemory` adds `WorkingMemoryExtractor`, defaults `workingMemory.agentManaged` to `false`, and defaults `workingMemory.useStateSignals` to `true` when working memory is enabled.
+- `observationalMemory.observation.manageWorkingMemory` adds `WorkingMemoryExtractor` and defaults `workingMemory.agentManaged` to `false`. It defaults `workingMemory.useStateSignals` to `true` when working memory is enabled.
 - Extraction failures are reported in OM marker data and don't discard other successful extracted values.
 
 ## Examples
@@ -341,16 +341,16 @@ export const agent = new Agent({
 
 ### Async buffering
 
-Async buffering is **enabled by default**. It pre-computes observations in the background as the conversation grows — when the `messageTokens` threshold is reached, buffered observations activate instantly with no blocking LLM call.
+Async buffering is **enabled by default**. It pre-computes observations in the background as the conversation grows: when the `messageTokens` threshold is reached, buffered observations activate instantly with no blocking LLM call.
 
-The lifecycle is: **buffer → activate → remove messages → repeat**. Background Observer calls run at `bufferTokens` intervals, each producing a chunk of observations. At threshold, chunks activate: observations move into the log, raw messages are removed from context. The `blockAfter` threshold forces a synchronous fallback if buffering can't keep up.
+The lifecycle follows **buffer → activate → remove messages → repeat**. Background Observer calls run at `bufferTokens` intervals, each producing a chunk of observations. At threshold, chunks activate: observations move into the log, raw messages are removed from context. The `blockAfter` threshold forces a synchronous fallback if buffering can't keep up.
 
 Default settings:
 
-- `observation.bufferTokens: 0.2` — buffer every 20% of `messageTokens` (e.g. every \~6k tokens with a 30k threshold)
-- `observation.bufferActivation: 0.8` — on activation, remove enough messages to keep only 20% of the threshold remaining
+- `observation.bufferTokens: 0.2`: Buffer every 20% of `messageTokens` (e.g. every \~6k tokens with a 30k threshold)
+- `observation.bufferActivation: 0.8`: On activation, remove enough messages to keep only 20% of the threshold remaining
 - Buffered observations include continuation hints (`suggestedResponse`, `currentTask`) that survive activation to maintain conversational continuity
-- `reflection.bufferActivation: 0.5` — start background reflection at 50% of observation threshold
+- `reflection.bufferActivation: 0.5`: start background reflection at 50% of observation threshold
 
 To customize:
 
@@ -476,7 +476,7 @@ interface DataOmStatusPart {
 }
 ```
 
-`buffered.reflection.inputObservationTokens` is the size of the observations that were sent to the Reflector. `buffered.reflection.observationTokens` is the compressed result — the size of what will replace those observations when the reflection activates. A client can use these two values to show a compression ratio.
+`buffered.reflection.inputObservationTokens` is the size of the observations that were sent to the Reflector. `buffered.reflection.observationTokens` is the compressed result: the size of what will replace those observations when the reflection activates. A client can use these two values to show a compression ratio.
 
 Clients can derive percentages and post-activation estimates from the raw values:
 
@@ -643,7 +643,7 @@ Emitted when async buffering fails. The system falls back to synchronous process
 
 ### `data-om-activation`
 
-Emitted when buffered observations or reflections are activated (moved into the active context window). This is an instant operation — no LLM call is involved.
+Emitted when buffered observations or reflections are activated (moved into the active context window). This is an instant operation: no LLM call is involved.
 
 **cycleId** (`string`): Unique ID for this activation event.
 
@@ -717,7 +717,7 @@ The standalone `ObservationalMemory` class accepts all the same options as the `
 
 ## Recall tool
 
-When `retrieval` is set (any truthy value), a `recall` tool is registered so the agent can page through raw messages behind observation group ranges. By default (scope `'resource'`), the tool supports listing threads (`mode: "threads"`), browsing other threads (`threadId`), and cross-thread search. With `retrieval: { vector: true }`, semantic search is available (`mode: "search"`). Set `scope: 'thread'` to restrict the tool to the current thread only. The tool is automatically added to the agent's tool list — no manual registration is needed.
+When `retrieval` is set (any truthy value), a `recall` tool is registered so the agent can page through raw messages behind observation group ranges. By default (scope `'resource'`), the tool supports listing threads (`mode: "threads"`), browsing other threads (`threadId`), and cross-thread search. With `retrieval: { vector: true }`, semantic search is available (`mode: "search"`). Set `scope: 'thread'` to restrict the tool to the current thread only. The tool is automatically added to the agent's tool list.
 
 ### Parameters
 

package/.docs/reference/memory/recall.md

@@ -59,9 +59,9 @@ const { messages } = await memory.recall({
 })
 ```
 
-All metadata entries are combined with AND semantics. A message must match every key and value with exact type equality. `null` matches metadata that is explicitly set to `null`; it doesn't match a missing key.
+All metadata entries are combined with AND semantics. A message must match every key and value with exact type equality. `null` matches metadata that's explicitly set to `null`. It doesn't match a missing key.
 
-Metadata filters only support shallow scalar values: `string`, finite `number`, `boolean`, and `null`. Nested objects, arrays, `NaN`, and infinities are not supported. Metadata keys must start with a letter or underscore, may contain only alphanumeric characters and underscores, must be 128 characters or fewer, and can't use reserved prototype keys such as `__proto__`, `constructor`, or `prototype`. Performance depends on the storage backend. Arbitrary metadata filters may require scanning candidate messages, so narrow the query with `threadId`, `resourceId`, or `dateRange` when possible.
+Metadata filters only support shallow scalar values: `string`, finite `number`, `boolean`, and `null`. Nested objects, arrays, `NaN`, and infinities aren't supported. Metadata keys must start with a letter or underscore and contain only alphanumeric or underscore characters. The limit is 128 characters. Reserved prototype keys such as `__proto__`, `constructor`, and `prototype` aren't allowed. Performance depends on the storage backend. Arbitrary metadata filters may require scanning candidate messages, so narrow the query with `threadId`, `resourceId`, or `dateRange` when possible.
 
 ## Returns
 

package/.docs/reference/memory/serialized-memory-config.md

@@ -68,7 +68,7 @@ new MastraEditor({
 
 ## Related
 
-- [Memory class](https://mastra.ai/reference/memory/memory-class) — the runtime type this config hydrates into.
-- [Observational memory](https://mastra.ai/reference/memory/observational-memory) — full observational memory reference.
-- [BuilderAgentDefaults](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults) — where this type is pinned as the Builder default.
-- [Agent Builder: Memory](https://mastra.ai/docs/agent-builder/memory) — concept and worked examples.
+- [Memory class](https://mastra.ai/reference/memory/memory-class): The runtime type this config hydrates into.
+- [Observational memory](https://mastra.ai/reference/memory/observational-memory): Full observational memory reference.
+- [BuilderAgentDefaults](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults): Where this type is pinned as the Builder default.
+- [Agent Builder: Memory](https://mastra.ai/docs/agent-builder/memory): Concept and worked examples.

package/.docs/reference/memory/summarizeConversation.md

@@ -2,11 +2,11 @@
 
 # summarizeConversation()
 
-The standalone `summarizeConversation()` function summarizes a conversation in one shot. It distills the messages you pass in with the same Observer plumbing that powers [Observational Memory](https://mastra.ai/reference/memory/observational-memory) — without Observational Memory attached to an agent, and without reading from or writing to storage.
+The standalone `summarizeConversation()` function summarizes a conversation in one shot. It distills the messages you pass in with the same Observer plumbing that powers [Observational Memory](https://mastra.ai/reference/memory/observational-memory): without Observational Memory attached to an agent, and without reading from or writing to storage.
 
-Nothing is written back to memory. The summary and extracted values are returned to you (and to each extractor's `onExtracted` hook), so you decide where they go — for example your own database.
+Nothing is written back to memory. The summary and extracted values are returned to you (and to each extractor's `onExtracted` hook), so you decide where they go: for example your own database.
 
-Use this when you already have the messages in hand and want explicit control over what gets summarized. To summarize a stored thread by ID instead, use [`Memory.summarizeThread()`](https://mastra.ai/reference/memory/summarizeThread), which loads the messages for you.
+Use this when you already have the messages in hand and want explicit control over what gets summarized. For a stored thread identified by ID, use [`Memory.summarizeThread()`](https://mastra.ai/reference/memory/summarizeThread), which loads the messages for you.
 
 ## Usage example
 

package/.docs/reference/memory/summarizeThread.md

@@ -2,13 +2,13 @@
 
 # Memory.summarizeThread()
 
-The `.summarizeThread()` method summarizes a thread's conversation in one shot. It loads the thread's messages from storage and distills them with the same Observer plumbing that powers [Observational Memory](https://mastra.ai/reference/memory/observational-memory) — as a standalone call, without Observational Memory attached to an agent.
+The `.summarizeThread()` method summarizes a thread's conversation in one shot. It loads the thread's messages from storage and distills them with the same Observer plumbing that powers [Observational Memory](https://mastra.ai/reference/memory/observational-memory): as a standalone call, without Observational Memory attached to an agent.
 
 Messages load page-by-page starting from the newest, bounded by `lastMessages` and `maxInputTokens`, so summarizing a long thread doesn't read its entire history from storage.
 
-Nothing is written back to memory. The summary and extracted values are returned to you (and to each extractor's `onExtracted` hook), so you decide where they go — for example your own database.
+Nothing is written back to memory. The summary and extracted values are returned to you (and to each extractor's `onExtracted` hook), so you decide where they go: for example your own database.
 
-Use this when a session ends and you want a summary or structured extraction of the whole conversation, such as a voice call at hang-up. To summarize messages you already have in hand (without loading them from a thread), use the standalone [`summarizeConversation()`](https://mastra.ai/reference/memory/summarizeConversation) function instead — it takes the same options with `messages` in place of `threadId`.
+Use this when a session ends and you want a summary or structured extraction of the whole conversation, such as a voice call at hang-up. For messages you already have in hand (without loading them from a thread), use the standalone [`summarizeConversation()`](https://mastra.ai/reference/memory/summarizeConversation) function instead. It takes the same options with `messages` in place of `threadId`.
 
 ## Usage example
 

package/.docs/reference/observability/feedback.md

@@ -73,7 +73,7 @@ await observability.createFeedback({
 })
 ```
 
-The HTTP and client SDK create route accepts `CreateFeedbackBody`, sets `timestamp` server-side, and generates `feedbackId` when omitted:
+The HTTP and client SDK create route accepts `CreateFeedbackBody` and sets `timestamp` server-side. It generates `feedbackId` when omitted:
 
 ```typescript
 await mastraClient.createFeedback({