@mastra/memory 1.17.6-alpha.1 → 1.18.0-alpha.2

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.17.6-alpha.1"
+  version: "1.18.0-alpha.2"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,119 +1,119 @@
 {
-  "version": "1.17.6-alpha.1",
+  "version": "1.18.0-alpha.2",
   "package": "@mastra/memory",
   "exports": {
     "ModelByInputTokens": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-QZGJY67D.js",
+      "implementation": "dist/chunk-PBZHHKPE.js",
       "line": 745
     },
     "OBSERVER_SYSTEM_PROMPT": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-QZGJY67D.js"
+      "implementation": "dist/chunk-PBZHHKPE.js"
     },
     "ObservationalMemory": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-QZGJY67D.js",
-      "line": 6674
+      "implementation": "dist/chunk-PBZHHKPE.js",
+      "line": 6690
     },
     "ObservationalMemoryProcessor": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-QZGJY67D.js",
-      "line": 9219
+      "implementation": "dist/chunk-PBZHHKPE.js",
+      "line": 9262
     },
     "TokenCounter": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-QZGJY67D.js",
-      "line": 6144
+      "implementation": "dist/chunk-PBZHHKPE.js",
+      "line": 6160
     },
     "buildObserverPrompt": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-QZGJY67D.js",
-      "line": 3643
+      "implementation": "dist/chunk-PBZHHKPE.js",
+      "line": 3659
     },
     "buildObserverSystemPrompt": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-QZGJY67D.js",
-      "line": 2951
+      "implementation": "dist/chunk-PBZHHKPE.js",
+      "line": 2967
     },
     "combineObservationGroupRanges": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-QZGJY67D.js",
+      "implementation": "dist/chunk-PBZHHKPE.js",
       "line": 837
     },
     "deriveObservationGroupProvenance": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-QZGJY67D.js",
+      "implementation": "dist/chunk-PBZHHKPE.js",
       "line": 871
     },
     "extractCurrentTask": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-QZGJY67D.js",
-      "line": 3757
+      "implementation": "dist/chunk-PBZHHKPE.js",
+      "line": 3773
     },
     "formatMessagesForObserver": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-QZGJY67D.js",
-      "line": 3369
+      "implementation": "dist/chunk-PBZHHKPE.js",
+      "line": 3385
     },
     "getObservationsAsOf": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-QZGJY67D.js",
-      "line": 9425
+      "implementation": "dist/chunk-PBZHHKPE.js",
+      "line": 9474
     },
     "hasCurrentTaskSection": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-QZGJY67D.js",
-      "line": 3745
+      "implementation": "dist/chunk-PBZHHKPE.js",
+      "line": 3761
     },
     "injectAnchorIds": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-QZGJY67D.js",
-      "line": 2499
+      "implementation": "dist/chunk-PBZHHKPE.js",
+      "line": 2515
     },
     "optimizeObservationsForContext": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-QZGJY67D.js",
-      "line": 3768
+      "implementation": "dist/chunk-PBZHHKPE.js",
+      "line": 3784
     },
     "parseAnchorId": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-QZGJY67D.js",
-      "line": 2472
+      "implementation": "dist/chunk-PBZHHKPE.js",
+      "line": 2488
     },
     "parseObservationGroups": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-QZGJY67D.js",
+      "implementation": "dist/chunk-PBZHHKPE.js",
       "line": 806
     },
     "parseObserverOutput": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-QZGJY67D.js",
-      "line": 3653
+      "implementation": "dist/chunk-PBZHHKPE.js",
+      "line": 3669
     },
     "reconcileObservationGroupsFromReflection": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-QZGJY67D.js",
+      "implementation": "dist/chunk-PBZHHKPE.js",
       "line": 895
     },
     "renderObservationGroupsForReflection": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-QZGJY67D.js",
+      "implementation": "dist/chunk-PBZHHKPE.js",
       "line": 851
     },
     "stripEphemeralAnchorIds": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-QZGJY67D.js",
-      "line": 2529
+      "implementation": "dist/chunk-PBZHHKPE.js",
+      "line": 2545
     },
     "stripObservationGroups": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-QZGJY67D.js",
+      "implementation": "dist/chunk-PBZHHKPE.js",
       "line": 828
     },
     "wrapInObservationGroup": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-QZGJY67D.js",
