@mastra/memory 1.10.1-alpha.3 → 1.11.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.10.1-alpha.3"
+  version: "1.11.0"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,120 +1,120 @@
 {
-  "version": "1.10.1-alpha.3",
+  "version": "1.11.0",
   "package": "@mastra/memory",
   "exports": {
     "ModelByInputTokens": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-SKRONGCV.js",
-      "line": 665
+      "implementation": "dist/chunk-D4D6ZFBQ.js",
+      "line": 666
     },
     "OBSERVER_SYSTEM_PROMPT": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-SKRONGCV.js"
+      "implementation": "dist/chunk-D4D6ZFBQ.js"
     },
     "ObservationalMemory": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-SKRONGCV.js",
-      "line": 5518
+      "implementation": "dist/chunk-D4D6ZFBQ.js",
+      "line": 5698
     },
     "ObservationalMemoryProcessor": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-SKRONGCV.js",
-      "line": 7976
+      "implementation": "dist/chunk-D4D6ZFBQ.js",
+      "line": 8220
     },
     "TokenCounter": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-SKRONGCV.js",
-      "line": 5070
+      "implementation": "dist/chunk-D4D6ZFBQ.js",
+      "line": 5250
     },
     "buildObserverPrompt": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-SKRONGCV.js",
-      "line": 3229
+      "implementation": "dist/chunk-D4D6ZFBQ.js",
+      "line": 3277
     },
     "buildObserverSystemPrompt": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-SKRONGCV.js",
-      "line": 2703
+      "implementation": "dist/chunk-D4D6ZFBQ.js",
+      "line": 2751
     },
     "combineObservationGroupRanges": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-SKRONGCV.js",
-      "line": 754
+      "implementation": "dist/chunk-D4D6ZFBQ.js",
+      "line": 755
     },
     "deriveObservationGroupProvenance": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-SKRONGCV.js",
-      "line": 781
+      "implementation": "dist/chunk-D4D6ZFBQ.js",
+      "line": 782
     },
     "extractCurrentTask": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-SKRONGCV.js",
-      "line": 3343
+      "implementation": "dist/chunk-D4D6ZFBQ.js",
+      "line": 3391
     },
     "formatMessagesForObserver": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-SKRONGCV.js",
-      "line": 2969
+      "implementation": "dist/chunk-D4D6ZFBQ.js",
+      "line": 3017
     },
     "getObservationsAsOf": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-SKRONGCV.js",
-      "line": 8148
+      "implementation": "dist/chunk-D4D6ZFBQ.js",
+      "line": 8398
     },
     "hasCurrentTaskSection": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-SKRONGCV.js",
-      "line": 3331
+      "implementation": "dist/chunk-D4D6ZFBQ.js",
+      "line": 3379
     },
     "injectAnchorIds": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-SKRONGCV.js",
-      "line": 2260
+      "implementation": "dist/chunk-D4D6ZFBQ.js",
+      "line": 2308
     },
     "optimizeObservationsForContext": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-SKRONGCV.js",
-      "line": 3354
+      "implementation": "dist/chunk-D4D6ZFBQ.js",
+      "line": 3402
     },
     "parseAnchorId": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-SKRONGCV.js",
-      "line": 2233
+      "implementation": "dist/chunk-D4D6ZFBQ.js",
+      "line": 2281
     },
     "parseObservationGroups": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-SKRONGCV.js",
-      "line": 726
+      "implementation": "dist/chunk-D4D6ZFBQ.js",
+      "line": 727
     },
     "parseObserverOutput": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-SKRONGCV.js",
-      "line": 3239
+      "implementation": "dist/chunk-D4D6ZFBQ.js",
+      "line": 3287
     },
     "reconcileObservationGroupsFromReflection": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-SKRONGCV.js",
-      "line": 808
+      "implementation": "dist/chunk-D4D6ZFBQ.js",
+      "line": 809
     },
     "renderObservationGroupsForReflection": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-SKRONGCV.js",
-      "line": 761
+      "implementation": "dist/chunk-D4D6ZFBQ.js",
+      "line": 762
     },
     "stripEphemeralAnchorIds": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-SKRONGCV.js",
-      "line": 2290
+      "implementation": "dist/chunk-D4D6ZFBQ.js",
+      "line": 2338
     },
     "stripObservationGroups": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-SKRONGCV.js",
-      "line": 748
+      "implementation": "dist/chunk-D4D6ZFBQ.js",
+      "line": 749
     },
     "wrapInObservationGroup": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-SKRONGCV.js",
