@mastra/memory 1.2.0 → 1.3.0

package/dist/docs/SKILL.md

@@ -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.2.0"
+  version: "1.3.0"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,58 +1,70 @@
 {
-  "version": "1.2.0",
+  "version": "1.3.0",
   "package": "@mastra/memory",
   "exports": {
     "OBSERVATIONAL_MEMORY_DEFAULTS": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-5YW6JV6Y.js"
+      "implementation": "dist/chunk-F5P5HTMC.js"
+    },
+    "OBSERVATION_CONTEXT_INSTRUCTIONS": {
+      "types": "dist/processors/index.d.ts",
+      "implementation": "dist/chunk-F5P5HTMC.js"
+    },
+    "OBSERVATION_CONTEXT_PROMPT": {
+      "types": "dist/processors/index.d.ts",
+      "implementation": "dist/chunk-F5P5HTMC.js"
+    },
+    "OBSERVATION_CONTINUATION_HINT": {
+      "types": "dist/processors/index.d.ts",
+      "implementation": "dist/chunk-F5P5HTMC.js"
     },
     "OBSERVER_SYSTEM_PROMPT": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-5YW6JV6Y.js"
+      "implementation": "dist/chunk-F5P5HTMC.js"
     },
     "ObservationalMemory": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-5YW6JV6Y.js",
-      "line": 1283
+      "implementation": "dist/chunk-F5P5HTMC.js",
+      "line": 1294
     },
     "TokenCounter": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-5YW6JV6Y.js",
+      "implementation": "dist/chunk-F5P5HTMC.js",
       "line": 957
     },
     "buildObserverPrompt": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-5YW6JV6Y.js",
+      "implementation": "dist/chunk-F5P5HTMC.js",
       "line": 646
     },
     "buildObserverSystemPrompt": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-5YW6JV6Y.js",
+      "implementation": "dist/chunk-F5P5HTMC.js",
       "line": 405
     },
     "extractCurrentTask": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-5YW6JV6Y.js",
+      "implementation": "dist/chunk-F5P5HTMC.js",
       "line": 732
     },
     "formatMessagesForObserver": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-5YW6JV6Y.js",
+      "implementation": "dist/chunk-F5P5HTMC.js",
       "line": 492
     },
     "hasCurrentTaskSection": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-5YW6JV6Y.js",
+      "implementation": "dist/chunk-F5P5HTMC.js",
       "line": 720
     },
     "optimizeObservationsForContext": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-5YW6JV6Y.js",
+      "implementation": "dist/chunk-F5P5HTMC.js",
       "line": 743
     },
     "parseObserverOutput": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-5YW6JV6Y.js",
+      "implementation": "dist/chunk-F5P5HTMC.js",
       "line": 677
     },
     "extractWorkingMemoryContent": {
@@ -84,7 +96,7 @@
     "processors": {
       "index": "dist/processors/index.js",
       "chunks": [
-        "chunk-5YW6JV6Y.js"
+        "chunk-F5P5HTMC.js"
       ]
     }
   }

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

