Skip to main content

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
Direct link to Installation

npm install @mastra/mongodb@latest

Usage example
Direct link to 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
Direct link to 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
Direct link to 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
Direct link to Methods

connect()
Direct link to 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()
Direct link to 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.

waitForIndexReady()
Direct link to 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()
Direct link to upsert

Adds or updates vectors and their metadata in the collection.

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()
Direct link to 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/

describeIndex()
Direct link to 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()
Direct link to deleteindex

Deletes a collection and all its data.

indexName:

string
Name of the collection to delete

listIndexes()
Direct link to listindexes

Lists all vector collections in the MongoDB database.

Returns: Promise<string[]>

updateVector()
Direct link to updatevector

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

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()
Direct link to 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()
Direct link to 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()
Direct link to disconnect

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

Response types
Direct link to 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
Direct link to 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)
  }
}

Best practices
Direct link to 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.

Usage example
Direct link to Usage example

Vector embeddings with MongoDB
Direct link to 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 install @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.5',
  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
Direct link to Vector embeddings with VoyageAI

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

npm install @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.5',
  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 comprehensive VoyageAI embedding examples including specialized models, multimodal embeddings, and retrieval optimization, see the VoyageAI embeddings documentation.

On this page