@mastra/memory 1.7.0 → 1.8.0

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-memory
 description: Documentation for @mastra/memory. Use when working with @mastra/memory APIs, configuration, or implementation.
 metadata:
   package: "@mastra/memory"
-  version: "1.7.0"
+  version: "1.8.0"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,71 +1,71 @@
 {
-  "version": "1.7.0",
+  "version": "1.8.0",
   "package": "@mastra/memory",
   "exports": {
     "OBSERVATIONAL_MEMORY_DEFAULTS": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-M7RAJAZ6.js"
+      "implementation": "dist/chunk-SUU4IAZJ.js"
     },
     "OBSERVATION_CONTEXT_INSTRUCTIONS": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-M7RAJAZ6.js"
+      "implementation": "dist/chunk-SUU4IAZJ.js"
     },
     "OBSERVATION_CONTEXT_PROMPT": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-M7RAJAZ6.js"
+      "implementation": "dist/chunk-SUU4IAZJ.js"
     },
     "OBSERVATION_CONTINUATION_HINT": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-M7RAJAZ6.js"
+      "implementation": "dist/chunk-SUU4IAZJ.js"
     },
     "OBSERVER_SYSTEM_PROMPT": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-M7RAJAZ6.js"
+      "implementation": "dist/chunk-SUU4IAZJ.js"
     },
     "ObservationalMemory": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-M7RAJAZ6.js",
-      "line": 2890
+      "implementation": "dist/chunk-SUU4IAZJ.js",
+      "line": 2966
     },
     "TokenCounter": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-M7RAJAZ6.js",
-      "line": 2371
+      "implementation": "dist/chunk-SUU4IAZJ.js",
+      "line": 2447
     },
     "buildObserverPrompt": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-M7RAJAZ6.js",
-      "line": 992
+      "implementation": "dist/chunk-SUU4IAZJ.js",
+      "line": 1068
     },
     "buildObserverSystemPrompt": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-M7RAJAZ6.js",
+      "implementation": "dist/chunk-SUU4IAZJ.js",
       "line": 572
     },
     "extractCurrentTask": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-M7RAJAZ6.js",
-      "line": 1100
+      "implementation": "dist/chunk-SUU4IAZJ.js",
+      "line": 1176
     },
     "formatMessagesForObserver": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-M7RAJAZ6.js",
-      "line": 819
+      "implementation": "dist/chunk-SUU4IAZJ.js",
+      "line": 827
     },
     "hasCurrentTaskSection": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-M7RAJAZ6.js",
-      "line": 1088
+      "implementation": "dist/chunk-SUU4IAZJ.js",
+      "line": 1164
     },
     "optimizeObservationsForContext": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-M7RAJAZ6.js",
-      "line": 1111
+      "implementation": "dist/chunk-SUU4IAZJ.js",
+      "line": 1187
     },
     "parseObserverOutput": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-M7RAJAZ6.js",
-      "line": 1002
+      "implementation": "dist/chunk-SUU4IAZJ.js",
+      "line": 1078
     },
     "extractWorkingMemoryContent": {
       "types": "dist/index.d.ts",
@@ -96,7 +96,7 @@
     "processors": {
       "index": "dist/processors/index.js",
       "chunks": [
-        "chunk-M7RAJAZ6.js"
+        "chunk-SUU4IAZJ.js"
       ]
     }
   }

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

@@ -230,6 +230,29 @@ Setting `bufferTokens: false` disables both observation and reflection async buf
 
 > **Note:** Async buffering isn't supported with `scope: 'resource'`. It's automatically disabled in resource scope.
 
+## Observer Context Optimization
+
+By default, the Observer receives the full observation history as context when processing new messages. The Observer also receives prior `current-task` and `suggested-response` metadata (when available), so it can stay oriented even when observation context is truncated. For long-running conversations where observations grow large, you can opt into context optimization to reduce Observer input costs.
+
+Set `observation.previousObserverTokens` to limit how many tokens of previous observations are sent to the Observer. Observations are tail-truncated, keeping the most recent entries. When a buffered reflection is pending, the already-reflected lines are automatically replaced with the reflection summary before truncation is applied.
+
+```typescript
+const memory = new Memory({
+  options: {
+    observationalMemory: {
+      model: 'google/gemini-2.5-flash',
+      observation: {
+        previousObserverTokens: 10_000, // keep only ~10k tokens of recent observations
+      },
+    },
+  },
+})
+```
+
+- `previousObserverTokens: 2000` → default; keeps \~2k tokens of recent observations.
+- `previousObserverTokens: 0` → omit previous observations completely.
+- `previousObserverTokens: false` → disable truncation and keep full previous observations.
+
 ## Migrating existing threads
 
 No manual migration needed. OM reads existing messages and observes them lazily when thresholds are exceeded.

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

@@ -5,9 +5,9 @@ Memory enables your agent to remember user messages, agent replies, and tool res
 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.
+- [**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.
 - [**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) 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.
 
@@ -16,9 +16,9 @@ If the combined memory exceeds the model's context limit, [memory processors](ht
 Choose a memory option to get started:
 
 - [Message history](https://mastra.ai/docs/memory/message-history)
+- [Observational memory](https://mastra.ai/docs/memory/observational-memory)
 - [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
 
@@ -41,5 +41,5 @@ This visibility helps you understand why an agent made specific decisions and ve
 ## 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), [Semantic recall](https://mastra.ai/docs/memory/semantic-recall), or [Observational memory](https://mastra.ai/docs/memory/observational-memory)
+- Add [Message history](https://mastra.ai/docs/memory/message-history), [Observational memory](https://mastra.ai/docs/memory/observational-memory), [Working memory](https://mastra.ai/docs/memory/working-memory), or [Semantic recall](https://mastra.ai/docs/memory/semantic-recall)
 - Visit [Memory configuration reference](https://mastra.ai/reference/memory/memory-class) for all available options

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

@@ -60,6 +60,8 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
 
 **observation.blockAfter** (`number`): Token threshold above which synchronous (blocking) observation is forced. Between \`messageTokens\` and \`blockAfter\`, only async buffering/activation is used. Above \`blockAfter\`, a synchronous observation runs as a last resort, while buffered activation still preserves a minimum remaining context (min(1000, retention floor)). Accepts a multiplier (1 < value < 2, multiplied by \`messageTokens\`) or an absolute token count (≥ 2, must be greater than \`messageTokens\`). Only relevant when \`bufferTokens\` is set. Defaults to \`1.2\` when async buffering is enabled.
 
+**observation.previousObserverTokens** (`number | false`): Optional token budget for the observer's previous-observations context. When set to a number, the observations passed to the Observer agent are tail-truncated to fit within this budget while keeping the newest observations and preserving highlighted 🔴 items when possible. When a buffered reflection is pending, the already-reflected observation lines are automatically replaced with the reflection summary before truncation. Set to \`0\` to omit previous observations entirely, or \`false\` to disable truncation explicitly.
+
 **reflection** (`ObservationalMemoryReflectionConfig`): Configuration for the reflection step. Controls when the Reflector agent runs and how it behaves.
 
 **reflection.model** (`string | LanguageModel | DynamicModel | ModelWithRetries[]`): Model for the Reflector agent. Cannot be set if a top-level \`model\` is also provided. If neither this nor the top-level \`model\` is set, falls back to \`observation.model\`.