npm - @mastra/memory - Versions diffs - 1.26.1 → 1.26.2-alpha.1 - Mend

@mastra/memory 1.26.1 → 1.26.2-alpha.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (33) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -1,5 +1,30 @@
 # @mastra/memory
+## 1.26.2-alpha.1
+### Patch Changes
+- Corrected the `observation.blockAfter` and `reflection.blockAfter` configuration documentation shown in editors. Crossing `observation.blockAfter` lets buffered activation overshoot the retention target; it does not force a blocking observation. The documented value ranges now match the runtime: values from 1 up to (but not including) 100 multiply the base threshold, and values of 100 or more are absolute token counts that must be greater than the base threshold. ([#21215](https://github.com/mastra-ai/mastra/pull/21215))
+- Added continuation support to the Observational Memory `recall` tool. When a single message part is larger than the result budget, the result now includes `nextCharOffset` and a note explaining how to fetch the next chunk, so oversized parts can be read across multiple calls instead of returning the same truncated prefix every time. ([#19821](https://github.com/mastra-ai/mastra/pull/19821))
+  ```json
+  { "mode": "messages", "cursor": "<message-id>", "partIndex": 0, "detail": "high", "charOffset": 8000 }
+  ```
+  Fixes [#19817](https://github.com/mastra-ai/mastra/issues/19817).
+- Updated dependencies [[`898bba4`](https://github.com/mastra-ai/mastra/commit/898bba46d4806dd255a44e5dc3a3d5827eaefdfe), [`f9aab1c`](https://github.com/mastra-ai/mastra/commit/f9aab1cfc3fda03238a7fd7bd8b794e07497878c), [`e31421b`](https://github.com/mastra-ai/mastra/commit/e31421bc9c11c03c6e74f447ecb5820000e2b9d7), [`aece0e7`](https://github.com/mastra-ai/mastra/commit/aece0e7cb124ae1eb1230689b887f5554b9a0bf0)]:
+  - @mastra/core@1.59.0-alpha.2
+## 1.26.2-alpha.0
+### Patch Changes
+- Updated dependencies [[`aa3e7be`](https://github.com/mastra-ai/mastra/commit/aa3e7be30f8addb0278ea74429f4df054517a287), [`90822db`](https://github.com/mastra-ai/mastra/commit/90822dba08fb2169c518e4a6d7f127c098eb46b8), [`3700208`](https://github.com/mastra-ai/mastra/commit/37002080c7838267803a7e579a7d58b908d62f36), [`8b7131e`](https://github.com/mastra-ai/mastra/commit/8b7131eb0407f58f5205e68fb27b81f026488f28), [`cf418b6`](https://github.com/mastra-ai/mastra/commit/cf418b65efb81997e9b8dc7638eee363c5d96c96), [`79c4f82`](https://github.com/mastra-ai/mastra/commit/79c4f8295f568752eeadf8a9b50010a7d9ec06ae)]:
+  - @mastra/core@1.59.0-alpha.1
+  - @mastra/schema-compat@1.3.7-alpha.0
 ## 1.26.1
 ### Patch Changes

package/dist/docs/SKILL.md CHANGED Viewed

@@ -3,7 +3,7 @@ name: mastra-memory
 description: Documentation for @mastra/memory. Use when working with @mastra/memory APIs, configuration, or implementation.
 metadata:
   package: "@mastra/memory"
-  version: "1.26.1"
+  version: "1.26.2-alpha.1"
 ---
 ## When to use
@@ -16,7 +16,7 @@ Read the individual reference documents for detailed explanations and code examp
 ### Docs
-- [Agent approval](references/docs-agents-agent-approval.md) - Learn how to require approvals and suspend tool execution, plus automatically resume suspended tools while keeping humans in control of agent workflows.
+- [Human-in-the-loop](references/docs-agents-agent-approval.md) - Learn how to require approvals and suspend tool execution, plus automatically resume suspended tools while keeping humans in control of agent workflows.
 - [Agent networks](references/docs-agents-networks.md) - Coordinate multiple agents, workflows, and tools using agent networks for complex, non-deterministic task execution.
 - [Subagents](references/docs-capabilities-subagents.md) - Learn how to coordinate multiple agents with delegation hooks, iteration monitoring, message filtering, and task completion scoring.
 - [Evals with memory](references/docs-evals-evals-with-memory.md) - Run scorers against memory-enabled agents, including observational memory in thread scope, using runEvals and dataset experiments.
@@ -26,10 +26,10 @@ Read the individual reference documents for detailed explanations and code examp
 - [Message history](references/docs-memory-message-history.md) - Learn how to configure message history in Mastra to store recent messages from the current conversation.
 - [Multi-user threads](references/docs-memory-multi-user-threads.md) - Share one Mastra thread between multiple users by carrying speaker identity in the message body.
 - [Observational Memory](references/docs-memory-observational-memory.md) - Learn how Observational Memory keeps your agent's context window small while preserving long-term memory across conversations.
-- [Memory overview](references/docs-memory-overview.md) - Learn how Mastra's memory system works with working memory, message history, semantic recall, and observational memory.
+- [Memory](references/docs-memory-overview.md) - Learn how Mastra's memory system works with working memory, message history, semantic recall, and observational memory.
 - [Semantic recall](references/docs-memory-semantic-recall.md) - Learn how to use semantic recall in Mastra to retrieve relevant messages from past conversations using vector search and embeddings.
 - [Working memory](references/docs-memory-working-memory.md) - Learn how to configure working memory in Mastra to store persistent user data, preferences.
-- [Storage overview](references/docs-storage-overview.md) - Configure storage for Mastra to persist runtime state across agents, workflows, observability, evals, schedules, and memory.
+- [Storage](references/docs-storage-overview.md) - Configure storage for Mastra to persist runtime state across agents, workflows, observability, evals, schedules, and memory.
 ### Integrations

package/dist/docs/assets/SOURCE_MAP.json CHANGED Viewed

@@ -1,5 +1,5 @@
 {
-  "version": "1.26.1",
+  "version": "1.26.2-alpha.1",
   "package": "@mastra/memory",
   "exports": {},
   "modules": {

package/dist/docs/references/docs-agents-agent-approval.md CHANGED Viewed

@@ -1,10 +1,10 @@
 > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-# Agent approval
+# Human-in-the-loop
-Agents sometimes require the same [human-in-the-loop](https://mastra.ai/docs/workflows/human-in-the-loop) oversight used in workflows when calling tools that handle sensitive operations, like deleting resources or running long processes. With agent approval you can suspend a tool call before it executes so a human can approve or decline it, or let tools suspend themselves to request additional context from the user.
+Agents sometimes require the same [human-in-the-loop (HITL)](https://mastra.ai/docs/workflows/human-in-the-loop) oversight used in workflows when calling tools that handle sensitive operations, like deleting resources or running long processes. With human-in-the-loop you can suspend a tool call before it executes so a human can approve or decline it, or let tools suspend themselves to request additional context from the user.
-## When to use agent approval
+## When to use human-in-the-loop
 - **Destructive or irreversible actions** such as deleting records or sending emails, or alternatively processing payments.
 - **Cost-heavy operations** like calling expensive third-party APIs where you want to verify arguments first.
@@ -12,7 +12,7 @@ Agents sometimes require the same [human-in-the-loop](https://mastra.ai/docs/wor
 ## Quickstart
-Mark a tool with `requireApproval: true`, then check for the `tool-call-approval` chunk in the stream to approve or decline:
+Mark a tool with `requireApproval: true`, then check for the `tool-call-approval` chunk in the stream to approve or decline the action:
 ```typescript
 import { Agent } from '@mastra/core/agent'
@@ -48,7 +48,7 @@ for await (const chunk of stream.fullStream) {
 }
 ```
-> **Note:** Agent approval uses snapshots to capture request state. Configure a [storage provider](https://mastra.ai/docs/storage/overview) on your Mastra instance or you'll see a "snapshot not found" error.
+> **Note:** Human-in-the-loop uses snapshots to capture request state. Configure a [storage provider](https://mastra.ai/docs/storage/overview) on your Mastra instance or you'll see a "snapshot not found" error.
 >
 > Snapshots for agent runs are minimal resume artifacts: they hold only what's needed to resume the suspended run and are deleted once the run finishes. Use [tracing](https://mastra.ai/docs/observability/overview) for the execution record and [memory](https://mastra.ai/docs/memory/overview) for the conversation history.

package/dist/docs/references/docs-capabilities-subagents.md CHANGED Viewed

@@ -136,7 +136,7 @@ Called after a delegation finishes. Use it to inspect results or provide feedbac
 - Return `{ feedback: '...' }`: Add feedback that gets saved to the parent agent's memory and is visible to subsequent iterations
 - Return `{ resultText: '...' }`: Replace the tool result text the parent model sees for this delegation, within the current run
-Use `resultText` when the subagent's own result would mislead the parent immediately. For example, a subagent that stops on a tool-calls step returns empty text, which the parent model reads as a successful but empty delegation. Unlike `feedback`, which only reaches the model on the next turn, `resultText` changes what the parent reasons on right away.
+Use `resultText` when the subagent's own result would mislead the parent immediately. For example, a subagent that stops on a tool-calls step returns empty text. The parent model reads this as a successful but empty delegation. Unlike `feedback`, which only reaches the model on the next turn, `resultText` changes what the parent reasons on right away.
 ```typescript
 const stream = await parentAgent.stream('Research AI trends', {
@@ -237,7 +237,7 @@ const stream = await parentAgent.stream('Research AI trends', {
 })
 ```
-Return `{ continue: true }` to keep iterating, or `{ continue: false }` to stop. Include optional `feedback` to inject guidance into the conversation. When `feedback` is combined with `continue: false`, the model may get one final turn to produce a text response incorporating the feedback, but only if the current iteration is still active (e.g., after tool calls), otherwise no extra turn is granted.
+Return `{ continue: true }` to keep iterating, or `{ continue: false }` to stop. Include optional `feedback` to inject guidance into the conversation. When `feedback` is combined with `continue: false`, the model may get one final turn for a text response that incorporates the feedback. The extra turn is granted only while the current iteration is active (e.g., after tool calls).
 ## Memory isolation
@@ -447,7 +447,7 @@ Version overrides propagate automatically through delegation. See [Subagent vers
 - [Background tasks](https://mastra.ai/docs/long-running-agents/background-tasks)
 - [Subagent versioning](https://mastra.ai/reference/editor/versioning)
-- [Guide: Research coordinator](https://mastra.ai/guides/guide/research-coordinator)
+- [Guide: Research coordinator](https://mastra.ai/blog/build-a-research-coordinator-with-supervisor-agents)
 - [Agent.stream() reference](https://mastra.ai/reference/streaming/agents/stream)
 - [Agent.streamUntilIdle() reference](https://mastra.ai/reference/streaming/agents/streamUntilIdle)
 - [Agent.generate() reference](https://mastra.ai/reference/agents/generate)

package/dist/docs/references/docs-long-running-agents-background-tasks.md CHANGED Viewed

@@ -4,7 +4,7 @@
 **Added in:** `@mastra/core@1.29.0`
-Background tasks let an agent dispatch a long-running tool call without blocking the agentic loop. The tool returns an immediate acknowledgement, the LLM continues responding, and the task runs to completion in the background. When it finishes, its result is written to memory and if you use `stream()` with the [`untilIdle`](https://mastra.ai/reference/streaming/agents/stream) option the agent is re-invoked automatically so the result is processed in the same call.
+Background tasks let an agent dispatch a long-running tool call without blocking the agentic loop. The tool returns an immediate acknowledgement while the LLM continues responding. The task then runs to completion in the background. When it finishes, its result is written to memory and if you use `stream()` with the [`untilIdle`](https://mastra.ai/reference/streaming/agents/stream) option the agent is re-invoked automatically so the result is processed in the same call.
 ## When to use background tasks
@@ -273,7 +273,7 @@ await mastra.backgroundTaskManager?.resume(taskId, {
 ### What happens to the agent loop
-When a task suspends mid-`stream()` with `untilIdle`, the wrapper treats it as terminal for the current iteration and closes. To continue the agent immediately when the resume payload is in hand, call `agent.resumeStream(resumeData, { runId, toolCallId, memory, untilIdle: true })`: the resumed bg task runs to completion, its result is added to the message list, and the agent runs a follow-up turn, all on the same SSE connection. If you'd rather drive the resume out-of-band, call `mastra.backgroundTaskManager.resume(taskId, resumeData)` directly and the result still writes into the thread for the next user turn to pick up.
+When a task suspends mid-`stream()` with `untilIdle`, the wrapper treats it as terminal for the current iteration and closes. To continue the agent immediately when the resume payload is in hand, call `agent.resumeStream(resumeData, { runId, toolCallId, memory, untilIdle: true })`: the resumed bg task runs to completion and adds its result to the message list. The agent then runs a follow-up turn, all on the same SSE connection. If you'd rather drive the resume out-of-band, call `mastra.backgroundTaskManager.resume(taskId, resumeData)` directly and the result still writes into the thread for the next user turn to pick up.
 ### Re-registering the executor on resume

package/dist/docs/references/docs-long-running-agents-goals.md CHANGED Viewed

@@ -114,5 +114,6 @@ Per-objective values written by `setObjective` / `updateObjectiveOptions` take p
 ## Related
 - [Supervisor agents](https://mastra.ai/docs/capabilities/subagents): `isTaskComplete` and the rubric scorer
-- [Signal providers](https://mastra.ai/docs/long-running-agents/signal-providers): how the objective is projected into context
-- [Memory storage](https://mastra.ai/docs/storage/overview): the storage backend goals require
+- [Signal providers](https://mastra.ai/docs/long-running-agents/signal-providers): How the objective is projected into context
+- [Memory storage](https://mastra.ai/docs/storage/overview): The storage backend goals require
+- [Mastra Factory](https://factory.mastra.ai) and [Mastra Code](https://code.mastra.ai): Examples of goal-driven coding agents

package/dist/docs/references/docs-memory-memory-processors.md CHANGED Viewed

@@ -163,7 +163,7 @@ const agent = new Agent({
 ## Manual control and deduplication
-If you manually add a memory processor to `inputProcessors` or `outputProcessors`, Mastra **won't** automatically add it. This gives you full control over processor ordering:
+If you manually add a memory processor to `inputProcessors` or `outputProcessors`, Mastra **won't** automatically add it. Manual configuration gives you full control over processor ordering:
 ```typescript
 import { Agent } from '@mastra/core/agent'

package/dist/docs/references/docs-memory-message-history.md CHANGED Viewed

@@ -117,7 +117,7 @@ await agent.stream('Hello', {
 You can use this history in two ways:
-- **Automatic inclusion**: Mastra automatically fetches and includes recent messages in the context window. By default, it includes the last 10 messages, keeping agents grounded in the conversation. You can adjust this number with `lastMessages`, but in most cases you don't need to think about it.
+- **Automatic inclusion**: Mastra automatically fetches recent messages and includes them in the context window. By default, the last 10 messages keep agents grounded in the conversation. You can adjust this number with `lastMessages`, but in most cases you don't need to think about it.
 - [**Manual querying**](#querying): For more control, use the `recall()` function to query threads and messages directly. This lets you choose exactly which memories are included in the context window, or fetch messages to render conversation history in your UI.
 > **Tip:** When memory is enabled, [Studio](https://mastra.ai/docs/studio/overview) uses message history to display past conversations in the chat sidebar.
@@ -339,7 +339,7 @@ const { thread, clonedMessages } = await memory.cloneThread({
 })
 ```
-You can filter which messages get cloned (by count or date range), specify custom thread IDs, and use utility methods to inspect clone relationships.
+You can filter cloned messages by count or date range and specify custom thread IDs. Utility methods are also available to inspect clone relationships.
 See [`cloneThread()`](https://mastra.ai/reference/memory/cloneThread) and [clone utilities](https://mastra.ai/reference/memory/clone-utilities) for the full API.

package/dist/docs/references/docs-memory-observational-memory.md CHANGED Viewed

@@ -418,7 +418,7 @@ With default settings, the context window doesn't grow unbounded. It oscillates
 3. **Repeat**: History grows from \~6k back toward 30k and shrinks again. Each cycle appends to the observation log, which grows much more slowly than raw history.
 4. **Observations reach 40k**: The Reflector creates a smaller log from the current observations and any earlier reflections.
-In the normal buffered cycle, raw history oscillates between roughly 6k and 30k tokens. The observation log stays around 40k tokens, however long the conversation runs. These are activation thresholds rather than hard caps. If background buffering doesn't keep pace, history can grow past the threshold until `blockAfter` (default `1.2`) forces a synchronous observation at \~36k tokens (\~48k for reflection) as a safety ceiling.
+In the normal buffered cycle, raw history oscillates between roughly 6k and 30k tokens. The observation log stays around 40k tokens, however long the conversation runs. These are activation thresholds rather than hard caps, so history can grow past the threshold whenever background buffering doesn't keep pace. Above `blockAfter` (default `1.2`, \~36k tokens) activation is allowed to overshoot the retention target instead of activating fewer chunks. It doesn't drain the buffer, and with the default settings it removes the same amount of history as below the threshold. Reflection falls back to a synchronous run above its own `blockAfter` (\~48k tokens).
 With [`shareTokenBudget`](https://mastra.ai/reference/memory/observational-memory) enabled, the two budgets pool together. While the observation log is small, message history can expand into the unused observation space (up to \~70k tokens with the defaults) before observation triggers. It then shrinks as observations accumulate.
@@ -714,23 +714,23 @@ When message tokens reach the `messageTokens` threshold, buffered chunks activat
 Buffered observations also include continuation hints, a suggested next response and the current task, so the main agent maintains conversational continuity after activation shrinks the context window.
-If the agent produces messages faster than the Observer can process them, a `blockAfter` safety threshold forces a synchronous observation as a last resort. Buffered activation still preserves a minimum remaining context (the smaller of \~1k tokens or the configured retention floor).
+If the agent produces messages faster than the Observer can process them, the `blockAfter` safety threshold lets activation overshoot the retention target instead of activating fewer chunks. It never activates more chunks than are needed to reach that target, and with the default settings it changes nothing. A synchronous observation runs when the `messageTokens` threshold is reached and buffered activation didn't happen. Buffered activation usually preserves a minimum remaining context (the smaller of \~1k tokens or the configured retention floor), but a single buffered chunk that covers the whole pending window still activates and can leave less.
 Reflection works similarly, the Reflector runs in the background when observations reach a fraction of the reflection threshold.
 ### Settings
-| Setting                               | Default | What it controls                                                                                                                                                                                                                                                              |
-| ------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `observation.bufferTokens`            | `0.2`   | How often to buffer. `0.2` means every 20% of `messageTokens`. With the default 30k threshold, that's roughly every 6k tokens. Can also be an absolute token count (e.g. `5000`).                                                                                             |
-| `observation.bufferActivation`        | `0.8`   | How aggressively to clear the message window on activation. `0.8` means remove enough messages to keep only 20% of `messageTokens` remaining. Lower values keep more message history.                                                                                         |
-| `observation.blockAfter`              | `1.2`   | Safety net if buffering can't keep up. Values from 1 up to (but not including) 100 multiply `messageTokens`: at `1.2`, synchronous observation is forced at 36k tokens (1.2 × 30k). Values of 100 or more are absolute token counts (e.g. `50_000`).                          |
-| `activateAfterIdle`                   | none    | Forces buffered observations to activate after a period of inactivity, even before `observation.messageTokens` is reached. Accepts a numeric millisecond value such as `300_000`, duration strings like `"5m"` or `"1hr"`, or `"auto"` for a provider-aware prompt cache TTL. |
-| `activateOnProviderChange`            | `false` | Forces buffered observations to activate when the next step uses a different `provider/model` than the one that produced the latest assistant step. Use this when switching providers or models would invalidate prompt cache reuse.                                          |
-| `reflection.bufferActivation`         | `0.5`   | When to start background reflection. `0.5` means reflection begins when observations reach 50% of the `observationTokens` threshold.                                                                                                                                          |
-| `reflection.activateAfterIdle`        | none    | Opts buffered reflections into idle activation. Reflections don't inherit top-level `activateAfterIdle`.                                                                                                                                                                      |
-| `reflection.activateOnProviderChange` | `false` | Opts buffered reflections into provider-change activation. Reflections don't inherit top-level `activateOnProviderChange`.                                                                                                                                                    |
-| `reflection.blockAfter`               | `1.2`   | Safety threshold for reflection, same logic as observation.                                                                                                                                                                                                                   |
+| Setting                               | Default | What it controls                                                                                                                                                                                                                                                                                                                                                      |
+| ------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `observation.bufferTokens`            | `0.2`   | How often to buffer. `0.2` means every 20% of `messageTokens`. With the default 30k threshold, that's roughly every 6k tokens. Can also be an absolute token count (e.g. `5000`).                                                                                                                                                                                     |
+| `observation.bufferActivation`        | `0.8`   | How aggressively to clear the message window on activation. `0.8` means remove enough messages to keep only 20% of `messageTokens` remaining. Lower values keep more message history.                                                                                                                                                                                 |
+| `observation.blockAfter`              | `1.2`   | Safety net if buffering can't keep up. Values from 1 up to (but not including) 100 multiply `messageTokens`: at `1.2`, the threshold is 36k tokens (1.2 × 30k). Above it, activation may overshoot the retention target instead of activating fewer chunks. Values of 100 or more are absolute token counts (e.g. `50_000`) and must be greater than `messageTokens`. |
+| `activateAfterIdle`                   | none    | Forces buffered observations to activate after a period of inactivity, even before `observation.messageTokens` is reached. Accepts a numeric millisecond value such as `300_000`, duration strings like `"5m"` or `"1hr"`, or `"auto"` for a provider-aware prompt cache TTL.                                                                                         |
+| `activateOnProviderChange`            | `false` | Forces buffered observations to activate when the next step uses a different `provider/model` than the one that produced the latest assistant step. Use this when switching providers or models would invalidate prompt cache reuse.                                                                                                                                  |
+| `reflection.bufferActivation`         | `0.5`   | When to start background reflection. `0.5` means reflection begins when observations reach 50% of the `observationTokens` threshold.                                                                                                                                                                                                                                  |
+| `reflection.activateAfterIdle`        | none    | Opts buffered reflections into idle activation. Reflections don't inherit top-level `activateAfterIdle`.                                                                                                                                                                                                                                                              |
+| `reflection.activateOnProviderChange` | `false` | Opts buffered reflections into provider-change activation. Reflections don't inherit top-level `activateOnProviderChange`.                                                                                                                                                                                                                                            |
+| `reflection.blockAfter`               | `1.2`   | Safety threshold for reflection. Same value format as observation (absolute values must be greater than `observationTokens`), but above it reflection runs synchronously when no buffered reflection is ready to activate.                                                                                                                                            |
 If you're relying on prompt caching, set `activateAfterIdle` to `"auto"` or to a specific cache TTL. That way, once a thread has been idle long enough for the cache to expire, the next request can activate buffered observations first and send a smaller compressed context window.

package/dist/docs/references/docs-memory-semantic-recall.md CHANGED Viewed

@@ -270,7 +270,7 @@ Supported embedding models:
 - **OpenAI**: `text-embedding-3-small`, `text-embedding-3-large`, `text-embedding-ada-002`
 - **Google**: `gemini-embedding-001`
-- **OpenRouter**: Access embedding models from various providers
+- **OpenRouter**: Access embedding models from multiple providers
 ```ts
 import { Agent } from '@mastra/core/agent'

package/dist/docs/references/docs-memory-working-memory.md CHANGED Viewed

@@ -1,6 +1,6 @@
 > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-# Working Memory
+# Working memory
 While [message history](https://mastra.ai/docs/memory/message-history) and [semantic recall](https://mastra.ai/docs/memory/semantic-recall) help agents remember conversations, working memory allows them to maintain persistent information about users across interactions.
@@ -213,7 +213,7 @@ const paragraphMemory = new Memory({
 ## Structured working memory
-Working memory can also be defined using a structured schema instead of a Markdown template. This allows you to specify the exact fields and types that should be tracked, using a [Standard JSON Schema](https://standardschema.dev/json-schema) ([Zod](https://zod.dev/), [Valibot](https://valibot.dev/), [ArkType](https://arktype.io/), etc.). When using a schema, the agent will see and update working memory as a JSON object matching your schema.
+Working memory can also be defined using a structured schema instead of a Markdown template. A [Standard JSON Schema](https://standardschema.dev/json-schema) ([Zod](https://zod.dev/), [Valibot](https://valibot.dev/), [ArkType](https://arktype.io/), etc.). When using a schema, the agent will see and update working memory as a JSON object matching your schema.
 **Requirement:** You must specify either `template` or `schema`, but not both.

package/dist/docs/references/docs-storage-overview.md CHANGED Viewed

@@ -1,6 +1,6 @@
 > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-# Storage overview
+# Storage
 Storage is the persistence layer for the Mastra runtime. It keeps memory, workflow state, observability data, eval results, schedules, and long-running agent state available after a process restarts.
@@ -188,25 +188,26 @@ You can also route `observability` to a dedicated analytics backend. See the [ob
 ## Supported providers
-Each provider page includes installation instructions, configuration parameters, and usage examples:
+Each provider page includes installation instructions, configuration parameters, and usage examples. libSQL is the fastest path for local development because it doesn't require running a separate database server.
+- [Aurora DSQL](https://mastra.ai/integrations/databases/aurora-dsql)
+- [ClickHouse](https://mastra.ai/integrations/databases/clickhouse)
 - [Cloudflare D1](https://mastra.ai/integrations/databases/cloudflare-d1)
-- [Cloudflare KV & Durable Objects](https://mastra.ai/integrations/databases/cloudflare-kv)
+- [Cloudflare KV](https://mastra.ai/integrations/databases/cloudflare-kv)
 - [Convex](https://mastra.ai/integrations/databases/convex)
+- [DuckDB](https://mastra.ai/integrations/databases/duckdb)
 - [DynamoDB](https://mastra.ai/integrations/databases/dynamodb)
 - [Google Cloud Spanner](https://mastra.ai/integrations/databases/spanner)
 - [LanceDB](https://mastra.ai/integrations/databases/lancedb)
 - [libSQL](https://mastra.ai/integrations/databases/libsql)
-- [Microsoft SQL Server](https://mastra.ai/integrations/databases/mssql)
 - [MongoDB](https://mastra.ai/integrations/databases/mongodb)
+- [MSSQL](https://mastra.ai/integrations/databases/mssql)
 - [Neon Postgres](https://mastra.ai/integrations/databases/neon)
 - [OracleDB](https://mastra.ai/integrations/databases/oracledb)
 - [PostgreSQL](https://mastra.ai/integrations/databases/postgresql)
 - [Redis](https://mastra.ai/integrations/databases/redis)
 - [Upstash](https://mastra.ai/integrations/databases/upstash)
-> **Tip:** libSQL is the fastest path for local development because it doesn't require running a separate database server.
 ## Next steps
 - [Composite storage](https://mastra.ai/reference/storage/composite)

package/dist/docs/references/integrations-databases-postgresql.md CHANGED Viewed

@@ -521,11 +521,11 @@ const stats = await storage.db.one(`
 PostgreSQL offers different index types optimized for specific scenarios:
-| Index Type          | Best For                                | Storage    | Speed                      |
-| ------------------- | --------------------------------------- | ---------- | -------------------------- |
-| **btree** (default) | Range queries, sorting, general purpose | Moderate   | Fast                       |
-| **hash**            | Equality comparisons only               | Small      | Very fast for `=`          |
-| **gin**             | JSONB, arrays, full-text search         | Large      | Fast for contains          |
-| **gist**            | Geometric data, full-text search        | Moderate   | Fast for nearest-neighbor  |
-| **spgist**          | Non-balanced data, text patterns        | Small      | Fast for specific patterns |
-| **brin**            | Large tables with natural ordering      | Very small | Fast for ranges            |
+| Index Type          | Best For                                | Storage size | Speed                      |
+| ------------------- | --------------------------------------- | ------------ | -------------------------- |
+| **btree** (default) | Range queries, sorting, general purpose | Moderate     | Fast                       |
+| **hash**            | Equality comparisons only               | Small        | Very fast for `=`          |
+| **gin**             | JSONB, arrays, full-text search         | Large        | Fast for contains          |
+| **gist**            | Geometric data, full-text search        | Moderate     | Fast for nearest-neighbor  |
+| **spgist**          | Non-balanced data, text patterns        | Small        | Fast for specific patterns |
+| **brin**            | Large tables with natural ordering      | Very small   | Fast for ranges            |

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

@@ -87,7 +87,7 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
 **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. Currently only applied when using the standalone ObservationalMemory class; new Memory(...) applies the top-level activateOnProviderChange only.
-**observation.blockAfter** (`number`): Safety net that forces a synchronous (blocking) observation when background buffering can't keep up. Values from 1 up to (but not including) 100 are multipliers of messageTokens: 1.2 forces a blocking observation at 120% of the threshold (36k tokens with the default 30k). Values of 100 or more are absolute token counts and must be greater than messageTokens. Between messageTokens and blockAfter, only async buffering and activation run; buffered activation still preserves a minimum remaining context (the smaller of 1000 tokens or the retention floor). Only relevant when bufferTokens is set. Defaults to 1.2 when async buffering is enabled.
+**observation.blockAfter** (`number`): Safety net for when background buffering can't keep up. Values from 1 up to (but not including) 100 are multipliers of messageTokens: 1.2 resolves to 120% of the threshold (36k tokens with the default 30k). Values of 100 or more are absolute token counts and must be greater than messageTokens. Above this point, activation uses the smallest set of buffered chunks that reaches the retention target, even when that overshoots the target by more than the usual safeguard allows. It never activates more chunks than are needed to reach the retention target, so it removes only slightly more history than a normal activation. It changes the result only when the retention floor is above roughly 20,000 tokens; with the default bufferActivation (a 6k floor) it has no observable effect. Activation usually keeps a minimum remaining context (the smaller of 1000 tokens or the retention floor), but a single buffered chunk that covers the whole pending window still activates and can leave less. Crossing blockAfter does not trigger a blocking observation. A synchronous (blocking) observation runs when the messageTokens threshold is reached and buffered activation did not happen. 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.
@@ -353,7 +353,7 @@ export const agent = new Agent({
 Async buffering is **enabled by default**. It pre-computes observations in the background as the conversation grows: when the `messageTokens` threshold is reached, buffered observations activate instantly with no blocking LLM call.
-The lifecycle follows **buffer → activate → remove messages → repeat**. Background Observer calls run at `bufferTokens` intervals, each producing a chunk of observations. At threshold, chunks activate: observations move into the log, raw messages are removed from context. The `blockAfter` threshold forces a synchronous fallback if buffering can't keep up.
+The lifecycle follows **buffer → activate → remove messages → repeat**. Background Observer calls run at `bufferTokens` intervals, each producing a chunk of observations. At threshold, chunks activate: observations move into the log, raw messages are removed from context. Above the `blockAfter` threshold, activation may overshoot the retention target instead of activating fewer chunks. If the threshold is reached and no buffered chunk activates, a synchronous observation runs instead.
 Default settings:
@@ -383,7 +383,7 @@ export const agent = new Agent({
           bufferTokens: 5_000,
           // Activate to retain 30% of threshold
           bufferActivation: 0.7,
-          // Force synchronous observation at 1.5x threshold
+          // Above 1.5x the threshold, let activation overshoot the retention target
           blockAfter: 1.5,
         },
         reflection: {
@@ -787,6 +787,8 @@ Mastra also injects scope-aware usage instructions into the agent's context. For
 **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.
+**charOffset** (`number`): Character position to continue reading a truncated single part. Only applies with cursor and partIndex. When a part is larger than the token budget, the result includes nextCharOffset — pass that exact value here in the next call to read the following chunk. The chunks concatenate to the original part text. (Default: `0`)
 **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").
@@ -809,10 +811,16 @@ Mastra also injects scope-aware usage instructions into the agent's context. For
 **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. When a single part is itself too large, the partIndex result includes nextCharOffset for continuing within the part.
 **tokenOffset** (`number`): Approximate number of tokens that were trimmed when truncated is true.
+**charOffset** (`number`): On single-part results (partIndex), the character position this chunk starts at. 0 unless the call passed a charOffset.
+**nextCharOffset** (`number`): On single-part results, present when the part was truncated and more content remains. Pass this value as charOffset in the next call to continue reading from where this chunk ended.
+**note** (`string`): On truncated single-part results, the exact follow-up call for retrieving the next chunk.
 ### Returns (threads mode)
 **threads** (`string`): Formatted thread listing. Each thread shows its title, ID, and dates. The current thread is marked with ← current.

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

@@ -220,7 +220,7 @@ const results = await store.textQuery({
 ### `hybridQuery()`
-Runs a hybrid search that fuses vector similarity and full-text results using MongoDB's server-side `$rankFusion`. It requires MongoDB >= 8.0 and is generally available from 8.1. On 8.0.x, it may need a MongoDB support case to enable, and it runs where enabled, such as Atlas 8.0.x. A full-text search index must exist: it's auto-created for managed indexes, but for a bring-your-own collection you must call `createSearchIndex()` first (opt-in).
+Runs a hybrid search that fuses vector similarity and full-text results using MongoDB's server-side `$rankFusion`. It requires MongoDB >= 8.0 and is generally available from 8.1. On 8.0.x, it may require a MongoDB support case for enablement. It runs where enabled, including Atlas 8.0.x. A full-text search index must exist: it's auto-created for managed indexes, but for a bring-your-own collection you must call `createSearchIndex()` first (opt-in).
 **indexName** (`string`): Name of the Mastra index to search
@@ -276,7 +276,7 @@ interface IndexStats {
 Deletes a vector index. Behavior depends on how the index was created:
 - **Managed index** (created without `collectionName`): drops the entire collection and all its data.
-- **Bring-your-own index** (created with `collectionName`): drops the Atlas vectorSearch index and, if one was provisioned via `createSearchIndex()`, the companion full-text search index. The caller's operational collection and its documents are preserved. This store never drops a collection it didn't create.
+- **Bring-your-own index** (created with `collectionName`): drops the Atlas vectorSearch index. If `createSearchIndex()` provisioned a companion full-text search index, it drops that index too. The caller's operational collection and its documents are preserved. This store never drops a collection it didn't create.
 The BYO classification is recorded durably when the index is created, so it's applied correctly even by a different process (e.g. an index created by a setup job and later deleted by a long-lived service). Always pass the **logical index name** (the `indexName` used at `createIndex`), not the physical collection name.

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

@@ -350,7 +350,7 @@ The `PgVector` class exposes its underlying PostgreSQL connection pool as a publ
 pgVector.pool // instance of pg.Pool
 ```
-This enables advanced usage such as running direct SQL queries, managing transactions, or monitoring pool state. When using the pool directly:
+Direct pool access supports advanced operations such as direct SQL queries, transactions, or pool-state monitoring. When using the pool directly:
 - You are responsible for releasing clients (`client.release()`) after use.
 - The pool remains accessible after calling `disconnect()`, but new queries will fail.

package/dist/index.cjs CHANGED Viewed

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_src = require("./src-CTwoCwmY.cjs");
+const require_src = require("./src-b5E69E65.cjs");
 let _mastra_core_processors = require("@mastra/core/processors");
 exports.Extractor = require_src.Extractor;
 exports.Memory = require_src.Memory;

package/dist/index.js CHANGED Viewed

@@ -1,2 +1,2 @@
-import { C as WorkingMemoryExtractor, R as Extractor, S as deepMergeWorkingMemory, T as summarizeConversation, a as extractWorkingMemoryContent, c as WORKING_MEMORY_STATE_ID, d as getObservationsAsOf, i as WorkingMemory, l as WORKING_MEMORY_STATE_PROCESSOR_ID, n as MessageHistory, o as extractWorkingMemoryTags, r as SemanticRecall, s as removeWorkingMemoryTags, t as Memory, u as WorkingMemoryStateProcessor, w as SUMMARIZE_THREAD_DEFAULTS, x as ModelByInputTokens } from "./src-DGdlH4fo.js";
+import { C as WorkingMemoryExtractor, R as Extractor, S as deepMergeWorkingMemory, T as summarizeConversation, a as extractWorkingMemoryContent, c as WORKING_MEMORY_STATE_ID, d as getObservationsAsOf, i as WorkingMemory, l as WORKING_MEMORY_STATE_PROCESSOR_ID, n as MessageHistory, o as extractWorkingMemoryTags, r as SemanticRecall, s as removeWorkingMemoryTags, t as Memory, u as WorkingMemoryStateProcessor, w as SUMMARIZE_THREAD_DEFAULTS, x as ModelByInputTokens } from "./src-BYD6Wp5m.js";
 export { Extractor, Memory, MessageHistory, ModelByInputTokens, SUMMARIZE_THREAD_DEFAULTS, SemanticRecall, WORKING_MEMORY_STATE_ID, WORKING_MEMORY_STATE_PROCESSOR_ID, WorkingMemory, WorkingMemoryExtractor, WorkingMemoryStateProcessor, deepMergeWorkingMemory, extractWorkingMemoryContent, extractWorkingMemoryTags, getObservationsAsOf, removeWorkingMemoryTags, summarizeConversation };

package/dist/processors/index.cjs CHANGED Viewed

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_src = require("../src-CTwoCwmY.cjs");
+const require_src = require("../src-b5E69E65.cjs");
 exports.Extractor = require_src.Extractor;
 exports.ModelByInputTokens = require_src.ModelByInputTokens;
 exports.OBSERVATIONAL_MEMORY_DEFAULTS = require_src.OBSERVATIONAL_MEMORY_DEFAULTS;

package/dist/processors/index.js CHANGED Viewed

@@ -1,2 +1,2 @@
-import { A as extractCurrentTask, B as OBSERVATION_CONTEXT_INSTRUCTIONS, C as WorkingMemoryExtractor, D as OBSERVER_SYSTEM_PROMPT, E as TokenCounter, F as injectAnchorIds, H as OBSERVATION_CONTINUATION_HINT, I as parseAnchorId, L as stripEphemeralAnchorIds, M as hasCurrentTaskSection, N as optimizeObservationsForContext, O as buildObserverPrompt, P as parseObserverOutput, R as Extractor, T as summarizeConversation, V as OBSERVATION_CONTEXT_PROMPT, _ as reconcileObservationGroupsFromReflection, b as wrapInObservationGroup, d as getObservationsAsOf, f as ObservationalMemoryProcessor, g as parseObservationGroups, h as deriveObservationGroupProvenance, j as formatMessagesForObserver, k as buildObserverSystemPrompt, m as combineObservationGroupRanges, p as ObservationalMemory, v as renderObservationGroupsForReflection, x as ModelByInputTokens, y as stripObservationGroups, z as OBSERVATIONAL_MEMORY_DEFAULTS } from "../src-DGdlH4fo.js";
+import { A as extractCurrentTask, B as OBSERVATION_CONTEXT_INSTRUCTIONS, C as WorkingMemoryExtractor, D as OBSERVER_SYSTEM_PROMPT, E as TokenCounter, F as injectAnchorIds, H as OBSERVATION_CONTINUATION_HINT, I as parseAnchorId, L as stripEphemeralAnchorIds, M as hasCurrentTaskSection, N as optimizeObservationsForContext, O as buildObserverPrompt, P as parseObserverOutput, R as Extractor, T as summarizeConversation, V as OBSERVATION_CONTEXT_PROMPT, _ as reconcileObservationGroupsFromReflection, b as wrapInObservationGroup, d as getObservationsAsOf, f as ObservationalMemoryProcessor, g as parseObservationGroups, h as deriveObservationGroupProvenance, j as formatMessagesForObserver, k as buildObserverSystemPrompt, m as combineObservationGroupRanges, p as ObservationalMemory, v as renderObservationGroupsForReflection, x as ModelByInputTokens, y as stripObservationGroups, z as OBSERVATIONAL_MEMORY_DEFAULTS } from "../src-BYD6Wp5m.js";
 export { Extractor, ModelByInputTokens, OBSERVATIONAL_MEMORY_DEFAULTS, OBSERVATION_CONTEXT_INSTRUCTIONS, OBSERVATION_CONTEXT_PROMPT, OBSERVATION_CONTINUATION_HINT, OBSERVER_SYSTEM_PROMPT, ObservationalMemory, ObservationalMemoryProcessor, TokenCounter, WorkingMemoryExtractor, buildObserverPrompt, buildObserverSystemPrompt, combineObservationGroupRanges, deriveObservationGroupProvenance, extractCurrentTask, formatMessagesForObserver, getObservationsAsOf, hasCurrentTaskSection, injectAnchorIds, optimizeObservationsForContext, parseAnchorId, parseObservationGroups, parseObserverOutput, reconcileObservationGroupsFromReflection, renderObservationGroupsForReflection, stripEphemeralAnchorIds, stripObservationGroups, summarizeConversation, wrapInObservationGroup };

package/dist/processors/observational-memory/constants.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/processors/observational-memory/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;+BAiBjB,MAAM,GAAG,SAAS;mCACd,MAAM,GAAG,SAAS;;;;;;;;;;;;;;;;mCAiBlB,MAAM,GAAG,SAAS;;CAErC,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,kdAM+B,CAAC;AAE1E;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,gGAAgG,CAAC;AAExI;;;GAGG;AACH,eAAO,MAAM,gCAAgC,+oDAQyM,CAAC;AAEvP;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,GAAE,QAAQ,GAAG,UAAuB,EACzC,kBAAkB,CAAC,EAAE,MAAM,EAC3B,aAAa,UAAO,GACnB,MAAM,~~CA6FR~~"}
1	+ {"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/processors/observational-memory/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;+BAiBjB,MAAM,GAAG,SAAS;mCACd,MAAM,GAAG,SAAS;;;;;;;;;;;;;;;;mCAiBlB,MAAM,GAAG,SAAS;;CAErC,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,kdAM+B,CAAC;AAE1E;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,gGAAgG,CAAC;AAExI;;;GAGG;AACH,eAAO,MAAM,gCAAgC,+oDAQyM,CAAC;AAEvP;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,GAAE,QAAQ,GAAG,UAAuB,EACzC,kBAAkB,CAAC,EAAE,MAAM,EAC3B,aAAa,UAAO,GACnB,MAAM,CA+FR"}

package/dist/processors/observational-memory/observation-turn/step.d.ts CHANGED Viewed

@@ -46,7 +46,8 @@ export declare class ObservationStep {
     prepare(): Promise<StepContext>;
     /**
      * Run the full threshold observation pipeline:
-     * waitForBuffering → re-check → activate → reflect → blockAfter gate → observe
+     * waitForBuffering → re-check → activate → reflect → observe (sync fallback when
+     * buffered activation did not happen)
      */
     private runThresholdObservation;
 }

package/dist/processors/observational-memory/observation-turn/step.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"step.d.ts","sourceRoot":"","sources":["../../../../src/processors/observational-memory/observation-turn/step.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C;;;;;;GAMG;AACH,qBAAa,eAAe;IAWxB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM;IAX7B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,CAAc;IAC/B;;;;OAIG;IACH,OAAO,CAAC,qBAAqB,CAAS;gBAGnB,IAAI,EAAE,eAAe,EAC7B,UAAU,EAAE,MAAM;IAG7B,2CAA2C;IAC3C,IAAI,QAAQ,YAEX;IAED;;;;;;;;OAQG;IACH,MAAM;;;;IAIN,2EAA2E;IAC3E,IAAI,OAAO,IAAI,WAAW,CAGzB;IAED;;;;;;OAMG;IACG,OAAO,IAAI,OAAO,CAAC,WAAW,CAAC;IAoTrC~~;;;OAGG~~;YACW,uBAAuB;CAwItC"}
1	+ {"version":3,"file":"step.d.ts","sourceRoot":"","sources":["../../../../src/processors/observational-memory/observation-turn/step.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C;;;;;;GAMG;AACH,qBAAa,eAAe;IAWxB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM;IAX7B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,CAAc;IAC/B;;;;OAIG;IACH,OAAO,CAAC,qBAAqB,CAAS;gBAGnB,IAAI,EAAE,eAAe,EAC7B,UAAU,EAAE,MAAM;IAG7B,2CAA2C;IAC3C,IAAI,QAAQ,YAEX;IAED;;;;;;;;OAQG;IACH,MAAM;;;;IAIN,2EAA2E;IAC3E,IAAI,OAAO,IAAI,WAAW,CAGzB;IAED;;;;;;OAMG;IACG,OAAO,IAAI,OAAO,CAAC,WAAW,CAAC;IAoTrC;;;;OAIG;YACW,uBAAuB;CAwItC"}

package/dist/processors/observational-memory/types.d.ts CHANGED Viewed

@@ -152,14 +152,15 @@ export interface ObservationConfig {
      */
     activateOnProviderChange?: boolean;
     /**
-     * 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.
+     * Token threshold above which buffered activation is allowed to overshoot the
+     * retention target. Crossing `blockAfter` does not trigger a blocking observation;
+     * a synchronous observation runs when `messageTokens` is reached and buffered
+     * activation did not happen.
      *
      * Accepts either:
-     * - A multiplier (1 < value < 2): multiplied by `messageTokens`.
+     * - A multiplier (1 ≤ value < 100): multiplied by `messageTokens`.
      *   e.g. `blockAfter: 1.5` with `messageTokens: 20_000` → blocks at 30,000.
-     * - An absolute token count (≥ 2): must be greater than `messageTokens`.
+     * - An absolute token count (≥ 100): must be greater than `messageTokens`.
      *
      * Only relevant when `bufferTokens` is set.
      * If not set, synchronous observation is never used when async buffering is enabled.
@@ -261,14 +262,15 @@ export interface ReflectionConfig {
      */
     providerOptions?: ProviderOptions;
     /**
-     * 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.
+     * Token threshold above which synchronous reflection is used as a last resort.
+     * Between `observationTokens` and `blockAfter`, only async buffering/activation
+     * is used. Above `blockAfter`, a synchronous reflection runs when no buffered
+     * reflection is ready to activate.
      *
      * Accepts either:
-     * - A multiplier (1 < value < 2): multiplied by `observationTokens`.
+     * - A multiplier (1 ≤ value < 100): multiplied by `observationTokens`.
      *   e.g. `blockAfter: 1.5` with `observationTokens: 30_000` → blocks at 45,000.
-     * - An absolute token count (≥ 2): must be greater than `observationTokens`.
+     * - An absolute token count (≥ 100): must be greater than `observationTokens`.
      *
      * Only relevant when `bufferActivation` is set.
      * If not set, synchronous reflection is never used when async reflection is enabled.