@mastra/memory 1.1.0 → 1.2.0-alpha.0

package/dist/docs/{memory/03-message-history.md → references/docs-memory-message-history.md}

@@ -1,25 +1,42 @@
-> Learn how to configure message history in Mastra to store recent messages from the current conversation.
-
 # Message History
 
-Message history is the most basic and important form of memory. It gives the LLM a view of recent messages in the context window, enabling your agent to reference earlier exchanges and respond coherently. 
+Message history is the most basic and important form of memory. It gives the LLM a view of recent messages in the context window, enabling your agent to reference earlier exchanges and respond coherently.
 
 You can also retrieve message history to display past conversations in your UI.
 
-> **Note:**
-Each message belongs to a thread (the conversation) and a resource (the user or entity it's associated with). See [Threads and resources](https://mastra.ai/docs/memory/storage#threads-and-resources) for more detail.
+> **Info:** Each message belongs to a thread (the conversation) and a resource (the user or entity it's associated with). See [Threads and resources](https://mastra.ai/docs/memory/storage) for more detail.
 
 ## Getting started
 
-Install the Mastra memory module along with a [storage adapter](https://mastra.ai/docs/memory/storage#supported-providers) for your database. The examples below use `@mastra/libsql`, which stores data locally in a `mastra.db` file.
+Install the Mastra memory module along with a [storage adapter](https://mastra.ai/docs/memory/storage) for your database. The examples below use `@mastra/libsql`, which stores data locally in a `mastra.db` file.
+
+**npm**:
 
-```bash npm2yarn
+```bash
 npm install @mastra/memory@latest @mastra/libsql@latest
 ```
 
+**pnpm**:
+
+```bash
+pnpm add @mastra/memory@latest @mastra/libsql@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/memory@latest @mastra/libsql@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/memory@latest @mastra/libsql@latest
+```
+
 Message history requires a storage adapter to persist conversations. Configure storage on your Mastra instance if you haven't already:
 
-```typescript title="src/mastra/index.ts"
+```typescript
 import { Mastra } from "@mastra/core";
 import { LibSQLStore } from "@mastra/libsql";
 
@@ -33,7 +50,7 @@ export const mastra = new Mastra({
 
 Give your agent a `Memory`:
 
-```typescript title="src/mastra/agents/your-agent.ts"
+```typescript
 import { Memory } from "@mastra/memory";
 import { Agent } from "@mastra/core/agent";
 
@@ -49,7 +66,7 @@ export const agent = new Agent({
 
 When you call the agent, messages are automatically saved to the database. You can specify a `threadId`, `resourceId`, and optional `metadata`:
 
-  **generate:**
+**Generate**:
 
 ```typescript
 await agent.generate("Hello", {
@@ -64,8 +81,7 @@ await agent.generate("Hello", {
 });
 ```
 
-  
-  **stream:**
+**Stream**:
 
 ```typescript
 await agent.stream("Hello", {
@@ -80,11 +96,7 @@ await agent.stream("Hello", {
 });
 ```
 
-  
-
-> **Note:**
-
-Threads and messages are created automatically when you call `agent.generate()` or `agent.stream()`, but you can also create them manually with [`createThread()`](https://mastra.ai/reference/memory/createThread) and [`saveMessages()`](https://mastra.ai/reference/memory/memory-class). 
+> **Info:** Threads and messages are created automatically when you call `agent.generate()` or `agent.stream()`, but you can also create them manually with [`createThread()`](https://mastra.ai/reference/memory/createThread) and [`saveMessages()`](https://mastra.ai/reference/memory/memory-class).
 
 There are two ways to use this history:
 
@@ -106,8 +118,7 @@ The `Memory` instance gives you access to functions for listing threads, recalli
 
 Use these methods to fetch threads and messages for displaying conversation history in your UI or for custom memory retrieval logic.
 
-> **Note:**
-The memory system does not enforce access control. Before running any query, verify in your application logic that the current user is authorized to access the `resourceId` being queried.
+> **Warning:** The memory system does not enforce access control. Before running any query, verify in your application logic that the current user is authorized to access the `resourceId` being queried.
 
 ### Threads
 
@@ -240,7 +251,7 @@ const { thread, clonedMessages } = await memory.cloneThread({
 });
 ```
 
-You can filter which messages get cloned (by count or date range), specify custom thread IDs, and use utility methods to inspect clone relationships. 
+You can filter which messages get cloned (by count or date range), specify custom thread IDs, and use utility methods to inspect clone relationships.
 
 See [`cloneThread()`](https://mastra.ai/reference/memory/cloneThread) and [clone utilities](https://mastra.ai/reference/memory/clone-utilities) for the full API.
 

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

@@ -0,0 +1,238 @@
+# Observational Memory
+
+**Added in:** `@mastra/memory@1.1.0`
+
+Observational Memory (OM) is Mastra's memory system for long-context agentic memory. Two background agents — an **Observer** and a **Reflector** — watch your agent's conversations and maintain a dense observation log that replaces raw message history as it grows.
+
+## Quick Start
+
+Enable `observationalMemory` in the memory options when creating your agent:
+
+```typescript
+import { Memory } from "@mastra/memory";
+import { Agent } from "@mastra/core/agent";
+
+export const agent = new Agent({
+  name: "my-agent",
+  instructions: "You are a helpful assistant.",
+  model: "openai/gpt-5-mini",
+  memory: new Memory({
+    options: {
+      observationalMemory: true,
+    },
+  }),
+});
+```
+
+That's it. The agent now has humanlike long-term memory that persists across conversations. Setting `observationalMemory: true` uses `google/gemini-2.5-flash` by default. To use a different model or customize thresholds, pass a config object instead:
+
+```typescript
+const memory = new Memory({
+  options: {
+    observationalMemory: {
+      model: "deepseek/deepseek-reasoner",
+    },
+  },
+});
+```
+
+See [configuration options](https://mastra.ai/reference/memory/observational-memory) for full API details.
+
+> **Note:** OM currently only supports `@mastra/pg`, `@mastra/libsql`, and `@mastra/mongodb` storage adapters. It uses background agents for managing memory. When using `observationalMemory: true`, the default model is `google/gemini-2.5-flash`. When passing a config object, a `model` must be explicitly set.
+
+## Benefits
+
+- **Prompt caching**: OM's context is stable — observations append over time rather than being dynamically retrieved each turn. This keeps the prompt prefix cacheable, which reduces costs.
+- **Compression**: Raw message history and tool results get compressed into a dense observation log. Smaller context means faster responses and longer coherent conversations.
+- **Zero context rot**: The agent sees relevant information instead of noisy tool calls and irrelevant tokens, so the agent stays on task over long sessions.
+
+## How It Works
+
+You don't remember every word of every conversation you've ever had. You observe what happened subconsciously, then your brain reflects — reorganizing, combining, and condensing into long-term memory. OM works the same way.
+
+Every time an agent responds, it sees a context window containing its system prompt, recent message history, and any injected context. The context window is finite — even models with large token limits perform worse when the window is full. This causes two problems:
+
+- **Context rot**: the more raw message history an agent carries, the worse it performs.
+- **Context waste**: most of that history contains tokens no longer needed to keep the agent on task.
+
+OM solves both problems by compressing old context into dense observations.
+
+### Observations
+
+When message history tokens exceed a threshold (default: 30,000), the Observer creates observations — concise notes about what happened:
+
+```text
+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 compression is typically 5–40×. The Observer also tracks a **current task** and **suggested response** so the agent picks up where it left off.
+
+Example: an agent using Playwright MCP might see 50,000+ tokens per page snapshot. With OM, the Observer watches the interaction and creates a few hundred tokens of observations about what was on the page and what actions were taken. The agent stays on task without carrying every raw snapshot.
+
+### Reflections
+
+When observations exceed their threshold (default: 40,000 tokens), the Reflector condenses them — combining related items and reflecting on patterns.
+
+The result is a three-tier system:
+
+1. **Recent messages**: Exact conversation history for the current task
+2. **Observations**: A log of what the Observer has seen
+3. **Reflections**: Condensed observations when memory becomes too long
+
+## Models
+
+The Observer and Reflector run in the background. Any model that works with Mastra's model routing (e.g. `openai/...`, `google/...`, `deepseek/...`) can be used.
+
+When using `observationalMemory: true`, the default model is `google/gemini-2.5-flash`. When passing a config object, a `model` must be explicitly set.
+
+We recommend `google/gemini-2.5-flash` — it works well for both observation and reflection, and its 1M token context window gives the Reflector headroom.
+
+We've also tested `deepseek`, `qwen3`, and `glm-4.7` for the Observer. For the Reflector, make sure the model's context window can fit all observations. Note that Claude 4.5 models currently don't work well as observer or reflector.
+
+```typescript
+const memory = new Memory({
+  options: {
+    observationalMemory: {
+      model: "deepseek/deepseek-reasoner",
+    },
+  },
+});
+```
+
+See [model configuration](https://mastra.ai/reference/memory/observational-memory) for using different models per agent.
+
+## Scopes
+
+### Thread scope (default)
+
+Each thread has its own observations.
+
+```typescript
+const memory = new Memory({
+  options: {
+    observationalMemory: {
+      model: "google/gemini-2.5-flash",
+      scope: "thread",
+    },
+  },
+});
+```
+
+### Resource scope
+
+Observations are shared across all threads for a resource (typically a user). Enables cross-conversation memory.
+
+```typescript
+const memory = new Memory({
+  options: {
+    observationalMemory: {
+      model: "google/gemini-2.5-flash",
+      scope: "resource",
+    },
+  },
+});
+```
+
+> **Warning:** In resource scope, unobserved messages across _all_ threads are processed together. For users with many existing threads, this can be slow. Use thread scope for existing apps.
+
+## Token Budgets
+
+OM uses token thresholds to decide when to observe and reflect. See [token budget configuration](https://mastra.ai/reference/memory/observational-memory) for details.
+
+```typescript
+const memory = new Memory({
+  options: {
+    observationalMemory: {
+      model: "google/gemini-2.5-flash",
+      observation: {
+        // when to run the Observer (default: 30,000)
+        messageTokens: 30_000,
+      },
+      reflection: {
+        // when to run the Reflector (default: 40,000)
+        observationTokens: 40_000,
+      },
+      // let message history borrow from observation budget
+      // requires bufferTokens: false (temporary limitation)
+      shareTokenBudget: false,
+    },
+  },
+});
+```
+
+## Async Buffering
+
+Without async buffering, the Observer runs synchronously when the message threshold is reached — the agent pauses mid-conversation while the Observer LLM call completes. With async buffering (enabled by default), observations are pre-computed in the background as the conversation grows. When the threshold is hit, buffered observations activate instantly with no pause.
+
+### How it works
+
+As the agent converses, message tokens accumulate. At regular intervals (`bufferTokens`), a background Observer call runs without blocking the agent. Each call produces a "chunk" of observations that's stored in a buffer.
+
+When message tokens reach the `messageTokens` threshold, buffered chunks activate: their observations move into the active observation log, and the corresponding raw messages are removed from the context window. The agent never pauses.
+
+If the agent produces messages faster than the Observer can process them, a `blockAfter` safety threshold forces a synchronous observation as a last resort.
+
+Reflection works similarly — the Reflector runs in the background when observations reach a fraction of the reflection threshold.
+
+### Settings
+
+| Setting                        | Default | What it controls                                                                                                                                                                      |
+| ------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `observation.bufferTokens`     | `0.2`   | How often to buffer. `0.2` means every 20% of `messageTokens` — with the default 30k threshold, that's roughly every 6k tokens. Can also be an absolute token count (e.g. `5000`).    |
+| `observation.bufferActivation` | `0.8`   | How aggressively to clear the message window on activation. `0.8` means remove enough messages to keep only 20% of `messageTokens` remaining. Lower values keep more message history. |
+| `observation.blockAfter`       | `1.2`   | Safety threshold as a multiplier of `messageTokens`. At `1.2`, synchronous observation is forced at 36k tokens (1.2 × 30k). Only matters if buffering can't keep up.                  |
+| `reflection.bufferActivation`  | `0.5`   | When to start background reflection. `0.5` means reflection begins when observations reach 50% of the `observationTokens` threshold.                                                  |
+| `reflection.blockAfter`        | `1.2`   | Safety threshold for reflection, same logic as observation.                                                                                                                           |
+
+### Disabling
+
+To disable async buffering and use synchronous observation/reflection instead:
+
+```typescript
+const memory = new Memory({
+  options: {
+    observationalMemory: {
+      model: "google/gemini-2.5-flash",
+      observation: {
+        bufferTokens: false,
+      },
+    },
+  },
+});
+```
+
+Setting `bufferTokens: false` disables both observation and reflection async buffering. See [async buffering configuration](https://mastra.ai/reference/memory/observational-memory) for the full API.
+
+> **Note:** Async buffering is not supported with `scope: 'resource'`. It is automatically disabled in resource scope.
+
+## Migrating existing threads
+
+No manual migration needed. OM reads existing messages and observes them lazily when thresholds are exceeded.
+
+- **Thread scope**: The first time a thread exceeds `observation.messageTokens`, the Observer processes the backlog.
+- **Resource scope**: All unobserved messages across all threads for a resource are processed together. For users with many existing threads, this could take significant time.
+
+## Viewing in Mastra Studio
+
+Mastra Studio shows OM status in real time in the memory tab: token usage, which model is running, current observations, and reflection history.
+
+## Comparing OM with other memory features
+
+- **[Message history](https://mastra.ai/docs/memory/message-history)**: High-fidelity record of the current conversation
+- **[Working memory](https://mastra.ai/docs/memory/working-memory)**: Small, structured state (JSON or markdown) for user preferences, names, goals
+- **[Semantic Recall](https://mastra.ai/docs/memory/semantic-recall)**: RAG-based retrieval of relevant past messages
+
+If you're using working memory to store conversation summaries or ongoing state that grows over time, OM is a better fit. Working memory is for small, structured data; OM is for long-running event logs. OM also manages message history automatically—the `messageTokens` setting controls how much raw history remains before observation runs.
+
+In practical terms, OM replaces both working memory and message history, and has greater accuracy (and lower cost) than Semantic Recall.
+
+## Related
+
+- [Observational Memory Reference](https://mastra.ai/reference/memory/observational-memory)
+- [Memory Overview](https://mastra.ai/docs/memory/overview)
+- [Message History](https://mastra.ai/docs/memory/message-history)
+- [Memory Processors](https://mastra.ai/docs/memory/memory-processors)

package/dist/docs/{memory/01-overview.md → references/docs-memory-overview.md}

@@ -1,14 +1,13 @@
-> Learn how Mastra
-
 # Memory
 
 Memory enables your agent to remember user messages, agent replies, and tool results across interactions, giving it the context it needs to stay consistent, maintain conversation flow, and produce better answers over time.
 
-Mastra supports three complementary memory types:
+Mastra supports four complementary memory types:
 
 - [**Message history**](https://mastra.ai/docs/memory/message-history) - keeps recent messages from the current conversation so they can be rendered in the UI and used to maintain short-term continuity within the exchange.
 - [**Working memory**](https://mastra.ai/docs/memory/working-memory) - stores persistent, structured user data such as names, preferences, and goals.
-- [**Semantic recall**](https://mastra.ai/docs/memory/semantic-recall) - retrieves relevant messages from older conversations based on semantic meaning rather than exact keywords, mirroring how humans recall information by association. Requires a [vector database](https://mastra.ai/docs/memory/semantic-recall#storage-configuration) and an [embedding model](https://mastra.ai/docs/memory/semantic-recall#embedder-configuration).
+- [**Semantic recall**](https://mastra.ai/docs/memory/semantic-recall) - retrieves relevant messages from older conversations based on semantic meaning rather than exact keywords, mirroring how humans recall information by association. Requires a [vector database](https://mastra.ai/docs/memory/semantic-recall) and an [embedding model](https://mastra.ai/docs/memory/semantic-recall).
+- [**Observational memory**](https://mastra.ai/docs/memory/observational-memory) - uses background Observer and Reflector agents to maintain a dense observation log that replaces raw message history as it grows, keeping the context window small while preserving long-term memory across conversations.
 
 If the combined memory exceeds the model's context limit, [memory processors](https://mastra.ai/docs/memory/memory-processors) can filter, trim, or prioritize content so the most relevant information is preserved.
 
@@ -19,12 +18,13 @@ Choose a memory option to get started:
 - [Message history](https://mastra.ai/docs/memory/message-history)
 - [Working memory](https://mastra.ai/docs/memory/working-memory)
 - [Semantic recall](https://mastra.ai/docs/memory/semantic-recall)
+- [Observational memory](https://mastra.ai/docs/memory/observational-memory)
 
 ## Storage
 
-Before enabling memory, you must first configure a storage adapter. Mastra supports several databases including PostgreSQL, MongoDB, libSQL, and [more](https://mastra.ai/docs/memory/storage#supported-providers).
+Before enabling memory, you must first configure a storage adapter. Mastra supports several databases including PostgreSQL, MongoDB, libSQL, and [more](https://mastra.ai/docs/memory/storage).
 
-Storage can be configured at the [instance level](https://mastra.ai/docs/memory/storage#instance-level-storage) (shared across all agents) or at the [agent level](https://mastra.ai/docs/memory/storage#agent-level-storage) (dedicated per agent).
+Storage can be configured at the [instance level](https://mastra.ai/docs/memory/storage) (shared across all agents) or at the [agent level](https://mastra.ai/docs/memory/storage) (dedicated per agent).
 
 For semantic recall, you can use a separate vector database like Pinecone alongside your primary storage.
 
@@ -34,12 +34,12 @@ See the [Storage](https://mastra.ai/docs/memory/storage) documentation for confi
 
 When [tracing](https://mastra.ai/docs/observability/tracing/overview) is enabled, you can inspect exactly which messages the agent uses for context in each request. The trace output shows all memory included in the agent's context window - both recent message history and messages recalled via semantic recall.
 
-![Trace output showing memory context included in an agent request](https://mastra.ai/_next/image?url=%2Ftracingafter.png&w=1920&q=75)
+![Trace output showing memory context included in an agent request](https://mastra.ai/_next/image?url=%2Ftracingafter.png\&w=1920\&q=75)
 
 This visibility helps you understand why an agent made specific decisions and verify that memory retrieval is working as expected.
 
 ## Next steps
 
 - Learn more about [Storage](https://mastra.ai/docs/memory/storage) providers and configuration options
-- Add [Message history](https://mastra.ai/docs/memory/message-history), [Working memory](https://mastra.ai/docs/memory/working-memory), or [Semantic recall](https://mastra.ai/docs/memory/semantic-recall)
+- Add [Message history](https://mastra.ai/docs/memory/message-history), [Working memory](https://mastra.ai/docs/memory/working-memory), [Semantic recall](https://mastra.ai/docs/memory/semantic-recall), or [Observational memory](https://mastra.ai/docs/memory/observational-memory)
 - Visit [Memory configuration reference](https://mastra.ai/reference/memory/memory-class) for all available options

package/dist/docs/{memory/05-semantic-recall.md → references/docs-memory-semantic-recall.md}

@@ -1,20 +1,16 @@
-> Learn how to use semantic recall in Mastra to retrieve relevant messages from past conversations using vector search and embeddings.
-
 # Semantic Recall
 
 If you ask your friend what they did last weekend, they will search in their memory for events associated with "last weekend" and then tell you what they did. That's sort of like how semantic recall works in Mastra.
 
-> **Watch 📹**
-
-What semantic recall is, how it works, and how to configure it in Mastra → [YouTube (5 minutes)](https://youtu.be/UVZtK8cK8xQ)
+> **Watch 📹:** What semantic recall is, how it works, and how to configure it in Mastra → [YouTube (5 minutes)](https://youtu.be/UVZtK8cK8xQ)
 
 ## How Semantic Recall Works
 
-Semantic recall is RAG-based search that helps agents maintain context across longer interactions when messages are no longer within [recent message history](./message-history).
+Semantic recall is RAG-based search that helps agents maintain context across longer interactions when messages are no longer within [recent message history](https://mastra.ai/docs/memory/message-history).
 
 It uses vector embeddings of messages for similarity search, integrates with various vector stores, and has configurable context windows around retrieved messages.
 
-![Diagram showing Mastra Memory semantic recall](/img/semantic-recall.png)
+![Diagram showing Mastra Memory semantic recall](/assets/images/semantic-recall-fd7b9336a6d0d18019216cb6d3dbe710.png)
 
 When it's enabled, new messages are used to query a vector DB for semantically similar messages.
 
@@ -24,7 +20,7 @@ After getting a response from the LLM, all new messages (user, assistant, and to
 
 Semantic recall is enabled by default, so if you give your agent memory it will be included:
 
-```typescript {9}
+```typescript
 import { Agent } from "@mastra/core/agent";
 import { Memory } from "@mastra/memory";
 
@@ -64,7 +60,7 @@ const { messages: relevantMessages } = await memory!.recall({
 
 Semantic recall relies on a [storage and vector db](https://mastra.ai/reference/memory/memory-class) to store messages and their embeddings.
 
-```ts {8-16}
+```ts
 import { Memory } from "@mastra/memory";
 import { Agent } from "@mastra/core/agent";
 import { LibSQLStore, LibSQLVector } from "@mastra/libsql";
@@ -113,7 +109,7 @@ The three main parameters that control semantic recall behavior are:
 2. **messageRange**: How much surrounding context to include with each match
 3. **scope**: Whether to search within the current thread or across all threads owned by a resource (the default is resource scope).
 
-```typescript {5-7}
+```typescript
 const agent = new Agent({
   memory: new Memory({
     options: {
@@ -135,7 +131,7 @@ Semantic recall relies on an [embedding model](https://mastra.ai/reference/memor
 
 The simplest way is to use a `provider/model` string with autocomplete support:
 
-```ts {7}
+```ts
 import { Memory } from "@mastra/memory";
 import { Agent } from "@mastra/core/agent";
 import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
@@ -158,7 +154,7 @@ The model router automatically handles API key detection from environment variab
 
 You can also use AI SDK embedding models directly:
 
-```ts {2,7}
+```ts
 import { Memory } from "@mastra/memory";
 import { Agent } from "@mastra/core/agent";
 import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
@@ -174,13 +170,33 @@ const agent = new Agent({
 
 To use FastEmbed (a local embedding model), install `@mastra/fastembed`:
 
-```bash npm2yarn
+**npm**:
+
+```bash
 npm install @mastra/fastembed@latest
 ```
 
+**pnpm**:
+
+```bash
+pnpm add @mastra/fastembed@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/fastembed@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/fastembed@latest
+```
+
 Then configure it in your memory:
 
-```ts {3,7}
+```ts
 import { Memory } from "@mastra/memory";
 import { Agent } from "@mastra/core/agent";
 import { fastembed } from "@mastra/fastembed";
@@ -198,7 +214,7 @@ When using PostgreSQL as your vector store, you can optimize semantic recall per
 
 PostgreSQL supports both IVFFlat and HNSW indexes. By default, Mastra creates an IVFFlat index, but HNSW indexes typically provide better performance, especially with OpenAI embeddings which use inner product distance.
 
-```typescript {18-23}
+```typescript
 import { Memory } from "@mastra/memory";
 import { PgStore, PgVector } from "@mastra/pg";
 
@@ -228,7 +244,7 @@ const agent = new Agent({
 });
 ```
 
-For detailed information about index configuration options and performance tuning, see the [PgVector configuration guide](https://mastra.ai/reference/vectors/pg#index-configuration-guide).
+For detailed information about index configuration options and performance tuning, see the [PgVector configuration guide](https://mastra.ai/reference/vectors/pg).
 
 ## Disabling
 
@@ -236,7 +252,7 @@ There is a performance impact to using semantic recall. New messages are convert
 
 Semantic recall is enabled by default but can be disabled when not needed:
 
-```typescript {4}
+```typescript
 const agent = new Agent({
   memory: new Memory({
     options: {