Get Started with the MongoDB Vercel AI SDK Integration

Install dependencies.

Run the following commands in your terminal to create a new directory named vercel-ai-mongodb-project and install the required dependencies:

mkdir vercel-ai-mongodb-projectcd vercel-ai-mongodb-projectnpm init -ynpm install @mongodb-developer/vercel-ai-memory ai mongodb zod @ai-sdk/openai voyage-ai-provider dotenvnpm install --save-dev tsx @types/node

Set your environment variables.

In your vercel-ai-mongodb-project directory, create a .env file and add the following code:

OPENAI_API_KEY="<openai-api-key>"VOYAGE_API_KEY="<voyage-api-key>"MONGODB_URI="<connection-string>"

Replace <connection-string> with the connection string for your Atlas cluster or local Atlas deployment.

mongodb+srv://<db_username>:<db_password>@<clusterName>.<hostname>.mongodb.net

mongodb://localhost:<port-number>/?directConnection=true

Create a project file.

In your vercel-ai-mongodb-project directory, create a file named main.ts. Add the following code to this file to load your environment variables and import the required modules:

import 'dotenv/config'import { createMongoDBMemory } from '@mongodb-developer/vercel-ai-memory'import { createVoyage } from 'voyage-ai-provider'import { openai } from '@ai-sdk/openai'import { ToolLoopAgent } from 'ai'

In future steps, you add code to this file to create the memory provider and build your agent.

Create the memory provider.

Add the following code to your main.ts file to create a Voyage AI client and a memory provider that uses a Voyage AI embedding model:

const voyage = createVoyage({  apiKey: process.env.VOYAGE_API_KEY,  baseURL: 'https://ai.mongodb.com/v1',})
const mongodbMemory = createMongoDBMemory({  uri: process.env.MONGODB_URI!,  embedder: voyage.embeddingModel('voyage-4'),})

The provider connects to MongoDB on first use and creates the agent_memory database. Then, it adds one collection for each memory tier to the database. The provider also creates the MongoDB Vector Search indexes that semantic recall requires. To learn more about the collections and indexes that the provider creates, see Collections and Indexes in the Vercel AI SDK reference.

Create the agent.

Add the following code to your main.ts file to create an agent whose memory tools are scoped to one user and session:

const agent = new ToolLoopAgent({  model: openai('gpt-4.1'),  tools: mongodbMemory({ userId: 'alice', sessionId: 'sess-001' }),  instructions: `You are an assistant with persistent memory.    At the start of every conversation, call session_recent to    restore context and semantic_search to recall facts about    the user. Save each conversation turn with session_append.    Save important facts about the user with semantic_save.`,})

The instructions tell the model which memory commands to call. The userId and sessionId values scope the memories that the agent stores and retrieves.

Add the code that runs the agent.

Add the following code to your main.ts file to pass a prompt to the agent from the command line, print the response, and close the MongoDB connection:

async function main() {  const prompt = process.argv[2]
  if (!prompt) {    console.error('Usage: npx tsx main.ts "<your message>"')    process.exit(1)  }
  const result = await agent.generate({ prompt })  console.log('[agent]:', result.text)
  await mongodbMemory.close()}
main().catch((error) => {  console.error(error)  process.exit(1)})

Run the agent and provide personal information.

From your vercel-ai-mongodb-project directory, run the following command:

npx tsx main.ts "I'm a marine biologist who studies emperor penguins in Antarctica. Remember that."

If the command runs successfully, the output resembles the following:

[agent]: I've noted that you are a marine biologist studying emperorpenguins in Antarctica.

Prompt the agent to recall information.

Run the agent again and pass the following prompt that asks the agent to recall previous information:

npx tsx main.ts "What do I study, and where?"

The output resembles the following:

[agent]: You are a marine biologist who studies emperor penguins inAntarctica.

The agent uses memory to answer the prompt. Both runs pass the same userId and sessionId values, so the model calls the session_recent and semantic_search commands at the start of the second run. These commands restore the conversation and the memories that the first run stored in MongoDB.