MongoDB vector store

The MongoDBVector class provides vector search using MongoDB Atlas Vector Search. It enables efficient similarity search and metadata filtering within your MongoDB collections.

Installation

npm

npm install @mastra/mongodb@latest

pnpm

pnpm add @mastra/mongodb@latest

Yarn

yarn add @mastra/mongodb@latest

Bun

bun add @mastra/mongodb@latest

Usage example

import { MongoDBVector } from '@mastra/mongodb'

const store = new MongoDBVector({
  id: 'mongodb-vector',
  uri: process.env.MONGODB_URI,
  dbName: process.env.MONGODB_DB_NAME,
})

Custom Embedding Field Path

If you need to store embeddings in a nested field structure (e.g., to integrate with existing MongoDB collections), use the embeddingFieldPath option:

import { MongoDBVector } from '@mastra/mongodb'

const store = new MongoDBVector({
  id: 'mongodb-vector',
  uri: process.env.MONGODB_URI,
  dbName: process.env.MONGODB_DB_NAME,
  embeddingFieldPath: 'text.contentEmbedding', // Store embeddings at text.contentEmbedding
})

Constructor options

id:

string

Unique identifier for this vector store instance

uri:

string

MongoDB connection string

dbName:

string

Name of the MongoDB database to use

options?:

MongoClientOptions

Optional MongoDB client options

embeddingFieldPath?:

string

= embedding

Path to the field that stores vector embeddings. Supports nested paths using dot notation (e.g., 'text.contentEmbedding').

Methods

connect()

Establishes connection to the MongoDB server. This is called automatically on first use, but can be called explicitly if needed.

await store.connect()

createIndex()

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)

metric?:

'cosine' | 'euclidean' | 'dotproduct'

= cosine

Distance metric for similarity search

filterFields?:

string[]

Metadata field names to declare as filter fields in the Atlas vectorSearch index (registered as metadata.<field>). Queries that filter only on declared fields are pushed directly into $vectorSearch instead of pre-filtering candidate _ids, avoiding the 16 MB BSON limit on large result sets. Filters that reference an undeclared field, or use an operator $vectorSearch does not support, fall back to the pre-filter automatically.

collectionName?:

string

Store the vectors on an existing (operational) collection instead of a managed collection named after the index. The collection is never created or dropped by this store when set. Defaults to indexName.

searchIndexName?:

string

Name for the Atlas vectorSearch index created on the collection. Defaults to ${indexName}_vector_index.

allowWrites?:

boolean

= false

Opt-in to write operations (upsert, updateVector, deleteVector, deleteVectors) on a bring-your-own collection. By default a BYO index is read-only: the store never modifies or deletes caller-owned operational documents. Ignored for managed collections, which are always writable. The policy is persisted with the index registration and survives restarts.

waitForIndexReady()

Waits for an index to become ready after creation. Useful when you need to ensure an index is ready before performing operations.

indexName:

string

Name of the index to wait for

timeoutMs?:

number

= 60000

Maximum time to wait in milliseconds

checkIntervalMs?:

number

= 2000

Interval between status checks in milliseconds

upsert()

Adds or updates vectors and their metadata in the collection. On a bring-your-own index, this requires allowWrites: true at createIndex() time because BYO collections are read-only by default.

indexName:

string

Name of the collection to insert into

vectors:

number[][]

Array of embedding vectors

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

query()

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

topK?:

number

= 10

Number of results to return

filter?:

Record<string, any>

Metadata filters (applies to the metadata field)

documentFilter?:

Record<string, any>

Filters on original document fields (not just metadata)

includeVector?:

boolean

= false

Whether to include vector data in results

numCandidates?:

number

= 20 * topK (capped at 10000)

Number of candidates the HNSW graph considers before selecting top-K results. Higher values improve recall at the cost of latency. See: https://www.mongodb.com/docs/atlas/atlas-vector-search/vector-search-stage/

metadataMode?:

'field' | 'document'

= field

