@mastra/memory 1.22.1 → 1.22.2-alpha.0

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

@@ -33,35 +33,35 @@ Observer input is multimodal-aware. OM keeps text placeholders like `[Image #1:
 
 OM performs thresholding with fast local token estimation. Text uses `tokenx`, and image-like inputs use provider-aware heuristics plus deterministic fallbacks when metadata is incomplete.
 
-**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 | ModelByInputTokens | 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 | ModelByInputTokens | 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'`)
 
-**activateAfterIdle** (`number | string | false | "auto"`): Time before buffered observations are forced to activate after inactivity, even before \`observation.messageTokens\` is reached. Accepts a numeric millisecond value such as \`300\_000\`, duration strings like \`"5m"\` or \`"1hr"\`, \`"auto"\` for a provider-aware prompt cache TTL, or \`false\` to disable inherited observation idle activation. Reflections do not inherit this setting. Use \`reflection.activateAfterIdle\` to opt reflections into idle activation.
+**activateAfterIdle** (`number | string | false | "auto"`): Time before buffered observations are forced to activate after inactivity, even before observation.messageTokens is reached. Accepts a numeric millisecond value such as 300\_000, duration strings like "5m" or "1hr", "auto" for a provider-aware prompt cache TTL, or false to disable inherited observation idle activation. Reflections do not inherit this setting. Use reflection.activateAfterIdle to opt reflections into idle activation.
 
-**activateOnProviderChange** (`boolean`): Force buffered observations to activate when the actor provider or model changes. Reflections do not inherit this setting. Use \`reflection.activateOnProviderChange\` to opt reflections into provider-change activation. (Default: `false`)
+**activateOnProviderChange** (`boolean`): Force buffered observations to activate when the actor provider or model changes. Reflections do not inherit this setting. Use reflection.activateOnProviderChange to opt reflections into provider-change activation. (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`)
+**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`)
 
 **temporalMarkers** (`boolean`): Insert temporal-gap reminder markers before new user messages when the previous message in the thread is at least 10 minutes older. The marker is persisted in memory, emitted as an inline reminder event so clients can render it specially, and shown to the observer so it can anchor observations to when events occurred. (Default: `false`)
 
-**retrieval** (`boolean | { vector?: boolean; scope?: 'thread' | 'resource' }`): Enable retrieval-mode observation groups as durable pointers to raw message history. \`true\` enables cross-thread browsing by default. \`{ vector: true }\` also enables semantic search using Memory's vector store and embedder. \`{ scope: 'thread' }\` restricts the recall tool to the current thread only. Default scope is \`'resource'\`. (Default: `false`)
+**retrieval** (`boolean | { vector?: boolean; scope?: 'thread' | 'resource' }`): Enable retrieval-mode observation groups as durable pointers to raw message history. true enables cross-thread browsing by default. { vector: true } also enables semantic search using Memory's vector store and embedder. { scope: 'thread' } restricts the recall tool to the current thread only. Default scope is 'resource'. (Default: `false`)
 
 **observation** (`ObservationalMemoryObservationConfig`): Configuration for the observation step. Controls when the Observer agent runs and how it behaves.
 
-**observation.model** (`string | LanguageModel | DynamicModel | ModelByInputTokens | 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.model** (`string | LanguageModel | DynamicModel | ModelByInputTokens | 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.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.threadTitle** (`boolean`): When \`true\`, the Observer suggests short thread titles and updates the thread title when the conversation topic meaningfully changes. This is opt-in and defaults to disabled.
+**observation.threadTitle** (`boolean`): When true, the Observer suggests short thread titles and updates the thread title when the conversation topic meaningfully changes. This is opt-in and defaults to disabled.
 
 **observation.extract** (`Extractor[]`): Custom values to extract after observation. Schema-less extractors are requested inline in the Observer output. Schema-backed extractors run as a follow-up structured output call and are stored in thread OM metadata.
 
-**observation.observeAttachments** (`boolean | string[]`): Controls which image/file attachments are forwarded to the Observer model alongside their placeholder text lines. \`true\` (default) forwards all attachments. \`false\` drops all attachments while keeping placeholders visible. An array is a case-insensitive mimeType allowlist supporting exact matches (\`'application/pdf'\`), wildcard subtypes (\`'image/\*'\`), and bare \`'\*'\` for everything. Useful when the Observer model is text-only (e.g. some DeepSeek endpoints) while the main agent uses a multimodal model. Tool-result attachments are filtered using the same rule.
+**observation.observeAttachments** (`boolean | string[]`): Controls which image/file attachments are forwarded to the Observer model alongside their placeholder text lines. true (default) forwards all attachments. false drops all attachments while keeping placeholders visible. An array is a case-insensitive mimeType allowlist supporting exact matches ('application/pdf'), wildcard subtypes ('image/\*'), and bare '\*' for everything. Useful when the Observer model is text-only (e.g. some DeepSeek endpoints) while the main agent uses a multimodal model. Tool-result attachments are filtered using the same rule.
 
-**observation.messageTokens** (`number`): Token count of unobserved messages that triggers observation. When unobserved message tokens exceed this threshold, the Observer agent is called. Text is estimated locally with \`tokenx\`. Image parts are included with model-aware heuristics when possible, with deterministic fallbacks when image metadata is incomplete. Image-like \`file\` parts are counted the same way when uploads are normalized as files.
+**observation.messageTokens** (`number`): Token count of unobserved messages that triggers observation. When unobserved message tokens exceed this threshold, the Observer agent is called. Text is estimated locally with tokenx. Image parts are included with model-aware heuristics when possible, with deterministic fallbacks when image metadata is incomplete. Image-like file parts are counted the same way when uploads are normalized as files.
 
 **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.
 
@@ -71,23 +71,23 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
 
 **observation.modelSettings.maxOutputTokens** (`number`): Maximum output tokens. Set high to prevent truncation of observations.
 
-**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).
+**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).
 
-**observation.bufferOnIdle** (`boolean`): Run background observation buffering when an agent turn ends and the agent becomes idle. This is separate from \`bufferTokens\`, which controls step-time async buffering. Set this to \`true\` to buffer short idle turns without waiting for the next turn or the \`messageTokens\` threshold.
+**observation.bufferOnIdle** (`boolean`): Run background observation buffering when an agent turn ends and the agent becomes idle. This is separate from bufferTokens, which controls step-time async buffering. Set this to true to buffer short idle turns without waiting for the next turn or the messageTokens threshold.
 
-**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.
+**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.
 
-**observation.activateAfterIdle** (`number | string | false | "auto"`): Time before buffered observations are forced to activate after inactivity. Accepts milliseconds, a duration string, \`"auto"\` for a provider-aware prompt cache TTL, or \`false\`. If unset, the top-level \`activateAfterIdle\` value is used for observations. Set \`false\` to disable the top-level idle setting for observations.
+**observation.activateAfterIdle** (`number | string | false | "auto"`): Time before buffered observations are forced to activate after inactivity. Accepts milliseconds, a duration string, "auto" for a provider-aware prompt cache TTL, or false. If unset, the top-level activateAfterIdle value is used for observations. Set false to disable the top-level idle setting for observations.
 
-**observation.activateOnProviderChange** (`boolean`): Force buffered observations to activate when the actor provider or model changes. If unset, the top-level \`activateOnProviderChange\` value is used for observations.
+**observation.activateOnProviderChange** (`boolean`): Force buffered observations to activate when the actor provider or model changes. If unset, the top-level activateOnProviderChange value is used for observations.
 
-**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.
+**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.
 
-**observation.previousObserverTokens** (`number | false`): Optional token budget for the observer's previous-observations context. When set to a number, the observations passed to the Observer agent are tail-truncated to fit within this budget while keeping the newest observations and preserving highlighted 🔴 items when possible. When a buffered reflection is pending, the already-reflected observation lines are automatically replaced with the reflection summary before truncation. Set to \`0\` to omit previous observations entirely, or \`false\` to disable truncation explicitly.
+**observation.previousObserverTokens** (`number | false`): Optional token budget for the observer's previous-observations context. When set to a number, the observations passed to the Observer agent are tail-truncated to fit within this budget while keeping the newest observations and preserving highlighted 🔴 items when possible. When a buffered reflection is pending, the already-reflected observation lines are automatically replaced with the reflection summary before truncation. Set to 0 to omit previous observations entirely, or false to disable truncation explicitly.
 
 **reflection** (`ObservationalMemoryReflectionConfig`): Configuration for the reflection step. Controls when the Reflector agent runs and how it behaves.
 
-**reflection.model** (`string | LanguageModel | DynamicModel | ModelByInputTokens | 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 | ModelByInputTokens | 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.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.
 
@@ -101,13 +101,13 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
 
 **reflection.modelSettings.maxOutputTokens** (`number`): Maximum output tokens. Set high to prevent truncation of observations.
 
-**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.
+**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.
 
-**reflection.activateAfterIdle** (`number | string | false | "auto"`): Time before buffered reflections are forced to activate after inactivity. Accepts milliseconds, a duration string, \`"auto"\` for a provider-aware prompt cache TTL, or \`false\`. Reflections do not inherit top-level \`activateAfterIdle\`; set this explicitly to opt reflections into idle activation.
+**reflection.activateAfterIdle** (`number | string | false | "auto"`): Time before buffered reflections are forced to activate after inactivity. Accepts milliseconds, a duration string, "auto" for a provider-aware prompt cache TTL, or false. Reflections do not inherit top-level activateAfterIdle; set this explicitly to opt reflections into idle activation.
 
-**reflection.activateOnProviderChange** (`boolean`): Force buffered reflections to activate when the actor provider or model changes. Reflections do not inherit top-level \`activateOnProviderChange\`; set this explicitly to opt reflections into provider-change activation.
+**reflection.activateOnProviderChange** (`boolean`): Force buffered reflections to activate when the actor provider or model changes. Reflections do not inherit top-level activateOnProviderChange; set this explicitly to opt reflections into provider-change activation.
 
-**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.
+**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.
 
 ### Token estimate metadata cache
 
@@ -156,7 +156,7 @@ const memory = new Memory({
 
 **schema** (`ZodType<T> | (context) => ZodType<T> | undefined`): Optional Zod schema for structured extraction. When provided, OM runs a follow-up structured output call after the main OM operation. When omitted, the extractor is an inline string extractor emitted in the Observer or Reflector response. Use a function to derive the schema from runtime context.
 
-**includePreviousExtraction** (`boolean`): Controls whether the previous extraction is shown to the extractor on future OM runs. Set to \`false\` for values that should only come from the current OM run. (Default: `true`)
+**includePreviousExtraction** (`boolean`): Controls whether the previous extraction is shown to the extractor on future OM runs. Set to false for values that should only come from the current OM run. (Default: `true`)
 
 **onExtracted** (`(context) => T | void | Promise<T | void>`): Optional hook called after a custom extractor returns a value and before metadata is persisted. Returning a value replaces the extracted value. Throwing records an extraction failure.
 
@@ -498,13 +498,13 @@ Emitted when the Observer or Reflector agent begins processing.
 
 **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.
 
@@ -534,7 +534,7 @@ Emitted when observation or reflection completes successfully.
 
 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.
 
@@ -576,7 +576,7 @@ Emitted when async buffering begins in the background. Buffering pre-computes ob
 
 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.
 
@@ -602,7 +602,7 @@ Emitted when async buffering completes. The content is stored but not yet activa
 
 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.
 
@@ -688,7 +688,7 @@ 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.
 
@@ -700,29 +700,29 @@ When `retrieval` is set (any truthy value), a `recall` tool is registered so the
 
 ### Parameters
 
-**mode** (`'messages' | 'threads' | 'search'`): What to retrieve. \`"messages"\` (default) pages through message history. \`"threads"\` lists all threads for the current user. \`"search"\` finds messages by semantic similarity across all threads (requires vector store and embedder). (Default: `'messages'`)
+**mode** (`'messages' | 'threads' | 'search'`): What to retrieve. "messages" (default) pages through message history. "threads" lists all threads for the current user. "search" finds messages by semantic similarity across all threads (requires vector store and embedder). (Default: `'messages'`)
 
-**query** (`string`): Search query for \`mode: "search"\`. Finds messages semantically similar to this text across all threads for the current user.
+**query** (`string`): Search query for mode: "search". Finds messages semantically similar to this text across all threads for the current user.
 
-**cursor** (`string`): A message ID to anchor the recall query. Required for \`mode: "messages"\` when browsing the current thread. Extract the start or end ID from an observation group range (e.g. from \`\_range: \\\`startId:endId\\\`\_\`, use either \`startId\` or \`endId\`). If a range string is passed directly, the tool returns a hint explaining how to extract the correct ID. Can be omitted when \`threadId\` is provided to start reading from the beginning of that thread.
+**cursor** (`string`): A message ID to anchor the recall query. Required for mode: "messages" when browsing the current thread. Extract the start or end ID from an observation group range (e.g. from \_range: \startId:endId\\\_, use either startId or endId). If a range string is passed directly, the tool returns a hint explaining how to extract the correct ID. Can be omitted when threadId is provided to start reading from the beginning of that thread.
 
-**threadId** (`string`): Browse a different thread by its ID. Use \`mode: "threads"\` first to discover thread IDs. When provided without a \`cursor\`, reading starts from the beginning of the thread.
+**threadId** (`string`): Browse a different thread by its ID. Use mode: "threads" first to discover thread IDs. When provided without a cursor, reading starts from the beginning of the thread.
 
-**page** (`number`): Pagination offset. For messages: positive values page forward from cursor, negative values page backward. For threads: page number (0-indexed). \`0\` is treated as \`1\` for messages. (Default: `1`)
+**page** (`number`): Pagination offset. For messages: positive values page forward from cursor, negative values page backward. For threads: page number (0-indexed). 0 is treated as 1 for messages. (Default: `1`)
 
 **limit** (`number`): Maximum number of items to return per page. (Default: `20`)
 
-**detail** (`'low' | 'high'`): Controls how much content is shown per message part. \`'low'\` shows truncated text and tool names with positional indices (\`\[p0]\`, \`\[p1]\`). \`'high'\` shows full content including tool arguments and results, clamped to one part per call with continuation hints. (Default: `'low'`)
+**detail** (`'low' | 'high'`): Controls how much content is shown per message part. 'low' shows truncated text and tool names with positional indices (\[p0], \[p1]). 'high' shows full content including tool arguments and results, clamped to one part per call with continuation hints. (Default: `'low'`)
 
-**partIndex** (`number`): Fetch a single message part at full detail by its positional index. Use this when a low-detail recall shows an interesting part at \`\[p1]\` — call again with \`partIndex: 1\` to see the full content without loading every part.
+**partIndex** (`number`): Fetch a single message part at full detail by its positional index. Use this when a low-detail recall shows an interesting part at \[p1] — call again with partIndex: 1 to see the full content without loading every part.
 
-**before** (`string`): For \`mode: "threads"\` only. Filter to threads created before this date. Accepts ISO 8601 format (e.g. \`"2026-03-15"\`, \`"2026-03-10T00:00:00Z"\`).
+**before** (`string`): For mode: "threads" only. Filter to threads created before this date. Accepts ISO 8601 format (e.g. "2026-03-15", "2026-03-10T00:00:00Z").
 
-**after** (`string`): For \`mode: "threads"\` only. Filter to threads created after this date. Accepts ISO 8601 format (e.g. \`"2026-03-01"\`, \`"2026-03-10T00:00:00Z"\`).
+**after** (`string`): For mode: "threads" only. Filter to threads created after this date. Accepts ISO 8601 format (e.g. "2026-03-01", "2026-03-10T00:00:00Z").
 
 ### Returns (messages mode)
 
-**messages** (`string`): Formatted message content. Format depends on the \`detail\` level.
+**messages** (`string`): Formatted message content. Format depends on the detail level.
 
 **count** (`number`): Number of messages in this page.
 
@@ -736,13 +736,13 @@ When `retrieval` is set (any truthy value), a `recall` tool is registered so the
 
 **hasPrevPage** (`boolean`): Whether more messages exist before this page.
 
-**truncated** (`boolean`): Present and \`true\` when the output was capped by the token budget. The agent can paginate or use \`partIndex\` to access remaining content.
+**truncated** (`boolean`): Present and true when the output was capped by the token budget. The agent can paginate or use partIndex to access remaining content.
 
-**tokenOffset** (`number`): Approximate number of tokens that were trimmed when \`truncated\` is true.
+**tokenOffset** (`number`): Approximate number of tokens that were trimmed when truncated is true.
 
 ### Returns (threads mode)
 
-**threads** (`string`): Formatted thread listing. Each thread shows its title, ID, and dates. The current thread is marked with \`← current\`.
+**threads** (`string`): Formatted thread listing. Each thread shows its title, ID, and dates. The current thread is marked with ← current.
 
 **count** (`number`): Number of threads returned.
 

package/dist/docs/references/reference-storage-dynamodb.md

@@ -118,7 +118,7 @@ For local development, you can use [DynamoDB Local](https://docs.aws.amazon.com/
 
 **config.endpoint** (`string`): Custom endpoint for DynamoDB (e.g., 'http\://localhost:8000' for local development).
 
-**config.credentials** (`object`): AWS credentials object with \`accessKeyId\` and \`secretAccessKey\`. If not provided, the AWS SDK will attempt to source credentials from environment variables, IAM roles (e.g., for EC2/Lambda), or the shared AWS credentials file.
+**config.credentials** (`object`): AWS credentials object with accessKeyId and secretAccessKey. If not provided, the AWS SDK will attempt to source credentials from environment variables, IAM roles (e.g., for EC2/Lambda), or the shared AWS credentials file.
 
 **config.ttl** (`object`): TTL (Time To Live) configuration for automatic data expiration. Configure per entity type: thread, message, trace, eval, workflow\_snapshot, resource, score. Each entity config includes: enabled (boolean), attributeName (string, default: 'ttl'), defaultTtlSeconds (number).
 

package/dist/docs/references/reference-storage-libsql.md

@@ -91,7 +91,7 @@ storage: new LibSQLStore({
 
 ## Options
 
-**url** (`string`): Database URL. Use \`:memory:\` for in-memory database, \`file:filename.db\` for a file database, or a libSQL connection string (e.g., \`libsql://your-database.turso.io\`) for remote storage.
+**url** (`string`): Database URL. Use :memory: for in-memory database, file:filename.db for a file database, or a libSQL connection string (e.g., libsql://your-database.turso.io) for remote storage.
 
 **authToken** (`string`): Authentication token for remote libSQL databases.
 

package/dist/docs/references/reference-storage-postgresql.md

@@ -45,7 +45,7 @@ const storage = new PostgresStore({
 
 **id** (`string`): Unique identifier for this storage instance.
 
-**connectionString** (`string`): PostgreSQL connection string (e.g., postgresql://user:pass\@host:5432/dbname). Required unless using \`pool\` or individual host-based parameters (\`host\`, \`port\`, \`database\`, \`user\`, \`password\`).
+**connectionString** (`string`): PostgreSQL connection string (e.g., postgresql://user:pass\@host:5432/dbname). Required unless using pool or individual host-based parameters (host, port, database, user, password).
 
 **host** (`string`): Database server hostname or IP address. Used with other host-based parameters as an alternative to connectionString.
 
@@ -57,7 +57,7 @@ const storage = new PostgresStore({
 
 **password** (`string`): Password for the database user.
 
-**pool** (`pg.Pool`): Pre-configured pg.Pool instance. Use this to reuse an existing connection pool. When provided, Mastra will not create its own pool and will not close it when \`store.close()\` is called.
+**pool** (`pg.Pool`): Pre-configured pg.Pool instance. Use this to reuse an existing connection pool. When provided, Mastra will not create its own pool and will not close it when store.close() is called.
 
 **schemaName** (`string`): The name of the schema you want the storage to use. Defaults to 'public'.
 

package/dist/docs/references/reference-storage-redis.md

@@ -69,7 +69,7 @@ const storage = new RedisStore({
 
 **id** (`string`): Unique identifier for the storage instance
 
-**connectionString** (`string`): Redis connection URL (e.g., \`redis\://localhost:6379\` or \`redis\://:password\@localhost:6379\`)
+**connectionString** (`string`): Redis connection URL (e.g., redis\://localhost:6379 or redis\://:password\@localhost:6379)
 
 **host** (`string`): Redis host address
 
@@ -79,7 +79,7 @@ const storage = new RedisStore({
 
 **db** (`number`): Redis database number (Default: `0`)
 
-**client** (`RedisClient`): Pre-configured redis client (from the \`redis\` package) for advanced setups
+**client** (`RedisClient`): Pre-configured redis client (from the redis package) for advanced setups
 
 > **Note:** You must provide either `connectionString`, `host`, or `client`. These options are mutually exclusive.
 

package/dist/docs/references/reference-vectors-mongodb.md

@@ -103,7 +103,7 @@ Searches for similar vectors with optional metadata filtering.
 
 **topK** (`number`): Number of results to return (Default: `10`)
 
-**filter** (`Record<string, any>`): Metadata filters (applies to the \`metadata\` field)
+**filter** (`Record<string, any>`): Metadata filters (applies to the metadata field)
 
 **documentFilter** (`Record<string, any>`): Filters on original document fields (not just metadata)
 

package/dist/docs/references/reference-vectors-pg.md

@@ -28,7 +28,7 @@ The PgVector class provides vector search using [PostgreSQL](https://www.postgre
 
 **pgPoolOptions** (`PoolConfig`): Additional pg pool configuration options
 
-**disableInit** (`boolean`): When true, automatic DDL (schema, extension, table, and index creation) inside \`createIndex\` is skipped. Useful for CI/CD pipelines where schema and indexes are managed separately and the runtime database role lacks DDL privileges. Can also be enabled with the \`MASTRA\_DISABLE\_STORAGE\_INIT\` environment variable. (Default: `false`)
+**disableInit** (`boolean`): When true, automatic DDL (schema, extension, table, and index creation) inside createIndex is skipped. Useful for CI/CD pipelines where schema and indexes are managed separately and the runtime database role lacks DDL privileges. Can also be enabled with the MASTRA\_DISABLE\_STORAGE\_INIT environment variable. (Default: `false`)
 
 ## Constructor examples
 

package/dist/index.cjs

@@ -1,57 +1,57 @@
 'use strict';
 
-var chunkYWAAIUB6_cjs = require('./chunk-YWAAIUB6.cjs');
+var chunk3JX4RMDN_cjs = require('./chunk-3JX4RMDN.cjs');
 var chunk43FJOLKM_cjs = require('./chunk-43FJOLKM.cjs');
 
 
 
 Object.defineProperty(exports, "Extractor", {
   enumerable: true,
-  get: function () { return chunkYWAAIUB6_cjs.Extractor; }
+  get: function () { return chunk3JX4RMDN_cjs.Extractor; }
 });
 Object.defineProperty(exports, "Memory", {
   enumerable: true,
-  get: function () { return chunkYWAAIUB6_cjs.Memory; }
+  get: function () { return chunk3JX4RMDN_cjs.Memory; }
 });
 Object.defineProperty(exports, "MessageHistory", {
   enumerable: true,
-  get: function () { return chunkYWAAIUB6_cjs.MessageHistory; }
+  get: function () { return chunk3JX4RMDN_cjs.MessageHistory; }
 });
 Object.defineProperty(exports, "ModelByInputTokens", {
   enumerable: true,
-  get: function () { return chunkYWAAIUB6_cjs.ModelByInputTokens; }
+  get: function () { return chunk3JX4RMDN_cjs.ModelByInputTokens; }
 });
 Object.defineProperty(exports, "SemanticRecall", {
   enumerable: true,
-  get: function () { return chunkYWAAIUB6_cjs.SemanticRecall; }
+  get: function () { return chunk3JX4RMDN_cjs.SemanticRecall; }
 });
 Object.defineProperty(exports, "WorkingMemory", {
   enumerable: true,
-  get: function () { return chunkYWAAIUB6_cjs.WorkingMemory; }
+  get: function () { return chunk3JX4RMDN_cjs.WorkingMemory; }
 });
 Object.defineProperty(exports, "WorkingMemoryExtractor", {
   enumerable: true,
-  get: function () { return chunkYWAAIUB6_cjs.WorkingMemoryExtractor; }
+  get: function () { return chunk3JX4RMDN_cjs.WorkingMemoryExtractor; }
 });
 Object.defineProperty(exports, "deepMergeWorkingMemory", {
   enumerable: true,
-  get: function () { return chunkYWAAIUB6_cjs.deepMergeWorkingMemory; }
+  get: function () { return chunk3JX4RMDN_cjs.deepMergeWorkingMemory; }
 });
 Object.defineProperty(exports, "extractWorkingMemoryContent", {
   enumerable: true,
-  get: function () { return chunkYWAAIUB6_cjs.extractWorkingMemoryContent; }
+  get: function () { return chunk3JX4RMDN_cjs.extractWorkingMemoryContent; }
 });
 Object.defineProperty(exports, "extractWorkingMemoryTags", {
   enumerable: true,
-  get: function () { return chunkYWAAIUB6_cjs.extractWorkingMemoryTags; }
+  get: function () { return chunk3JX4RMDN_cjs.extractWorkingMemoryTags; }
 });
 Object.defineProperty(exports, "getObservationsAsOf", {
   enumerable: true,
-  get: function () { return chunkYWAAIUB6_cjs.getObservationsAsOf; }
+  get: function () { return chunk3JX4RMDN_cjs.getObservationsAsOf; }
 });
 Object.defineProperty(exports, "removeWorkingMemoryTags", {
   enumerable: true,
-  get: function () { return chunkYWAAIUB6_cjs.removeWorkingMemoryTags; }
+  get: function () { return chunk3JX4RMDN_cjs.removeWorkingMemoryTags; }
 });
 Object.defineProperty(exports, "WORKING_MEMORY_STATE_ID", {
   enumerable: true,

package/dist/index.js

@@ -1,4 +1,4 @@
-export { Extractor, Memory, MessageHistory, ModelByInputTokens, SemanticRecall, WorkingMemory, WorkingMemoryExtractor, deepMergeWorkingMemory, extractWorkingMemoryContent, extractWorkingMemoryTags, getObservationsAsOf, removeWorkingMemoryTags } from './chunk-2NSPHF6Q.js';
+export { Extractor, Memory, MessageHistory, ModelByInputTokens, SemanticRecall, WorkingMemory, WorkingMemoryExtractor, deepMergeWorkingMemory, extractWorkingMemoryContent, extractWorkingMemoryTags, getObservationsAsOf, removeWorkingMemoryTags } from './chunk-TB6SV7QK.js';
 export { WORKING_MEMORY_STATE_ID, WORKING_MEMORY_STATE_PROCESSOR_ID, WorkingMemoryStateProcessor } from './chunk-WCGXQIEN.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/{observational-memory-QL6BKIQX.js → observational-memory-NNGAOKRQ.js}

@@ -1,4 +1,4 @@
-export { Extractor, ModelByInputTokens, OBSERVER_SYSTEM_PROMPT, ObservationalMemory, ObservationalMemoryProcessor, TokenCounter, WorkingMemoryExtractor, buildObserverPrompt, buildObserverSystemPrompt, combineObservationGroupRanges, deriveObservationGroupProvenance, extractCurrentTask, formatMessagesForObserver, getObservationsAsOf, hasCurrentTaskSection, injectAnchorIds, optimizeObservationsForContext, parseAnchorId, parseObservationGroups, parseObserverOutput, reconcileObservationGroupsFromReflection, renderObservationGroupsForReflection, stripEphemeralAnchorIds, stripObservationGroups, wrapInObservationGroup } from './chunk-2NSPHF6Q.js';
+export { Extractor, ModelByInputTokens, OBSERVER_SYSTEM_PROMPT, ObservationalMemory, ObservationalMemoryProcessor, TokenCounter, WorkingMemoryExtractor, buildObserverPrompt, buildObserverSystemPrompt, combineObservationGroupRanges, deriveObservationGroupProvenance, extractCurrentTask, formatMessagesForObserver, getObservationsAsOf, hasCurrentTaskSection, injectAnchorIds, optimizeObservationsForContext, parseAnchorId, parseObservationGroups, parseObserverOutput, reconcileObservationGroupsFromReflection, renderObservationGroupsForReflection, stripEphemeralAnchorIds, stripObservationGroups, wrapInObservationGroup } from './chunk-TB6SV7QK.js';
 export { OBSERVATIONAL_MEMORY_DEFAULTS, OBSERVATION_CONTEXT_INSTRUCTIONS, OBSERVATION_CONTEXT_PROMPT, OBSERVATION_CONTINUATION_HINT } from './chunk-LSJJAJAF.js';
-//# sourceMappingURL=observational-memory-QL6BKIQX.js.map
-//# sourceMappingURL=observational-memory-QL6BKIQX.js.map
+//# sourceMappingURL=observational-memory-NNGAOKRQ.js.map
+//# sourceMappingURL=observational-memory-NNGAOKRQ.js.map

package/dist/{observational-memory-QL6BKIQX.js.map → observational-memory-NNGAOKRQ.js.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"observational-memory-QL6BKIQX.js"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"observational-memory-NNGAOKRQ.js"}

package/dist/{observational-memory-CZ22AU3H.cjs → observational-memory-TEIGXE56.cjs}

@@ -1,109 +1,109 @@
 'use strict';
 
-var chunkYWAAIUB6_cjs = require('./chunk-YWAAIUB6.cjs');
+var chunk3JX4RMDN_cjs = require('./chunk-3JX4RMDN.cjs');
 var chunkD4J4XPGM_cjs = require('./chunk-D4J4XPGM.cjs');
 
 
 
 Object.defineProperty(exports, "Extractor", {
   enumerable: true,
-  get: function () { return chunkYWAAIUB6_cjs.Extractor; }
+  get: function () { return chunk3JX4RMDN_cjs.Extractor; }
 });
 Object.defineProperty(exports, "ModelByInputTokens", {
   enumerable: true,
-  get: function () { return chunkYWAAIUB6_cjs.ModelByInputTokens; }
+  get: function () { return chunk3JX4RMDN_cjs.ModelByInputTokens; }
 });
 Object.defineProperty(exports, "OBSERVER_SYSTEM_PROMPT", {
   enumerable: true,
-  get: function () { return chunkYWAAIUB6_cjs.OBSERVER_SYSTEM_PROMPT; }
+  get: function () { return chunk3JX4RMDN_cjs.OBSERVER_SYSTEM_PROMPT; }
 });
 Object.defineProperty(exports, "ObservationalMemory", {
   enumerable: true,
-  get: function () { return chunkYWAAIUB6_cjs.ObservationalMemory; }
+  get: function () { return chunk3JX4RMDN_cjs.ObservationalMemory; }
 });
 Object.defineProperty(exports, "ObservationalMemoryProcessor", {
   enumerable: true,
-  get: function () { return chunkYWAAIUB6_cjs.ObservationalMemoryProcessor; }
+  get: function () { return chunk3JX4RMDN_cjs.ObservationalMemoryProcessor; }
 });
 Object.defineProperty(exports, "TokenCounter", {
   enumerable: true,
-  get: function () { return chunkYWAAIUB6_cjs.TokenCounter; }
+  get: function () { return chunk3JX4RMDN_cjs.TokenCounter; }
 });
 Object.defineProperty(exports, "WorkingMemoryExtractor", {
   enumerable: true,
-  get: function () { return chunkYWAAIUB6_cjs.WorkingMemoryExtractor; }
+  get: function () { return chunk3JX4RMDN_cjs.WorkingMemoryExtractor; }
 });
 Object.defineProperty(exports, "buildObserverPrompt", {
   enumerable: true,
-  get: function () { return chunkYWAAIUB6_cjs.buildObserverPrompt; }
+  get: function () { return chunk3JX4RMDN_cjs.buildObserverPrompt; }
 });
 Object.defineProperty(exports, "buildObserverSystemPrompt", {
   enumerable: true,
-  get: function () { return chunkYWAAIUB6_cjs.buildObserverSystemPrompt; }
+  get: function () { return chunk3JX4RMDN_cjs.buildObserverSystemPrompt; }
 });
 Object.defineProperty(exports, "combineObservationGroupRanges", {
   enumerable: true,
-  get: function () { return chunkYWAAIUB6_cjs.combineObservationGroupRanges; }
+  get: function () { return chunk3JX4RMDN_cjs.combineObservationGroupRanges; }
 });
 Object.defineProperty(exports, "deriveObservationGroupProvenance", {
   enumerable: true,
-  get: function () { return chunkYWAAIUB6_cjs.deriveObservationGroupProvenance; }
+  get: function () { return chunk3JX4RMDN_cjs.deriveObservationGroupProvenance; }
 });
 Object.defineProperty(exports, "extractCurrentTask", {
   enumerable: true,
-  get: function () { return chunkYWAAIUB6_cjs.extractCurrentTask; }
+  get: function () { return chunk3JX4RMDN_cjs.extractCurrentTask; }
 });
 Object.defineProperty(exports, "formatMessagesForObserver", {
   enumerable: true,
-  get: function () { return chunkYWAAIUB6_cjs.formatMessagesForObserver; }
+  get: function () { return chunk3JX4RMDN_cjs.formatMessagesForObserver; }
 });
 Object.defineProperty(exports, "getObservationsAsOf", {
   enumerable: true,
-  get: function () { return chunkYWAAIUB6_cjs.getObservationsAsOf; }
+  get: function () { return chunk3JX4RMDN_cjs.getObservationsAsOf; }
 });
 Object.defineProperty(exports, "hasCurrentTaskSection", {
   enumerable: true,
-  get: function () { return chunkYWAAIUB6_cjs.hasCurrentTaskSection; }
+  get: function () { return chunk3JX4RMDN_cjs.hasCurrentTaskSection; }
 });
 Object.defineProperty(exports, "injectAnchorIds", {
   enumerable: true,
-  get: function () { return chunkYWAAIUB6_cjs.injectAnchorIds; }
+  get: function () { return chunk3JX4RMDN_cjs.injectAnchorIds; }
 });
 Object.defineProperty(exports, "optimizeObservationsForContext", {
   enumerable: true,
-  get: function () { return chunkYWAAIUB6_cjs.optimizeObservationsForContext; }
+  get: function () { return chunk3JX4RMDN_cjs.optimizeObservationsForContext; }
 });
 Object.defineProperty(exports, "parseAnchorId", {
   enumerable: true,
-  get: function () { return chunkYWAAIUB6_cjs.parseAnchorId; }
+  get: function () { return chunk3JX4RMDN_cjs.parseAnchorId; }
 });
 Object.defineProperty(exports, "parseObservationGroups", {
   enumerable: true,
-  get: function () { return chunkYWAAIUB6_cjs.parseObservationGroups; }
+  get: function () { return chunk3JX4RMDN_cjs.parseObservationGroups; }
 });
 Object.defineProperty(exports, "parseObserverOutput", {
   enumerable: true,
-  get: function () { return chunkYWAAIUB6_cjs.parseObserverOutput; }
+  get: function () { return chunk3JX4RMDN_cjs.parseObserverOutput; }
 });
 Object.defineProperty(exports, "reconcileObservationGroupsFromReflection", {
   enumerable: true,
-  get: function () { return chunkYWAAIUB6_cjs.reconcileObservationGroupsFromReflection; }
+  get: function () { return chunk3JX4RMDN_cjs.reconcileObservationGroupsFromReflection; }
 });
 Object.defineProperty(exports, "renderObservationGroupsForReflection", {
   enumerable: true,
-  get: function () { return chunkYWAAIUB6_cjs.renderObservationGroupsForReflection; }
+  get: function () { return chunk3JX4RMDN_cjs.renderObservationGroupsForReflection; }
 });
 Object.defineProperty(exports, "stripEphemeralAnchorIds", {
   enumerable: true,
-  get: function () { return chunkYWAAIUB6_cjs.stripEphemeralAnchorIds; }
+  get: function () { return chunk3JX4RMDN_cjs.stripEphemeralAnchorIds; }
 });
 Object.defineProperty(exports, "stripObservationGroups", {
   enumerable: true,
-  get: function () { return chunkYWAAIUB6_cjs.stripObservationGroups; }
+  get: function () { return chunk3JX4RMDN_cjs.stripObservationGroups; }
 });
 Object.defineProperty(exports, "wrapInObservationGroup", {
   enumerable: true,
-  get: function () { return chunkYWAAIUB6_cjs.wrapInObservationGroup; }
+  get: function () { return chunk3JX4RMDN_cjs.wrapInObservationGroup; }
 });
 Object.defineProperty(exports, "OBSERVATIONAL_MEMORY_DEFAULTS", {
   enumerable: true,
@@ -121,5 +121,5 @@ Object.defineProperty(exports, "OBSERVATION_CONTINUATION_HINT", {
   enumerable: true,
   get: function () { return chunkD4J4XPGM_cjs.OBSERVATION_CONTINUATION_HINT; }
 });
-//# sourceMappingURL=observational-memory-CZ22AU3H.cjs.map
-//# sourceMappingURL=observational-memory-CZ22AU3H.cjs.map
+//# sourceMappingURL=observational-memory-TEIGXE56.cjs.map
+//# sourceMappingURL=observational-memory-TEIGXE56.cjs.map

package/dist/{observational-memory-CZ22AU3H.cjs.map → observational-memory-TEIGXE56.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"observational-memory-CZ22AU3H.cjs"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"observational-memory-TEIGXE56.cjs"}