Skip to main content

Observational Memory

Added in: @mastra/memory@1.1.0

Observational Memory (OM) lets an agent work in one thread for as long as the task takes, with a context that stays small, focused and prompt-cache friendly. An Observer agent turns older messages into short, dated observations in the background, and a Reflector agent condenses those observations when they grow. The agent sees its recent messages in full and everything earlier as observations.

Use OM for any agent that does more than a one-off summary or a single workflow step. Every agent that takes multiple steps benefits: chat assistants, coding agents, browser agents, support threads that run for hours.

Quickstart
Direct link to Quickstart

Install @mastra/memory and a storage adapter. The examples below use @mastra/libsql, which stores data locally in a memory.db file.

npm install @mastra/memory@latest @mastra/libsql@latest

OM needs storage that supports it (@mastra/libsql, @mastra/pg, @mastra/mysql, @mastra/mongodb, @mastra/convex, @mastra/oracledb or @mastra/mssql), a thread for every call, and observationalMemory: true. This script stores memory in a local LibSQL file and calls the agent twice on one thread:

src/observational-memory.ts
import { Agent } from '@mastra/core/agent'
import { LibSQLStore } from '@mastra/libsql'
import { Memory } from '@mastra/memory'

const memory = new Memory({
storage: new LibSQLStore({
id: 'memory-storage',
url: 'file:./memory.db',
}),
options: {
observationalMemory: true,
},
})

const agent = new Agent({
id: 'memory-agent',
name: 'Memory Agent',
instructions: 'You are a helpful assistant.',
model: 'openai/gpt-6-luna',
memory,
})

const memoryOptions = {
resource: 'user-123',
thread: 'conversation-123',
}

const first = await agent.generate('Remember that my favorite color is blue.', {
memory: memoryOptions,
})
console.log(first.text)

const second = await agent.generate('What is my favorite color?', {
memory: memoryOptions,
})
console.log(second.text)

resource identifies the user or entity and thread identifies the conversation. Reuse both to continue the conversation. Nothing is observed in this short exchange. Once the thread's message history passes 30,000 tokens, OM starts replacing older messages with observations.

If your Mastra instance already has storage, you can leave storage out of Memory and it uses that.

To watch OM work, open the Memory tab of the agent in Studio. Progress bars show how close messages and observations are to their thresholds, and Analyze observations opens the observation log and its history.

Benefits
Direct link to Benefits

  • Long tasks stay in one thread: The agent keeps working past its context limit without compacting and without losing earlier decisions.
  • Prompt caching: Observations append to a stable prefix instead of being retrieved each turn, which lets the provider serve most of each request from its prompt cache. See cost and latency.
  • Smaller context: Raw messages and tool results compress into a dense observation log, which lowers the cost and latency of every call.
  • Less context rot: The agent reads what matters instead of stale tool output and noise, which keeps it on task over long sessions.

Mastra's own agents run on OM. Mastra Code, a coding agent for the terminal, uses it so a session can run for days without compacting. Mastra Factory runs its planning, implementation and review sessions on Mastra Code. Each agent keeps the context of a long task from start to finish.

How it works
Direct link to How it works

Every time an agent responds, it reads a context window holding its system prompt, recent messages and any injected context. The more raw history it carries, the worse it performs, and most of those tokens are no longer needed to stay on task. OM compresses that history.

Observations
Direct link to Observations

When the thread's unobserved messages pass observation.messageTokens (default 30,000), the Observer writes observations: short, dated notes about what happened.

Date: 2026-01-15

- ๐Ÿ”ด 12:10 User is building a Next.js app with Supabase auth, due in 1 week (meaning January 22nd 2026)
- ๐Ÿ”ด 12:10 App uses server components with client-side hydration
- ๐ŸŸก 12:12 User asked about middleware configuration for protected routes
- ๐Ÿ”ด 12:15 User stated the app name is "Acme Dashboard"

The observed messages leave the context window and the observations take their place, typically 5 to 40 times smaller. A browser agent that sees 50,000 tokens per page snapshot ends up carrying a few hundred tokens about what was on the page and what it did.

