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.
QuickstartDirect 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
- pnpm
- Yarn
- Bun
npm install @mastra/memory@latest @mastra/libsql@latest
pnpm add @mastra/memory@latest @mastra/libsql@latest
yarn add @mastra/memory@latest @mastra/libsql@latest
bun add @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:
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.
BenefitsDirect 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 worksDirect 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.
ObservationsDirect 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.
ReflectionsDirect 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:
- Recent messages: the exact conversation for the current task.
- Observations: what the Observer has seen since the last reflection.
- Reflections: the condensed log of everything before that.
How context changes over timeDirect link to How context changes over time
With the default settings, the context window grows and shrinks in a cycle:
- 0 to 30,000 tokens: message history grows. In the background, the Observer prepares observations about every 6,000 tokens (
observation.bufferTokens: 0.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.8keeps 20% of the threshold). - Repeat: history grows back toward 30,000 and shrinks again. Each cycle adds a little to the observation log.
- 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 recoveryDirect 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 modelsDirect 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.
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 modelsDirect 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:
google/gemini-2.5-flashwhen Google is usable:GOOGLE_GENERATIVE_AI_API_KEYis set, or yourcanUseProviderfunction returnstruefor'google'.- Otherwise, a low-cost model from the main model's provider, for example
anthropic/claude-haiku-4-5for an Anthropic agent. - 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 selectionDirect 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: tellautowhether 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 modelsDirect 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 observersDirect 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 latencyDirect 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:
| Setting | Default | What it controls |
|---|---|---|
observation.bufferTokens | 0.2 | How 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.bufferActivation | 0.8 | How much of the message window clears when observations activate. 0.8 keeps 20% of messageTokens. Lower values keep more recent messages. |
observation.blockAfter | 1.2 | When 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 callsDirect 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 expiresDirect 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 observationDirect 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 memoryDirect 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.
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 modeDirect 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)
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.
ExtractorsDirect 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:
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 streamDirect 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:
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.
RelatedDirect link to Related
- Observational Memory reference
- Memory overview
- Multi-user threads: how OM attributes facts to individual users in a shared thread
- Memory processors
- Mastra Code: a coding agent using Observational Memory
- Mastra Factory: a software factory whose agent sessions use Observational Memory
- ๐น Mastra processors and Observational Memory workshop