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

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({

package/.docs/reference/observability/metrics/automatic-metrics.md

@@ -12,7 +12,7 @@ Metrics are extracted from spans when they end. The observability layer inspects
 
 ### What affects whether a metric is available
 
-Two conditions must be true for a metric to reach storage:
+A metric reaches storage when:
 
 1. `MastraStorageExporter` is configured as an exporter.
 2. The storage backend supports metrics (ClickHouse, DuckDB, or Postgres v-next with the observability domain enabled).
@@ -33,7 +33,7 @@ Duration metrics record execution time in milliseconds, calculated from the span
 
 ## Token usage metrics
 
-Token metrics are emitted only from `MODEL_GENERATION` spans that include `usage` data. If the provider doesn't report usage, no token metrics are emitted for that span.
+Token metrics are emitted only from `MODEL_GENERATION` spans that include `usage` data. Token metrics require usage data from the provider.
 
 ### Input token metrics
 
@@ -64,7 +64,7 @@ The detailed breakdown metrics (everything except `total_input` and `total_outpu
 
 ### When cost context is attached
 
-Cost context is attached to token metrics when the embedded pricing registry has a matching entry for the provider and model. The registry ships with Mastra and covers common providers and models. If no match is found, token metrics are still emitted but without cost fields.
+Cost context is attached to token metrics when the embedded pricing registry has a matching entry for the provider and model. Mastra includes the registry and covers common providers and models. If no match is found, token metrics are still emitted but without cost fields.
 
 ### What cost fields may be included
 
@@ -80,9 +80,9 @@ Cost context is attached to token metrics when the embedded pricing registry has
 
 ### How metrics relate to spans and trace context
 
-Each metric carries a `CorrelationContext` snapshot from the span that produced it. This context is stored alongside the metric value and lets you navigate from a metric to the exact span and trace.
+Each metric carries a `CorrelationContext` snapshot from the span that produced it. This context is stored alongside the metric value and links a metric to the exact span and trace.
 
-The correlation fields are grouped into four categories:
+Correlation fields use these categories:
 
 **Trace correlation**
 
@@ -110,7 +110,7 @@ The correlation fields are grouped into four categories:
 
 ### Why correlation helps with debugging
 
-When you spot a spike in latency or token usage on the Metrics dashboard, correlation context lets you drill directly into the trace that produced the metric. From there you can inspect the individual span to find the root cause: a slow tool call, a large prompt, or an unexpected error.
+When you spot a spike in latency or token usage on the Metrics dashboard, correlation context lets you drill directly into the trace that produced the metric. From there you can inspect the individual span. The root cause might be a slow tool call or a large prompt. It might also be an unexpected error.
 
 ## Troubleshooting
 
@@ -129,7 +129,7 @@ When you spot a spike in latency or token usage on the Metrics dashboard, correl
 ### Token metrics are missing
 
 - **Span is a model generation**: Token metrics are only emitted from `MODEL_GENERATION` spans.
-- **Provider reports usage**: The model provider must include `usage` data in its response. If usage is absent, no token metrics are emitted.
+- **Provider reports usage**: The model provider must include `usage` data in its response. Usage data is required to emit token metrics.
 
 ## Related
 

package/.docs/reference/observability/tracing/bridges/datadog.md

@@ -40,7 +40,7 @@ Extends `BaseExporterConfig`, which includes:
 createSpan(options: CreateSpanOptions<SpanType>): SpanIds | undefined
 ```
 
-Called by the Mastra observability instance during span construction. Creates a dd-trace APM span eagerly via `tracer.startSpan()` and returns Mastra-compatible identifiers. The returned IDs are used by Mastra throughout the span's lifetime; the dd-trace span object is stored internally and used for scope activation.
+Called by the Mastra observability instance during span construction. Creates a dd-trace APM span eagerly via `tracer.startSpan()` and returns Mastra-compatible identifiers. The returned IDs are used by Mastra throughout the span's lifetime. The dd-trace span object is stored internally and used for scope activation.
 
 **Returns:** `SpanIds | undefined` - `{ spanId, traceId, parentSpanId }`, or `undefined` if the bridge is disabled.
 
@@ -151,7 +151,7 @@ const mastra = new Mastra({
 })
 ```
 
-> **Note:** Don't combine `DatadogBridge` with `DatadogExporter` in the same configuration — both emit to LLM Observability and would double-write the same data.
+> **Note:** Don't combine `DatadogBridge` with `DatadogExporter` in the same configuration. Both emit to LLM Observability and would double-write the same data.
 
 ## Setup requirements
 

package/.docs/reference/observability/tracing/exporters/cloud-exporter.md

@@ -4,7 +4,7 @@
 
 **Added in:** `@mastra/observability@1.8.0`. **Deprecated in `1.12.0`** in favor of [`MastraPlatformExporter`](https://mastra.ai/reference/observability/tracing/exporters/mastra-platform-exporter).
 
-> **Deprecated:** `CloudExporter` is retained for backward compatibility and will be removed in a future major version. Use [`MastraPlatformExporter`](https://mastra.ai/reference/observability/tracing/exporters/mastra-platform-exporter) for new projects. The two classes share the same constructor, environment variables, and runtime behavior; `CloudExporter` keeps its original `mastra-cloud-observability-exporter` exporter `name` and `CLOUD_EXPORTER_*` error IDs so monitoring rules built against it keep working.
+> **Deprecated:** `CloudExporter` is retained for backward compatibility and will be removed in a future major version. Use [`MastraPlatformExporter`](https://mastra.ai/reference/observability/tracing/exporters/mastra-platform-exporter) for new projects. Both classes share the same constructor, environment variables, and runtime behavior; `CloudExporter` keeps its original `mastra-cloud-observability-exporter` exporter `name` and `CLOUD_EXPORTER_*` error IDs so monitoring rules built against it keep working.
 
 Sends tracing spans, logs, metrics, scores, and feedback to the Mastra platform for online visualization and monitoring.
 
@@ -106,7 +106,7 @@ async onMetricEvent(event: MetricEvent): Promise<void>
 
 Processes metric signals for Cloud export.
 
-Every `MetricEvent` passed to this handler is buffered and exported to the Cloud metrics endpoint derived from the configured base endpoint. Additional filtering by metric subtype or status inside `CloudExporter` isn't performed; the exporter forwards every metric event it receives unless it's disabled.
+Every `MetricEvent` passed to this handler is buffered and exported to the Cloud metrics endpoint derived from the configured base endpoint. Additional filtering by metric subtype or status inside `CloudExporter` isn't performed. The exporter forwards every metric event it receives unless it's disabled.
 
 **Returns:** `Promise<void>` after the metric event has been accepted for buffering.
 
@@ -130,7 +130,7 @@ async onFeedbackEvent(event: FeedbackEvent): Promise<void>
 
 Processes feedback signals for Cloud export.
 
-Every `FeedbackEvent` passed to this handler is buffered and exported to the Cloud feedback endpoint derived from the configured base endpoint. No feedback-type filtering inside `CloudExporter` is performed; all feedback events received here are forwarded unless the exporter is disabled.
+Every `FeedbackEvent` passed to this handler is buffered and exported to the Cloud feedback endpoint derived from the configured base endpoint. No feedback-type filtering inside `CloudExporter` is performed. All feedback events received here are forwarded unless the exporter is disabled.
 
 **Returns:** `Promise<void>` after the feedback event has been accepted for buffering.
 

package/.docs/reference/observability/tracing/exporters/default-exporter.md

@@ -4,7 +4,7 @@
 
 **Deprecated in `@mastra/observability@1.12.0`** in favor of [`MastraStorageExporter`](https://mastra.ai/reference/observability/tracing/exporters/mastra-storage-exporter).
 
-> **Deprecated:** `DefaultExporter` is retained for backward compatibility and will be removed in a future major version. Use [`MastraStorageExporter`](https://mastra.ai/reference/observability/tracing/exporters/mastra-storage-exporter) for new projects. The two classes share the same constructor, configuration, and runtime behavior; `DefaultExporter` keeps its original `mastra-default-observability-exporter` exporter `name` so monitoring rules built against it keep working.
+> **Deprecated:** `DefaultExporter` is retained for backward compatibility and will be removed in a future major version. Use [`MastraStorageExporter`](https://mastra.ai/reference/observability/tracing/exporters/mastra-storage-exporter) for new projects. Both classes share the same constructor, configuration, and runtime behavior. `DefaultExporter` keeps its original `mastra-default-observability-exporter` exporter `name` so monitoring rules built against it keep working.
 
 Persists observability events to Mastra Storage with automatic batching and retry logic.
 

package/.docs/reference/observability/tracing/exporters/mastra-platform-exporter.md

@@ -108,7 +108,7 @@ async onMetricEvent(event: MetricEvent): Promise<void>
 
 Processes metric signals for export.
 
-Every `MetricEvent` passed to this handler is buffered and exported to the metrics endpoint derived from the configured base endpoint. No additional filtering by metric subtype or status inside `MastraPlatformExporter` is performed; the exporter forwards every metric event it receives unless it's disabled.
+Every `MetricEvent` passed to this handler is buffered and exported to the metrics endpoint derived from the configured base endpoint. No additional filtering by metric subtype or status inside `MastraPlatformExporter` is performed. The exporter forwards every metric event it receives unless it's disabled.
 
 **Returns:** `Promise<void>` after the metric event has been accepted for buffering.
 
@@ -132,7 +132,7 @@ async onFeedbackEvent(event: FeedbackEvent): Promise<void>
 
 Processes feedback signals for export.
 
-Every `FeedbackEvent` passed to this handler is buffered and exported to the feedback endpoint derived from the configured base endpoint. No feedback-type filtering inside `MastraPlatformExporter` is performed; all feedback events received here are forwarded unless the exporter is disabled.
+Every `FeedbackEvent` passed to this handler is buffered and exported to the feedback endpoint derived from the configured base endpoint. No feedback-type filtering inside `MastraPlatformExporter` is performed. All feedback events received here are forwarded unless the exporter is disabled.
 
 **Returns:** `Promise<void>` after the feedback event has been accepted for buffering.
 
@@ -192,7 +192,7 @@ Errors raised by `MastraPlatformExporter` use the `MASTRA_PLATFORM_EXPORTER_*` `
 
 ## Span wire format
 
-The shape of each span sent to Mastra platform is documented here for reference only — it's not exported from `@mastra/observability` and shouldn't be imported. The exporter spreads the original `AnyExportedSpan` (so the source field names are preserved) and layers a small set of platform-friendly aliases on top:
+The shape of each span sent to Mastra platform is documented here for reference only: it's not exported from `@mastra/observability` and shouldn't be imported. The exporter spreads the original `AnyExportedSpan` (so the source field names are preserved) and layers a small set of platform-friendly aliases on top:
 
 ```typescript
 type MastraPlatformSpanRecord = AnyExportedSpan & {
@@ -231,7 +231,7 @@ const customExporter = new MastraPlatformExporter({
 
 ## Migrating from `CloudExporter`
 
-The two classes share the same constructor signature, environment variables, and behavior. To migrate, replace the import and constructor:
+Both classes share the same constructor signature, environment variables, and behavior. To migrate, replace the import and constructor:
 
 ```typescript
 // Before

package/.docs/reference/observability/tracing/exporters/mastra-storage-exporter.md

@@ -162,7 +162,7 @@ const customExporter = new MastraStorageExporter({
 
 ## Migrating from `DefaultExporter`
 
-The two classes share the same constructor signature and behavior. To migrate, replace the import and constructor:
+Both classes share the same constructor signature and behavior. To migrate, replace the import and constructor:
 
 ```typescript
 // Before

package/.docs/reference/observability/tracing/interfaces.md

@@ -803,7 +803,7 @@ interface CustomSamplerOptions {
 
 ### `ConfigSelector`
 
-Function to select which observability instance to use for a given span.
+Function to select which observability instance to use for a span.
 
 ```typescript
 type ConfigSelector = (

package/.docs/reference/observability/tracing/processors/sensitive-data-filter.md

@@ -22,7 +22,7 @@ new Observability({
 })
 ```
 
-If a config already includes a `SensitiveDataFilter` in `spanOutputProcessors`, the auto-applied filter is skipped to avoid double redaction. Pre-instantiated `ObservabilityInstance` values aren't modified — add a `SensitiveDataFilter` to their processors yourself if needed.
+If a config already includes a `SensitiveDataFilter` in `spanOutputProcessors`, the auto-applied filter is skipped to avoid double redaction. Pre-instantiated `ObservabilityInstance` values aren't modified. Add a `SensitiveDataFilter` to their processors yourself if needed.
 
 ## Constructor
 

package/.docs/reference/observability/tracing/span-filtering.md

@@ -2,7 +2,7 @@
 
 # Span filtering
 
-Span filtering controls which spans are exported from an observability config. Use it to reduce noise, lower per-span costs, or keep only the spans that matter for a specific exporter or environment.
+Span filtering controls which spans are exported from an observability config. Use it to reduce noise or lower per-span costs. It can also keep only the spans that matter for a specific exporter or environment.
 
 For a shorter overview of tracing configuration, see [Tracing](https://mastra.ai/docs/observability/tracing/overview).
 

package/.docs/reference/processors/cost-guard-processor.md

@@ -14,7 +14,7 @@ Supports three scoping modes:
 - **Resource scope** (default): Tracks cumulative cost per `resourceId` across runs
 - **Thread scope**: Tracks cumulative cost per `threadId` across runs
 
-> **Approximate cost guard.** Cost data is persisted asynchronously via buffered exporters in the observability pipeline. Fast-running agents may exceed the configured limit before metrics are available for query. Treat `maxCost` as a best-effort threshold, not a hard ceiling.
+> **Approximate cost guard.** Cost data is persisted asynchronously via buffered exporters in the observability pipeline. Fast-running agents may exceed the configured limit before metrics are available for query. Treat `maxCost` as an approximate threshold that fast-running agents may exceed.
 
 ## Usage example
 

package/.docs/reference/processors/pii-detector.md

@@ -2,7 +2,7 @@
 
 # PIIDetector
 
-The `PIIDetector` is a **hybrid processor** that can be used for both input and output processing to detect and redact personally identifiable information (PII) for privacy compliance. This processor helps maintain privacy by identifying various types of PII and providing flexible strategies for handling them, including multiple redaction methods to ensure compliance with GDPR, CCPA, HIPAA, and other privacy regulations.
+The `PIIDetector` is a **hybrid processor** that can be used for both input and output processing to detect and redact personally identifiable information (PII) for privacy compliance. This processor helps maintain privacy by identifying types of PII and providing flexible strategies for handling them, including multiple redaction methods to ensure compliance with GDPR, CCPA, HIPAA, and other privacy regulations.
 
 ## Usage example
 

package/.docs/reference/processors/processor-interface.md

@@ -6,7 +6,7 @@ The `Processor` interface defines the contract for all processors in Mastra. Pro
 
 ## When processor methods run
 
-The eight processor methods run at different points in the agent execution lifecycle:
+Processor methods run at different points in the agent execution lifecycle:
 
 ```text
 ┌────────────────────────────────────────────────────────────────────┐
@@ -168,16 +168,16 @@ Use `messages` when you only need to read, map over, or lightly edit fields on t
 
 ### Persistence
 
-When memory is enabled, only what ends up in `messageList` after all processors finish is persisted to storage. The two return styles are equivalent for persistence:
+When memory is enabled, only what ends up in `messageList` after all processors finish is persisted to storage. Both return styles are equivalent for persistence:
 
-- Mutating `messageList` directly (or returning the same `MessageList` instance) — recorded mutations are applied in place, so the saved conversation reflects your changes.
-- Returning a `MastraDBMessage[]` or `{ messages, systemMessages }` — Mastra reconciles the returned array against `messageList` for the current stage, removing missing messages and replacing system messages.
+- When you mutate `messageList` directly (or return the same `MessageList` instance), recorded mutations are applied in place, so the saved conversation reflects your changes.
+- When you return a `MastraDBMessage[]` or `{ messages, systemMessages }`, Mastra reconciles the returned array against `messageList` for the current stage, removing missing messages and replacing system messages.
 
-Returning a different `MessageList` instance is an error; always mutate the one passed to your processor.
+Returning a different `MessageList` instance is an error. Always mutate the one passed to your processor.
 
 ### Reading text from a message
 
-`MastraDBMessage.content` is a structured object, not a string. The canonical way to read user or assistant text is `content.parts`:
+`MastraDBMessage.content` uses a structured object. Strings aren't supported. The canonical way to read user or assistant text is `content.parts`:
 
 ```typescript
 import type { MastraDBMessage } from '@mastra/core/memory'
@@ -313,10 +313,10 @@ processInputStep?<TTripwireMetadata = unknown>(
 
 `processInputStep` can return several shapes:
 
-- **`ProcessInputStepResult` object** — override any combination of the properties below for this step (described next).
-- **`MessageList`** — return the same `messageList` instance to signal you mutated messages in place.
-- **`MastraDBMessage[]`** — return a transformed messages array; replaces the step's messages.
-- **`void` or `undefined`** — return nothing to leave the step unchanged.
+- **`ProcessInputStepResult` object**: Override any combination of the properties below for this step (described next).
+- **`MessageList`**: Return the same `messageList` instance to signal you mutated messages in place.
+- **`MastraDBMessage[]`**: Return a transformed messages array. Replaces the step's messages.
+- **`void` or `undefined`**: Return nothing to leave the step unchanged.
 
 The object form can return any combination of these properties:
 
@@ -480,7 +480,7 @@ Handles LLM API rejection errors before they surface as final errors. This runs
 
 Add processors that implement `processAPIError` to an agent's `errorProcessors` array.
 
-Processors can inspect the error, modify the request (for example, by appending messages to the `messageList`), and return `{ retry: true }` to signal a retry with the modified state.
+Processors can inspect the error and modify the request, for example by appending messages to the `messageList`. Return `{ retry: true }` to retry with the modified state.
 
 ```typescript
 processAPIError?(args: ProcessAPIErrorArgs): Promise<ProcessAPIErrorResult | void> | ProcessAPIErrorResult | void;
@@ -896,7 +896,7 @@ export class WordCounter implements Processor {
 
 Every processor receives a `state` object in `processLLMRequest`, `processLLMResponse`, `processOutputStream`, `processOutputStep`, `processOutputResult`, and `processAPIError`. State has three important properties:
 
-- **Per-processor**: Each processor gets its own `state` object, keyed by the processor's `id`. Two processors with different ids can't read or overwrite each other's state.
+- **Per-processor**: Each processor gets its own `state` object, keyed by the processor's `id`. Processors with different ids can't read or overwrite each other's state.
 - **Per-request**: A fresh state object is created at the start of every `agent.generate()` or `agent.stream()` call. State doesn't leak between requests or between users.
 - **Shared across methods**: Within one request, the same `state` object is passed to `processLLMRequest` (before the provider call), `processLLMResponse` (after the step completes), `processOutputStream` (for every chunk), `processOutputStep` (after every LLM step), `processOutputResult` (once at the end), and `processAPIError` (when an LLM call fails). For example, `processLLMRequest` can stash a cache key and `processLLMResponse` can read it back to write the response.
 

package/.docs/reference/processors/prompt-injection-detector.md

@@ -2,7 +2,7 @@
 
 # PromptInjectionDetector
 
-The `PromptInjectionDetector` is an **input processor** that detects and prevents prompt injection attacks, jailbreaks, and system manipulation attempts before messages are sent to the language model. This processor helps maintain security by identifying various types of injection attempts and providing flexible strategies for handling them, including content rewriting to neutralize attacks while preserving legitimate user intent.
+The `PromptInjectionDetector` is an **input processor** that detects and prevents prompt injection attacks, jailbreaks, and system manipulation attempts before messages are sent to the language model. This processor helps maintain security by identifying types of injection attempts and providing flexible strategies for handling them, including content rewriting to neutralize attacks while preserving legitimate user intent.
 
 ## Usage example
 

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

@@ -4,7 +4,7 @@
 
 The `ProviderHistoryCompat` processor handles provider-specific history incompatibilities. It can rewrite the outbound language model prompt before a provider call, or react to API errors and retry with repaired message history.
 
-Use it when an agent may switch between model providers, reuse message history across providers, or call a provider that rejects fields emitted by another provider.
+Use it when an agent may switch between model providers or reuse message history across providers. It also handles providers that reject fields emitted by another provider.
 
 ## Usage example
 

package/.docs/reference/processors/regex-filter-processor.md

@@ -2,7 +2,7 @@
 
 # RegexFilterProcessor
 
-The `RegexFilterProcessor` applies zero-cost regex pattern matching to filter, redact, or block content in agent messages. No LLM calls are made — all detection is regex-based.
+The `RegexFilterProcessor` applies zero-cost regex pattern matching to filter, redact, or block content in agent messages. No LLM calls are made. All detection is regex-based.
 
 Supports built-in presets for common patterns (PII, secrets, URLs) and custom regex rules. Can be applied to input, output, or both phases.
 

package/.docs/reference/processors/response-cache.md

@@ -2,11 +2,11 @@
 
 # ResponseCache
 
-`ResponseCache` is an input processor that caches LLM responses on the request/response boundary inside the agentic loop. It hooks into `processLLMRequest` (cache lookup; short-circuits on hit) and `processLLMResponse` (cache write on completion).
+`ResponseCache` is an input processor that caches LLM responses on the request/response boundary inside the agentic loop. It hooks into `processLLMRequest` for cache lookup and short-circuits on a hit. It uses `processLLMResponse` to write the completed response.
 
-The cache key is derived from the resolved `LanguageModelV2Prompt` Mastra is about to send to the model — i.e. _after_ memory has loaded and earlier input processors have transformed the prompt — so two users with different memory contexts produce different cache keys. Each step in an agentic tool loop is independently cached.
+The cache key is derived from the resolved `LanguageModelV2Prompt` Mastra is about to send to the model (i.e. _after_ memory has loaded and earlier input processors have transformed the prompt) so two users with different memory contexts produce different cache keys. Each step in an agentic tool loop is independently cached.
 
-No agent-level option for response caching exists; register `ResponseCache` explicitly on `inputProcessors`. Per-call overrides flow through `RequestContext` via [`ResponseCache.context()`](#static-helpers) and [`ResponseCache.applyContext()`](#static-helpers).
+No agent-level option for response caching exists. Register `ResponseCache` explicitly on `inputProcessors`. Per-call overrides flow through `RequestContext` via [`ResponseCache.context()`](#static-helpers) and [`ResponseCache.applyContext()`](#static-helpers).
 
 ## Usage example
 
@@ -55,7 +55,7 @@ See [Response caching](https://mastra.ai/docs/agents/processors) for the concept
 
 ## Static helpers
 
-`ResponseCache` exposes two static helpers for setting per-call overrides on a `RequestContext`. The helpers keep the underlying context key a private implementation detail — prefer them over reading/writing the raw key.
+`ResponseCache` exposes two static helpers for setting per-call overrides on a `RequestContext`. The helpers keep the underlying context key a private implementation detail: prefer them over reading/writing the raw key.
 
 ### `ResponseCache.context(options)`
 
@@ -88,7 +88,7 @@ The shape passed to `ResponseCache.context()` / `ResponseCache.applyContext()`.
 
 **bust** (`boolean`): Skip the cache read but still write on completion.
 
-`cache`, `ttl`, and `agentId` are intentionally not overridable per call — they're instance-level concerns that shouldn't vary per request.
+`cache`, `ttl`, and `agentId` are intentionally not overridable per call: they're instance-level concerns that shouldn't vary per request.
 
 ## ResponseCacheKeyInputs
 
@@ -106,9 +106,9 @@ The argument passed to a `key` function (constructor or per-call). All fields co
 
 ## Helper exports
 
-- `buildResponseCacheKey(inputs)` — the deterministic hash used by default. Re-export it to override individual fields while preserving the rest of the standard key shape.
-- `DEFAULT_RESPONSE_CACHE_TTL_SECONDS` — the default `ttl` (`300`).
-- `RESPONSE_CACHE_CONTEXT_KEY` — the `RequestContext` key the static helpers write to. Exposed for advanced cases (e.g. clearing the override mid-pipeline); prefer the helpers.
+- `buildResponseCacheKey(inputs)`: The deterministic hash used by default. Re-export it to override individual fields while preserving the rest of the standard key shape.
+- `DEFAULT_RESPONSE_CACHE_TTL_SECONDS`: The default `ttl` (`300`).
+- `RESPONSE_CACHE_CONTEXT_KEY`: The `RequestContext` key the static helpers write to. Exposed for advanced cases (e.g. clearing the override mid-pipeline). Prefer the helpers.
 
 ## Related
 

package/.docs/reference/processors/system-prompt-scrubber.md

@@ -2,7 +2,7 @@
 
 # SystemPromptScrubber
 
-The `SystemPromptScrubber` is an **output processor** that detects and handles system prompts, instructions, and other revealing information that could introduce security vulnerabilities. This processor helps maintain security by identifying various types of system prompts and providing flexible strategies for handling them, including multiple redaction methods to ensure sensitive information is properly sanitized.
+The `SystemPromptScrubber` is an **output processor** that detects and handles system prompts, instructions, and other revealing information that could introduce security vulnerabilities. This processor helps maintain security by identifying types of system prompts and providing flexible strategies for handling them, including multiple redaction methods to ensure sensitive information is properly sanitized.
 
 ## Usage example
 

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

@@ -94,7 +94,7 @@ export const agent = new Agent({
 
 ### As a per-step input processor (limit multi-step token growth)
 
-When an agent uses tools across multiple steps (e.g. `maxSteps > 1`), each step accumulates conversation history from all previous steps. Use `inputProcessors` to also limit tokens at each step of the agentic loop — the `TokenLimiterProcessor` automatically applies to both the initial input and every subsequent step:
+When an agent uses tools across multiple steps (e.g. `maxSteps > 1`), each step accumulates conversation history from all previous steps. Use `inputProcessors` to also limit tokens at each step of the agentic loop. The `TokenLimiterProcessor` automatically applies to both the initial input and every subsequent step:
 
 ```typescript
 import { Agent } from '@mastra/core/agent'

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

@@ -2,7 +2,7 @@
 
 # ToolSearchProcessor
 
-The `ToolSearchProcessor` is an **input processor** that enables dynamic tool discovery and loading. Instead of providing all tools to the agent upfront, it gives the agent two meta-tools (`search_tools` and `load_tool`) that let it find and load tools on demand. This reduces context token usage when working with large tool libraries.
+The `ToolSearchProcessor` is an **input processor** that enables runtime-defined tool discovery and loading. Instead of providing all tools to the agent upfront, it gives the agent two meta-tools (`search_tools` and `load_tool`) that let it find and load tools on demand. This reduces context token usage when working with large tool libraries.
 
 ## Usage example
 
@@ -91,11 +91,11 @@ Immediately runs TTL cleanup instead of waiting for the scheduled sweep.
 const cleaned = processor.cleanupNow()
 ```
 
-Returns: `number` — the count of threads cleaned up.
+Returns: `number`: the count of threads cleaned up.
 
 ## Request-aware filtering
 
-Use `filter` to apply request-specific policy to dynamic tools. The hook receives the resolved tool ID as `toolName`, the tool, request context, and phase. `toolName` is the ID returned by `search_tools`, which may differ from the key used in the `tools` object.
+Use `filter` to apply request-specific policy to runtime-defined tools. The hook receives the resolved tool ID as `toolName`, the tool, request context, and phase. `toolName` is the ID returned by `search_tools`, which may differ from the key used in the `tools` object.
 
 ```typescript
 import { ToolSearchProcessor } from '@mastra/core/processors'
@@ -120,7 +120,7 @@ The `phase` value describes where the filter is being applied:
 - `load`: Blocks `load_tool` from loading disallowed tools.
 - `active`: Hides already-loaded tools from the current request if they're no longer allowed.
 
-If the hook throws or rejects, `ToolSearchProcessor` treats the tool as disallowed for that request. The hook may run for every matching search candidate, so keep async policy checks cheap or cached. The `search_tools` meta-tool is always available; `load_tool` is available unless `search.autoLoad` is enabled. Tools passed directly through the agent or `processInputStep` remain available unless you filter them outside `ToolSearchProcessor`.
+If the hook throws or rejects, `ToolSearchProcessor` treats the tool as disallowed for that request. The hook may run for every matching search candidate, so keep async policy checks cheap or cached. The `search_tools` meta-tool is always available. `load_tool` is available unless `search.autoLoad` is enabled. Tools passed directly through the agent or `processInputStep` remain available unless you filter them outside `ToolSearchProcessor`.
 
 ## Extended usage example
 
@@ -188,7 +188,7 @@ Every match is activated, so keep `topK` small (for example, `3`) to avoid addin
 
 ## Loaded-tool storage
 
-The `storage` option controls where the set of loaded tools is tracked. The default is `'in-memory'`; the `'context'` store is opt-in.
+The `storage` option controls where the set of loaded tools is tracked. The default is `'in-memory'`. The `'context'` store is opt-in.
 
 ### `'in-memory'` (default)
 
@@ -205,7 +205,7 @@ Use `clearState`, `clearAllState`, `getStateStats`, and `cleanupNow` to inspect
 Loaded state is derived from the conversation messages: a tool is loaded while a `search_tools` or `load_tool` result naming it remains in the messages. This mode:
 
 - Requires no memory configuration.
-- Is restart-safe — the durable record is the persisted message history.
+- Is restart-safe: the durable record is the persisted message history.
 - De-loads a tool automatically once that result is no longer present in the messages.
 
 ```typescript
@@ -219,7 +219,7 @@ const toolSearch = new ToolSearchProcessor({
 
 Loading tools is cache-friendly in both modes: loads are append-only, so the cached prompt prefix stays stable for providers that support prompt caching.
 
-Unloading a tool changes the tool definitions sent to the model, which shifts the cached prefix and causes the next turn to pay a cache write instead of a cache hit. In `'in-memory'` mode this happens when a thread's state is evicted by `ttl`. In `'context'` mode it happens when a tool's discovery result is no longer present in the messages (for example, when older messages are trimmed) — the tool de-loads and the model must search for it again before reuse. This is expected: removing an unused tool trades one cache write for a smaller prefix on later turns.
+Unloading a tool changes the tool definitions sent to the model, which shifts the cached prefix and causes the next turn to pay a cache write instead of a cache hit. In `'in-memory'` mode this happens when a thread's state is evicted by `ttl`. In `'context'` mode it happens when a tool's discovery result is no longer present in the messages (for example, when older messages are trimmed). The tool de-loads, and the model must search for it again before reuse. This is expected: removing an unused tool trades one cache write for a smaller prefix on later turns.
 
 ## Combining with other processors