@mongodb-developer/vercel-ai-memory weekly downloads statistics

@mongodb-developer/vercel-ai-memory

MongoDB-backed persistent memory for the Vercel AI SDK and a first-class memory provider for Vercel Eve. Gives your agent five structured memory tiers — Session, Semantic, Procedural, Episodic, and Scratchpad — all stored in MongoDB Atlas with automatic vector search indexes and per-type retention policies. Bring your own embedding model, or let Atlas Automated Embedding (Voyage AI) generate vectors server-side with zero client embedding pipeline.

Features

• 🧠 5 memory types — session history, entity knowledge, how-to procedures, event episodes, and a temporary scratchpad
• 🤖 Vercel Eve provider — drop-in mongodbMemory() for Eve's memory slots via the /eve subpath: automatic recall before every turn, automatic or agent-driven capture, and remember / forget tools — all partitioned by Eve's trusted scope key
• ⚡ Atlas Automated Embedding — opt in with autoEmbed: { model: 'voyage-4' } and Atlas embeds your memories server-side (Voyage AI); no embedding API key or client pipeline required
• 🔍 Atlas Vector Search — semantic retrieval powered by any Vercel AI SDK embedding model
• 📏 Auto-detected dimensions — no need to configure vector dimensions; the package probes them at startup
• ⏱️ Flexible retention — per-type policies: none, ttl, ttl+importance, or fully dynamic (forgetting curve)
• 🗑️ Agent-driven memory_forget — let the model mark individual memories for immediate deletion
• 🧩 Multi-tenant ready — custom collection/index names, extra filter fields (e.g. tenant_id), or disable types entirely
• 🔄 Temporal versioning — semantic and procedural memories are versioned; history is preserved
• 🏗️ Zero lock-in — works with any AI SDK model and any embedding provider (VoyageAI, OpenAI, Cohere, Google, etc.)
• 🔌 Lazy connection — MongoDB connects on first tool use; call .connect() early if you prefer

Installation

npm install @mongodb-developer/vercel-ai-memory
# or
pnpm add @mongodb-developer/vercel-ai-memory

Peer dependencies (install separately):

npm install ai mongodb zod

This package supports AI SDK v6 and v7 (ai@^6.0.0 || ^7.0.0). The examples use APIs such as ToolLoopAgent and isLoopFinished() that are available in both major versions.

Quick Start

import { createMongoDBMemory } from '@mongodb-developer/vercel-ai-memory'
import { openai } from '@ai-sdk/openai'
import { ToolLoopAgent } from 'ai'

// ── 1. Create the memory instance (once, at module/server level) ──────────────
const mongodbMemory = createMongoDBMemory({
  uri: process.env.MONGODB_URI!,
  embedder: openai.embedding('text-embedding-3-small'),
})

// ── 2. Use per-request, scoped to a user and session ─────────────────────────
const agent = new ToolLoopAgent({
  model: openai('gpt-4.1'),
  tools: mongodbMemory({ userId: 'alice', sessionId: 'sess-001' }),
})

const result = await agent.generate({
  prompt: 'My name is Alice and I love hiking. Remember that.',
})

mongodbMemory({ userId, sessionId }) returns the tools record directly — no spreading needed.

Session memory: two modes

The package exposes session (short-term conversation) memory in two modes, both backed by the same Mongo collection. Pick based on how much determinism you need — they can't be combined for the same session.

Mode A — Tool-driven (LLM-controlled)

Shown in the Quick Start above. The LLM sees memory with session_append / session_recent commands and decides when to call them. This is the simplest setup but not deterministic: the model sometimes skips writes (only user or only assistant turns get persisted) or skips reads (agent forgets earlier turns).

Use this for demos, prototypes, or agents where the LLM genuinely curates what belongs in the transcript.

Mode B — Hook-driven (runtime-controlled) ✅ recommended for production

Hide the session tool commands from the LLM and let the runtime read/write the transcript on every turn via Vercel AI SDK hooks. Every user, assistant, and tool turn is captured exactly once per generation, regardless of what the LLM decides.

import { createMongoDBMemory } from '@mongodb-developer/vercel-ai-memory'
import { openai } from '@ai-sdk/openai'
import { ToolLoopAgent, isLoopFinished } from 'ai'
import { z } from 'zod'

const mongodbMemory = createMongoDBMemory({
  uri: process.env.MONGODB_URI!,
  embedder: openai.embedding('text-embedding-3-small'),
  // Hide session_append / session_recent from the LLM tool surface, but keep
  // the session collection + store methods live for the runtime hooks below.
  // (Use `disable: ['session']` instead if you want the collection entirely off.)
  topology: { hideToolCommands: ['session'] },
})

const agent = new ToolLoopAgent({
  model: openai('gpt-4o-mini'),

  callOptionsSchema: z.object({
    userId: z.string(),
    sessionId: z.string(),
    prompt: z.string(),
  }),

  // ── PRE hook: read history + scope onFinish ─────────────────────────────────
  // Strip `prompt` / `messages` from the incoming settings — the AI SDK enforces
  // `prompt` XOR `messages`, and we're replacing them with our restored history.
  prepareCall: async ({ options, prompt: _p, messages: _m, ...settings }) => {
    const { userId, sessionId, prompt } = options!
    const history = await mongodbMemory.loadSession({ userId, sessionId })

    return {
      ...settings,
      tools: mongodbMemory({ userId, sessionId }),
      messages: [...history, { role: 'user', content: prompt }],
      // per-call state flows to onFinish via experimental_context
      experimental_context: { userId, sessionId, prompt },
    }
  },

  // ── POST hook: write every turn exactly once ────────────────────────────────
  onFinish: mongodbMemory.onFinish(),

  stopWhen: isLoopFinished(),
})…