@@ -24,11 +24,21 @@ export const agent = new Agent({
 });
 ```
 
-That's it. The agent now has humanlike long-term memory that persists across conversations.
+That's it. The agent now has humanlike long-term memory that persists across conversations. Setting `observationalMemory: true` uses `google/gemini-2.5-flash` by default. To use a different model or customize thresholds, pass a config object instead:
+
+```typescript
+const memory = new Memory({
+  options: {
+    observationalMemory: {
+      model: "deepseek/deepseek-reasoner",
+    },
+  },
+});
+```
 
 See [configuration options](https://mastra.ai/reference/memory/observational-memory) for full API details.
 
-> **Note:** OM currently only supports `@mastra/pg`, `@mastra/libsql`, and `@mastra/mongodb` storage adapters. It also uses background agents for managing memory. The default model (configurable) is `google/gemini-2.5-flash` as it's the one we've tested the most.
+> **Note:** OM currently only supports `@mastra/pg`, `@mastra/libsql`, and `@mastra/mongodb` storage adapters. It uses background agents for managing memory. When using `observationalMemory: true`, the default model is `google/gemini-2.5-flash`. When passing a config object, a `model` must be explicitly set.
 
 ## Benefits
 
@@ -77,7 +87,9 @@ The result is a three-tier system:
 
 The Observer and Reflector run in the background. Any model that works with Mastra's model routing (e.g. `openai/...`, `google/...`, `deepseek/...`) can be used.
 
-The default is `google/gemini-2.5-flash` — it works well for both observation and reflection, and its 1M token context window gives the Reflector headroom.
+When using `observationalMemory: true`, the default model is `google/gemini-2.5-flash`. When passing a config object, a `model` must be explicitly set.
+
+We recommend `google/gemini-2.5-flash` — it works well for both observation and reflection, and its 1M token context window gives the Reflector headroom.
 
 We've also tested `deepseek`, `qwen3`, and `glm-4.7` for the Observer. For the Reflector, make sure the model's context window can fit all observations. Note that Claude 4.5 models currently don't work well as observer or reflector.
 
@@ -97,24 +109,40 @@ See [model configuration](https://mastra.ai/reference/memory/observational-memor
 
 ### Thread scope (default)
 
-Each thread has its own observations.
+Each thread has its own observations. This scope is well tested and works well as a general purpose memory system, especially for long horizon agentic use-cases.
 
 ```typescript
-observationalMemory: {
-  scope: "thread",
-}
+const memory = new Memory({
+  options: {
+    observationalMemory: {
+      model: "google/gemini-2.5-flash",
+      scope: "thread",
+    },
+  },
+});
 ```
 
-### Resource scope
+### Resource scope (experimental)
 
 Observations are shared across all threads for a resource (typically a user). Enables cross-conversation memory.
 
 ```typescript
-observationalMemory: {
-  scope: "resource",
-}
+const memory = new Memory({
+  options: {
+    observationalMemory: {
+      model: "google/gemini-2.5-flash",
+      scope: "resource",
+    },
+  },
+});
 ```
 
+Resource scope works, however it's marked as experimental for now until we prove task adherence/continuity across multiple ongoing simultaneous threads. As of today, you may need to tweak your system prompt to prevent one thread from continuing the work that another had already started (but hadn't finished).
+
+This is because in resource scope, each thread is a perspective on _all_ threads for the resource.
+
+For your use-case this may not be a problem, so your mileage may vary.
+
 > **Warning:** In resource scope, unobserved messages across _all_ threads are processed together. For users with many existing threads, this can be slow. Use thread scope for existing apps.
 
 ## Token Budgets
@@ -125,6 +153,7 @@ OM uses token thresholds to decide when to observe and reflect. See [token budge
 const memory = new Memory({
   options: {
     observationalMemory: {
+      model: "google/gemini-2.5-flash",
       observation: {
         // when to run the Observer (default: 30,000)
         messageTokens: 30_000,
@@ -134,12 +163,58 @@ const memory = new Memory({
         observationTokens: 40_000,
       },
       // let message history borrow from observation budget
+      // requires bufferTokens: false (temporary limitation)
       shareTokenBudget: false,
     },
   },
 });
 ```
 
