@mastra/memory 1.32.0 → 1.32.1

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.32.0"
+  version: "1.32.1"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.32.0",
+  "version": "1.32.1",
   "package": "@mastra/memory",
   "exports": {},
   "modules": {

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

@@ -186,6 +186,7 @@ const memory = new Memory({
 - Schema-less extractors are inline string extractors emitted directly in the Observer or Reflector output.
 - Dynamic extractor functions receive runtime context, including `source`, `threadId`, `resourceId`, `mainAgent`, `memory`, and `requestContext` when available.
 - `WorkingMemoryExtractor` uses the normal extractor pipeline to update working memory through the active `Memory` instance. It uses structured extraction when working memory has a JSON schema and skips OM metadata persistence, so the working memory payload isn't duplicated under OM extracted metadata.
+- When `workingMemory.schema` is set, `WorkingMemoryExtractor` validates each update against that schema before saving it. If an update doesn't match, it's skipped and reported as an extraction failure while the previous working memory stays in place. Because the schema isn't sent to the model as a structured output constraint, one invalid working memory update can't fail other extractors. A `null` in an optional field is treated as not provided.
 - `observationalMemory.observation.manageWorkingMemory` adds `WorkingMemoryExtractor` and defaults `workingMemory.agentManaged` to `false`. It defaults `workingMemory.useStateSignals` to `true` when working memory is enabled.
 - Extraction failures are reported in OM marker data and don't discard other successful extracted values.
 

package/dist/docs/references/reference-vectors-mongodb.md

@@ -87,7 +87,9 @@ Creates a new vector index (collection) in MongoDB.
 
 **indexName** (`string`): Name of the collection to create
 
-**dimension** (`number`): Vector dimension (must match your embedding model)
+**dimension** (`number`): Vector dimension (must match your embedding model). Required unless autoEmbed is set, where the embedding model determines the dimension. Passing both is an error.
+
+**autoEmbed** (`MongoDBAutoEmbedConfig`): Generate the embeddings in MongoDB instead of supplying vectors. See Automated Embedding for the supported fields.
 
 **metric** (`'cosine' | 'euclidean' | 'dotproduct'`): Distance metric for similarity search (Default: `cosine`)
 
@@ -115,13 +117,13 @@ Adds or updates vectors and their metadata in the collection. On a bring-your-ow
 
 **indexName** (`string`): Name of the collection to insert into
 
-**vectors** (`number[][]`): Array of embedding vectors
+**vectors** (`number[][]`): Array of embedding vectors. Required unless the index was created with autoEmbed, where MongoDB generates them from documents and supplying vectors is an error.
 
 **metadata** (`Record<string, any>[]`): Metadata for each vector
 
 **ids** (`string[]`): Optional vector IDs (auto-generated if not provided)
 
-**documents** (`string[]`): Optional document text content to store alongside vectors
+**documents** (`string[]`): Document text content to store alongside vectors. On an autoEmbed index this is the text MongoDB embeds, and it is required.
 
 ### `query()`
 
@@ -129,7 +131,11 @@ Searches for similar vectors with optional metadata filtering.
 
 **indexName** (`string`): Name of the collection to search in
 
-**queryVector** (`number[]`): Query vector to find similar vectors for
+**queryVector** (`number[]`): Query vector to find similar vectors for. Supply this or queryText, not both.
+
+**queryText** (`string`): Text for MongoDB to embed at query time. autoEmbed indexes only, and mutually exclusive with queryVector. For full-text matching use textQuery() instead.
+
+**model** (`string`): Embedding model for this query, overriding the index's. Requires queryText, and must be compatible with the index's model.
 
 **topK** (`number`): Number of results to return (Default: `10`)
 
@@ -226,7 +232,11 @@ Runs a hybrid search that fuses vector similarity with full-text results through
 
 **indexName** (`string`): Name of the Mastra index to search
 
-**queryVector** (`number[]`): Query vector for similarity search
+**queryVector** (`number[]`): Query vector for the vector branch. Supply this or queryText, not both.
+
+**queryText** (`string`): Text for MongoDB to embed for the vector branch. autoEmbed indexes only. Independent of query, so each branch can search for something different.
+
+**model** (`string`): Embedding model for the vector branch, overriding the index's. Requires queryText.
 
 **query** (`string`): Full-text search query string
 
@@ -273,6 +283,8 @@ interface IndexStats {
 }
 ```
 
+On an `autoEmbed` index, `dimension` is read from the index definition and reports MongoDB's default of `1024` when the index doesn't pin one. `count` counts documents that carry the embedded text field, since the generated vectors aren't stored on your documents.
+
 ### `deleteIndex()`
 
 Deletes a vector index. Behavior depends on how the index was created:
@@ -367,6 +379,79 @@ try {
 }
 ```
 
+## Automated Embedding
+
+MongoDB can generate the embeddings for you. Create the index with `autoEmbed` and a Voyage AI model, write plain text through `documents`, and search with `queryText`. No embedding provider runs in your application, and no vectors travel through it.
+
+```typescript
+import { MongoDBVector } from '@mastra/mongodb'
+
+const store = new MongoDBVector({
+  id: 'mongodb-vector',
+  uri: process.env.MONGODB_URI,
+  dbName: process.env.MONGODB_DB_NAME,
+})
+
+// No `dimension`: the embedding model determines it.
+await store.createIndex({
+  indexName: 'movies',
+  autoEmbed: { model: 'voyage-4' },
+  filterFields: ['year'],
+})
+
+// Automated Embedding indexes build slower than client-embedded ones.
+await store.waitForIndexReady({ indexName: 'movies', timeoutMs: 300000 })
+
+// No `vectors`: MongoDB embeds the text as documents are written.
+await store.upsert({
+  indexName: 'movies',
+  documents: [
+    'A lonely astronaut adrift near a strange ocean planet.',
+    'A heist crew robs a bank vault in Paris.',
+  ],
+  metadata: [{ year: 1972 }, { year: 2001 }],
+})
+
+// No `queryVector`: MongoDB embeds the query string with the same model.
+const results = await store.query({
+  indexName: 'movies',
+  queryText: 'space opera about isolation',
+  topK: 5,
+  filter: { year: { $gt: 1970 } },
+})
+```
+
+### `autoEmbed` options
+
+**model** (`string`): Voyage AI model to embed with, for example voyage-4. MongoDB rejects a name it does not support and lists the ones it does.
+
+**path** (`string`): Text field to embed. Defaults to the managed document field that upsert({ documents }) writes. Point it at a field of your own to index an existing collection in place. (Default: `document`)
+
+**similarity** (`'cosine' | 'dotProduct' | 'euclidean'`): Vector similarity function. Defaults to MongoDB's own default when omitted.
+
+**numDimensions** (`256 | 512 | 1024 | 2048`): Length of the generated embeddings. (Default: `1024`)
+
+**quantization** (`'float' | 'scalar' | 'binary' | 'binaryNoRescore'`): Storage format for the generated vectors. (Default: `scalar`)
+
+**indexingMethod** (`'hnsw' | 'flat'`): Index structure for the vector field. (Default: `hnsw`)
+
+**hnswOptions** (`{ maxEdges?: number; numEdgeCandidates?: number }`): Tuning for the HNSW graph. MongoDB's defaults suit most workloads.
+
+Any other field the `autoEmbed` index definition accepts is forwarded to MongoDB as given, so options added after this release work without a package update. Anything omitted keeps MongoDB's default.
+
+**Important notes:**
+
+- Automated Embedding is a **MongoDB Preview feature**. It requires an Atlas cluster with Automated Embedding available, or the `mongodb/mongodb-atlas-local:preview` image for local development. Self-managed deployments need `mongot` configured with a Voyage AI API key.
+- The Voyage AI API key must be provisioned through the Atlas UI. A key issued directly by Voyage AI is rejected by the default embedding endpoint.
+- **MongoDB stores the generated vectors outside your collection**, so documents carry text only. `includeVector: true` isn't supported on an `autoEmbed` index and throws.
+- Embeddings are generated asynchronously. A query can legitimately return no results for a short time after a write, even once the index reports ready.
+- An index declares either a vector field or an `autoEmbed` field, never both. Omit `autoEmbed` to keep supplying your own vectors. The client-side path is unchanged.
+- Passing `vectors` to an `autoEmbed` index is an error, since they would be written to a field no index reads.
+- When `document` is the embedded field it's no longer a declared filter field, so `documentFilter` uses the `$match` pre-filter automatically. Metadata filters declared through `filterFields` still push into `$vectorSearch`.
+- `updateVector()` rejects a vector update on an `autoEmbed` index. Upsert the document with new text instead, and MongoDB re-embeds it.
+- `queryVector` still works against an `autoEmbed` index, but the vector must come from a compatible model and match the index `quantization`. MongoDB rejects a mismatch.
+- Embedding generation is billed per token, for both documents and queries.
+
 ## Indexing an existing collection
 
 You can create a vector index on an existing operational collection instead of using a managed collection. This is useful when you want to add vector search capabilities to documents that already exist in your MongoDB database.

package/dist/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_src = require("./src-C7u5SaET.cjs");
+const require_src = require("./src-DS-duN3y.cjs");
 let _mastra_core_processors = require("@mastra/core/processors");
 exports.Extractor = require_src.Extractor;
 exports.KnowledgeSemanticIndexCoordinator = require_src.KnowledgeSemanticIndexCoordinator;

package/dist/index.js

@@ -1,2 +1,2 @@
-import { C as SUMMARIZE_THREAD_DEFAULTS, G as StaleKnowledgeSemanticIndexError, Q as Extractor, S as WorkingMemoryExtractor, U as Subconscious, W as KnowledgeSemanticIndexCoordinator, a as extractWorkingMemoryContent, b as WorkingMemoryStateProcessor, c as getObservationsAsOf, i as WorkingMemory, n as MessageHistory, o as extractWorkingMemoryTags, q as ModelByInputTokens, r as SemanticRecall, s as removeWorkingMemoryTags, t as Memory, v as WORKING_MEMORY_STATE_ID, w as summarizeConversation, x as deepMergeWorkingMemory, y as WORKING_MEMORY_STATE_PROCESSOR_ID } from "./src-B0ISVOJX.js";
+import { C as SUMMARIZE_THREAD_DEFAULTS, G as StaleKnowledgeSemanticIndexError, Q as Extractor, S as deepMergeWorkingMemory, U as Subconscious, W as KnowledgeSemanticIndexCoordinator, a as extractWorkingMemoryContent, b as WorkingMemoryStateProcessor, c as getObservationsAsOf, i as WorkingMemory, n as MessageHistory, o as extractWorkingMemoryTags, q as ModelByInputTokens, r as SemanticRecall, s as removeWorkingMemoryTags, t as Memory, v as WORKING_MEMORY_STATE_ID, w as summarizeConversation, x as WorkingMemoryExtractor, y as WORKING_MEMORY_STATE_PROCESSOR_ID } from "./src-DsewkOlu.js";
 export { Extractor, KnowledgeSemanticIndexCoordinator, Memory, MessageHistory, ModelByInputTokens, SUMMARIZE_THREAD_DEFAULTS, SemanticRecall, StaleKnowledgeSemanticIndexError, Subconscious, WORKING_MEMORY_STATE_ID, WORKING_MEMORY_STATE_PROCESSOR_ID, WorkingMemory, WorkingMemoryExtractor, WorkingMemoryStateProcessor, deepMergeWorkingMemory, extractWorkingMemoryContent, extractWorkingMemoryTags, getObservationsAsOf, removeWorkingMemoryTags, summarizeConversation };

package/dist/processors/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_src = require("../src-C7u5SaET.cjs");
+const require_src = require("../src-DS-duN3y.cjs");
 exports.Extractor = require_src.Extractor;
 exports.KnowledgeSemanticIndexCoordinator = require_src.KnowledgeSemanticIndexCoordinator;
 exports.ModelByInputTokens = require_src.ModelByInputTokens;

package/dist/processors/index.js

@@ -1,2 +1,2 @@
-import { A as formatMessagesForObserver, B as OBSERVATION_CONTEXT_PROMPT_THREAD, D as buildObserverPrompt, E as OBSERVER_SYSTEM_PROMPT, F as parseAnchorId, G as StaleKnowledgeSemanticIndexError, H as getObservationContextPrompt, I as stripEphemeralAnchorIds, J as SUBCONSCIOUS_ACTIVITY_STATE_ID, K as SubconsciousRemindExtractor, L as OBSERVATIONAL_MEMORY_DEFAULTS, M as optimizeObservationsForContext, N as parseObserverOutput, O as buildObserverSystemPrompt, P as injectAnchorIds, Q as Extractor, R as OBSERVATION_CONTEXT_INSTRUCTIONS, S as WorkingMemoryExtractor, T as TokenCounter, U as Subconscious, V as OBSERVATION_CONTINUATION_HINT, W as KnowledgeSemanticIndexCoordinator, X as publishSubconsciousActivity, Y as buildSubconsciousActivitySnapshot, Z as renderSubconsciousActivity, _ as wrapInObservationGroup, c as getObservationsAsOf, d as combineObservationGroupRanges, f as deriveObservationGroupProvenance, g as stripObservationGroups, h as renderObservationGroupsForReflection, j as hasCurrentTaskSection, k as extractCurrentTask, l as ObservationalMemoryProcessor, m as reconcileObservationGroupsFromReflection, p as parseObservationGroups, q as ModelByInputTokens, u as ObservationalMemory, w as summarizeConversation, z as OBSERVATION_CONTEXT_PROMPT } from "../src-B0ISVOJX.js";
+import { A as formatMessagesForObserver, B as OBSERVATION_CONTEXT_PROMPT_THREAD, D as buildObserverPrompt, E as OBSERVER_SYSTEM_PROMPT, F as parseAnchorId, G as StaleKnowledgeSemanticIndexError, H as getObservationContextPrompt, I as stripEphemeralAnchorIds, J as SUBCONSCIOUS_ACTIVITY_STATE_ID, K as SubconsciousRemindExtractor, L as OBSERVATIONAL_MEMORY_DEFAULTS, M as optimizeObservationsForContext, N as parseObserverOutput, O as buildObserverSystemPrompt, P as injectAnchorIds, Q as Extractor, R as OBSERVATION_CONTEXT_INSTRUCTIONS, T as TokenCounter, U as Subconscious, V as OBSERVATION_CONTINUATION_HINT, W as KnowledgeSemanticIndexCoordinator, X as publishSubconsciousActivity, Y as buildSubconsciousActivitySnapshot, Z as renderSubconsciousActivity, _ as wrapInObservationGroup, c as getObservationsAsOf, d as combineObservationGroupRanges, f as deriveObservationGroupProvenance, g as stripObservationGroups, h as renderObservationGroupsForReflection, j as hasCurrentTaskSection, k as extractCurrentTask, l as ObservationalMemoryProcessor, m as reconcileObservationGroupsFromReflection, p as parseObservationGroups, q as ModelByInputTokens, u as ObservationalMemory, w as summarizeConversation, x as WorkingMemoryExtractor, z as OBSERVATION_CONTEXT_PROMPT } from "../src-DsewkOlu.js";
 export { Extractor, KnowledgeSemanticIndexCoordinator, ModelByInputTokens, OBSERVATIONAL_MEMORY_DEFAULTS, OBSERVATION_CONTEXT_INSTRUCTIONS, OBSERVATION_CONTEXT_PROMPT, OBSERVATION_CONTEXT_PROMPT_THREAD, OBSERVATION_CONTINUATION_HINT, OBSERVER_SYSTEM_PROMPT, ObservationalMemory, ObservationalMemoryProcessor, SUBCONSCIOUS_ACTIVITY_STATE_ID, StaleKnowledgeSemanticIndexError, Subconscious, SubconsciousRemindExtractor, TokenCounter, WorkingMemoryExtractor, buildObserverPrompt, buildObserverSystemPrompt, buildSubconsciousActivitySnapshot, combineObservationGroupRanges, deriveObservationGroupProvenance, extractCurrentTask, formatMessagesForObserver, getObservationContextPrompt, getObservationsAsOf, hasCurrentTaskSection, injectAnchorIds, optimizeObservationsForContext, parseAnchorId, parseObservationGroups, parseObserverOutput, publishSubconsciousActivity, reconcileObservationGroupsFromReflection, renderObservationGroupsForReflection, renderSubconsciousActivity, stripEphemeralAnchorIds, stripObservationGroups, summarizeConversation, wrapInObservationGroup };

package/dist/processors/observational-memory/working-memory-extractor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"working-memory-extractor.d.ts","sourceRoot":"","sources":["../../../src/processors/observational-memory/working-memory-extractor.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAyDxC,qBAAa,sBAAuB,SAAQ,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;;CAqC7F"}
+{"version":3,"file":"working-memory-extractor.d.ts","sourceRoot":"","sources":["../../../src/processors/observational-memory/working-memory-extractor.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAgFxC,qBAAa,sBAAuB,SAAQ,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;;CAyC7F"}