-      "line": 719
+      "implementation": "dist/chunk-D4D6ZFBQ.js",
+      "line": 720
     },
     "OBSERVATIONAL_MEMORY_DEFAULTS": {
       "types": "dist/processors/index.d.ts",
@@ -161,7 +161,7 @@
     "processors": {
       "index": "dist/processors/index.js",
       "chunks": [
-        "chunk-SKRONGCV.js",
+        "chunk-D4D6ZFBQ.js",
         "chunk-LSJJAJAF.js"
       ]
     }

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

@@ -95,27 +95,72 @@ The result is a three-tier system:
 
 Normal OM compresses messages into observations, which is great for staying on task — but the original wording is gone. Retrieval mode fixes this by keeping each observation group linked to the raw messages that produced it. When the agent needs exact wording, tool output, or chronology that the summary compressed away, it can call a `recall` tool to page through the source messages.
 
+#### Browsing only
+
+Set `retrieval: true` to enable the recall tool for browsing raw messages. No vector store needed. By default, the recall tool can browse across all threads for the current resource.
+
 ```typescript
 const memory = new Memory({
   options: {
     observationalMemory: {
       model: 'google/gemini-2.5-flash',
-      scope: 'thread',
       retrieval: true,
     },
   },
 })
 ```
 
+#### With semantic search
+
+Set `retrieval: { vector: true }` to also enable semantic search. This reuses the vector store and embedder already configured on your Memory instance:
+
+```typescript
+const memory = new Memory({
+  storage,
+  vector: myVectorStore,
+  embedder: myEmbedder,
+  options: {
+    observationalMemory: {
+      model: 'google/gemini-2.5-flash',
+      retrieval: { vector: true },
+    },
+  },
+})
+```
+
+When vector search is configured, new observation groups are automatically indexed at buffer time and during synchronous observation (fire-and-forget, non-blocking). Semantic search returns observation-group matches with their raw source message ID ranges, so the recall tool can show the summarized memory alongside where it came from.
+
+#### Restricting to the current thread
+
+By default, the recall tool scope is `'resource'` — the agent can list threads, browse other threads, and search across all conversations. Set `scope: 'thread'` to restrict the agent to only the current thread:
+
+```typescript
+const memory = new Memory({
+  options: {
+    observationalMemory: {
+      model: 'google/gemini-2.5-flash',
+      retrieval: { vector: true, scope: 'thread' },
+    },
+  },
+})
+```
+
+#### What retrieval enables
+
 With retrieval mode enabled, OM:
 
 - Stores a `range` (e.g. `startId:endId`) on each observation group pointing to the messages it was derived from
+
 - Keeps range metadata visible in the agent's context so the agent knows which observations map to which messages
-- Registers a `recall` tool the agent can call to page through the raw messages behind any range
 
-Retrieval mode is only active for thread-scoped OM. Setting `retrieval: true` with `scope: 'resource'` has no effect — OM keeps resource-scoped behavior but skips retrieval-mode context and does not register the `recall` tool.
+- Registers a `recall` tool the agent can call to:
+
+  - Page through the raw messages behind any observation group range
+  - Search by semantic similarity (`mode: "search"` with a `query` string) — requires `vector: true`
+  - List all threads (`mode: "threads"`), browse other threads (`threadId`), and search across all threads (default `scope: 'resource'`)
+  - When `scope: 'thread'`: restrict browsing and search to the current thread only
 
-See the [recall tool reference](https://mastra.ai/reference/memory/observational-memory) for the full API (detail levels, part indexing, pagination, and token limiting).
+See the [recall tool reference](https://mastra.ai/reference/memory/observational-memory) for the full API (detail levels, part indexing, pagination, cross-thread browsing, and token limiting).
 
 ## Models
 

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

@@ -38,7 +38,7 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
 
 **shareTokenBudget** (`boolean`): Share the token budget between messages and observations. When enabled, the total budget is \`observation.messageTokens + reflection.observationTokens\`. Messages can use more space when observations are small, and vice versa. This maximizes context usage through flexible allocation. \`shareTokenBudget\` is not yet compatible with async buffering. You must set \`observation: { bufferTokens: false }\` when using this option (this is a temporary limitation). (Default: `false`)
 
-**retrieval** (`boolean`): \*\*Experimental.\*\* Enable retrieval-mode observation groups as durable pointers to raw message history. Retrieval mode is only active when \`scope\` is \`'thread'\`. If you set \`retrieval: true\` with \`scope: 'resource'\`, OM keeps resource-scoped memory behavior but skips retrieval-mode context and does not register the \`recall\` tool. (Default: `false`)
+**retrieval** (`boolean | { vector?: boolean; scope?: 'thread' | 'resource' }`): \*\*Experimental.\*\* Enable retrieval-mode observation groups as durable pointers to raw message history. \`true\` enables cross-thread browsing by default. \`{ vector: true }\` also enables semantic search using Memory's vector store and embedder. \`{ scope: 'thread' }\` restricts the recall tool to the current thread only. Default scope is \`'resource'\`. (Default: `false`)
 
 **observation** (`ObservationalMemoryObservationConfig`): Configuration for the observation step. Controls when the Observer agent runs and how it behaves.
 
@@ -578,21 +578,31 @@ The standalone `ObservationalMemory` class accepts all the same options as the `
 
 ## Recall tool
 
-When `retrieval: true` is set with `scope: 'thread'`, OM registers a `recall` tool that the agent can call to page through the raw messages behind an observation group's `_range`. The tool is automatically added to the agent's tool list — no manual registration is needed.
+When `retrieval` is set (any truthy value), a `recall` tool is registered so the agent can page through raw messages behind observation group ranges. By default (scope `'resource'`), the tool supports listing threads (`mode: "threads"`), browsing other threads (`threadId`), and cross-thread search. With `retrieval: { vector: true }`, semantic search is available (`mode: "search"`). Set `scope: 'thread'` to restrict the tool to the current thread only. The tool is automatically added to the agent's tool list — no manual registration is needed.
 
 ### Parameters
 
-**cursor** (`string`): A message ID to anchor the recall query. Extract the start or end ID from an observation group range (e.g. from \`\_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.
+**mode** (`'messages' | 'threads' | 'search'`): What to retrieve. \`"messages"\` (default) pages through message history. \`"threads"\` lists all threads for the current user. \`"search"\` finds messages by semantic similarity across all threads (requires vector store and embedder). (Default: `'messages'`)
 
-**page** (`number`): Pagination offset from the cursor. Positive values page forward (messages after the cursor), negative values page backward (messages before the cursor). \`0\` is treated as \`1\`. (Default: `1`)
+**query** (`string`): Search query for \`mode: "search"\`. Finds messages semantically similar to this text across all threads for the current user.
 
-**limit** (`number`): Maximum number of messages per page. (Default: `20`)
+**cursor** (`string`): A message ID to anchor the recall query. Required for \`mode: "messages"\` when browsing the current thread. Extract the start or end ID from an observation group range (e.g. from \`\_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. Can be omitted when \`threadId\` is provided to start reading from the beginning of that thread.
+
+**threadId** (`string`): Browse a different thread by its ID. Use \`mode: "threads"\` first to discover thread IDs. When provided without a \`cursor\`, reading starts from the beginning of the thread.
+
+**page** (`number`): Pagination offset. For messages: positive values page forward from cursor, negative values page backward. For threads: page number (0-indexed). \`0\` is treated as \`1\` for messages. (Default: `1`)
+
+**limit** (`number`): Maximum number of items to return per page. (Default: `20`)
 
 **detail** (`'low' | 'high'`): Controls how much content is shown per message part. \`'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. (Default: `'low'`)
 
 **partIndex** (`number`): Fetch a single message part at full detail by its positional index. Use this when a low-detail recall shows an interesting part at \`\[p1]\` — call again with \`partIndex: 1\` to see the full content without loading every part.
 
-### Returns
+**before** (`string`): For \`mode: "threads"\` only. Filter to threads created before this date. Accepts ISO 8601 format (e.g. \`"2026-03-15"\`, \`"2026-03-10T00:00:00Z"\`).
+
+**after** (`string`): For \`mode: "threads"\` only. Filter to threads created after this date. Accepts ISO 8601 format (e.g. \`"2026-03-01"\`, \`"2026-03-10T00:00:00Z"\`).
+
+### Returns (messages mode)
 
 **messages** (`string`): Formatted message content. Format depends on the \`detail\` level.
 
@@ -612,6 +622,22 @@ When `retrieval: true` is set with `scope: 'thread'`, OM registers a `recall` to
 
 **tokenOffset** (`number`): Approximate number of tokens that were trimmed when \`truncated\` is true.
 
+### Returns (threads mode)
+
+**threads** (`string`): Formatted thread listing. Each thread shows its title, ID, and dates. The current thread is marked with \`← current\`.
+
+**count** (`number`): Number of threads returned.
+
+**page** (`number`): The page number returned.
+
+**hasMore** (`boolean`): Whether more threads exist on the next page.
+
+### Returns (search mode)
+
+**results** (`string`): Formatted search results grouped by thread. Each result shows the thread title, thread ID, relevance score, message preview, and a cursor ID for browsing into that thread.
+
+**count** (`number`): Number of matching messages found.
+
 ### 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.