Agregue memoria a largo plazo a los agentes de LangGraph.js con MongoDB Atlas.

Descripción general de los mecanismos de memoria de MongoDB en LangGraph

LangGraph proporciona dos mecanismos de memoria complementarios:

Requisitos previos

Antes de comenzar, asegúrate de tener lo siguiente:

• Uno de los siguientes tipos de clúster de MongoDB:

  • Un clúster de Atlas que ejecuta la versión 6.0.11, 7.0.2 o posterior de MongoDB. Asegúrese de que su dirección IP esté incluida en la lista de acceso de su proyecto Atlas.

  • Una implementación local de Atlas creada usando Atlas CLI. Para obtener más información, consulta Crear una Implementación local de Atlas.

  • Un clúster de MongoDB Community o Enterprise con Search y Vector Search instalados.

• npm y Node.js instalados.

• Una clave de la API de Voyage IA. Para crear una clave de API, consulta Claves de API del modelo.

• Una llave de API de OpenAI. Debes tener una cuenta de OpenAI con créditos disponibles para las solicitudes de API. Para obtener más información sobre cómo registrar una cuenta de OpenAI, consulta el sitio web de la API de OpenAI.

• Si planea usar la búsqueda semántica, necesitará una base de datos y una colección de MongoDB configuradas para MongoDB Vector Search. Para obtener más información, consulte Crear un índice de Atlas Vector Search.

Debes estar familiarizado con lo siguiente e idealmente haberlo completado:

• Integración de MongoDB con LangGraph.js (descripción general, puntero de control y herramientas de recuperación).

• Crea un agente de IA con LangGraph.js y MongoDB Atlas (agente integral, búsqueda vectorial y memoria a corto plazo).

Instale las dependencias

Instala las dependencias principales utilizadas en el tutorial "Crear un agente de IA", además del módulo MongoDB Store para 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

El paquete @langchain/langgraph-checkpoint-mongodb incluye tanto el puntero de control como el almacenamiento MongoDB para memoria a largo plazo.

Configurar el almacén de MongoDB

LangGraph Stores implementa la BaseStore interfaz con operaciones get putcomo,, delete y search para documentos JSON bajo espacios de nombres jerárquicos.

// 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;
}

Diseña tu esquema de memoria a largo plazo

La memoria a largo plazo funciona mejor cuando se modelan hechos estables sobre los usuarios o el dominio.

Los patrones comunes incluyen:

• Perfiles de usuario: rol, antigüedad, equipo, ubicación. Preferencias persistentes (por ejemplo, tono, idioma, nivel de producto).

• Restricciones y políticas: alergias, restricciones de cumplimiento, límites presupuestarios.

• Resúmenes del historial de interacciones: resúmenes generales de sesiones anteriores. Decisiones que deben conservarse (por ejemplo, "el usuario prefiere MongoDB Atlas a la gestión propia").

Puedes almacenarlos como documentos JSON simples o como documentos con elementos incrustados para la búsqueda semántica.

Conservar la memoria del usuario

La API de MongoDB Store admite las siguientes operaciones:

• put - Almacenar o actualizar un valor.

• get - Recuperar un valor por espacio de nombres y clave.

• delete - eliminar un valor.

• search - Recuperar valores mediante similitud vectorial y/o filtros de metadatos.

Los tipos exactos de TypeScript pueden variar, pero el siguiente código demuestra un patrón de uso típico en 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;
}

Agregue memoria a largo plazo al flujo de trabajo de su agente.

Esta sección asume que ya dispone de un flujo de trabajo de agente similar al descrito en "Crear un agente de IA con LangGraph.js y MongoDB Atlas", que incluye:

• Una anotación GraphState con un campo messages.

• Un nodo de herramienta que llama a MongoDB Vector Search utilizando incrustaciones de Voyage AI.

• Un nodo del modelo de chat que decide si llamar a herramientas o responder directamente.

• Un puntero de control MongoDBSaver para la memoria a corto plazo.

// 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;
}

Utilice la búsqueda semántica y las incrustaciones automáticas para la memoria a largo plazo.

Para que la memoria a largo plazo sea consultable por significado, puedes:

1. Almacena cada recuerdo como un documento que incluya:

   • Un resumen o descripción de texto.

   • Metadatos estructurados (por ejemplo, userId, type, tags).

   • Un vector de incrustación para la búsqueda semántica.

2. Configure un índice de búsqueda vectorial de MongoDB en el campo embedding para su colección de memoria.

3. Utilice las incrustaciones de Voyage AI o Voyage AutoEmbeddings (a través de la API de Atlas Embedding and Reranking) para generar incrustaciones para cada documento en memoria antes de insertarlo.

4. Utilice el método incorporado search en MongoDBStore, que llama a $vectorSearch en su colección de memoria, opcionalmente combinado con filtros de metadatos como userId y type.

El siguiente código demuestra cómo usar el método integrado search en MongoDBStore para encontrar recuerdos por similitud semántica y filtros de metadatos:

// 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;
}

El método search acepta un prefijo de espacio de nombres y un objeto de opciones con los siguientes campos:

• query - Una cadena de texto para la búsqueda semántica. El sistema utiliza la búsqueda vectorial de MongoDB para encontrar recuerdos que sean semánticamente similares a la consulta.

• filter - Un objeto de filtro de metadatos para restringir los resultados (por ejemplo, { type: "fact" }).

• limit - El número máximo de resultados a devolver (valor predeterminado: 10).

• offset - El número de resultados que se omitirán para la paginación (predeterminado: 0).

Cuándo usar la memoria a corto plazo frente a la memoria a largo plazo

Utilice las siguientes directrices para elegir el mecanismo de memoria adecuado para cada parte de su aplicación:

En muchas aplicaciones del mundo real, usted deberá:

• Utiliza la memoria a corto plazo para mantener la conversación actual coherente.

• Utiliza la memoria a largo plazo para recordar al usuario y los datos importantes de conversaciones anteriores.

• Utilice la búsqueda vectorial de MongoDB y las incrustaciones de Voyage AI con AutoEmbeddings para buscar recuerdos semánticamente al generar respuestas.

Próximos pasos

• Sigue el tutorial completo en "Crea un agente de IA con LangGraph.js y MongoDB Atlas".

• Utilice esta página como referencia para incorporar memoria a largo plazo y búsqueda semántica a su agente existente.

• Consulta la documentación de Voyage AI y la API de Atlas Embedding and Reranking para obtener más detalles sobre las incrustaciones y los flujos de trabajo de incrustación automática.

MongoDB también proporciona los siguientes recursos para desarrolladores:

• Repositorio de GitHub para desarrolladores de MongoDB