@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

Peer dependencies (install separately):

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

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.

What the hooks do:

| Hook | Method | When it runs | What it does |

| Pre | mongodbMemory.loadSession({ userId, sessionId }) | Inside prepareCall, before every LLM call | Reads prior turns from Mongo, returns ModelMessage[] you prepend to messages. | | Post | mongodbMemory.onFinish() | After the full tool loop finishes | Persists the user prompt + every assistant & tool message across all steps. |

loadSession() restores user/assistant turns only. Tool turns remain stored in Mongo as transcript/audit records, but they are not replayed as provider tool-result blocks because OpenAI Responses and Anthropic Messages reject orphan tool results without the matching prior assistant tool call.

Why experimental_context? ToolLoopAgent only accepts onFinish at construction time, but you still need per-call scope (userId, sessionId, prompt). The hook reads those from event.experimental_context, which you set inside prepareCall. You can also call mongodbMemory.onFinish({ userId, sessionId, prompt }) with a baked-in closure when using one-shot generateText / streamText.

See examples/deterministic-agent.ts for the full runnable example.

Note: The other memory tiers (semantic, procedural, episodic, scratchpad) are intentionally left under LLM control — they should be selective and content-dependent, not every-turn.

Vercel Eve

MongoDB is also available as a first-class Vercel Eve memory provider via the additive /eve subpath — layered on top of the exact same store, embeddings, vector search, retention, and forgetting logic used by the AI SDK integration.

eve is an optional peer dependency. If you only use the AI SDK integration (the root import), you don't need to install eve, and it is never bundled into the root entrypoint.

That's the whole integration. Eve owns the agent runtime and lifecycle; MongoDB provides persistent, personalized, cross-session memory. You don't write remember.ts, recall.ts, semantic_search.ts, episodic_search.ts, or forget.ts — the provider handles all of it.

How it maps to the Eve provider contract

| Eve surface | What MongoDB does |

| recall["turn.started"] | Parallel semantic / episodic / procedural vector search, returned as recalled messages before the model responds — automatically. | | capture["turn.completed"] | (When capture: "automatic") extracts & classifies durable memories and stores them. | | tools | Exposes remember and forget (Eve qualifies them as profileremember, profileforget). |

Trusted scope (security)

The MongoDB owner/user id is never supplied by the model. The adapter uses Eve's trusted ctx.memory.scope.key as the partition key for every read and write:

Two principals therefore can never retrieve each other's memories.…