Add Long-Term Memory to LangGraph.js Agents with MongoDB Atlas

Overview of MongoDB Memory Mechanisms in LangGraph

LangGraph provides two complementary memory mechanisms:

Prerequisites

Before you begin, ensure that you have the following:

• One of the following MongoDB cluster types:

  • An Atlas cluster running MongoDB version 6.0.11, 7.0.2, or later. Ensure that your IP address is included in your Atlas project's access list.

  • A local Atlas deployment created using the Atlas CLI. To learn more, see Create a Local Atlas Deployment.

  • A MongoDB Community or Enterprise cluster with Search and Vector Search installed.

• npm and Node.js installed.

• A Voyage AI API key. To create an API key, see Model API Keys.

• An OpenAI API Key. You must have an OpenAI account with credits available for API requests. To learn more about registering an OpenAI account, see the OpenAI API website.

• A MongoDB database and collection configured for MongoDB Vector Search if you plan to use semantic search. To learn more, see Create an Atlas Vector Search Index.

You should be familiar with and ideally have completed:

• Integrate MongoDB with LangGraph.js (overview, checkpointer, and retrieval tools).

• Build an AI Agent with LangGraph.js and MongoDB Atlas (end-to-end agent, vector search, and short-term memory).

Install Dependencies

Install the core dependencies used in the Build an AI Agent tutorial, plus the MongoDB Store module for LangGraph.js.

npm init -y
# Core LangChain / LangGraph / MongoDB dependencies
npm i --legacy-peer-deps \
  langchain \
  @langchain/langgraph \
  @langchain/mongodb \
  @langchain/community \
  @langchain/langgraph-checkpoint-mongodb \
  dotenv \
  express \
  mongodb \
  zod

The @langchain/langgraph-checkpoint-mongodb package includes both the checkpointer and the MongoDB Store for long-term memory.

Configure the MongoDB Store

LangGraph Stores implement the BaseStore interface with operations such as get, put, delete, and search for JSON documents under hierarchical namespaces.

// mongodb-client.ts
import { MongoClient } from "mongodb";
import "dotenv/config";
export const client = new MongoClient(process.env.MONGODB_URI as string);
export async function connectClient() {
  await client.connect();
  await client.db("admin").command({ ping: 1 });
  console.log("Pinged your deployment. You successfully connected to MongoDB!");
}

// long-term-store.ts
import type { MongoClient } from "mongodb";
import { MongoDBStore } from "@langchain/langgraph-checkpoint-mongodb";
const DB_NAME = "hr_database";
const COLLECTION_NAME = "long_term_memory";
export function createMongoDBStore(client: MongoClient) {
  const store = new MongoDBStore({
    client,
    dbName: DB_NAME,
    collectionName: COLLECTION_NAME,
  });
  return store;
}

Design Your Long-Term Memory Schema

Long-term memory works best when you model stable facts about your users or domain.

Common patterns include:

• User profiles - Role, seniority, team, location. Persistent preferences (for example, tone, language, product tier).

• Constraints and policies - Allergies, compliance restrictions, budget caps.

• Interaction history summaries - High-level summaries of past sessions. Decisions that should carry forward (for example, "user prefers MongoDB Atlas over self-managed").

You can store these either as simple JSON documents or as documents with embeddings for semantic search.

Persist User Memories

The MongoDB Store API supports the following operations:

• put - store or update a value.

• get - retrieve a value by namespace and key.

• delete - remove a value.

• search - retrieve values by vector similarity and/or metadata filters.

The exact TypeScript types might differ, but the following code demonstrates a typical usage pattern in LangGraph.js:

// memory-api.ts
import type { MongoDBStore } from "@langchain/langgraph-checkpoint-mongodb";
type MemoryValue = {
  type: "profile" | "preference" | "fact";
  data: Record<string, unknown>;
  updatedAt: string;
};
export async function putUserMemory(
  store: MongoDBStore,
  userId: string,
  key: string,
  value: MemoryValue
) {
  await store.put(
    [userId, "memories"],
    key,
    value
  );
}
export async function getUserMemories(
  store: MongoDBStore,
  userId: string,
  key: string
) {
  const result = await store.get(
    [userId, "memories"],
    key
  );
  return result;
}

Add Long-Term Memory to Your Agent Workflow

This section assumes you already have an agent workflow similar to the one described in Build an AI Agent with LangGraph.js and MongoDB Atlas, including:

• A GraphState annotation with a messages field.

• A tool node that calls MongoDB Vector Search using embeddings from Voyage AI.

• A chat model node that decides whether to call tools or respond directly.

• A MongoDBSaver checkpointer for short-term memory.

