@mastra/core 1.9.0 → 1.10.0

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

@@ -26,55 +26,63 @@ export const agent = new Agent({
 
 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`.
 
-**enabled?:** (`boolean`): Enable or disable Observational Memory. When omitted from a config object, defaults to \`true\`. Only \`enabled: false\` explicitly disables it. (Default: `true`)
+**enabled** (`boolean`): Enable or disable Observational Memory. When omitted from a config object, defaults to \`true\`. Only \`enabled: false\` explicitly disables it. (Default: `true`)
 
-**model?:** (`string | LanguageModel | DynamicModel | ModelWithRetries[]`): Model for both the Observer and Reflector agents. Sets the model for both at once. Cannot be used together with \`observation.model\` or \`reflection.model\` — an error will be thrown if both are set. When using \`observationalMemory: true\`, defaults to \`google/gemini-2.5-flash\`. When passing a config object, this or \`observation.model\`/\`reflection.model\` must be set. Use \`"default"\` to explicitly use the default model (\`google/gemini-2.5-flash\`). (Default: `'google/gemini-2.5-flash' (when using observationalMemory: true)`)
+**model** (`string | LanguageModel | DynamicModel | ModelWithRetries[]`): Model for both the Observer and Reflector agents. Sets the model for both at once. Cannot be used together with \`observation.model\` or \`reflection.model\` — an error will be thrown if both are set. When using \`observationalMemory: true\`, defaults to \`google/gemini-2.5-flash\`. When passing a config object, this or \`observation.model\`/\`reflection.model\` must be set. Use \`"default"\` to explicitly use the default model (\`google/gemini-2.5-flash\`). (Default: `'google/gemini-2.5-flash' (when using observationalMemory: true)`)
 
-**scope?:** (`'resource' | 'thread'`): Memory scope for observations. \`'thread'\` keeps observations per-thread. \`'resource'\` (experimental) shares observations across all threads for a resource, enabling cross-conversation memory. (Default: `'thread'`)
+**scope** (`'resource' | 'thread'`): Memory scope for observations. \`'thread'\` keeps observations per-thread. \`'resource'\` (experimental) shares observations across all threads for a resource, enabling cross-conversation memory. (Default: `'thread'`)
 
-**shareTokenBudget?:** (`boolean`): Share the token budget between messages and observations. When enabled, the total budget is \`observation.messageTokens + reflection.observationTokens\`. Messages can use more space when observations are small, and vice versa. This maximizes context usage through flexible allocation. \*\*Note:\*\* \`shareTokenBudget\` is not yet compatible with async buffering. You must set \`observation: { bufferTokens: false }\` when using this option (this is a temporary limitation). (Default: `false`)
+**shareTokenBudget** (`boolean`): Share the token budget between messages and observations. When enabled, the total budget is \`observation.messageTokens + reflection.observationTokens\`. Messages can use more space when observations are small, and vice versa. This maximizes context usage through flexible allocation. \`shareTokenBudget\` is not yet compatible with async buffering. You must set \`observation: { bufferTokens: false }\` when using this option (this is a temporary limitation). (Default: `false`)
 
-**observation?:** (`ObservationalMemoryObservationConfig`): Configuration for the observation step. Controls when the Observer agent runs and how it behaves.
+**observation** (`ObservationalMemoryObservationConfig`): Configuration for the observation step. Controls when the Observer agent runs and how it behaves.
 
-**reflection?:** (`ObservationalMemoryReflectionConfig`): Configuration for the reflection step. Controls when the Reflector agent runs and how it behaves.
+**observation.model** (`string | LanguageModel | DynamicModel | ModelWithRetries[]`): Model for the Observer agent. Cannot be set if a top-level \`model\` is also provided. If neither this nor the top-level \`model\` is set, falls back to \`reflection.model\`.
 
-### Observation config
+**observation.instruction** (`string`): Custom instruction appended to the Observer's system prompt. Use this to customize what the Observer focuses on, such as domain-specific preferences or priorities.
 
-**model?:** (`string | LanguageModel | DynamicModel | ModelWithRetries[]`): Model for the Observer agent. Cannot be set if a top-level \`model\` is also provided. If neither this nor the top-level \`model\` is set, falls back to \`reflection.model\`.
+**observation.messageTokens** (`number`): Token count of unobserved messages that triggers observation. When unobserved message tokens exceed this threshold, the Observer agent is called.
 
-**instruction?:** (`string`): Custom instruction appended to the Observer's system prompt. Use this to customize what the Observer focuses on, such as domain-specific preferences or priorities.
+**observation.maxTokensPerBatch** (`number`): Maximum tokens per batch when observing multiple threads in resource scope. Threads are chunked into batches of this size and processed in parallel. Lower values mean more parallelism but more API calls.
 
-**messageTokens?:** (`number`): Token count of unobserved messages that triggers observation. When unobserved message tokens exceed this threshold, the Observer agent is called. (Default: `30000`)
+**observation.modelSettings** (`ObservationalMemoryModelSettings`): Model settings for the Observer agent.
 
-**maxTokensPerBatch?:** (`number`): Maximum tokens per batch when observing multiple threads in resource scope. Threads are chunked into batches of this size and processed in parallel. Lower values mean more parallelism but more API calls. (Default: `10000`)
+**observation.modelSettings.temperature** (`number`): Temperature for generation. Lower values produce more consistent output.
 
-**modelSettings?:** (`ObservationalMemoryModelSettings`): Model settings for the Observer agent. (Default: `{ temperature: 0.3, maxOutputTokens: 100_000 }`)
+**observation.modelSettings.maxOutputTokens** (`number`): Maximum output tokens. Set high to prevent truncation of observations.
 
-**bufferTokens?:** (`number | false`): Token interval for async background observation buffering. Can be an absolute token count (e.g. \`5000\`) or a fraction of \`messageTokens\` (e.g. \`0.25\` = buffer every 25% of threshold). When set, observations run in the background at this interval, storing results in a buffer. When the main \`messageTokens\` threshold is reached, buffered observations activate instantly without a blocking LLM call. Must resolve to less than \`messageTokens\`. Set to \`false\` to explicitly disable all async buffering (both observation and reflection). (Default: `0.2`)
+**observation.bufferTokens** (`number | false`): Token interval for async background observation buffering. Can be an absolute token count (e.g. \`5000\`) or a fraction of \`messageTokens\` (e.g. \`0.25\` = buffer every 25% of threshold). When set, observations run in the background at this interval, storing results in a buffer. When the main \`messageTokens\` threshold is reached, buffered observations activate instantly without a blocking LLM call. Must resolve to less than \`messageTokens\`. Set to \`false\` to explicitly disable all async buffering (both observation and reflection).
 
-**bufferActivation?:** (`number`): Controls how much of the message window to retain after activation. Accepts a ratio (0-1) or an absolute token count (≥ 1000). For example, \`0.8\` means: activate enough buffers to remove 80% of \`messageTokens\` and leave 20% as active message history. An absolute token count like \`4000\` targets a goal of keeping \~4k message tokens remaining after activation. Higher values remove more message history per activation when using a ratio. Higher values keep more message history when using a token count. (Default: `0.8`)
+**observation.bufferActivation** (`number`): Controls how much of the message window to retain after activation. Accepts a ratio (0-1) or an absolute token count (≥ 1000). For example, \`0.8\` means: activate enough buffers to remove 80% of \`messageTokens\` and leave 20% as active message history. An absolute token count like \`4000\` targets a goal of keeping \~4k message tokens remaining after activation. Higher values remove more message history per activation when using a ratio. Higher values keep more message history when using a token count.
 
-**blockAfter?:** (`number`): Token threshold above which synchronous (blocking) observation is forced. Between \`messageTokens\` and \`blockAfter\`, only async buffering/activation is used. Above \`blockAfter\`, a synchronous observation runs as a last resort, while buffered activation still preserves a minimum remaining context (min(1000, retention floor)). Accepts a multiplier (1 < value < 2, multiplied by \`messageTokens\`) or an absolute token count (≥ 2, must be greater than \`messageTokens\`). Only relevant when \`bufferTokens\` is set. Defaults to \`1.2\` when async buffering is enabled. (Default: `1.2 (when bufferTokens is set)`)
+**observation.blockAfter** (`number`): Token threshold above which synchronous (blocking) observation is forced. Between \`messageTokens\` and \`blockAfter\`, only async buffering/activation is used. Above \`blockAfter\`, a synchronous observation runs as a last resort, while buffered activation still preserves a minimum remaining context (min(1000, retention floor)). Accepts a multiplier (1 < value < 2, multiplied by \`messageTokens\`) or an absolute token count (≥ 2, must be greater than \`messageTokens\`). Only relevant when \`bufferTokens\` is set. Defaults to \`1.2\` when async buffering is enabled.
 
-### Reflection config
+**reflection** (`ObservationalMemoryReflectionConfig`): Configuration for the reflection step. Controls when the Reflector agent runs and how it behaves.
 
-**model?:** (`string | LanguageModel | DynamicModel | ModelWithRetries[]`): Model for the Reflector agent. Cannot be set if a top-level \`model\` is also provided. If neither this nor the top-level \`model\` is set, falls back to \`observation.model\`.
+**reflection.model** (`string | LanguageModel | DynamicModel | ModelWithRetries[]`): Model for the Reflector agent. Cannot be set if a top-level \`model\` is also provided. If neither this nor the top-level \`model\` is set, falls back to \`observation.model\`.
 
-**instruction?:** (`string`): Custom instruction appended to the Reflector's system prompt. Use this to customize how the Reflector consolidates observations, such as prioritizing certain types of information.
+**reflection.instruction** (`string`): Custom instruction appended to the Reflector's system prompt. Use this to customize how the Reflector consolidates observations, such as prioritizing certain types of information.
 
-**observationTokens?:** (`number`): Token count of observations that triggers reflection. When observation tokens exceed this threshold, the Reflector agent is called to condense them. (Default: `40000`)
+**reflection.observationTokens** (`number`): Token count of observations that triggers reflection. When observation tokens exceed this threshold, the Reflector agent is called to condense them.
 
-**modelSettings?:** (`ObservationalMemoryModelSettings`): Model settings for the Reflector agent. (Default: `{ temperature: 0, maxOutputTokens: 100_000 }`)
+**reflection.modelSettings** (`ObservationalMemoryModelSettings`): Model settings for the Reflector agent.
 
-**bufferActivation?:** (`number`): Ratio (0-1) controlling when async reflection buffering starts. When observation tokens reach \`observationTokens \* bufferActivation\`, reflection runs in the background. On activation at the full threshold, the buffered reflection replaces the observations it covers, preserving any new observations appended after that range. (Default: `0.5`)
+**reflection.modelSettings.temperature** (`number`): Temperature for generation. Lower values produce more consistent output.
 
-**blockAfter?:** (`number`): Token threshold above which synchronous (blocking) reflection is forced. Between \`observationTokens\` and \`blockAfter\`, only async buffering/activation is used. Above \`blockAfter\`, a synchronous reflection runs as a last resort. Accepts a multiplier (1 < value < 2, multiplied by \`observationTokens\`) or an absolute token count (≥ 2, must be greater than \`observationTokens\`). Only relevant when \`bufferActivation\` is set. Defaults to \`1.2\` when async reflection is enabled. (Default: `1.2 (when bufferActivation is set)`)
+**reflection.modelSettings.maxOutputTokens** (`number`): Maximum output tokens. Set high to prevent truncation of observations.
 
-### Model settings
+**reflection.bufferActivation** (`number`): Ratio (0-1) controlling when async reflection buffering starts. When observation tokens reach \`observationTokens \* bufferActivation\`, reflection runs in the background. On activation at the full threshold, the buffered reflection replaces the observations it covers, preserving any new observations appended after that range.
 
-**temperature?:** (`number`): Temperature for generation. Lower values produce more consistent output. (Default: `0.3`)
+**reflection.blockAfter** (`number`): Token threshold above which synchronous (blocking) reflection is forced. Between \`observationTokens\` and \`blockAfter\`, only async buffering/activation is used. Above \`blockAfter\`, a synchronous reflection runs as a last resort. Accepts a multiplier (1 < value < 2, multiplied by \`observationTokens\`) or an absolute token count (≥ 2, must be greater than \`observationTokens\`). Only relevant when \`bufferActivation\` is set. Defaults to \`1.2\` when async reflection is enabled.
 
-**maxOutputTokens?:** (`number`): Maximum output tokens. Set high to prevent truncation of observations. (Default: `100000`)
+### Token estimate metadata cache
+
+OM persists token payload estimates so repeated counting can reuse prior tiktoken work.
+
+- Part-level cache: `part.providerMetadata.mastra`.
+- String-content fallback cache: message-level metadata when no parts exist.
+- Cache entries are ignored and recomputed if cache version/tokenizer source does not match.
+- Per-message and per-conversation overhead are always recomputed at runtime and are not cached.
+- `data-*` and `reasoning` parts are skipped and do not receive cache entries.
 
 ## Examples
 
@@ -357,161 +365,161 @@ if (inputObservationTokens > 0) {
 
 Emitted when the Observer or Reflector agent begins processing.
 
-**cycleId:** (`string`): Unique ID for this cycle — shared between start/end/failed markers.
+**cycleId** (`string`): Unique ID for this cycle — shared between start/end/failed markers.
 
-**operationType:** (`'observation' | 'reflection'`): Whether this is an observation or reflection operation.
+**operationType** (`'observation' | 'reflection'`): Whether this is an observation or reflection operation.
 
-**startedAt:** (`string`): ISO timestamp when processing started.
+**startedAt** (`string`): ISO timestamp when processing started.
 
-**tokensToObserve:** (`number`): Message tokens (input) being processed in this batch.
+**tokensToObserve** (`number`): Message tokens (input) being processed in this batch.
 
-**recordId:** (`string`): The OM record ID.
+**recordId** (`string`): The OM record ID.
 
-**threadId:** (`string`): This thread's ID.
+**threadId** (`string`): This thread's ID.
 
-**threadIds:** (`string[]`): All thread IDs in this batch (for resource-scoped).
+**threadIds** (`string[]`): All thread IDs in this batch (for resource-scoped).
 
-**config:** (`ObservationMarkerConfig`): Snapshot of \`messageTokens\`, \`observationTokens\`, and \`scope\` at observation time.
+**config** (`ObservationMarkerConfig`): Snapshot of \`messageTokens\`, \`observationTokens\`, and \`scope\` at observation time.
 
 ### `data-om-observation-end`
 
 Emitted when observation or reflection completes successfully.
 
-**cycleId:** (`string`): Matches the corresponding \`start\` marker.
+**cycleId** (`string`): Matches the corresponding \`start\` marker.
 
-**operationType:** (`'observation' | 'reflection'`): Type of operation that completed.
+**operationType** (`'observation' | 'reflection'`): Type of operation that completed.
 
-**completedAt:** (`string`): ISO timestamp when processing completed.
+**completedAt** (`string`): ISO timestamp when processing completed.
 
-**durationMs:** (`number`): Duration in milliseconds.
+**durationMs** (`number`): Duration in milliseconds.
 
-**tokensObserved:** (`number`): Message tokens (input) that were processed.
+**tokensObserved** (`number`): Message tokens (input) that were processed.
 
-**observationTokens:** (`number`): Resulting observation tokens (output) after the Observer compressed them.
+**observationTokens** (`number`): Resulting observation tokens (output) after the Observer compressed them.
 
-**observations?:** (`string`): The generated observations text.
+**observations** (`string`): The generated observations text.
 
-**currentTask?:** (`string`): Current task extracted by the Observer.
+**currentTask** (`string`): Current task extracted by the Observer.
 
-**suggestedResponse?:** (`string`): Suggested response extracted by the Observer.
+**suggestedResponse** (`string`): Suggested response extracted by the Observer.
 
-**recordId:** (`string`): The OM record ID.
+**recordId** (`string`): The OM record ID.
 
-**threadId:** (`string`): This thread's ID.
+**threadId** (`string`): This thread's ID.
 
 ### `data-om-observation-failed`
 
 Emitted when observation or reflection fails. The system falls back to synchronous processing.
 
-**cycleId:** (`string`): Matches the corresponding \`start\` marker.
+**cycleId** (`string`): Matches the corresponding \`start\` marker.
 
-**operationType:** (`'observation' | 'reflection'`): Type of operation that failed.
+**operationType** (`'observation' | 'reflection'`): Type of operation that failed.
 
-**failedAt:** (`string`): ISO timestamp when the failure occurred.
+**failedAt** (`string`): ISO timestamp when the failure occurred.
 
-**durationMs:** (`number`): Duration until failure in milliseconds.
+**durationMs** (`number`): Duration until failure in milliseconds.
 
-**tokensAttempted:** (`number`): Message tokens (input) that were attempted.
+**tokensAttempted** (`number`): Message tokens (input) that were attempted.
 
-**error:** (`string`): Error message.
+**error** (`string`): Error message.
 
-**observations?:** (`string`): Any partial content available for display.
+**observations** (`string`): Any partial content available for display.
 
-**recordId:** (`string`): The OM record ID.
+**recordId** (`string`): The OM record ID.
 
-**threadId:** (`string`): This thread's ID.
+**threadId** (`string`): This thread's ID.
 
 ### `data-om-buffering-start`
 
 Emitted when async buffering begins in the background. Buffering pre-computes observations or reflections before the main threshold is reached.
 
-**cycleId:** (`string`): Unique ID for this buffering cycle.
+**cycleId** (`string`): Unique ID for this buffering cycle.
 
-**operationType:** (`'observation' | 'reflection'`): Type of operation being buffered.
+**operationType** (`'observation' | 'reflection'`): Type of operation being buffered.
 
-**startedAt:** (`string`): ISO timestamp when buffering started.
+**startedAt** (`string`): ISO timestamp when buffering started.
 
-**tokensToBuffer:** (`number`): Message tokens (input) being buffered in this cycle.
+**tokensToBuffer** (`number`): Message tokens (input) being buffered in this cycle.
 
-**recordId:** (`string`): The OM record ID.
+**recordId** (`string`): The OM record ID.
 
-**threadId:** (`string`): This thread's ID.
+**threadId** (`string`): This thread's ID.
 
-**threadIds:** (`string[]`): All thread IDs being buffered (for resource-scoped).
+**threadIds** (`string[]`): All thread IDs being buffered (for resource-scoped).
 
-**config:** (`ObservationMarkerConfig`): Snapshot of config at buffering time.
+**config** (`ObservationMarkerConfig`): Snapshot of config at buffering time.
 
 ### `data-om-buffering-end`
 
 Emitted when async buffering completes. The content is stored but not yet activated in the main context.
 
-**cycleId:** (`string`): Matches the corresponding \`buffering-start\` marker.
+**cycleId** (`string`): Matches the corresponding \`buffering-start\` marker.
 
-**operationType:** (`'observation' | 'reflection'`): Type of operation that was buffered.
+**operationType** (`'observation' | 'reflection'`): Type of operation that was buffered.
 
-**completedAt:** (`string`): ISO timestamp when buffering completed.
+**completedAt** (`string`): ISO timestamp when buffering completed.
 
-**durationMs:** (`number`): Duration in milliseconds.
+**durationMs** (`number`): Duration in milliseconds.
 
-**tokensBuffered:** (`number`): Message tokens (input) that were buffered.
+**tokensBuffered** (`number`): Message tokens (input) that were buffered.
 
-**bufferedTokens:** (`number`): Observation tokens (output) after the Observer compressed them.
+**bufferedTokens** (`number`): Observation tokens (output) after the Observer compressed them.
 
-**observations?:** (`string`): The buffered content.
+**observations** (`string`): The buffered content.
 
-**recordId:** (`string`): The OM record ID.
+**recordId** (`string`): The OM record ID.
 
-**threadId:** (`string`): This thread's ID.
+**threadId** (`string`): This thread's ID.
 
 ### `data-om-buffering-failed`
 
 Emitted when async buffering fails. The system falls back to synchronous processing when the threshold is reached.
 
-**cycleId:** (`string`): Matches the corresponding \`buffering-start\` marker.
+**cycleId** (`string`): Matches the corresponding \`buffering-start\` marker.
 
-**operationType:** (`'observation' | 'reflection'`): Type of operation that failed.
+**operationType** (`'observation' | 'reflection'`): Type of operation that failed.
 
-**failedAt:** (`string`): ISO timestamp when the failure occurred.
+**failedAt** (`string`): ISO timestamp when the failure occurred.
 
-**durationMs:** (`number`): Duration until failure in milliseconds.
+**durationMs** (`number`): Duration until failure in milliseconds.
 
-**tokensAttempted:** (`number`): Message tokens (input) that were attempted to buffer.
+**tokensAttempted** (`number`): Message tokens (input) that were attempted to buffer.
 
-**error:** (`string`): Error message.
+**error** (`string`): Error message.
 
-**observations?:** (`string`): Any partial content.
+**observations** (`string`): Any partial content.
 
-**recordId:** (`string`): The OM record ID.
+**recordId** (`string`): The OM record ID.
 
-**threadId:** (`string`): This thread's ID.
+**threadId** (`string`): This thread's ID.
 
 ### `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.
 
-**cycleId:** (`string`): Unique ID for this activation event.
+**cycleId** (`string`): Unique ID for this activation event.
 
-**operationType:** (`'observation' | 'reflection'`): Type of content activated.
+**operationType** (`'observation' | 'reflection'`): Type of content activated.
 
-**activatedAt:** (`string`): ISO timestamp when activation occurred.
+**activatedAt** (`string`): ISO timestamp when activation occurred.
 
-**chunksActivated:** (`number`): Number of buffered chunks activated.
+**chunksActivated** (`number`): Number of buffered chunks activated.
 
-**tokensActivated:** (`number`): Message tokens (input) from activated chunks. For observation activation, these are removed from the message window. For reflection activation, this is the observation tokens that were compressed.
+**tokensActivated** (`number`): Message tokens (input) from activated chunks. For observation activation, these are removed from the message window. For reflection activation, this is the observation tokens that were compressed.
 
-**observationTokens:** (`number`): Resulting observation tokens after activation.
+**observationTokens** (`number`): Resulting observation tokens after activation.
 
-**messagesActivated:** (`number`): Number of messages that were observed via activation.
+**messagesActivated** (`number`): Number of messages that were observed via activation.
 
-**generationCount:** (`number`): Current reflection generation count.
+**generationCount** (`number`): Current reflection generation count.
 
-**observations?:** (`string`): The activated observations text.
+**observations** (`string`): The activated observations text.
 
-**recordId:** (`string`): The OM record ID.
+**recordId** (`string`): The OM record ID.
 
-**threadId:** (`string`): This thread's ID.
+**threadId** (`string`): This thread's ID.
 
-**config:** (`ObservationMarkerConfig`): Snapshot of config at activation time.
+**config** (`ObservationMarkerConfig`): Snapshot of config at activation time.
 
 ## Standalone usage
 
@@ -552,11 +560,11 @@ export const agent = new Agent({
 
 The standalone `ObservationalMemory` class accepts all the same options as the `observationalMemory` config object above, plus the following:
 
-**storage:** (`MemoryStorage`): Storage adapter for persisting observations. Must be a MemoryStorage instance (from \`MastraStorage.stores.memory\`).
+**storage** (`MemoryStorage`): Storage adapter for persisting observations. Must be a MemoryStorage instance (from \`MastraStorage.stores.memory\`).
 
-**onDebugEvent?:** (`(event: ObservationDebugEvent) => void`): Debug callback for observation events. Called whenever observation-related events occur. Useful for debugging and understanding the observation flow.
+**onDebugEvent** (`(event: ObservationDebugEvent) => void`): Debug callback for observation events. Called whenever observation-related events occur. Useful for debugging and understanding the observation flow.
 
-**obscureThreadIds?:** (`boolean`): When enabled, thread IDs are hashed before being included in observation context. This prevents the LLM from recognizing patterns in thread identifiers. Automatically enabled when using resource scope through the Memory class. (Default: `false`)
+**obscureThreadIds** (`boolean`): When enabled, thread IDs are hashed before being included in observation context. This prevents the LLM from recognizing patterns in thread identifiers. Automatically enabled when using resource scope through the Memory class. (Default: `false`)
 
 ### Related
 

package/dist/docs/references/reference-observability-tracing-configuration.md

@@ -10,6 +10,12 @@ interface ObservabilityRegistryConfig {
 }
 ```
 
+**default** (`{ enabled?: boolean }`): Enable default configuration with DefaultExporter and CloudExporter
+
+**configs** (`Record<string, Omit<ObservabilityInstanceConfig, 'name'> | ObservabilityInstance>`): Named observability instance configurations or pre-instantiated instances
+
+**configSelector** (`ConfigSelector`): Runtime configuration selector function
+
 ## ObservabilityInstanceConfig
 
 ```typescript
@@ -25,18 +31,29 @@ interface ObservabilityInstanceConfig {
 }
 ```
 
-## SerializationOptions
+**name** (`string`): Configuration identifier
 
-Options for controlling how span data is serialized before export. Use these to customize truncation limits for large payloads.
+**serviceName** (`string`): Service name in traces
 
-```typescript
-interface SerializationOptions {
-  maxStringLength?: number
-  maxDepth?: number
-  maxArrayLength?: number
-  maxObjectKeys?: number
-}
-```
+**sampling** (`SamplingStrategy`): Sampling configuration (defaults to ALWAYS)
+
+**exporters** (`ObservabilityExporter[]`): Trace data exporters
+
+**spanOutputProcessors** (`SpanOutputProcessor[]`): Span output processors
+
+**includeInternalSpans** (`boolean`): Include spans internal to Mastra operations
+
+**requestContextKeys** (`string[]`): RequestContext keys to extract as metadata (supports dot notation)
+
+**serializationOptions** (`SerializationOptions`): Options for controlling serialization of span data (input/output/attributes)
+
+**serializationOptions.maxStringLength** (`number`): Maximum length for string values (default: 1024)
+
+**serializationOptions.maxDepth** (`number`): Maximum depth for nested objects (default: 6)
+
+**serializationOptions.maxArrayLength** (`number`): Maximum number of items in arrays (default: 50)
+
+**serializationOptions.maxObjectKeys** (`number`): Maximum number of keys in objects (default: 50)
 
 ## SamplingStrategy
 

package/dist/docs/references/reference-observability-tracing-exporters-console-exporter.md

@@ -8,14 +8,11 @@ Outputs trace events to the console for debugging and development.
 new ConsoleExporter(config?: BaseExporterConfig)
 ```
 
-## BaseExporterConfig
+**config** (`BaseExporterConfig`): Configuration options
 
-```typescript
-interface BaseExporterConfig {
-  logger?: IMastraLogger
-  logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error'
-}
-```
+**config.logger** (`IMastraLogger`): Logger instance (falls back to ConsoleLogger with INFO level)
+
+**config.logLevel** (`LogLevel | 'debug' | 'info' | 'warn' | 'error'`): Log level for the exporter (default: INFO)
 
 ## Properties
 

package/dist/docs/references/reference-processors-batch-parts-processor.md

@@ -16,25 +16,23 @@ const processor = new BatchPartsProcessor({
 
 ## Constructor parameters
 
-**options?:** (`Options`): Configuration options for batching stream parts
+**options** (`Options`): Configuration options for batching stream parts
 
-### Options
+**options.batchSize** (`number`): Number of parts to batch together before emitting
 
-**batchSize?:** (`number`): Number of parts to batch together before emitting
+**options.maxWaitTime** (`number`): Maximum time to wait before emitting a batch (in milliseconds). If set, will emit the current batch even if it hasn't reached batchSize
 
-**maxWaitTime?:** (`number`): Maximum time to wait before emitting a batch (in milliseconds). If set, will emit the current batch even if it hasn't reached batchSize
-
-**emitOnNonText?:** (`boolean`): Whether to emit immediately when a non-text part is encountered
+**options.emitOnNonText** (`boolean`): Whether to emit immediately when a non-text part is encountered
 
 ## Returns
 
-**id:** (`string`): Processor identifier set to 'batch-parts'
+**id** (`string`): Processor identifier set to 'batch-parts'
 
-**name?:** (`string`): Optional processor display name
+**name** (`string`): Optional processor display name
 
-**processOutputStream:** (`(args: { part: ChunkType; streamParts: ChunkType[]; state: Record<string, any>; abort: (reason?: string) => never }) => Promise<ChunkType | null>`): Processes streaming output parts to batch them together
+**processOutputStream** (`(args: { part: ChunkType; streamParts: ChunkType[]; state: Record<string, any>; abort: (reason?: string) => never }) => Promise<ChunkType | null>`): Processes streaming output parts to batch them together
 
-**flush:** (`(state?: BatchPartsState) => ChunkType | null`): Force flush any remaining batched parts when the stream ends
+**flush** (`(state?: BatchPartsState) => ChunkType | null`): Force flush any remaining batched parts when the stream ends
 
 ## Extended usage example
 

package/dist/docs/references/reference-processors-language-detector.md

@@ -17,37 +17,35 @@ const processor = new LanguageDetector({
 
 ## Constructor parameters
 
-**options:** (`Options`): Configuration options for language detection and translation
+**options** (`Options`): Configuration options for language detection and translation
 
-### Options
+**options.model** (`MastraModelConfig`): Model configuration for the detection/translation agent
 
-**model:** (`MastraModelConfig`): Model configuration for the detection/translation agent
+**options.targetLanguages** (`string[]`): Target language(s) for the project. If content is detected in a different language, it may be translated. Can be language name ('English') or ISO code ('en')
 
-**targetLanguages?:** (`string[]`): Target language(s) for the project. If content is detected in a different language, it may be translated. Can be language name ('English') or ISO code ('en')
+**options.threshold** (`number`): Confidence threshold for language detection (0-1). Only process when detection confidence exceeds this threshold
 
-**threshold?:** (`number`): Confidence threshold for language detection (0-1). Only process when detection confidence exceeds this threshold
+**options.strategy** (`'detect' | 'translate' | 'block' | 'warn'`): Strategy when non-target language is detected: 'detect' only detects language, 'translate' automatically translates to target language, 'block' rejects content not in target language, 'warn' logs warning but allows through
 
-**strategy?:** (`'detect' | 'translate' | 'block' | 'warn'`): Strategy when non-target language is detected: 'detect' only detects language, 'translate' automatically translates to target language, 'block' rejects content not in target language, 'warn' logs warning but allows through
+**options.preserveOriginal** (`boolean`): Whether to preserve original content in message metadata. Useful for audit trails and debugging
 
-**preserveOriginal?:** (`boolean`): Whether to preserve original content in message metadata. Useful for audit trails and debugging
+**options.instructions** (`string`): Custom detection instructions for the agent. If not provided, uses default instructions
 
-**instructions?:** (`string`): Custom detection instructions for the agent. If not provided, uses default instructions
+**options.minTextLength** (`number`): Minimum text length to perform detection. Short text is often unreliable for language detection
 
-**minTextLength?:** (`number`): Minimum text length to perform detection. Short text is often unreliable for language detection
+**options.includeDetectionDetails** (`boolean`): Whether to include detailed detection info in logs
 
-**includeDetectionDetails?:** (`boolean`): Whether to include detailed detection info in logs
+**options.translationQuality** (`'speed' | 'quality' | 'balanced'`): Translation quality preference: 'speed' prioritizes fast translation, 'quality' prioritizes accuracy, 'balanced' balances between speed and quality
 
-**translationQuality?:** (`'speed' | 'quality' | 'balanced'`): Translation quality preference: 'speed' prioritizes fast translation, 'quality' prioritizes accuracy, 'balanced' balances between speed and quality
-
-**providerOptions?:** (`ProviderOptions`): Provider-specific options passed to the internal detection agent. Use this to control model behavior like reasoning effort for thinking models (e.g., \`{ openai: { reasoningEffort: 'low' } }\`)
+**options.providerOptions** (`ProviderOptions`): Provider-specific options passed to the internal detection agent. Use this to control model behavior like reasoning effort for thinking models (e.g., \`{ openai: { reasoningEffort: 'low' } }\`)
 
 ## Returns
 
-**id:** (`string`): Processor identifier set to 'language-detector'
+**id** (`string`): Processor identifier set to 'language-detector'
 
-**name?:** (`string`): Optional processor display name
+**name** (`string`): Optional processor display name
 
-**processInput:** (`(args: { messages: MastraDBMessage[]; abort: (reason?: string) => never; tracingContext?: TracingContext }) => Promise<MastraDBMessage[]>`): Processes input messages to detect language and optionally translate content before sending to LLM
+**processInput** (`(args: { messages: MastraDBMessage[]; abort: (reason?: string) => never; tracingContext?: TracingContext }) => Promise<MastraDBMessage[]>`): Processes input messages to detect language and optionally translate content before sending to LLM
 
 ## Extended usage example
 

package/dist/docs/references/reference-processors-message-history-processor.md

@@ -15,23 +15,21 @@ const processor = new MessageHistory({
 
 ## Constructor parameters
 
-**options:** (`MessageHistoryOptions`): Configuration options for the message history processor
+**options** (`MessageHistoryOptions`): Configuration options for the message history processor
 
-### Options
+**options.storage** (`MemoryStorage`): Storage instance for retrieving and persisting messages
 
-**storage:** (`MemoryStorage`): Storage instance for retrieving and persisting messages
-
-**lastMessages?:** (`number`): Maximum number of historical messages to retrieve. If not specified, retrieves all messages
+**options.lastMessages** (`number`): Maximum number of historical messages to retrieve. If not specified, retrieves all messages
 
 ## Returns
 
-**id:** (`string`): Processor identifier set to 'message-history'
+**id** (`string`): Processor identifier set to 'message-history'
 
-**name:** (`string`): Processor display name set to 'MessageHistory'
+**name** (`string`): Processor display name set to 'MessageHistory'
 
-**processInput:** (`(args: { messages: MastraDBMessage[]; messageList: MessageList; abort: (reason?: string) => never; tracingContext?: TracingContext; requestContext?: RequestContext }) => Promise<MessageList | MastraDBMessage[]>`): Fetches historical messages from storage and adds them to the message list
+**processInput** (`(args: { messages: MastraDBMessage[]; messageList: MessageList; abort: (reason?: string) => never; tracingContext?: TracingContext; requestContext?: RequestContext }) => Promise<MessageList | MastraDBMessage[]>`): Fetches historical messages from storage and adds them to the message list
 
-**processOutputResult:** (`(args: { messages: MastraDBMessage[]; messageList: MessageList; abort: (reason?: string) => never; tracingContext?: TracingContext; requestContext?: RequestContext }) => Promise<MessageList>`): Persists new messages (user input and assistant response) to storage, excluding system messages
+**processOutputResult** (`(args: { messages: MastraDBMessage[]; messageList: MessageList; abort: (reason?: string) => never; tracingContext?: TracingContext; requestContext?: RequestContext }) => Promise<MessageList>`): Persists new messages (user input and assistant response) to storage, excluding system messages
 
 ## Extended usage example
 

package/dist/docs/references/reference-processors-moderation-processor.md

@@ -17,35 +17,33 @@ const processor = new ModerationProcessor({
 
 ## Constructor parameters
 
-**options:** (`Options`): Configuration options for content moderation
+**options** (`Options`): Configuration options for content moderation
 
-### Options
+**options.model** (`MastraModelConfig`): Model configuration for the moderation agent
 
-**model:** (`MastraModelConfig`): Model configuration for the moderation agent
+**options.categories** (`string[]`): Categories to check for moderation. If not specified, uses default OpenAI categories
 
-**categories?:** (`string[]`): Categories to check for moderation. If not specified, uses default OpenAI categories
+**options.threshold** (`number`): Confidence threshold for flagging (0-1). Content is flagged if any category score exceeds this threshold
 
-**threshold?:** (`number`): Confidence threshold for flagging (0-1). Content is flagged if any category score exceeds this threshold
+**options.strategy** (`'block' | 'warn' | 'filter'`): Strategy when content is flagged: 'block' rejects with error, 'warn' logs warning but allows through, 'filter' removes flagged messages
 
-**strategy?:** (`'block' | 'warn' | 'filter'`): Strategy when content is flagged: 'block' rejects with error, 'warn' logs warning but allows through, 'filter' removes flagged messages
+**options.instructions** (`string`): Custom moderation instructions for the agent. If not provided, uses default instructions based on categories
 
-**instructions?:** (`string`): Custom moderation instructions for the agent. If not provided, uses default instructions based on categories
+**options.includeScores** (`boolean`): Whether to include confidence scores in logs. Useful for tuning thresholds and debugging
 
-**includeScores?:** (`boolean`): Whether to include confidence scores in logs. Useful for tuning thresholds and debugging
+**options.chunkWindow** (`number`): Number of previous chunks to include for context when moderating stream chunks. If set to 1, includes the previous part, etc.
 
-**chunkWindow?:** (`number`): Number of previous chunks to include for context when moderating stream chunks. If set to 1, includes the previous part, etc.
-
-**providerOptions?:** (`ProviderOptions`): Provider-specific options passed to the internal moderation agent. Use this to control model behavior like reasoning effort for thinking models (e.g., \`{ openai: { reasoningEffort: 'low' } }\`)
+**options.providerOptions** (`ProviderOptions`): Provider-specific options passed to the internal moderation agent. Use this to control model behavior like reasoning effort for thinking models (e.g., \`{ openai: { reasoningEffort: 'low' } }\`)
 
 ## Returns
 
-**id:** (`string`): Processor identifier set to 'moderation'
+**id** (`string`): Processor identifier set to 'moderation'
 
-**name?:** (`string`): Optional processor display name
+**name** (`string`): Optional processor display name
 
-**processInput:** (`(args: { messages: MastraDBMessage[]; abort: (reason?: string) => never; tracingContext?: TracingContext }) => Promise<MastraDBMessage[]>`): Processes input messages to moderate content before sending to LLM
+**processInput** (`(args: { messages: MastraDBMessage[]; abort: (reason?: string) => never; tracingContext?: TracingContext }) => Promise<MastraDBMessage[]>`): Processes input messages to moderate content before sending to LLM
 
-**processOutputStream:** (`(args: { part: ChunkType; streamParts: ChunkType[]; state: Record<string, any>; abort: (reason?: string) => never; tracingContext?: TracingContext }) => Promise<ChunkType | null | undefined>`): Processes streaming output parts to moderate content during streaming
+**processOutputStream** (`(args: { part: ChunkType; streamParts: ChunkType[]; state: Record<string, any>; abort: (reason?: string) => never; tracingContext?: TracingContext }) => Promise<ChunkType | null | undefined>`): Processes streaming output parts to moderate content during streaming
 
 ## Extended usage example