+      "implementation": "dist/chunk-PBZHHKPE.js",
       "line": 799
     },
     "OBSERVATIONAL_MEMORY_DEFAULTS": {
@@ -149,7 +149,7 @@
     "processors": {
       "index": "dist/processors/index.js",
       "chunks": [
-        "chunk-QZGJY67D.js",
+        "chunk-PBZHHKPE.js",
         "chunk-LSJJAJAF.js"
       ]
     }

package/dist/docs/references/docs-memory-semantic-recall.md

@@ -121,26 +121,88 @@ Each vector store page below includes installation instructions, configuration p
 
 ## Recall configuration
 
-The three main parameters that control semantic recall behavior are:
+The following options control semantic recall behavior:
 
-1. **topK**: How many semantically similar messages to retrieve
-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).
+1. **topK**: The number of similar messages to retrieve
+2. **messageRange**: The surrounding messages to include with each match
+3. **scope**: Whether to search the current thread or all threads for a resource
+4. **filter**: Metadata criteria that restrict search results
 
 ```typescript
 const agent = new Agent({
   memory: new Memory({
     options: {
       semanticRecall: {
-        topK: 3, // Retrieve 3 most similar messages
+        topK: 3, // Retrieve 3 similar messages
         messageRange: 2, // Include 2 messages before and after each match
-        scope: 'resource', // Search across all threads for this user (default setting if omitted)
+        scope: 'resource', // Search all threads for this resource
+        filter: { projectId: { $eq: 'project-a' } },
       },
     },
   }),
 })
 ```
 