During synchronous observation, the Observer also records a current task and a suggested response. These help the agent pick up where it left off. With observation.threadTitle enabled, it can suggest a new thread title when the topic changes.

The Observer sees attachments in the history it reviews. The transcript keeps placeholders such as [Image #1: reference-board.png], and the attachments themselves are forwarded beside the text. See choosing models for Observers that can't read attachments.

Reflections
Direct link to Reflections

When observations pass reflection.observationTokens (default 40,000), the Reflector rewrites the whole log: it merges related items, condenses older ones more and keeps recent detail. Its output becomes the new log, and new observations append after it. The log stays around the reflection threshold however long the thread runs.

The agent's context then has three layers:

  1. Recent messages: the exact conversation for the current task.
  2. Observations: what the Observer has seen since the last reflection.
  3. Reflections: the condensed log of everything before that.

How context changes over time
Direct link to How context changes over time

With the default settings, the context window grows and shrinks in a cycle:

Chart of context tokens over the course of a conversation with Observational Memory enabled: message history repeatedly grows toward the 30,000 token observation threshold, then shrinks back to around 6,000 tokens as observations activate, while the observation log steps up with each cycle until it reaches the 40,000 token reflection threshold and the Reflector condenses it into reflections
  1. 0 to 30,000 tokens: message history grows. In the background, the Observer prepares observations about every 6,000 tokens (observation.bufferTokens: 0.2).
  2. 30,000 reached: the prepared observations activate. The observed messages leave the context and about 6,000 tokens of recent messages stay (observation.bufferActivation: 0.8 keeps 20% of the threshold).
  3. Repeat: history grows back toward 30,000 and shrinks again. Each cycle adds a little to the observation log.
  4. Observations reach 40,000: the Reflector rewrites the log into a smaller one.

Thresholds mark when work starts. History can run past 30,000 tokens when background observation falls behind. At observation.blockAfter (default 1.2, or 36,000 tokens) the agent waits for a synchronous observation. See when buffering falls behind.

Token counts are local tokenx estimates. The provider's own count is often higher, especially with attachments.

Context-overflow recovery
Direct link to Context-overflow recovery

A provider can reject a request for exceeding its context window before OM's estimate reaches the threshold. When that happens, OM activates any prepared observations, observes everything still pending, and retries the request once with the smaller context. This is on by default; set observation.observeOnContextOverflow: false to let the error reach your code instead.

Gateway models
Direct link to Gateway models

A Mastra Gateway model can keep a thread's observations on the gateway instead of your storage adapter. The gateway only does that for a Gateway project key (msk_...) that it serves with its own provider keys and with memory enabled for the project. An organization key (msk-gateway-... or mskv2_...) is served by a gateway without the memory API, so OM keeps running locally against the Memory you configured.

Keep Memory configured with observationalMemory: true in both cases. With a project key the gateway owns the thread, which means your storage adapter stays empty and memory.recall() doesn't return those messages.

warning

A project key alone doesn't mean the gateway stores the thread. When the request is routed with your own provider key, or memory is disabled for the project, the gateway proxies it without storing observations, while Mastra still skips local OM for a mastra/ model on a project key. Neither the gateway nor your storage adapter keeps the conversation in that case. Use gateway-managed provider keys with project memory enabled, or a directly configured provider model, when the thread has to be stored.

Choosing models
Direct link to Choosing models

The Observer and Reflector are model calls that run beside your agent. By default both use model: 'auto', which resolves each time a role runs:

  1. google/gemini-2.5-flash when Google is usable: GOOGLE_GENERATIVE_AI_API_KEY is set, or your canUseProvider function returns true for 'google'.
  2. Otherwise, a low-cost model from the main model's provider, for example anthropic/claude-haiku-4-5 for an Anthropic agent.
  3. Otherwise, the main model itself.

auto reads the main model's provider/model ID. When that isn't known, such as a model created with a custom URL, API key or gateway, auto uses the main model itself, because a sibling model isn't known to share that route.

Set model to use one model for both roles:

const memory = new Memory({
options: {
observationalMemory: {
model: 'deepseek/deepseek-flash',
},
},
})

Use a model with a large context window (128,000 tokens or more) that's fast enough to run in the background. Mastra has tested google/gemini-2.5-flash, openai/gpt-6-luna, anthropic/claude-haiku-5-5 and deepseek/deepseek-flash.

To use a different model per role, set observation.model and reflection.model instead, and leave the top-level model out. Setting both throws. Some models keep so much detail that their reflections can stay above the threshold; in testing, google/gemini-2.5-flash did this. A common split uses a detail-preserving model as the Observer and one that condenses more aggressively, such as deepseek/deepseek-flash, as the Reflector. See different models per agent.

Tune automatic selection
Direct link to Tune automatic selection

These observationalMemory options adjust what auto picks:

  • autoModels: replace the low-cost pick for a provider, for example { openai: 'openai/gpt-6-luna' }.
  • canUseProvider: tell auto whether the current request can use a provider, when credentials are per tenant or per request rather than in the server's environment. It receives the provider ID and { requestContext }.
  • resolveModel: create the picked model yourself, with your own credentials or routing. It receives a concrete model ID, never 'auto'.
const memory = new Memory({
options: {
observationalMemory: {
autoModels: { openai: 'openai/gpt-6-luna' },
canUseProvider: (provider, { requestContext }) => hasCredentials(provider, requestContext),
resolveModel: (modelId, { requestContext }) => createRoutedModel(modelId, requestContext),
},
},
})

resolveAutoModelId(mainModelId, { autoModels }) from @mastra/memory returns the model auto would pick, for showing the effective model in a settings UI.

Token-tiered models
Direct link to Token-tiered models

Added in: @mastra/memory@1.10.0

ModelByInputTokens picks a model by the size of each Observer or Reflector call:

import { Memory, ModelByInputTokens } from '@mastra/memory'

const memory = new Memory({
options: {
observationalMemory: {
observation: {
model: new ModelByInputTokens({
upTo: {
5_000: 'openrouter/mistralai/ministral-8b-2512',
20_000: 'openrouter/mistralai/mistral-small-2603',
40_000: 'openai/gpt-6-luna',
1_000_000: 'google/gemini-3.8-flash',
},
}),
},
reflection: {
model: new ModelByInputTokens({
upTo: {
20_000: 'openai/gpt-6-luna',
100_000: 'deepseek/deepseek-flash',
},
}),
},
},
},
})

Each tier needs a concrete model ID, not 'auto'. Each upTo key is an inclusive upper bound. A call larger than the biggest key throws, so make the last tier cover the largest input you expect.

Attachments and text-only observers
Direct link to Attachments and text-only observers

By default the Observer receives images and PDFs (observation.observeAttachments: ['image/*', 'application/pdf']). Other attachments are left out, and their placeholders stay in the transcript. Change it when your Observer model handles more or less:

  • false: send no attachments. Use this for a text-only Observer.
  • true: send every attachment.
  • A list of MIME types such as ['image/*']: send only matching attachments. Matching is case-insensitive and * matches any subtype.
  • 'auto': send attachments when the provider registry says the Observer model accepts multimodal input. When it has no data for the model, everything is sent.
const memory = new Memory({
options: {
observationalMemory: {
observation: {
model: 'deepseek/deepseek-flash',
observeAttachments: false,
},
},
},
})

The same filter applies to images and files inside tool results. Attachments the agent recorded as unavailable, because they could no longer be downloaded, are never sent. See attachment download failures.

Cost and latency
Direct link to Cost and latency

Each observation and reflection is a model call. With the defaults, a thread costs one Observer call for about every 6,000 tokens of new messages, and one Reflector call each time the log reaches 40,000 tokens. In return, every main-agent call reads a context of at most a few tens of thousands of tokens instead of the whole thread. The observation prefix stays stable, so prompt caching keeps working: users see 97 to 99% prompt cache hit rates with OM.

The Observer runs ahead in the background (async buffering), so the agent doesn't stop to wait for it. These settings control the timing:

SettingDefaultWhat it controls
observation.bufferTokens0.2How often the Observer runs in the background, as a fraction of messageTokens (0.2 is every 6,000 tokens at the default threshold), or an absolute token count such as 5000. false turns buffering off.
observation.bufferActivation0.8How much of the message window clears when observations activate. 0.8 keeps 20% of messageTokens. Lower values keep more recent messages.
observation.blockAfter1.2When the agent waits for a synchronous observation because buffering fell behind, as a multiple of messageTokens (1.2 is 36,000 tokens), or an absolute count of 100 or more. 1 observes synchronously at messageTokens.

To change when OM observes and reflects, set the thresholds:

const memory = new Memory({
options: {
observationalMemory: {
observation: {
messageTokens: 30_000,
},
reflection: {
observationTokens: 40_000,
},
},
},
})

Long runs of tool calls
Direct link to Long runs of tool calls

Agents that run long chains of tool calls, such as coding and browser agents, re-send the same growing prefix on every step, and the provider serves most of it from the prompt cache. For these agents, raise the observation threshold well above the default, for example to 60,000 to 80,000 tokens, so OM compresses less often and more of each run stays cached:

const memory = new Memory({
options: {
observationalMemory: {
observation: {
messageTokens: 70_000,
},
},
},
})

Keep the threshold within the main model's context window. bufferTokens, bufferActivation and blockAfter are fractions of messageTokens by default, so they scale with it.

Activate when the prompt cache expires
Direct link to Activate when the prompt cache expires

Once the prompt cache expires, the next request pays full price for the whole context anyway. activateAfterIdle makes OM activate its prepared observations when a thread has been idle that long, so the request after a pause sends a smaller, compressed context. It isn't set by default. Set it to 'auto' to use the active provider's prompt cache TTL (for example 5 minutes for Anthropic, 1 hour for DeepSeek):

const memory = new Memory({
options: {
observationalMemory: {
activateAfterIdle: 'auto',
},
},
})

See early activation for fixed durations, per-provider values and activating when the provider changes.

Synchronous observation
Direct link to Synchronous observation

To observe synchronously instead, set observation.bufferTokens: false. That turns off background buffering for both observations and reflections, and the agent pauses while each one runs.

shareTokenBudget: true lets message history borrow the unused part of the observation budget, so up to about 70,000 tokens of messages stay before observation starts while the log is small. It requires observation.bufferTokens: false. See shared token budget.

Threads and cross-thread memory
Direct link to Threads and cross-thread memory

Thread scope (default)
Direct link to Thread scope (default)

Each thread has its own observations. Every call needs a thread: without one, OM throws OBSERVATIONAL_MEMORY_THREAD_ID_REQUIRED, so that unrelated threads never share one observation record.

warning

When a client application calls your agent, send only the new message instead of the full conversation. OM already loads the thread's history from storage. See message history for how Mastra handles echoed history and when to use retainFullInput.

OM remembers within a thread. To let the agent reach a user's other threads, turn on retrieval mode, which gives it a recall tool for the raw messages behind observations and for other threads of the same resource.

Retrieval mode
Direct link to Retrieval mode

Observations drop the original wording. With retrieval mode, each observation group stays linked to the messages it came from, and the agent gets a recall tool to read them back, including exact wording and tool output.

retrieval: true lets the agent browse raw messages, list the resource's threads and read other threads. No vector store is needed.

retrieval: { vector: true } adds semantic search over observation groups, using the vector store and embedder configured on Memory. With a vector store that generates embeddings itself, leave the embedder out. See server-side embeddings. New observation groups are indexed in the background as they're created.

const memory = new Memory({
storage,
vector: myVectorStore,
embedder: myEmbedder,
options: {
observationalMemory: {
retrieval: { vector: true },
},
},
})

The recall tool's scope is 'resource' by default, so it can reach every thread of the resource. Set retrieval: { scope: 'thread' } to limit it to the current thread. Use retrieval.instructions to add app-specific guidance after the built-in recall instructions, for example "Prefer the current conversation when it already contains the answer."

See the recall tool reference for its modes, detail levels and pagination.

Resource scope (deprecated)
Direct link to Resource scope (deprecated)

Deprecated

scope: 'resource' is deprecated and will be removed in a future release. Mastra logs a warning the first time OM is created with resource scope. Remove the scope option to use thread scope, and use retrieval mode for cross-thread continuity. Knowledge, now in alpha, gives agents shared information across threads and is planned to replace resource scope.

Resource scope shares one observation record across all of a resource's threads. It works much worse than thread scope:

  • Prompt caching: observing any thread changes the context of every other thread, which breaks their cached prefixes.
  • Agent understanding: each thread sees observations from every other thread, and the agent may continue work that another thread started.
  • Performance: unobserved messages from all threads are processed together, which is slow for users with many threads. Resource scope also turns off async buffering.

Switching to thread scope doesn't migrate resource-scoped observations. Each thread uses its own thread-scoped record if it has one, or starts empty, and messages already observed under resource scope aren't observed again.

Extractors
Direct link to Extractors

Extractors persist specific values alongside observations. The built-in current task, suggested response and thread title use the same pipeline. This example extracts a small user profile:

src/mastra/agents/assistant.ts
import { Agent } from '@mastra/core/agent'
import { Extractor, Memory } from '@mastra/memory'
import { z } from 'zod'

const memory = new Memory({
options: {
observationalMemory: {
observation: {
extract: [
new Extractor({
name: 'User profile',
instructions: 'Extract stable user profile facts that should be remembered.',
schema: z.object({
preferredName: z.string().optional(),
timezone: z.string().optional(),
tools: z.array(z.string()).optional(),
}),
}),
],
},
},
},
})

export const assistant = new Agent({
id: 'assistant',
name: 'Assistant',
instructions: 'You are a helpful assistant.',
model: 'openai/gpt-6-luna',
memory,
})

An extractor with a schema runs as a follow-up structured-output request. Without a schema it's an inline string extractor, emitted directly in the Observer or Reflector response:

new Extractor({
name: 'Mood',
instructions: 'Extract the user mood as a short phrase.',
})

By default the extractor sees its last value on later runs. Set includePreviousExtraction: false to hide it:

new Extractor({
name: 'Latest blocker',
instructions: 'Extract any blockers the agent is running into.',
includePreviousExtraction: false,
})

instructions and schema can be functions when they depend on runtime context, such as the memory instance or request context:

new Extractor({
name: 'Workspace summary',
instructions: ({ memory }) =>
memory ? 'Extract workspace facts for this memory instance.' : 'Extract workspace facts.',
})

Use onExtracted to normalize a value before it's persisted:

new Extractor({
name: 'Project status',
instructions: 'Extract the current project status.',
schema: z.string(),
onExtracted: ({ current }) => current.trim().toLowerCase(),
})

onExtracted also receives previous and sendSignal, so it can tell the agent when a value changes. The hook runs on every extraction, so compare previous with current before sending a signal; otherwise each observation sends another one.

A failed extractor is reported in OM markers and doesn't drop values from extractors that succeeded. See the Extractor API for the full shape.

Read extracted values from a stream
Direct link to Read extracted values from a stream

Extractor results arrive when OM completes an observation or reflection. Read both completion data parts from the stream:

src/run.ts
import { assistant } from './mastra/agents/assistant'

const stream = await assistant.stream('Remember that I prefer dark mode.', {
memory: { resource: 'user-123', thread: 'conversation-123' },
})

for await (const chunk of stream.fullStream) {
if (chunk.type === 'data-om-observation-end' || chunk.type === 'data-om-buffering-end') {
const { operationType, extractedValues = {}, extractionFailures = [] } = chunk.data

for (const [slug, value] of Object.entries(extractedValues)) {
console.log(`${operationType} extractor ${slug}:`, value)
}

for (const failure of extractionFailures) {
console.error(`Extractor ${failure.slug} failed:`, failure.error)
}
}
}

extractedValues is keyed by each extractor's slug. Both fields are optional.

data-om-observation-end reports a synchronous completion. data-om-buffering-end reports finished background work: its extractor values are persisted at once, but the buffered observations stay inactive until activation. operationType says whether the work was an observation or a reflection. See data-om-observation-end and data-om-buffering-end for the payloads.