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

Resumen 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. Es necesario garantizar que la dirección IP esté incluida en la lista de acceso del proyecto Atlas.

  • Implementación local de Atlas creada con Python y Docker. Instale atlas-local-lib-py pip install atlas-local-lib-py() para crear y administrar implementaciones locales mediante programación. Para obtener más información, consulte el repositorio atlas-local-lib-py.

  • Un clúster de MongoDB Community con Search y búsqueda vectorial instalados.

• npm y Node.js instalados.

• Una clave API de Voyage AI. Para crear una clave API, consulte la sección "Administrar claves API de modelos de Voyage AI".

• 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.

• Una base de datos y una colección de MongoDB configuradas para MongoDB búsqueda vectorial si planeas usar búsqueda semántica. Para saber más, consulta Crear un índice de Atlas Vector Search.

Debes estar familiarizado y preferiblemente haber completado:

• Integra MongoDB con LangGraph.js (visión general, punto de control y herramientas de recuperación).

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

Instale las dependencias

Instala las dependencias principales usadas en el tutorial Crear un agente 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 checkpointer como el MongoDB Store para la memoria a largo plazo.

Configurar la tienda MongoDB

Las tiendas LangGraph implementan la interfaz BaseStore con operaciones como get, put, 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 modelas hechos estables sobre tus usuarios o el dominio.

Los patrones comunes incluyen:

• Perfiles de usuario: rol, antigüedad, equipo y 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 de alto nivel de sesiones anteriores. Decisiones que deben mantenerse en el tiempo (por ejemplo, "el usuario prefiere MongoDB Atlas sobre lo autogestionado").

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

Persistir memorias de usuario

La API de Store de MongoDB admite las siguientes operaciones:

• put - almacenar o actualizar un valor.

• get - recuperar un valor por namespace y clave.

• delete - remover un valor.

• search - recuperar valores mediante similitud de vectores y/o filtros de metadatos.

Los tipos exactos de TypeScript pueden diferir, 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;
}

Agrega memoria a largo plazo a tu flujo de trabajo de agentes

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

• Una anotación de GraphState con un campo messages.

• Un nodo de herramienta que llama a MongoDB búsqueda vectorial utilizando incrustaciones de Voyage IA.

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

• Un register 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;
}

Utilizar búsqueda semántica y AutoEmbeddings para la memoria a largo plazo

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

1. Almacene cada memoria 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. Configura un índice de MongoDB búsqueda vectorial en el campo embedding de tu colección de memoria.

3. Utiliza las incrustaciones de Voyage AI o Voyage AutoEmbeddings (a través del API de Embedding y Reranking de Atlas) para generar incrustaciones para cada documento de memoria antes de insertarlo.

4. Use el método de funcionalidad incorporada 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 muestra cómo utilizar el método incorporado search en MongoDBStore para encontrar memorias 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 namespace y un objeto de opciones con los siguientes campos:

• query - Una string de texto para la búsqueda semántica. La tienda utiliza MongoDB búsqueda vectorial para encontrar recuerdos que sean semánticamente similares a la query.

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

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

• offset - El número de resultados a omitir para la paginación (por defecto: 0).

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

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

En muchas aplicaciones del mundo real, tú:

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

• Utiliza la memoria a largo plazo para recordar al usuario y hechos importantes de conversaciones pasadas.

• Utilice la Búsqueda Vectorial de MongoDB y las incrustaciones de Voyage AI con AutoEmbeddings para buscar recuerdos a nivel semántico al generar respuestas.

Próximos pasos

• Siga el tutorial de principio a fin en Crear un agente de IA con LangGraph.js y MongoDB Atlas.

• Usa esta página como referencia para añadir memoria a largo plazo y búsqueda semántica sobre tu 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