+## Async Buffering
+
+Without async buffering, the Observer runs synchronously when the message threshold is reached — the agent pauses mid-conversation while the Observer LLM call completes. With async buffering (enabled by default), observations are pre-computed in the background as the conversation grows. When the threshold is hit, buffered observations activate instantly with no pause.
+
+### How it works
+
+As the agent converses, message tokens accumulate. At regular intervals (`bufferTokens`), a background Observer call runs without blocking the agent. Each call produces a "chunk" of observations that's stored in a buffer.
+
+When message tokens reach the `messageTokens` threshold, buffered chunks activate: their observations move into the active observation log, and the corresponding raw messages are removed from the context window. The agent never pauses.
+
+If the agent produces messages faster than the Observer can process them, a `blockAfter` safety threshold forces a synchronous observation as a last resort.
+
+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 threshold as a multiplier of `messageTokens`. At `1.2`, synchronous observation is forced at 36k tokens (1.2 × 30k). Only matters if buffering can't keep up.                  |
+| `reflection.bufferActivation`  | `0.5`   | When to start background reflection. `0.5` means reflection begins when observations reach 50% of the `observationTokens` threshold.                                                  |
+| `reflection.blockAfter`        | `1.2`   | Safety threshold for reflection, same logic as observation.                                                                                                                           |
+
+### Disabling
+
+To disable async buffering and use synchronous observation/reflection instead:
+
+```typescript
+const memory = new Memory({
+  options: {
+    observationalMemory: {
+      model: "google/gemini-2.5-flash",
+      observation: {
+        bufferTokens: false,
+      },
+    },
+  },
+});
+```
+
+Setting `bufferTokens: false` disables both observation and reflection async buffering. See [async buffering configuration](https://mastra.ai/reference/memory/observational-memory) for the full API.
+
+> **Note:** Async buffering is not supported with `scope: 'resource'`. It is automatically disabled in resource scope.
+
 ## Migrating existing threads
 
 No manual migration needed. OM reads existing messages and observes them lazily when thresholds are exceeded.

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

@@ -24,17 +24,15 @@ export const agent = new Agent({
 
 ## Configuration
 
-The `observationalMemory` option accepts `true`, `false`, or a configuration object.
-
-Setting `observationalMemory: true` enables it with all defaults. Setting `observationalMemory: false` or omitting it disables it.
+The `observationalMemory` option accepts `true`, a configuration object, or `false`. Setting `true` enables OM with `google/gemini-2.5-flash` as the default model. When passing a config object, a `model` must be explicitly set — either at the top level, or on `observation.model` and/or `reflection.model`.
 
 **enabled?:** (`boolean`): Enable or disable Observational Memory. When omitted from a config object, defaults to \`true\`. Only \`enabled: false\` explicitly disables it. (Default: `true`)
 
-**model?:** (`string | LanguageModel | DynamicModel | ModelWithRetries[]`): Model for both the Observer and Reflector agents. Sets the model for both at once. Cannot be used together with \`observation.model\` or \`reflection.model\` — an error will be thrown if both are set. (Default: `'google/gemini-2.5-flash'`)
+**model?:** (`string | LanguageModel | DynamicModel | ModelWithRetries[]`): Model for both the Observer and Reflector agents. Sets the model for both at once. Cannot be used together with \`observation.model\` or \`reflection.model\` — an error will be thrown if both are set. When using \`observationalMemory: true\`, defaults to \`google/gemini-2.5-flash\`. When passing a config object, this or \`observation.model\`/\`reflection.model\` must be set. Use \`"default"\` to explicitly use the default model (\`google/gemini-2.5-flash\`). (Default: `'google/gemini-2.5-flash' (when using observationalMemory: true)`)
 
-**scope?:** (`'resource' | 'thread'`): Memory scope for observations. \`'thread'\` keeps observations per-thread. \`'resource'\` shares observations across all threads for a resource, enabling cross-conversation memory. (Default: `'thread'`)
+**scope?:** (`'resource' | 'thread'`): Memory scope for observations. \`'thread'\` keeps observations per-thread. \`'resource'\` (experimental) shares observations across all threads for a resource, enabling cross-conversation memory. (Default: `'thread'`)
 
-**shareTokenBudget?:** (`boolean`): Share the token budget between messages and observations. When enabled, the total budget is \`observation.messageTokens + reflection.observationTokens\`. Messages can use more space when observations are small, and vice versa. This maximizes context usage through flexible allocation. (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. \*\*Note:\*\* \`shareTokenBudget\` is not yet compatible with async buffering. You must set \`observation: { bufferTokens: false }\` when using this option (this is a temporary limitation). (Default: `false`)
 
 **observation?:** (`ObservationalMemoryObservationConfig`): Configuration for the observation step. Controls when the Observer agent runs and how it behaves.
 
@@ -42,7 +40,7 @@ Setting `observationalMemory: true` enables it with all defaults. Setting `obser
 
 ### Observation config
 
-**model?:** (`string | LanguageModel | DynamicModel | ModelWithRetries[]`): Model for the Observer agent. Cannot be set if a top-level \`model\` is also provided. (Default: `'google/gemini-2.5-flash'`)
+**model?:** (`string | LanguageModel | DynamicModel | ModelWithRetries[]`): Model for the Observer agent. Cannot be set if a top-level \`model\` is also provided. If neither this nor the top-level \`model\` is set, falls back to \`reflection.model\`.
 
 **messageTokens?:** (`number`): Token count of unobserved messages that triggers observation. When unobserved message tokens exceed this threshold, the Observer agent is called. (Default: `30000`)
 
@@ -50,14 +48,24 @@ Setting `observationalMemory: true` enables it with all defaults. Setting `obser
 
 **modelSettings?:** (`ObservationalMemoryModelSettings`): Model settings for the Observer agent. (Default: `{ temperature: 0.3, maxOutputTokens: 100_000 }`)
 
+**bufferTokens?:** (`number | false`): Token interval for async background observation buffering. Can be an absolute token count (e.g. \`5000\`) or a fraction of \`messageTokens\` (e.g. \`0.25\` = buffer every 25% of threshold). When set, observations run in the background at this interval, storing results in a buffer. When the main \`messageTokens\` threshold is reached, buffered observations activate instantly without a blocking LLM call. Must resolve to less than \`messageTokens\`. Set to \`false\` to explicitly disable all async buffering (both observation and reflection). (Default: `0.2`)
+
+**bufferActivation?:** (`number`): Ratio (0-1) controlling how much of the message window to retain after activation. For example, \`0.8\` means activate enough to keep only 20% of \`messageTokens\` remaining. Higher values remove more message history per activation. (Default: `0.8`)
+
+**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. Accepts a multiplier (1 < value < 2, multiplied by \`messageTokens\`) or an absolute token count (≥ 2, must be greater than \`messageTokens\`). Only relevant when \`bufferTokens\` is set. Defaults to \`1.2\` when async buffering is enabled. (Default: `1.2 (when bufferTokens is set)`)
+
 ### Reflection config
 
-**model?:** (`string | LanguageModel | DynamicModel | ModelWithRetries[]`): Model for the Reflector agent. Cannot be set if a top-level \`model\` is also provided. (Default: `'google/gemini-2.5-flash'`)
+**model?:** (`string | LanguageModel | DynamicModel | ModelWithRetries[]`): Model for the Reflector agent. Cannot be set if a top-level \`model\` is also provided. If neither this nor the top-level \`model\` is set, falls back to \`observation.model\`.
 
 **observationTokens?:** (`number`): Token count of observations that triggers reflection. When observation tokens exceed this threshold, the Reflector agent is called to condense them. (Default: `40000`)
 
 **modelSettings?:** (`ObservationalMemoryModelSettings`): Model settings for the Reflector agent. (Default: `{ temperature: 0, maxOutputTokens: 100_000 }`)
 
+**bufferActivation?:** (`number`): Ratio (0-1) controlling when async reflection buffering starts. When observation tokens reach \`observationTokens \* bufferActivation\`, reflection runs in the background. On activation at the full threshold, the buffered reflection replaces the observations it covers, preserving any new observations appended after that range. (Default: `0.5`)
+
+**blockAfter?:** (`number`): Token threshold above which synchronous (blocking) reflection is forced. Between \`observationTokens\` and \`blockAfter\`, only async buffering/activation is used. Above \`blockAfter\`, a synchronous reflection runs as a last resort. Accepts a multiplier (1 < value < 2, multiplied by \`observationTokens\`) or an absolute token count (≥ 2, must be greater than \`observationTokens\`). Only relevant when \`bufferActivation\` is set. Defaults to \`1.2\` when async reflection is enabled. (Default: `1.2 (when bufferActivation is set)`)
+
 ### Model settings
 
 **temperature?:** (`number`): Temperature for generation. Lower values produce more consistent output. (Default: `0.3`)
@@ -66,7 +74,7 @@ Setting `observationalMemory: true` enables it with all defaults. Setting `obser
 
 ## Examples
 
-### Resource scope with custom thresholds
+### Resource scope with custom thresholds (experimental)
 
 ```typescript
 import { Memory } from "@mastra/memory";
@@ -79,6 +87,7 @@ export const agent = new Agent({
   memory: new Memory({
     options: {
       observationalMemory: {
+        model: "google/gemini-2.5-flash",
         scope: "resource",
         observation: {
           messageTokens: 20_000,
@@ -108,6 +117,7 @@ export const agent = new Agent({
         shareTokenBudget: true,
         observation: {
           messageTokens: 20_000,
+          bufferTokens: false, // required when using shareTokenBudget (temporary limitation)
         },
         reflection: {
           observationTokens: 80_000,
@@ -165,6 +175,305 @@ export const agent = new Agent({
 });
 ```
 
+### Async buffering
+
+Async buffering is **enabled by default**. It pre-computes observations in the background as the conversation grows — when the `messageTokens` threshold is reached, buffered observations activate instantly with no blocking LLM call.
+
+The lifecycle is: **buffer → activate → remove messages → repeat**. Background Observer calls run at `bufferTokens` intervals, each producing a chunk of observations. At threshold, chunks activate: observations move into the log, raw messages are removed from context. The `blockAfter` threshold forces a synchronous fallback if buffering can't keep up.
+
+Default settings:
+
+- `observation.bufferTokens: 0.2` — buffer every 20% of `messageTokens` (e.g. every \~6k tokens with a 30k threshold)
+- `observation.bufferActivation: 0.8` — on activation, remove enough messages to keep only 20% of the threshold remaining
+- `reflection.bufferActivation: 0.5` — start background reflection at 50% of observation threshold
+
+To customize:
+
+```typescript
+import { Memory } from "@mastra/memory";
+import { Agent } from "@mastra/core/agent";
+
+export const agent = new Agent({
+  name: "my-agent",
+  instructions: "You are a helpful assistant.",
+  model: "openai/gpt-5-mini",
+  memory: new Memory({
+    options: {
+      observationalMemory: {
+        model: "google/gemini-2.5-flash",
+        observation: {
+          messageTokens: 30_000,
+          // Buffer every 5k tokens (runs in background)
+          bufferTokens: 5_000,
+          // Activate to retain 30% of threshold
+          bufferActivation: 0.7,
+          // Force synchronous observation at 1.5x threshold
+          blockAfter: 1.5,
+        },
+        reflection: {
+          observationTokens: 60_000,
+          // Start background reflection at 50% of threshold
+          bufferActivation: 0.5,
+          // Force synchronous reflection at 1.2x threshold
+          blockAfter: 1.2,
+        },
+      },
+    },
+  }),
+});
+```
+
+To disable async buffering entirely:
+
+```typescript
+observationalMemory: {
+  model: "google/gemini-2.5-flash",
+  observation: {
+    bufferTokens: false,
+  },
+}
+```
+
+Setting `bufferTokens: false` disables both observation and reflection async buffering. Observations and reflections will run synchronously when their thresholds are reached.
+
+> **Note:** Async buffering is not supported with `scope: 'resource'` and is automatically disabled in resource scope.
+
+## Streaming data parts
+
+Observational Memory emits typed data parts during agent execution that clients can use for real-time UI feedback. These are streamed alongside the agent's response.
+
+### `data-om-status`
+
+Emitted once per agent loop step, before model generation. Provides a snapshot of the current memory state, including token usage for both context windows and the state of any async buffered content.
+
+```typescript
+interface DataOmStatusPart {
+  type: 'data-om-status';
+  data: {
+    windows: {
+      active: {
+        /** Unobserved message tokens and the threshold that triggers observation */
+        messages: { tokens: number; threshold: number };
+        /** Observation tokens and the threshold that triggers reflection */
+        observations: { tokens: number; threshold: number };
+      };
+      buffered: {
+        observations: {
+          /** Number of buffered chunks staged for activation */
+          chunks: number;
+          /** Total message tokens across all buffered chunks */
+          messageTokens: number;
+          /** Projected message tokens that would be removed if activation happened now (based on bufferActivation ratio and chunk boundaries) */
+          projectedMessageRemoval: number;
+          /** Observation tokens that will be added on activation */
+          observationTokens: number;
+          /** idle: no buffering in progress. running: background observer is working. complete: chunks are ready for activation. */
+          status: 'idle' | 'running' | 'complete';
+        };
+        reflection: {
+          /** Observation tokens that were fed into the reflector (pre-compression size) */
+          inputObservationTokens: number;
+          /** Observation tokens the reflection will produce on activation (post-compression size) */
+          observationTokens: number;
+          /** idle: no reflection buffered. running: background reflector is working. complete: reflection is ready for activation. */
+          status: 'idle' | 'running' | 'complete';
+        };
+      };
+    };
+    recordId: string;
+    threadId: string;
+    stepNumber: number;
+    /** Increments each time the Reflector creates a new generation */
+    generationCount: number;
+  };
+}
+```
+
+`buffered.reflection.inputObservationTokens` is the size of the observations that were sent to the Reflector. `buffered.reflection.observationTokens` is the compressed result — the size of what will replace those observations when the reflection activates. A client can use these two values to show a compression ratio.
+
+Clients can derive percentages and post-activation estimates from the raw values:
+
+```typescript
+// Message window usage %
+const msgPercent = status.windows.active.messages.tokens
+  / status.windows.active.messages.threshold;
+
+// Observation window usage %
+const obsPercent = status.windows.active.observations.tokens
+  / status.windows.active.observations.threshold;
+
+// Projected message tokens after buffered observations activate
+// Uses projectedMessageRemoval which accounts for bufferActivation ratio and chunk boundaries
+const postActivation = status.windows.active.messages.tokens
+  - status.windows.buffered.observations.projectedMessageRemoval;
+
+// Reflection compression ratio (when buffered reflection exists)
+const { inputObservationTokens, observationTokens } = status.windows.buffered.reflection;
+if (inputObservationTokens > 0) {
+  const compressionRatio = observationTokens / inputObservationTokens;
+}
+```
+
+### `data-om-observation-start`
+
+Emitted when the Observer or Reflector agent begins processing.
+
+**cycleId:** (`string`): Unique ID for this cycle — shared between start/end/failed markers.
+
+**operationType:** (`'observation' | 'reflection'`): Whether this is an observation or reflection operation.
+
+**startedAt:** (`string`): ISO timestamp when processing started.
+
+**tokensToObserve:** (`number`): Message tokens (input) being processed in this batch.
+
+**recordId:** (`string`): The OM record ID.
+
+**threadId:** (`string`): This thread's ID.
+
+**threadIds:** (`string[]`): All thread IDs in this batch (for resource-scoped).
+
+**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.
+
+**operationType:** (`'observation' | 'reflection'`): Type of operation that completed.
+
+**completedAt:** (`string`): ISO timestamp when processing completed.
+
+**durationMs:** (`number`): Duration in milliseconds.
+
+**tokensObserved:** (`number`): Message tokens (input) that were processed.
+
+**observationTokens:** (`number`): Resulting observation tokens (output) after the Observer compressed them.
+
+**observations?:** (`string`): The generated observations text.
+
+**currentTask?:** (`string`): Current task extracted by the Observer.
+
+**suggestedResponse?:** (`string`): Suggested response extracted by the Observer.
+
+**recordId:** (`string`): The OM record ID.
+
+**threadId:** (`string`): This thread's ID.
+
+### `data-om-observation-failed`
+
+Emitted when observation or reflection fails. The system falls back to synchronous processing.
+
+**cycleId:** (`string`): Matches the corresponding \`start\` marker.
+
+**operationType:** (`'observation' | 'reflection'`): Type of operation that failed.
+
+**failedAt:** (`string`): ISO timestamp when the failure occurred.
+
+**durationMs:** (`number`): Duration until failure in milliseconds.
+
+**tokensAttempted:** (`number`): Message tokens (input) that were attempted.
+
+**error:** (`string`): Error message.
+
+**observations?:** (`string`): Any partial content available for display.
+
+**recordId:** (`string`): The OM record ID.
+
+**threadId:** (`string`): This thread's ID.
+
+### `data-om-buffering-start`
+
+Emitted when async buffering begins in the background. Buffering pre-computes observations or reflections before the main threshold is reached.
+
+**cycleId:** (`string`): Unique ID for this buffering cycle.
+
+**operationType:** (`'observation' | 'reflection'`): Type of operation being buffered.
+
+**startedAt:** (`string`): ISO timestamp when buffering started.
+
+**tokensToBuffer:** (`number`): Message tokens (input) being buffered in this cycle.
+
+**recordId:** (`string`): The OM record ID.
+
+**threadId:** (`string`): This thread's ID.
+
+**threadIds:** (`string[]`): All thread IDs being buffered (for resource-scoped).
+
+**config:** (`ObservationMarkerConfig`): Snapshot of config at buffering time.
+
+### `data-om-buffering-end`
+
+Emitted when async buffering completes. The content is stored but not yet activated in the main context.
+
+**cycleId:** (`string`): Matches the corresponding \`buffering-start\` marker.
+
+**operationType:** (`'observation' | 'reflection'`): Type of operation that was buffered.
+
+**completedAt:** (`string`): ISO timestamp when buffering completed.
+
+**durationMs:** (`number`): Duration in milliseconds.
+
+**tokensBuffered:** (`number`): Message tokens (input) that were buffered.
+
+**bufferedTokens:** (`number`): Observation tokens (output) after the Observer compressed them.
+
+**observations?:** (`string`): The buffered content.
+
+**recordId:** (`string`): The OM record ID.
+
+**threadId:** (`string`): This thread's ID.
+
+### `data-om-buffering-failed`
+
+Emitted when async buffering fails. The system falls back to synchronous processing when the threshold is reached.
+
+**cycleId:** (`string`): Matches the corresponding \`buffering-start\` marker.
+
+**operationType:** (`'observation' | 'reflection'`): Type of operation that failed.
+
+**failedAt:** (`string`): ISO timestamp when the failure occurred.
+
+**durationMs:** (`number`): Duration until failure in milliseconds.
+
+**tokensAttempted:** (`number`): Message tokens (input) that were attempted to buffer.
+
+**error:** (`string`): Error message.
+
+**observations?:** (`string`): Any partial content.
+
+**recordId:** (`string`): The OM record ID.
+
+**threadId:** (`string`): This thread's ID.
+
+### `data-om-activation`
+
+Emitted when buffered observations or reflections are activated (moved into the active context window). This is an instant operation — no LLM call is involved.
+
+**cycleId:** (`string`): Unique ID for this activation event.
+
+**operationType:** (`'observation' | 'reflection'`): Type of content activated.
+
+**activatedAt:** (`string`): ISO timestamp when activation occurred.
+
+**chunksActivated:** (`number`): Number of buffered chunks activated.
+
+**tokensActivated:** (`number`): Message tokens (input) from activated chunks. For observation activation, these are removed from the message window. For reflection activation, this is the observation tokens that were compressed.
+
+**observationTokens:** (`number`): Resulting observation tokens after activation.
+
+**messagesActivated:** (`number`): Number of messages that were observed via activation.
+
+**generationCount:** (`number`): Current reflection generation count.
+
+**observations?:** (`string`): The activated observations text.
+
+**recordId:** (`string`): The OM record ID.
+
+**threadId:** (`string`): This thread's ID.
+
+**config:** (`ObservationMarkerConfig`): Snapshot of config at activation time.
+
 ## Standalone usage
 
 Most users should use the `Memory` class above. Using `ObservationalMemory` directly is mainly useful for benchmarking, experimentation, or when you need to control processor ordering with other processors (like [guardrails](https://mastra.ai/docs/agents/guardrails)).