'field' (default) projects the managed metadata/document fields, and filter fields are matched against the metadata subdocument. 'document' returns the full source document as metadata — use for bring-your-own operational collections whose documents have their own shape — and filter fields are matched against the **root** document (no metadata. prefix). The embedding field is omitted from metadata by default (to avoid payload bloat); set includeVector: true to retain it in metadata and also expose it as a top-level vector.

createSearchIndex()

Provisions an Atlas Search (BM25/full-text) index on the collection backing an index and records it as the text-search index that textQuery() and hybridQuery() will target.

Managed vs. bring-your-own collections:

• For a managed index (created without collectionName), createIndex() already provisions a dynamic full-text index named ${collectionName}_search_index (covering all string fields). createSearchIndex() is therefore only needed when you want a field-restricted mapping or a custom index name.
• For a bring-your-own index (created with collectionName), createIndex() doesn't auto-create any full-text index. Enabling textQuery()/hybridQuery() on a caller-owned operational collection is opt-in. Call createSearchIndex() explicitly to provision the (billable) text index. Until you do, textQuery()/hybridQuery() throw a clear error rather than querying a non-existent index.

Naming:

• When fields is provided without an explicit searchIndexName, the field-mapped index is created under a distinct default name (${collectionName}_${indexName}_search_fields_index, unique per logical index) so it doesn't collide with a managed collection's auto-created dynamic index and get silently ignored. This distinct index is persisted as the text-search index, so textQuery()/hybridQuery() use the restricted mapping automatically.
• When searchIndexName is provided, that exact name is used and persisted. textQuery()/hybridQuery() resolve the persisted name automatically. You can also override the name per call via their searchIndexName / textSearchIndexName parameters.

indexName:

string

Name of the Mastra index whose collection will have the search index

fields?:

string[]

Field names to index for full-text search. Omit for dynamic mapping (all string fields).

searchIndexName?:

string

= ${collectionName}_search_index (or ${collectionName}_${indexName}_search_fields_index when `fields` is given)

Name for the Atlas Search index. When fields is provided and this is omitted, a distinct default name that is unique per logical index is used, so the field mapping is not shadowed by the auto-created dynamic index and two logical indexes on the same collection do not collide.

waitUntilReady?:

boolean

= false

When true, block until the provisioned full-text index reports READY before resolving. Defaults to false to avoid surprising latency; call waitForSearchIndexReady() explicitly if you prefer to await separately.

await store.createSearchIndex({
  indexName: 'precedents',
  fields: ['note', 'description'],
})

The field-mapped index name includes the logical indexName, so two logical indexes on the same collection get distinct text indexes. Recreating the same logical index with different fields still requires dropping the existing index first (IndexAlreadyExists).

waitForSearchIndexReady()

Waits for the full-text (BM25) search index of an index to become READY. waitForIndexReady() polls only the vectorSearch index; createSearchIndex() returns while the Atlas Search full-text index is still building, so an immediate textQuery()/hybridQuery() can intermittently fail. Call this (or pass waitUntilReady: true to createSearchIndex()) to block until the resolved text index reports READY.

indexName:

string

Logical name of the index whose text index to wait for

searchIndexName?:

string

Override the resolved text-search index name

timeoutMs?:

number

= 60000

Maximum time to wait in milliseconds

checkIntervalMs?:

number

= 2000

Interval between status checks in milliseconds

await store.createSearchIndex({ indexName: 'precedents', fields: ['note'] })
await store.waitForSearchIndexReady({ indexName: 'precedents' })

textQuery()

Runs a full-text (BM25) search against an Atlas Search index. By default it targets the text-search index recorded for this index (set by createSearchIndex(), or the dynamic ${collectionName}_search_index auto-created by createIndex()). Pass searchIndexName to target a specific index for this call.

Metadata filters here (like hybridQuery()) are applied via a $match stage. For the vector branch of hybridQuery(), filters on fields not declared via filterFields at index creation are transparently materialised as candidate _ids (the same fallback query() uses), so undeclared-field filters don't error.

indexName:

string

Name of the Mastra index to search

query:

string

Full-text search query string

paths:

string[]

Field paths to search in (e.g., ["note", "description"])

topK?:

number

= 10

Number of results to return

filter?:

Record<string, any>

Metadata filters (applies to the metadata field)

metadataMode?:

'field' | 'document'

= field

'field' (default) projects the managed metadata/document fields. 'document' returns the full source document as metadata.

searchIndexName?:

string

Override the resolved full-text search index name for this call. Defaults to the index persisted by createSearchIndex() / createIndex().

const results = await store.textQuery({
  indexName: 'precedents',
  query: 'shell company offshore',
  paths: ['note'],
  topK: 10,
})

hybridQuery()

Runs a hybrid search that fuses vector similarity and full-text results using MongoDB's server-side $rankFusion. It requires MongoDB >= 8.0 and is generally available from 8.1. On 8.0.x, it may need a MongoDB support case to enable, and it runs where enabled, such as Atlas 8.0.x. A full-text search index must exist: it's auto-created for managed indexes, but for a bring-your-own collection you must call createSearchIndex() first (opt-in).

indexName:

string

Name of the Mastra index to search

queryVector:

number[]

Query vector for similarity search

query:

string

Full-text search query string

paths:

string[]

Field paths to search in for full-text (e.g., ["note", "description"])

topK?:

number

= 10

Number of results to return

filter?:

Record<string, any>

Metadata filters (applies to both vector and text branches)

weights?:

{ vector?: number; text?: number }

Relative weights for vector vs. text results in fusion (default: 1:1)

numCandidates?:

number

= 20 * topK (capped at 10000)

Number of candidates for the vector search branch

metadataMode?:

'field' | 'document'

= field

'field' (default) projects the managed metadata/document fields. 'document' returns the full source document as metadata.

textSearchIndexName?:

string

Override the resolved full-text search index name for this call. Defaults to the index persisted by createSearchIndex() / createIndex().

const results = await store.hybridQuery({
  indexName: 'precedents',
  queryVector: embedding,
  query: 'shell company offshore',
  paths: ['note'],
  topK: 10,
  weights: { vector: 1, text: 1.5 }, // Favor text matches
})

hybridQuery() requires MongoDB >= 8.0 for the $rankFusion stage. The stage is generally available from 8.1. On 8.0.x, it may need a MongoDB support case to enable and runs where enabled, such as Atlas 8.0.x. If you're running an older version, or $rankFusion isn't enabled on your 8.0.x deployment, use query() and textQuery() separately and merge the results client-side.

describeIndex()

Returns information about the index (collection).

indexName:

string

Name of the collection to describe

Returns:

interface IndexStats {
  dimension: number
  count: number
  metric: 'cosine' | 'euclidean' | 'dotproduct'
}

deleteIndex()

Deletes a vector index. Behavior depends on how the index was created:

• Managed index (created without collectionName): drops the entire collection and all its data.
• Bring-your-own index (created with collectionName): drops the Atlas vectorSearch index and, if one was provisioned via createSearchIndex(), the companion full-text search index. The caller's operational collection and its documents are preserved. This store never drops a collection it didn't create.

The BYO classification is recorded durably when the index is created, so it's applied correctly even by a different process (e.g. an index created by a setup job and later deleted by a long-lived service). Always pass the logical index name (the indexName used at createIndex), not the physical collection name.

indexName:

string

Logical name of the index to delete

listIndexes()

Lists the logical Mastra index names (the indexName values passed to createIndex), not physical collection names. For a bring-your-own index whose data lives in an operational collection, the logical index name is returned instead of the physical collection name. The value can be passed straight back into deleteIndex() / describeIndex(). Managed indexes created before durable metadata was introduced are still discovered via their ${name}_vector_index search index. The internal registry collection is never listed.

Returns: Promise<string[]>

updateVector()

Update a single vector by ID or by metadata filter. Either id or filter must be provided, but not both.

Bring-your-own collections are read-only by default. upsert(), updateVector(), deleteVector(), and deleteVectors() throw a USER-category error on a BYO index unless it was created with allowWrites: true. See Indexing an existing collection.

indexName:

string

Name of the collection containing the vector

id?:

string

ID of the vector entry to update (mutually exclusive with filter)

filter?:

Record<string, any>