// agent-with-long-term-memory.ts
import { ChatOpenAI } from "@langchain/openai";
import {
  AIMessage,
  BaseMessage,
  HumanMessage,
} from "@langchain/core/messages";
import {
  ChatPromptTemplate,
  MessagesPlaceholder,
} from "@langchain/core/prompts";
import { StateGraph, Annotation } from "@langchain/langgraph";
import { tool } from "@langchain/core/tools";
import { ToolNode } from "@langchain/langgraph/prebuilt";
import { MongoDBSaver } from "@langchain/langgraph-checkpoint-mongodb";
import type { MongoClient } from "mongodb";
import type { MongoDBStore } from "@langchain/langgraph-checkpoint-mongodb";
import { putUserMemory, getUserMemories } from "./memory-api";
export async function callAgent(
  client: MongoClient,
  store: MongoDBStore,
  query: string,
  threadId: string,
  userId: string,
) {
  const dbName = "hr_database";
  const db = client.db(dbName);
  const collection = db.collection("employees");
  // 1. Retrieve long-term memories for the user
  const existingMemories = await getUserMemories(store, userId, "last_response");
  // 2. Define graph state
  const GraphState = Annotation.Root({
    messages: Annotation<BaseMessage[]>({
      reducer: (x, y) => x.concat(y),
    }),
    userId: Annotation<string>(),
    memories: Annotation<unknown | null>(),
  });
  // 3. Define tools (for example, MongoDB Vector Search retriever)
  const employeeLookupTool = tool(/* ...reuse from Build an AI Agent tutorial... */);
  const tools = [employeeLookupTool];
  const toolNode = new ToolNode<typeof GraphState.State>(tools);
  // 4. Configure the chat model
  const model = new ChatOpenAI({
    model: "gpt-5.4-mini",
  }).bindTools(tools);
  // 5. Define the model node
  async function callModel(state: typeof GraphState.State) {
    const prompt = ChatPromptTemplate.fromMessages([
      "system",
      `You are a helpful HR chatbot agent.
Use the provided tools and long-term memories to answer questions.
Long-term memories (if any) are in the "memories" field.`,
      new MessagesPlaceholder("messages"),
    ]);
    const formatted = await prompt.formatMessages({
      messages: state.messages,
    });
    const result = await model.invoke(formatted);
    return { messages: [result] };
  }
  // 6. Define routing logic
  function shouldContinue(state: typeof GraphState.State) {
    const messages = state.messages;
    const lastMessage = messages[messages.length - 1] as AIMessage;
    if (lastMessage.tool_calls?.length) {
      return "tools";
    }
    return "__end__";
  }
  // 7. Build the workflow
  const workflow = new StateGraph(GraphState)
    .addNode("agent", callModel)
    .addNode("tools", toolNode)
    .addEdge("__start__", "agent")
    .addConditionalEdges("agent", shouldContinue)
    .addEdge("tools", "agent");
  // 8. Configure short-term memory (checkpointer)
  const checkpointer = new MongoDBSaver({ client, dbName });
  const app = workflow.compile({
    checkpointer,
    store,
  });
  // 9. Invoke the graph with both short-term and long-term memory
  const finalState = await app.invoke(
    {
      messages: [new HumanMessage(query)],
      userId,
      memories: existingMemories,
    },
    {
      recursionLimit: 15,
      configurable: { thread_id: threadId },
    },
  );
  const last = finalState.messages[finalState.messages.length - 1];
  const content = last.content;
  // 10. Optionally, update long-term memory with new facts
  await putUserMemory(store, userId, "last_response", {
    type: "fact",
    data: { content },
    updatedAt: new Date().toISOString(),
  });
  return content;
}

Use Semantic Search and AutoEmbeddings for Long-Term Memory

To make long-term memory searchable by meaning, you can:

1. Store each memory as a document that includes:

   • A text summary or description.

   • Structured metadata (for example, userId, type, tags).

   • An embedding vector for semantic search.

2. Configure a MongoDB Vector Search index on the embedding field for your memory collection.

3. Use Voyage AI embeddings or Voyage AutoEmbeddings (through the Atlas Embedding and Reranking API) to generate embeddings for each memory document before inserting it.

4. Use the built-in search method on MongoDBStore, which calls $vectorSearch on your memory collection, optionally combined with metadata filters such as userId and type.

The following code demonstrates how to use the built-in search method on MongoDBStore to find memories by semantic similarity and metadata filters:

// semantic-memory.ts
import type { MongoDBStore } from "@langchain/langgraph-checkpoint-mongodb";
export async function searchUserMemories(
  store: MongoDBStore,
  userId: string,
  queryText: string,
  limit = 5,
) {
  const results = await store.search(
    [userId, "memories"],
    {
      query: queryText,
      filter: { type: "fact" },
      limit,
    },
  );
  return results;
}

The search method accepts a namespace prefix and an options object with the following fields:

• query - A text string for semantic search. The store uses MongoDB Vector Search to find memories that are semantically similar to the query.

• filter - A metadata filter object to narrow results (for example, { type: "fact" }).

• limit - The maximum number of results to return (default: 10).

• offset - The number of results to skip for pagination (default: 0).

When to Use Short-Term vs Long-Term Memory

Use the following guidelines to choose the right memory mechanism for each part of your application:

In many real-world applications, you will:

• Use short-term memory to keep the current conversation coherent.

• Use long-term memory to remember the user and important facts from past conversations.

• Use MongoDB Vector Search and Voyage AI embeddings with AutoEmbeddings to search memories semantically when generating responses.

Next Steps

• Follow the end-to-end tutorial in Build an AI Agent with LangGraph.js and MongoDB Atlas.

• Use this page as a reference to layer long-term memory and semantic search on top of your existing agent.

• Explore the Voyage AI docs and the Atlas Embedding and Reranking API for more details on embeddings and auto-embedding workflows.

MongoDB also provides the following developer resources:

• MongoDB Developer GitHub Repository