Observational Memory
Added in: @mastra/memory@1.1.0
Observational Memory (OM) is Mastra's memory system for long-context agentic memory. An Observer watches conversations and creates observations, which a Reflector restructures by combining related items and condensing overarching patterns. Together, they maintain an observation log that replaces raw message history as it grows.
UsageDirect link to Usage
import { Memory } from '@mastra/memory'
import { Agent } from '@mastra/core/agent'
export const agent = new Agent({
id: 'my-agent',
name: 'my-agent',
instructions: 'You are a helpful assistant.',
model: 'openai/gpt-6-luna',
memory: new Memory({
options: {
observationalMemory: true,
},
}),
})
ConfigurationDirect link to Configuration
The observationalMemory option accepts true, a configuration object, or false. Setting true enables OM with automatic model selection. When passing a config object, set model at the top level or on observation.model and/or reflection.model. When all model fields are omitted, each role defaults to 'auto'.
Observer input is multimodal-aware. OM keeps text placeholders like [Image #1: screenshot.png] in the transcript it builds for the Observer, and also sends the underlying image parts when possible. This applies to both single-thread observation and batched multi-thread observation. Non-image files appear as placeholders only.
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?:
true. Only enabled: false explicitly disables it.model?:
observation.model or reflection.model. When all model fields are omitted, each role defaults to "auto". Automatic selection prefers google/gemini-2.5-flash when GOOGLE_GENERATIVE_AI_API_KEY is configured, then a low-cost model for the active provider, then the active main model. Use "default" for the legacy fixed default.autoModels?:
{ openai: "__GATEWAY_OPENAI_MODEL_LUNA__" }. Providers not listed use the built-in pick.canUseProvider?:
'auto' prefers Gemini only when this returns true for 'google'. Use it when credentials are scoped per request, such as per tenant. When omitted, automatic selection checks GOOGLE_GENERATIVE_AI_API_KEY.resolveModel?:
"auto". When omitted, the picked ID goes through Mastra model routing.scope?:
'thread' keeps observations per-thread. 'resource' is deprecated and will be removed in a future release. It shares observations across all threads for a resource and works much worse than thread scope for prompt caching and agent understanding. For cross-thread continuity, use thread scope with retrieval. See resource scope (deprecated).activateAfterIdle?:
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, false to disable inherited observation idle activation, or an object of per-provider TTLs such as { default: "auto", anthropic: "1h" }. Object keys match the actor model provider before the first ., case-insensitively, so anthropic covers the direct Anthropic provider but not Claude through another provider such as amazon-bedrock; default covers every other provider. Reflections do not inherit this setting. Use reflection.activateAfterIdle to opt reflections into idle activation.activateOnProviderChange?:
reflection.activateOnProviderChange to opt reflections into provider-change activation.temporalMarkers?:
retrieval?:
recall tool is registered so the agent can browse them. true enables cross-thread browsing by default. { vector: true } also enables semantic search using Memory's vector store and embedder. A vector store that generates embeddings itself needs no embedder. { scope: 'thread' } restricts the recall tool to the current thread only. Default scope is 'resource'. { instructions: '...' } appends application-specific recall guidance after Mastra's built-in retrieval instructions.hooks?:
observe()/reflect() APIs, turn-driven synchronous observation, and fire-and-forget async buffering. Callbacks receive threadId/resourceId/trigger call context ('manual' | 'turn-sync' | 'async-buffer'), and the end hooks (onObservationEnd/onReflectionEnd) additionally receive the OM model call's token usage and providerMetadata (where providers such as the AI Gateway report per-call cost), so apps can account for OM model spend without wrapping the observer/reflector models in middleware. Config-level lifecycle hooks are non-blocking by default: their errors are logged without failing the cycle. With hookExecution: 'await', config-level lifecycle errors can reject observe() or reflect(). Per-call observe({ hooks }) lifecycle hooks are also awaited and can reject observe(). A failing awaited start hook skips the model call; an end-hook failure can reject the call after its work has completed. Async-buffered cycles always use non-blocking config-level lifecycle hooks, regardless of hookExecution. Their cycle failures are reported through onObservationEnd.error or onReflectionEnd.error, rather than thrown to the caller. ObserveHooks also accepts transform hooks that intercept and can replace cycle data: beforeObservation({ messages, ...context }) runs on the messages about to be observed (return { messages } to filter/redact; an empty array skips the Observer call), afterObservation({ observations, ...context }) runs on the Observer's output before it is persisted, beforeReflection({ observations, ...context }) runs on the text sent to the Reflector, and afterReflection({ observations, ...context }) runs on the Reflector's output before it is persisted. Transform hooks return void to pass data through unchanged and are always awaited on every path. A thrown error fails the cycle before committing its transformed observation or reflection text, but doesn't roll back extractor callbacks or other side effects that already ran. The after hooks replace only text, not the separate structured extractor results stored in thread metadata. Reflection extraction and its callbacks run before afterReflection; this hook neither recomputes extracted values nor reruns callbacks. After hooks aren't a redaction boundary for all cycle data.observation?:
model?:
'auto', each observation uses the Gemini default when GOOGLE_GENERATIVE_AI_API_KEY is set, otherwise a low-cost model for the calling agent's effective provider, then the calling model or configured model instance. 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.instruction?:
continuationHints?:
false to disable both, or an object to disable them individually. Agents that drive their own control flow generally want { suggestedResponse: false } so memory does not compete for what the agent says next. A previously stored hint stops being injected into context once both observation and reflection disable its section.threadTitle?:
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.extract?:
manageWorkingMemory?:
WorkingMemoryExtractor, defaults workingMemory.agentManaged to false, and defaults workingMemory.useStateSignals to true. See Let the Observer manage working memory.observeAttachments?:
['image/*', 'application/pdf']. true forwards all attachments. false drops all attachments while keeping placeholders visible. 'auto' uses the provider capabilities registry to decide: attachments are forwarded when the Observer model supports multimodal input, dropped otherwise, and forwarded when no capability data is available for the model. 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, or when you only want specific file types forwarded. Tool-result attachments are filtered using the same rule.maxRetries?:
failurePolicy?:
om_buffering_failed and never stop the turn. 'abort' aborts the agent turn. 'continue' emits the existing failure diagnostic, keeps the failed input pending for a later cycle, and allows the main agent turn to continue. Persistence, indexing, transform, locking, invariant, and explicit abort failures remain fatal. This setting doesn't prevent the underlying provider error or change blockAfter or attachment handling, and it has no backstop for a sustained outage: pending messages keep accruing in the main agent's context until they reach the model's context limit.messageTokens?:
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.maxTokensPerBatch?:
modelSettings?:
temperature: 0.3 default is only applied when the resolved model is known to support temperature. The maxOutputTokens: 100_000 default is only applied with default model selection (no model set, "default", or a ModelByInputTokens selector). Custom models get no maxOutputTokens default.temperature?:
0.3 default is only applied when the resolved model is known to support temperature.maxOutputTokens?:
100000 default is only applied with default model selection; custom models get no default.providerOptions?:
bufferTokens?:
0 and 1 are fractions of messageTokens: 0.25 buffers every 25% of the threshold (7.5k tokens with the default 30k). Values of 1 or more are absolute token counts: 5000 buffers every 5k tokens. Buffered observations are stored until the messageTokens threshold is reached, then activate instantly without a blocking LLM call. Must resolve to less than messageTokens. Set to false to disable all async buffering (both observation and reflection).bufferOnIdle?:
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.observeOnContextOverflow?:
messageTokens threshold is reached. When this happens, Observational Memory activates buffered observations, observes every pending message regardless of the threshold, and retries the request once with the smaller context. Set to false to let the error reach the caller instead.bufferActivation?:
0 and 1 are the fraction of messageTokens to remove: 0.8 removes ~80% of the message history and keeps ~20% (6k tokens with the default 30k). Values of 1000 or more are the token count to keep: 4000 keeps ~4k message tokens after activation. Note the direction flips: a higher ratio removes more history, while a higher token count keeps more.activateAfterIdle?:
"auto" for a provider-aware prompt cache TTL, false, or an object of per-provider TTLs. An object replaces the top-level value and is not merged with it. If unset, the top-level activateAfterIdle value is used for observations. Set false to disable the top-level idle setting for observations. Currently only applied when using the standalone ObservationalMemory class; new Memory(...) applies the top-level activateAfterIdle only.activateOnProviderChange?:
activateOnProviderChange value is used for observations. Currently only applied when using the standalone ObservationalMemory class; new Memory(...) applies the top-level activateOnProviderChange only.blockAfter?:
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). Multipliers apply to a per-thread messageTokens override when one is set. 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: reaching the threshold without a buffered chunk to activate starts background buffering, and the chunk activates on a later step. A synchronous (blocking) observation runs if pending tokens still reach blockAfter after buffered activation. All remaining buffered chunks are activated first, so the synchronous observation only covers messages no chunk has observed. Set blockAfter: 1 to observe synchronously at messageTokens. Above this point, activation also 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. Only relevant when bufferTokens is set. Defaults to 1.2 when async buffering is enabled.previousObserverTokens?:
0 to omit previous observations entirely, or false to disable truncation explicitly.reflection?:
model?:
'auto', each reflection uses the Gemini default when GOOGLE_GENERATIVE_AI_API_KEY is set, otherwise a low-cost model for the calling agent's effective provider, then the calling model or configured model instance. 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.maxRetries?:
failurePolicy?:
om_buffering_failed and never stop the turn. 'abort' aborts the agent turn. 'continue' emits the failure diagnostic and allows the turn to continue, leaving already-persisted observations committed and deferring reflection to the next threshold crossing. A provider outage usually takes out both stages, so set the policy on observation too if the turn should survive one.instruction?:
continuationHints?:
false to disable both, or an object to disable them individually. A previously stored hint stops being injected into context once both observation and reflection disable its section.extract?:
observationTokens?:
modelSettings?:
temperature: 0 default is only applied when the resolved model is known to support temperature. The maxOutputTokens: 100_000 default is only applied with default model selection (no model set, "default", or a ModelByInputTokens selector). Custom models get no maxOutputTokens default.temperature?:
0 default is only applied when the resolved model is known to support temperature.maxOutputTokens?:
100000 default is only applied with default model selection; custom models get no default.providerOptions?:
bufferActivation?:
observationTokens: 0.5 starts reflecting in the background once observations reach 50% of the threshold (20k tokens with the default 40k). When the full threshold is reached, the buffered reflection replaces the observations it covers, preserving any new observations appended after that range.activateAfterIdle?:
"auto" for a provider-aware prompt cache TTL, false, or an object of per-provider TTLs. Reflections do not inherit top-level activateAfterIdle; set this explicitly to opt reflections into idle activation. Currently only applied when using the standalone ObservationalMemory class; this setting has no effect through new Memory(...).activateOnProviderChange?:
activateOnProviderChange; set this explicitly to opt reflections into provider-change activation. Currently only applied when using the standalone ObservationalMemory class; this setting has no effect through new Memory(...).blockAfter?:
1 up to (but not including) 100 are multipliers of observationTokens: 1.2 forces a blocking reflection at 120% of the threshold (48k tokens with the default 40k). Values of 100 or more are absolute token counts and must be greater than observationTokens. Between observationTokens and blockAfter, only async buffering and activation run. Only relevant when bufferActivation is set. Defaults to 1.2 when async reflection is enabled.Extractor APIDirect link to Extractor API
Extractor defines a value that OM should extract during observation or reflection. Built-in OM values such as current-task, suggested-response, and thread-title use the same extractor pipeline as custom values.
import { Memory, Extractor } from '@mastra/memory'
import { z } from 'zod'
const memory = new Memory({
options: {
observationalMemory: {
model: 'openai/gpt-6-luna',
observation: {
extract: [
new Extractor({
name: 'User profile',
instructions: 'Extract stable user profile facts that should be remembered.',
schema: z.object({
name: z.string().optional(),
timezone: z.string().optional(),
}),
}),
],
},
},
},
})
name:
slug:
name — not a constructor option. Generated stable identifier for persisted values and XML tags. Slugs use lowercase letters, numbers, and hyphens. Built-in slugs and reserved XML tags cannot be used by custom extractors.instructions:
schema?:
includePreviousExtraction?:
false for values that should only come from the current OM run.metadataKeyPath?:
false to skip OM metadata persistence entirely.onExtracted?:
Extraction behaviorDirect link to Extraction behavior
- Extracted values are stored in thread OM metadata under
om.extracted. - Built-in extractor values are also mirrored to the compatibility metadata fields
currentTask,suggestedResponse, andthreadTitle. thread-titleupdates the thread title only whenobservation.threadTitleis enabled.observation.extractruns during observation.reflection.extractruns during reflection.- Schema-backed extractors add a follow-up structured output request.
- Schema-less extractors are inline string extractors emitted directly in the Observer or Reflector output.
- Dynamic extractor functions receive runtime context, including
source,threadId,resourceId,mainAgent,memory, andrequestContextwhen available. WorkingMemoryExtractoruses the normal extractor pipeline to update working memory through the activeMemoryinstance. It uses structured extraction when working memory has a JSON schema and skips OM metadata persistence, so the working memory payload isn't duplicated under OM extracted metadata.- When
workingMemory.schemais set,WorkingMemoryExtractorvalidates each update against that schema before saving it. If an update doesn't match, it's skipped and reported as an extraction failure while the previous working memory stays in place. Because the schema isn't sent to the model as a structured output constraint, one invalid working memory update can't fail other extractors. Anullin an optional field is treated as not provided. observationalMemory.observation.manageWorkingMemoryaddsWorkingMemoryExtractorand defaultsworkingMemory.agentManagedtofalse. It defaultsworkingMemory.useStateSignalstotruewhen working memory is enabled.- Extraction failures are reported in OM marker data and don't discard other successful extracted values.
ExamplesDirect link to Examples
Thresholds, instructions and bufferingDirect link to Thresholds, instructions and buffering
One config that sets the main tuning options together. Every field is optional.
import { Memory } from '@mastra/memory'
import { Agent } from '@mastra/core/agent'
export const agent = new Agent({
id: 'health-assistant',
name: 'health-assistant',
instructions: 'You are a health and wellness assistant.',
model: 'openai/gpt-6.1-sol',
memory: new Memory({
options: {
observationalMemory: {
model: 'auto',
observation: {
messageTokens: 20_000,
bufferTokens: 5_000,
bufferActivation: 0.7,
blockAfter: 1.5,
instruction:
'Prioritize health goals, dietary restrictions and exercise preferences. Skip general chit-chat.',
},
reflection: {
observationTokens: 60_000,
instruction:
'Group related health information together. Keep specific metrics and dates.',
},
},
},
}),
})
Different models per agentDirect link to Different models per agent
Set observation.model and reflection.model and leave the top-level model out. Setting the top-level model together with either one throws.
import { Memory } from '@mastra/memory'
import { Agent } from '@mastra/core/agent'
export const agent = new Agent({
id: 'my-agent',
name: 'my-agent',
instructions: 'You are a helpful assistant.',
model: 'openai/gpt-6.1-sol',
memory: new Memory({
options: {
observationalMemory: {
observation: {
model: 'auto',
},
reflection: {
model: 'openai/gpt-6-luna',
},
},
},
}),
})
Shared token budgetDirect link to Shared token budget
When shareTokenBudget is enabled, the total budget is observation.messageTokens + reflection.observationTokens, which is 100k in this example. Observations that use only 30k tokens leave up to 70k for messages, while short messages give observations more room before reflection starts. Shared budgets need async buffering turned off.
import { Memory } from '@mastra/memory'
import { Agent } from '@mastra/core/agent'
export const agent = new Agent({
id: 'my-agent',
name: 'my-agent',
instructions: 'You are a helpful assistant.',
model: 'openai/gpt-6-luna',
memory: new Memory({
options: {
observationalMemory: {
shareTokenBudget: true,
observation: {
messageTokens: 20_000,
bufferTokens: false,
},
reflection: {
observationTokens: 80_000,
},
},
},
}),
})
Async bufferingDirect link to Async buffering
Async buffering is on by default with these settings:
observation.bufferTokens: 0.2buffers every 20% ofmessageTokens.observation.bufferActivation: 0.8keeps 20% of the threshold after activation.reflection.bufferActivation: 0.5starts background reflection at half the reflection threshold.
Buffered Observer calls don't produce continuation hints, and activation clears stored ones. See When buffering falls behind for what happens between the threshold and blockAfter.
Set observation.bufferTokens: false to turn off buffering for both observation and reflection. Each then runs synchronously at its threshold.
observationalMemory: {
observation: {
bufferTokens: false,
},
}
Async buffering is off in the deprecated scope: 'resource'.
Early activationDirect link to Early activation
By default, buffered observations activate when message history reaches observation.messageTokens. OM can activate them sooner, which helps when a prompt cache is about to expire or when the agent switches model providers. In both cases the next request can't reuse the cached prompt anyway, so sending a smaller, compressed context costs nothing extra.
activateAfterIdle: activate after the thread has been idle for this long. Accepts milliseconds (300_000), a duration string ('5m','1hr'),'auto'for a provider-aware prompt cache TTL, or a per-provider object (see per-provider idle TTLs).activateOnProviderChange: activate when the next step uses a differentprovider/modelthan the one that produced the latest assistant step. Defaultfalse.
import { Memory } from '@mastra/memory'
const memory = new Memory({
options: {
observationalMemory: {
activateAfterIdle: 'auto',
activateOnProviderChange: true,
},
},
})
Top-level settings apply to observations only. Reflections opt in on their own, through the nested reflection settings:
import { Memory } from '@mastra/memory'
const memory = new Memory({
options: {
observationalMemory: {
activateAfterIdle: '5m',
observation: {
activateAfterIdle: false,
},
reflection: {
activateAfterIdle: '10m',
activateOnProviderChange: true,
},
},
},
})
Here observations ignore the top-level idle setting, while reflections opt into idle and provider-change activation.
Automatic idle TTLsDirect link to Automatic idle TTLs
With activateAfterIdle: 'auto', Mastra picks the idle TTL from the active model provider:
| Provider | Auto TTL |
|---|---|
| Anthropic, OpenRouter, unknown providers, xAI | 5 minutes |
| DeepSeek | 1 hour |
| Google Gemini | 24 hours |
| Groq | 2 hours |
OpenAI with providerOptions.openai.promptCacheRetention: "24h" | 1 hour |
OpenAI with providerOptions.openai.promptCacheRetention: "in_memory" | 5 minutes |
OpenAI gpt-4*, gpt-5, gpt-5-*, and gpt-5.1 through gpt-5.4 (including - suffixed variants) | 5 minutes |
| Other OpenAI models | 1 hour |
For a fixed TTL instead, use '5m' or 300_000.
Per-provider idle TTLsDirect link to Per-provider idle TTLs
'auto' can't see a cache TTL that you set on individual messages, such as Anthropic's cacheControl: { type: 'ephemeral', ttl: '1h' }. It keeps using the provider's 5-minute default, so buffered observations activate while the 1-hour cache is still warm. Pass an object to set the TTL per provider:
import { Memory } from '@mastra/memory'
const memory = new Memory({
options: {
observationalMemory: {
activateAfterIdle: { default: 'auto', anthropic: '1h' },
},
},
})
Set the anthropic entry to the same TTL as your cacheControl.ttl. Mastra doesn't read the per-message cache setting, so keep the two in sync by hand.
How the object resolves:
- Keys are provider names. Mastra compares them case-insensitively with the part of the model's provider before the first
., soanthropicmatches bothanthropicandanthropic.messages. Claude served through another provider uses that provider's key, for exampleamazon-bedrock. Keys must not contain.or/. - Each value accepts the same forms as a single TTL: milliseconds, a duration string,
'auto', orfalseto turn off idle activation for that provider. defaultapplies to every provider without its own key. Withoutdefault, those providers don't idle-activate.observation.activateAfterIdleandreflection.activateAfterIdleaccept the same object. Anobservation.activateAfterIdleobject replaces the top-level value and isn't merged with it.
Buffer on idleDirect link to Buffer on idle
Set observation.bufferOnIdle: true to run background observation buffering when an agent turn ends and the agent becomes idle. Short turns then get observed without waiting for the next turn or the messageTokens threshold.
import { Memory } from '@mastra/memory'
const memory = new Memory({
options: {
observationalMemory: {
observation: {
bufferOnIdle: true,
},
},
},
})
bufferOnIdle is off by default. It's separate from bufferTokens: bufferTokens controls buffering during steps, bufferOnIdle controls buffering at the end of an idle turn.
When buffering falls behindDirect link to When buffering falls behind
When messages arrive faster than the Observer can buffer them, history can pass messageTokens before a buffered chunk is ready. Between messageTokens and observation.blockAfter (default 1.2, so 36,000 tokens with the default threshold), Mastra keeps buffering in the background and activates the chunk on a later step, so the agent doesn't wait.
If pending tokens still reach blockAfter after buffered activation, for example when a large tool result leaves an uncovered tail, a synchronous observation runs. At blockAfter, activation first waits a bounded time for a buffered observation that's still being produced. If that takes longer, Mastra observes the remaining messages synchronously and drops the late observation if its messages are already observed. Activations triggered by the idle TTL or a provider change don't wait.
Above blockAfter, activation may overshoot the retention target instead of using fewer chunks. Buffered activation usually keeps a minimum remaining context (the smaller of about 1,000 tokens or the configured retention floor), but a single chunk that covers the whole pending window still activates and can leave less.
Async buffered Observer calls don't produce continuation hints, because a delayed hint can be stale by the time it activates. When buffered chunks activate, any stored suggested response and current task are cleared.
Reflection buffers the same way. It starts in the background when observations reach reflection.bufferActivation (default 0.5) of reflection.observationTokens, and runs synchronously above reflection.blockAfter (default 1.2) when no buffered reflection is ready.
Retries and failure policyDirect link to Retries and failure policy
Observer and Reflector model calls are retried on transient provider errors. Each stage has two settings:
maxRetries: retries after the first model call. Default8. This is the only retry setting for the stage: the underlying model call runs with no provider-level retries.failurePolicy: what happens once retries run out.'abort'(default) fails the turn, and'continue'lets it go on.
import { Memory } from '@mastra/memory'
const memory = new Memory({
options: {
observationalMemory: {
observation: {
maxRetries: 8,
failurePolicy: 'continue',
},
reflection: {
maxRetries: 8,
failurePolicy: 'continue',
},
},
},
})
A provider outage usually takes out both stages, so set the policy on both if you want the turn to survive one.
With 'continue', Mastra reports the failure through OM diagnostics, keeps the failed input pending for a later cycle, and lets the turn continue. It doesn't advance observation boundaries or discard unobserved messages. A Reflector failure leaves already-persisted observations committed and retries reflection at the next threshold crossing.
The policy covers only Observer and Reflector model and provider failures in synchronous runs: at blockAfter, when async buffering is off, and in resource-scoped observation. Persistence, indexing, transform, locking, invariant and explicit abort failures stay fatal.
Background buffering failures never stop the turn, whatever the policy. They're reported as om_buffering_failed, and the failed input stays pending. If it keeps growing, it reaches blockAfter, where synchronous observation applies failurePolicy.
'continue' has no backstop for a long outage. Unobserved messages stay pending and keep growing in the main agent's context until they reach the model's context limit.
Temporal gap markersDirect link to Temporal gap markers
Temporal gap markers insert a short reminder before a new user message when at least 10 minutes have passed since the previous message in the thread. They're off by default.
import { Memory } from '@mastra/memory'
const memory = new Memory({
options: {
observationalMemory: {
temporalMarkers: true,
},
},
})
The marker is stored in memory and also emitted as a transient reminder event, so clients can render it as a timeline hint. The Observer sees the markers too, so observations can say when something happened, for example "User asked about deployment after a 2-day gap".
Token estimatesDirect link to Token estimates
OM decides when to observe from local token estimates, not from the provider's usage report. Text is estimated with tokenx; images use provider-aware heuristics, which also apply to image-like file parts. Provider counts can run higher than the estimate, which is why context-overflow recovery exists.
Token-count cacheDirect link to Token-count cache
OM caches estimates in message metadata so threshold checks don't recount the same content:
- Per-part estimates are stored on
part.providerMetadata.mastraand reused while the cache version and tokenizer source match. - Messages with string-only content (no parts) use a message-level cache.
- Message and conversation overhead is recalculated every pass. Only payload estimates are cached.
data-*andreasoningparts are skipped and not cached.
Supplying your own estimate for a fileDirect link to Supplying your own estimate for a file
You can attach a token estimate to an image or file part with providerMetadata.mastra.tokenEstimate. The token counter uses it as is:
const filePart = {
type: 'file',
data: 'storage://bucket/large-report.pdf',
mimeType: 'application/pdf',
filename: 'large-report.pdf',
providerMetadata: {
mastra: {
tokenEstimate: {
v: 0,
source: 'client',
key: 'client',
tokens: 100_000,
},
},
},
}
v: cache schema version. Set it to0. OM doesn't read it for caller entries.source: must be'client'. This marks the entry as authoritative so it isn't recomputed or overwritten.key: set to'client'. Framework entries put a content hash here.'client'keeps your estimate stable across writes.tokens: the count to use. Must be a finite, non-negative number.
The estimate is honored only on image and file parts. text and tool-invocation parts are always counted.
Limiting what the Observer re-readsDirect link to Limiting what the Observer re-reads
By default the Observer receives the full observation log as context with every batch of new messages, plus the previous current-task and suggested-response values. When the log grows large, set observation.previousObserverTokens to cap it:
import { Memory } from '@mastra/memory'
const memory = new Memory({
options: {
observationalMemory: {
observation: {
previousObserverTokens: 10_000,
},
},
},
})
false(default): send the full log.- A number such as
2000: keep about that many tokens of the most recent observations. 0: send no previous observations.
When a buffered reflection is pending, the lines it already covers are replaced with the reflection before truncation.
Let the Observer manage working memoryDirect link to Let the Observer manage working memory
Set observation.manageWorkingMemory: true to have the Observer keep working memory up to date, instead of relying on the main agent to call the working memory tool.
import { Memory } from '@mastra/memory'
const memory = new Memory({
options: {
workingMemory: {
enabled: true,
},
observationalMemory: {
observation: {
manageWorkingMemory: true,
},
},
},
})
This adds a WorkingMemoryExtractor and changes two working memory defaults:
workingMemory.agentManageddefaults tofalse, so the main agent no longer gets the working memory tool and instructions. Set it totrueto keep them.workingMemory.useStateSignalsdefaults totrue, which moves working memory out of the system prompt into state signals so updates don't invalidate the prompt cache.
HooksDirect link to Hooks
observationalMemory.hooks takes two kinds of hooks:
- Lifecycle hooks (
onObservationStart,onObservationEnd,onReflectionStart,onReflectionEnd) are for telemetry. They receivethreadId,resourceIdandtrigger; the end hooks also receive the model call'susage,providerMetadataand anyerror. They never change what OM stores. - Transform hooks (
beforeObservation,afterObservation,beforeReflection,afterReflection) change the data flowing through a cycle. Return nothing to pass the input through, or return a replacement.
const memory = new Memory({
options: {
observationalMemory: {
hooks: {
// Drop or redact messages before the Observer sees them.
beforeObservation: ({ messages }) => ({
messages: messages.filter(m => !isSensitive(m)),
}),
// Rewrite observations before they are persisted.
afterObservation: ({ observations }) => ({
observations: redact(observations),
}),
// Rewrite the text the Reflector condenses.
beforeReflection: ({ observations }) => ({
observations: stripInternalNotes(observations),
}),
afterReflection: async ({ observations, resourceId }) => {
await syncToExternalStore(resourceId, observations)
},
},
},
},
})
Transform hooks are always awaited, on every path: manual observe() and reflect(), synchronous observation during a turn, and async buffering. If beforeObservation returns an empty messages array, the Observer call is skipped and those messages are still marked as observed. If a transform hook throws, the cycle fails before committing the transformed text. Extractor callbacks and other side effects that already ran aren't rolled back.
afterObservation and afterReflection replace only the observation or reflection text. They don't touch the structured extractor values stored in thread metadata, and reflection extraction runs before afterReflection. Don't treat an after hook as a redaction boundary for everything in the cycle.
Hooks receive threadId and resourceId, so they can also update working memory with memory.updateWorkingMemory(). Those updates aren't atomic with the OM commit.
To keep skill instructions out of the Observer, use skillResultRedactor.
Migrating existing threadsDirect link to Migrating existing threads
No migration is needed. OM reads existing messages and observes them when a thread first exceeds observation.messageTokens, processing the backlog then. Under the deprecated resource scope, all unobserved messages across a resource's threads are processed together, which can take a long time for users with many threads.
Streaming data partsDirect link to 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.
Read extractor resultsDirect link to Read extractor results
Both completion events carry extractor output in their data payload. The extractor fields are:
interface DataOmObservationEndPart {
type: 'data-om-observation-end'
data: {
/** Whether the completed work was an observation or reflection */
operationType: 'observation' | 'reflection'
/** Values extracted during this OM operation, keyed by extractor slug */
extractedValues?: Record<string, unknown>
/** Extractor failures from this OM operation. Successful extractor values are still included */
extractionFailures?: Array<{ slug: string; error: string }>
// ...other fields documented in the tables below
}
}
Both extractor fields are optional. A completion can include values, failures, both, or neither. data-om-observation-end reports synchronous completion. data-om-buffering-end reports completed background work whose buffered content still awaits activation, although extractor metadata is already persisted. DataOmBufferingEndPart carries the same extractor fields, and both types are exported from @mastra/memory/processors. See Read extracted values from a stream for a consumer example.
data-om-statusDirect link to 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.
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:
// 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-startDirect link to data-om-observation-start
Emitted when the Observer or Reflector agent begins processing.
cycleId:
operationType:
startedAt:
tokensToObserve:
recordId:
threadId:
threadIds:
config:
messageTokens, observationTokens, and scope at observation time.data-om-observation-endDirect link to data-om-observation-end
Emitted when observation or reflection completes successfully.
cycleId:
start marker.operationType:
completedAt:
durationMs:
tokensObserved:
observationTokens:
observations?:
currentTask?:
suggestedResponse?:
extractedValues?:
extractionFailures?:
recordId:
threadId:
data-om-observation-failedDirect link to data-om-observation-failed
Emitted when observation or reflection fails. The system falls back to synchronous processing.
cycleId:
start marker.operationType:
failedAt:
durationMs:
tokensAttempted:
error:
retrying?:
start marker follows, so this failure is not final. Absent on final failures.observations?:
recordId:
threadId:
data-om-buffering-startDirect link to 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:
operationType:
startedAt:
tokensToBuffer:
recordId:
threadId:
threadIds:
config:
data-om-buffering-endDirect link to data-om-buffering-end
Emitted when async buffering completes. The content is stored but not yet activated in the main context.
cycleId:
buffering-start marker.operationType:
completedAt:
durationMs:
tokensBuffered:
bufferedTokens:
observations?:
extractedValues?:
extractionFailures?:
recordId:
threadId:
data-om-buffering-failedDirect link to data-om-buffering-failed
Emitted when async buffering fails. The system falls back to synchronous processing when the threshold is reached.
cycleId:
buffering-start marker.operationType:
failedAt:
durationMs:
tokensAttempted:
error:
observations?:
recordId:
threadId:
data-om-activationDirect link to 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:
operationType:
activatedAt:
chunksActivated:
tokensActivated:
observationTokens:
messagesActivated:
generationCount:
observations?:
triggeredBy?:
activateAfterIdle expiry, or a model/provider change.lastActivityAt?:
ttlExpiredMs?:
activateAfterIdle had been exceeded when activation fired.previousModel?:
openai/gpt-4o).currentModel?:
recordId:
threadId:
config:
data-om-thread-updateDirect link to data-om-thread-update
Emitted when the Observer updates the thread title. Only emitted when observation.threadTitle is enabled.
cycleId:
threadId:
oldTitle?:
newTitle:
timestamp:
Standalone usageDirect link to Standalone usage
Most apps should use the Memory class. Use the ObservationalMemory engine directly for benchmarking, experiments, or when OM must run in a specific order with other processors such as guardrails.
Wrap the engine in an ObservationalMemoryProcessor, which needs a Memory instance to load and persist messages. stores.memory is typed as optional on storage adapters, so assert or check it:
import { Agent } from '@mastra/core/agent'
import { LibSQLStore } from '@mastra/libsql'
import { Memory } from '@mastra/memory'
import { ObservationalMemory, ObservationalMemoryProcessor } from '@mastra/memory/processors'
const storage = new LibSQLStore({
id: 'my-storage',
url: 'file:./memory.db',
})
const memory = new Memory({ storage })
const om = new ObservationalMemory({
storage: storage.stores.memory!,
memory,
model: 'google/gemini-3.8-flash',
observation: {
messageTokens: 20_000,
},
reflection: {
observationTokens: 60_000,
},
})
const omProcessor = new ObservationalMemoryProcessor(om, memory)
export const agent = new Agent({
id: 'my-agent',
name: 'My Agent',
instructions: 'You are a helpful assistant.',
model: 'openai/gpt-6-luna',
inputProcessors: [omProcessor],
outputProcessors: [omProcessor],
})
The engine takes the same options as the observationalMemory config, plus storage, onDebugEvent and obscureThreadIds. See standalone config.
om.observe() only observes once pending tokens reach the threshold. Pass force: true to observe pending messages now. The bypass applies to that call only.
const result = await om.observe({ threadId, resourceId, force: true })
// result.observed is true when pending messages were observed
Agents don't need this to recover from context-window errors. Context-overflow recovery handles that.
Standalone configDirect link to Standalone config
The standalone ObservationalMemory class accepts all the same options as the observationalMemory config object above, plus the following:
storage:
MastraStorage.stores.memory).onDebugEvent?:
obscureThreadIds?:
Recall toolDirect link to Recall tool
When retrieval is truthy, Mastra registers a recall tool that pages through raw messages behind observation group ranges. With the default resource scope, the tool can list threads (mode: "threads") and browse another thread through threadId. It also supports cross-thread search. Set retrieval: { vector: true } for semantic search (mode: "search"), or use scope: 'thread' to restrict the tool to the current thread. The tool is automatically added to the agent.
When retrieval is enabled, OM also injects instructions telling the agent how to use recall: when to verify details, how to search and page, and when to read raw messages. They're included from the first turn, including read-only runs, and only describe the modes that are configured. Reflected groups are marked _kind: reflection_ so the agent treats them as lossy summaries. Use retrieval: { instructions: '...' } to append your own guidance after the built-in instructions.
Observation pagesDirect link to Observation pages
With vector search configured, mode: "observations" reads the original observation groups around a search hit, including groups that reflection condensed away and buffered groups that haven't been activated yet. Copy the hit's groupId exactly as shown and, in resource scope, its threadId:
{
"mode": "observations",
"threadId": "source-thread-id",
"groupId": "group-id-from-search",
"direction": "after",
"limit": 5
}
Use direction: "before" to page backward, or omit direction to include the anchor group itself. Pages return { results, count, hasMore } with continuation calls, and say when newer messages haven't been observed yet.
Search resultsDirect link to Search results
Search results are listed by date and share a 2,000-token text allowance, so long groups are shortened, starting at the line that best matches the query. Results already in the agent's context come back as short references, and lower-ranked hits fill the freed space. limit counts excerpts, not references, so count can exceed limit.
Storage requirementsDirect link to Storage requirements
Group IDs in search results include the record that holds them (groupId@recordId), so paging reads a single record. Groups indexed before this change still work, but page by scanning the thread's observation history. Paging needs a storage adapter that supports observation history filters, so upgrade it together with @mastra/memory. Convex users need to redeploy their Mastra server functions.
ParametersDirect link to Parameters
mode?:
"messages" (default) pages through message history. "threads" lists threads for the current user. "search" finds messages by semantic similarity (requires a vector store, plus an embedder unless the store generates embeddings itself). "observations" pages original observation groups around a search hit.groupId?:
groupId@recordId let paging read the record directly; a plain group ID also works.direction?:
query?:
mode: "search". Finds messages semantically similar to this text across all threads for the current user.cursor?:
_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. When both cursor and threadId are omitted for mode: "messages", the tool browses the current thread from the position set by anchor.threadId?:
"current" for the active thread. Use mode: "threads" first to discover thread IDs. When provided without a cursor, reading starts from the beginning of the thread.anchor?:
mode: "messages" without a cursor, page from the start (oldest-first) or end (newest-first) of the thread.page?:
0 is treated as 1 for messages.limit?:
detail?:
'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. Image and file parts show their filename, media type, and stored URL or provider file ID so the agent can reuse the attachment. Inline file data such as base64 or data URIs is omitted. Pass viewAttachment with cursor and partIndex to send inline attachment data to the model.partType?:
mode: "messages".toolName?:
mode: "messages".partIndex?:
[p1] — call again with partIndex: 1 to see the full content without loading every part.charOffset?:
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.viewAttachment?:
cursor and partIndex, and applies when that part is an image or file. Inline data such as base64 or data URIs is sent as a native media part. Attachments stored as remote URLs or provider file IDs, media types outside image/* and application/pdf, and oversized payloads come back as an explanation instead.before?:
"2026-03-15", "2026-03-10T00:00:00Z").after?:
"2026-03-01", "2026-03-10T00:00:00Z").Returns (messages mode)Direct link to Returns (messages mode)
messages:
detail level.count:
cursor:
page:
limit:
detail:
hasNextPage:
hasPrevPage:
truncated?:
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?:
truncated is true.charOffset?:
partIndex), the character position this chunk starts at. 0 unless the call passed a charOffset.nextCharOffset?:
charOffset in the next call to continue reading from where this chunk ended.note?:
Returns (threads mode)Direct link to Returns (threads mode)
threads:
← current.count:
page:
hasMore:
Returns (search mode)Direct link to Returns (search mode)
results:
count:
ModelByInputTokensDirect link to ModelByInputTokens
ModelByInputTokens selects a model based on the input token count. It chooses the model for the smallest threshold that covers the actual input size.
ConstructorDirect link to Constructor
new ModelByInputTokens(config)
Where config is an object with upTo keys that map token thresholds (numbers) to model targets. Each tier needs a concrete model ID, not "auto".
ExampleDirect link to Example
import { ModelByInputTokens } from '@mastra/memory'
const selector = new ModelByInputTokens({
upTo: {
10_000: 'google/gemini-2.5-flash', // Fast for small inputs
40_000: 'openai/gpt-6-luna', // Stronger for medium inputs
1_000_000: 'openai/gpt-6.1-sol', // Most capable for large inputs
},
})
BehaviorDirect link to Behavior
- Thresholds are sorted internally, so the order in the config object doesn't matter.
inputTokens ≤ smallest threshold→ uses that threshold's modelinputTokens > largest threshold→resolve()throws an error. If this happens during an OM Observer or Reflector run, OM aborts via TripWire, so callers receive an emptytextresult or streamedtripwireinstead of a normal assistant response.- OM computes the input token count for the Observer or Reflector call and resolves the matching model tier directly
MethodsDirect link to Methods
resolve:
getThresholds:
skillResultRedactorDirect link to skillResultRedactor
skillResultRedactor builds a beforeObservation transform hook that redacts the results of the built-in Agent Skills tools (skill, skill_search, and skill_read) before the Observer model sees them. Each result is replaced with a placeholder while the tool call is kept, so the Observer still records which skill was used and what it was called with, without the skill text.
import { Memory } from '@mastra/memory'
import { skillResultRedactor } from '@mastra/memory/hooks'
const memory = new Memory({
options: {
observationalMemory: {
model: 'google/gemini-3.8-flash',
hooks: {
beforeObservation: skillResultRedactor(),
},
},
},
})
Pass toolNames to redact a different set of tools. To combine it with your own transform, chain the outputs and await each hook:
const dropSkillResults = skillResultRedactor()
hooks: {
beforeObservation: async input => {
const messages = (await dropSkillResults(input))?.messages ?? input.messages
return { messages: messages.filter(m => m.role !== 'signal') }
},
}
ParametersDirect link to Parameters
toolNames?:
skill, skill_search, and skill_read. Use this to redact a different set of tool results.ReturnsDirect link to Returns
(input: { messages: MastraDBMessage[] } & ObserveHookContext) => { messages: MastraDBMessage[] } | undefined
The hook returns messages with matching tool results replaced by a placeholder, or undefined when no message matched (which passes the payload through unchanged). Tool calls, arguments, and every other message are left as they are.