Metadata filter to identify vector(s) to update (mutually exclusive with id)

update:

object

Update data containing vector and/or metadata

update.vector?:

number[]

New vector data to update

update.metadata?:

Record<string, any>

New metadata to update

deleteVector()

Deletes a specific vector entry from an index by its ID.

indexName:

string

Name of the collection containing the vector

id:

string

ID of the vector entry to delete

deleteVectors()

Delete multiple vectors by IDs or by metadata filter. Either ids or filter must be provided, but not both.

indexName:

string

Name of the collection containing the vectors to delete

ids?:

string[]

Array of vector IDs to delete (mutually exclusive with filter)

filter?:

Record<string, any>

Metadata filter to identify vectors to delete (mutually exclusive with ids)

disconnect()

Closes the MongoDB client connection. Should be called when done using the store.

Response types

Query results are returned in this format:

interface QueryResult {
  id: string
  score: number
  metadata: Record<string, any>
  vector?: number[] // Only included if includeVector is true
}

Error handling

The store throws typed errors that can be caught:

try {
  await store.query({
    indexName: 'my_collection',
    queryVector: queryVector,
  })
} catch (error) {
  // Handle specific error cases
  if (error.message.includes('Invalid collection name')) {
    console.error(
      'Collection name must start with a letter or underscore and contain only valid characters.',
    )
  } else if (error.message.includes('Collection not found')) {
    console.error('The specified collection does not exist')
  } else {
    console.error('Vector store error:', error.message)
  }
}

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.

import { MongoDBVector } from '@mastra/mongodb'

const store = new MongoDBVector({
  id: 'mongodb-vector',
  uri: process.env.MONGODB_URI,
  dbName: process.env.MONGODB_DB_NAME,
})

// Create a vector index on an existing 'transactions' collection
await store.createIndex({
  indexName: 'precedents',
  dimension: 1024,
  collectionName: 'transactions', // Use existing collection
  searchIndexName: 'txn_vec_idx', // Custom search index name
})

// Wait for the index to be ready
await store.waitForIndexReady({ indexName: 'precedents' })

// Query using document mode to get full source documents
const hits = await store.query({
  indexName: 'precedents',
  queryVector: embeddings,
  topK: 5,
  metadataMode: 'document', // Returns full document as metadata
})

// hits[0].metadata now contains all fields from the source document
console.log(hits[0].metadata.amount, hits[0].metadata.customField)

// Full-text / hybrid search on a BYO collection is opt-in: provision the text index first.
await store.createSearchIndex({ indexName: 'precedents', fields: ['note'] })

Important notes:

• The collection must already exist and contain documents with an embedding field (or the custom embeddingFieldPath you configured)
• The collection is never created or dropped when using collectionName
• A BYO index is read-only by default. upsert(), updateVector(), deleteVector(), and deleteVectors() throw a clear error rather than mutating caller-owned operational documents. To let the store write embeddings into (or delete documents from) your collection, opt in explicitly with createIndex({ ..., allowWrites: true }). The policy is persisted and survives restarts. Entries written by older versions without the flag are treated as read-only (fail closed).
• Use metadataMode: 'document' when querying to retrieve the full source document as metadata
• In 'document' mode the embedding is omitted from metadata by default; pass includeVector: true to retain it (and also expose it as a top-level vector)
• Filtering in 'document' mode operates on root document fields, not a nested metadata. subdocument. filter: { lane: 'fraud' } matches the top-level lane field of your operational documents (in the default 'field' mode, bare fields are rewritten to metadata.<field> for managed collections). Both the pushdown and $match fallback paths honor this.
• Native ObjectId _ids are supported. Operational collections commonly key on ObjectId; query results coerce _id to a string (the QueryResult.id contract), and deleteVector()/updateVector()/deleteVectors() accept that string and match the underlying ObjectId document. Managed collections (string _ids) are unaffected.
• Full-text and hybrid search on a BYO collection are opt-in: no full-text index is auto-created, so call createSearchIndex() before textQuery()/hybridQuery(). The full-text index builds asynchronously. Call waitForSearchIndexReady() (or pass waitUntilReady: true) before an immediate text/hybrid query.
• deleteIndex() on a BYO index drops the vector index (and the text index if one was created) but preserves the collection and its documents