+> **Note:** `scope: 'resource'` is supported by the LibSQL, PostgreSQL, and Upstash storage adapters.
+
+### Metadata filtering
+
+The `filter` option restricts semantic recall results to messages with matching thread metadata.
+
+```typescript
+const agent = new Agent({
+  memory: new Memory({
+    options: {
+      semanticRecall: {
+        scope: 'resource',
+        filter: {
+          projectId: { $eq: 'project-a' },
+          category: { $in: ['work', 'personal'] },
+        },
+      },
+    },
+  }),
+})
+```
+
+Filters match metadata stored on message embeddings when messages are saved. If thread metadata changes later, existing embeddings keep their previous metadata until those messages are saved or indexed again.
+
+Supported filter operators:
+
+- `$and`: Logical AND
+- `$eq`: Equal to
+- `$gt`: Greater than
+- `$gte`: Greater than or equal
+- `$in`: In array
+- `$lt`: Less than
+- `$lte`: Less than or equal
+- `$ne`: Not equal to
+- `$nin`: Not in array
+- `$or`: Logical OR
+
+The following example demonstrates metadata filters for common use cases:
+
+```typescript
+// Filter by project
+const options = {
+  semanticRecall: { filter: { projectId: { $eq: 'my-project' } } },
+}
+
+// Filter by multiple categories
+const options = {
+  semanticRecall: { filter: { category: { $in: ['work', 'research'] } } },
+}
+
+// Filter by project and priority
+const options = {
+  semanticRecall: {
+    filter: {
+      $and: [{ projectId: { $eq: 'project-a' } }, { priority: { $gte: 3 } }],
+    },
+  },
+}
+```
+
 ## Embedder configuration
 
 Semantic recall relies on an [embedding model](https://mastra.ai/reference/memory/memory-class) to convert messages into embeddings. Mastra supports embedding models through the model router using `provider/model` strings, or you can use any [embedding model](https://sdk.vercel.ai/docs/ai-sdk-core/embeddings) compatible with the AI SDK.

package/dist/index.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunkWNLFJKTX_cjs = require('./chunk-WNLFJKTX.cjs');
+var chunkMJNTQ6GP_cjs = require('./chunk-MJNTQ6GP.cjs');
 var v3 = require('zod/v3');
 var zod = require('zod');
 var z4 = require('zod/v4');
@@ -16110,7 +16110,7 @@ function formatTimestamp(date) {
 }
 function truncateByTokens(text4, maxTokens, hint) {
   if (tokenx.estimateTokenCount(text4) <= maxTokens) return { text: text4, wasTruncated: false };
-  const truncated = chunkWNLFJKTX_cjs.truncateStringByTokens(text4, maxTokens);
+  const truncated = chunkMJNTQ6GP_cjs.truncateStringByTokens(text4, maxTokens);
   const suffix = hint ? ` [${hint} for more]` : "";
   return { text: truncated + suffix, wasTruncated: true };
 }
@@ -16162,11 +16162,11 @@ ${JSON.stringify(inv.args, null, 2)}`;
             });
           }
           if (inv.state === "result") {
-            const { value: resultValue } = chunkWNLFJKTX_cjs.resolveToolResultValue(
+            const { value: resultValue } = chunkMJNTQ6GP_cjs.resolveToolResultValue(
               part,
               inv.result
             );
-            const resultStr = chunkWNLFJKTX_cjs.formatToolResultForObserver(resultValue, { maxTokens: HIGH_DETAIL_TOOL_RESULT_TOKENS });
+            const resultStr = chunkMJNTQ6GP_cjs.formatToolResultForObserver(resultValue, { maxTokens: HIGH_DETAIL_TOOL_RESULT_TOKENS });
             const fullText = `[Tool Result: ${inv.toolName}]
 ${resultStr}`;
             parts.push(makePart(msg, i, "tool-result", fullText, detail, inv.toolName));
@@ -16193,7 +16193,7 @@ ${typeof rawArgs === "string" ? rawArgs : JSON.stringify(rawArgs, null, 2)}`;
         const toolName = part.toolName;
         if (toolName) {
           const rawResult = part.output ?? part.result;
-          const resultStr = chunkWNLFJKTX_cjs.formatToolResultForObserver(rawResult, { maxTokens: HIGH_DETAIL_TOOL_RESULT_TOKENS });
+          const resultStr = chunkMJNTQ6GP_cjs.formatToolResultForObserver(rawResult, { maxTokens: HIGH_DETAIL_TOOL_RESULT_TOKENS });
           const fullText = `[Tool Result: ${toolName}]
 ${resultStr}`;
           parts.push(makePart(msg, i, "tool-result", fullText, detail, toolName));
@@ -16272,7 +16272,7 @@ function renderFormattedParts(parts, timestamps, options) {
   const text4 = buildRenderedText(parts, timestamps);
   let totalTokens = tokenx.estimateTokenCount(text4);
   if (totalTokens > options.maxTokens) {
-    const truncated = chunkWNLFJKTX_cjs.truncateStringByTokens(text4, options.maxTokens);
+    const truncated = chunkMJNTQ6GP_cjs.truncateStringByTokens(text4, options.maxTokens);
     return { text: truncated, truncated: true, tokenOffset: totalTokens - options.maxTokens };
   }
   const truncatedIndices = parts.map((p, i) => ({ part: p, index: i })).filter(({ part }) => part.text !== part.fullText).sort((a, b) => expandPriority(a.part) - expandPriority(b.part));
@@ -16305,7 +16305,7 @@ function renderFormattedParts(parts, timestamps, options) {
   if (expandedTokens <= options.maxTokens) {
     return { text: expanded, truncated: false, tokenOffset: 0 };
   }
-  const hardTruncated = chunkWNLFJKTX_cjs.truncateStringByTokens(expanded, options.maxTokens);
+  const hardTruncated = chunkMJNTQ6GP_cjs.truncateStringByTokens(expanded, options.maxTokens);
   return { text: hardTruncated, truncated: true, tokenOffset: expandedTokens - options.maxTokens };
 }
 async function recallPart({
@@ -16356,7 +16356,7 @@ async function recallPart({
 
 `;
           const fallbackText = `${fallbackNote}${firstNextPart.text}`;
-          const truncatedText2 = chunkWNLFJKTX_cjs.truncateStringByTokens(fallbackText, maxTokens);
+          const truncatedText2 = chunkMJNTQ6GP_cjs.truncateStringByTokens(fallbackText, maxTokens);
           const wasTruncated2 = truncatedText2 !== fallbackText;
           return {
             text: truncatedText2,
@@ -16371,7 +16371,7 @@ async function recallPart({
     }
     throw new Error(`Part index ${partIndex} not found in message ${cursor}. Available indices: ${availableIndices}`);
   }
-  const truncatedText = chunkWNLFJKTX_cjs.truncateStringByTokens(target.text, maxTokens);
+  const truncatedText = chunkMJNTQ6GP_cjs.truncateStringByTokens(target.text, maxTokens);
   const wasTruncated = truncatedText !== target.text;
   return {
     text: truncatedText,
@@ -17351,16 +17351,15 @@ var Memory = class extends memory.MastraMemory {
                 `Tried to query vector index ${indexName} but this Memory instance doesn't have an attached vector db.`
               );
             }
+            const scopeFilter = resourceScope ? { resource_id: resourceId } : { thread_id: threadId };
+            const userFilter = typeof config.semanticRecall === "object" ? config.semanticRecall.filter : void 0;
+            const combinedFilter = userFilter ? { $and: [scopeFilter, userFilter] } : scopeFilter;
             vectorResults.push(
               ...await this.vector.query({
                 indexName,
                 queryVector: embedding,
                 topK: vectorConfig.topK,
-                filter: resourceScope ? {
-                  resource_id: resourceId
-                } : {
-                  thread_id: threadId
-                }
+                filter: combinedFilter
               })
             );
           })
@@ -17762,6 +17761,31 @@ ${workingMemory}`;
       });
       let totalTokens = 0;
       if (this.vector && config.semanticRecall) {
+        const messagesByThread = /* @__PURE__ */ new Map();
+        updatedMessages.forEach((message) => {
+          if (message.threadId) {
+            if (!messagesByThread.has(message.threadId)) {
+              messagesByThread.set(message.threadId, []);
+            }
+            messagesByThread.get(message.threadId).push(message);
+          }
+        });
+        const threadMetadataMap = /* @__PURE__ */ new Map();
+        await Promise.all(
+          Array.from(messagesByThread.keys()).map(async (threadId) => {
+            try {
+              const thread = await memoryStore.getThreadById({ threadId });
+              if (thread?.metadata) {
+                threadMetadataMap.set(threadId, thread.metadata);
+              }
+            } catch (error) {
+              const message = error instanceof Error ? error.message : String(error);
+              throw new Error(
+                `Could not fetch metadata for thread ${threadId} while saving semantic recall embeddings: ${message}`
+              );
+            }
+          })
+        );
         const embeddingData = [];
         let dimension;
         await Promise.all(
@@ -17779,9 +17803,11 @@ ${workingMemory}`;
             if (result2.usage?.tokens) {
               totalTokens += result2.usage.tokens;
             }
+            const threadMetadata = message.threadId ? threadMetadataMap.get(message.threadId) || {} : {};
             embeddingData.push({
               embeddings: result2.embeddings,
               metadata: result2.chunks.map(() => ({
+                ...threadMetadata,
                 message_id: message.id,
                 thread_id: message.threadId,
                 resource_id: message.resourceId
@@ -18094,7 +18120,7 @@ ${workingMemory}`;
         "Observational memory requires @mastra/core support for request-response-id-rotation. Please bump @mastra/core to a newer version."
       );
     }
-    const { ObservationalMemory: OMClass } = await import('./observational-memory-BJF72NKJ.cjs');
+    const { ObservationalMemory: OMClass } = await import('./observational-memory-TASIB4PH.cjs');
     const onIndexObservations = this.hasRetrievalSearch(omConfig.retrieval) ? async (observation) => {
       await this.indexObservation(observation);
     } : void 0;
@@ -19020,7 +19046,7 @@ Notes:
     if (!effectiveConfig) return null;
     const engine = await this.omEngine;
     if (!engine) return null;
-    const { ObservationalMemoryProcessor } = await import('./observational-memory-BJF72NKJ.cjs');
+    const { ObservationalMemoryProcessor } = await import('./observational-memory-TASIB4PH.cjs');
     return new ObservationalMemoryProcessor(engine, this, {
       temporalMarkers: effectiveConfig.temporalMarkers
     });
@@ -19029,11 +19055,11 @@ Notes:
 
 Object.defineProperty(exports, "ModelByInputTokens", {
   enumerable: true,
-  get: function () { return chunkWNLFJKTX_cjs.ModelByInputTokens; }
+  get: function () { return chunkMJNTQ6GP_cjs.ModelByInputTokens; }
 });
 Object.defineProperty(exports, "getObservationsAsOf", {
   enumerable: true,
-  get: function () { return chunkWNLFJKTX_cjs.getObservationsAsOf; }
+  get: function () { return chunkMJNTQ6GP_cjs.getObservationsAsOf; }
 });
 Object.defineProperty(exports, "MessageHistory", {
   enumerable: true,