Best practices

• Index metadata fields used in filters for optimal query performance.
• Use consistent field naming in metadata to avoid unexpected query results.
• Regularly monitor index and collection statistics to ensure efficient search.
• When indexing existing collections, ensure all documents have the required embedding field.

Usage example

Vector embeddings with MongoDB

Embeddings are numeric vectors used by memory's semanticRecall to retrieve related messages by meaning (not keywords).

note

MongoDB Atlas Vector Search is recommended for production use. For self-hosted deployments, Vector Search is available with local Atlas deployments via the Atlas CLI.

This setup uses FastEmbed, a local embedding model, to generate vector embeddings. To use this, install @mastra/fastembed:

npm

npm install @mastra/fastembed@latest

pnpm

pnpm add @mastra/fastembed@latest

Yarn

yarn add @mastra/fastembed@latest

Bun

bun add @mastra/fastembed@latest

Add the following to your agent:

src/mastra/agents/example-mongodb-agent.ts

import { Memory } from '@mastra/memory'
import { Agent } from '@mastra/core/agent'
import { MongoDBStore, MongoDBVector } from '@mastra/mongodb'
import { fastembed } from '@mastra/fastembed'

export const mongodbAgent = new Agent({
  id: 'mongodb-agent',
  name: 'mongodb-agent',
  instructions:
    'You are an AI agent with the ability to automatically recall memories from previous interactions.',
  model: 'openai/gpt-5.6-sol',
  memory: new Memory({
    storage: new MongoDBStore({
      id: 'mongodb-storage',
      uri: process.env.MONGODB_URI!,
      dbName: process.env.MONGODB_DB_NAME!,
    }),
    vector: new MongoDBVector({
      id: 'mongodb-vector',
      uri: process.env.MONGODB_URI!,
      dbName: process.env.MONGODB_DB_NAME!,
    }),
    embedder: fastembed,
    options: {
      lastMessages: 10,
      semanticRecall: {
        topK: 3,
        messageRange: 2,
      },
      generateTitle: true, // generates descriptive thread titles automatically
    },
  }),
})

Vector embeddings with VoyageAI

VoyageAI provides specialized embedding models optimized for retrieval tasks. VoyageAI is also integrated with MongoDB Atlas for multimodal embeddings.

npm

npm install @mastra/voyageai@latest

pnpm

pnpm add @mastra/voyageai@latest

Yarn

yarn add @mastra/voyageai@latest

Bun

bun add @mastra/voyageai@latest

Basic usage example:

src/mastra/agents/example-mongodb-voyageai-agent.ts

import { Memory } from '@mastra/memory'
import { Agent } from '@mastra/core/agent'
import { MongoDBStore, MongoDBVector } from '@mastra/mongodb'
import { voyage } from '@mastra/voyageai'

export const mongodbVoyageAgent = new Agent({
  id: 'mongodb-voyage-agent',
  name: 'MongoDB VoyageAI Agent',
  instructions: 'You are an AI agent with semantic recall powered by VoyageAI and MongoDB.',
  model: 'openai/gpt-5.6-sol',
  memory: new Memory({
    storage: new MongoDBStore({
      id: 'mongodb-storage',
      uri: process.env.MONGODB_URI!,
      dbName: process.env.MONGODB_DB_NAME!,
    }),
    vector: new MongoDBVector({
      id: 'mongodb-vector',
      uri: process.env.MONGODB_URI!,
      dbName: process.env.MONGODB_DB_NAME!,
    }),
    embedder: voyage, // VoyageAI's default model (voyage-3.5, 1024 dimensions)
    options: {
      lastMessages: 10,
      semanticRecall: {
        topK: 5,
        messageRange: 2,
      },
    },
  }),
})

For detailed VoyageAI embedding examples including specialized models, multimodal embeddings, and retrieval optimization, see the VoyageAI embeddings documentation.

Related

• Metadata Filters
• VoyageAI Embeddings Documentation