Adicionar memória de longo prazo aos agentes LangGraph.js com o MongoDB Atlas

Visão geral dos mecanismos de memória MongoDB em LangGraph

O LangGraph fornece dois mecanismos de memória complementares:

Pré-requisitos

Antes de começar, certifique-se de ter o seguinte:

• Um dos seguintes tipos de cluster MongoDB :

  • Um cluster do Atlas executando a versão 6.0.11 do MongoDB, 7.0.2, ou posterior. Certifique-se de que seu endereço IP esteja incluído na lista de acesso do seu projeto Atlas.

  • Um sistema local do Atlas criado utilizando o Atlas CLI. Para saber mais, consulte Criar uma implantação de Atlas local.

  • Um cluster MongoDB Community ou Enterprise com Search e Vector Search instalados.

• npm e Node.js instalados.

• Uma chave de API do Voyage AI. Para criar uma chave de API, consulte Chaves de API do modelo.

• Uma chave de API da OpenAI. Você deve ter uma conta da OpenAI com créditos disponíveis para solicitações de API. Para aprender mais sobre como registrar uma conta OpenAI, consulte o website de API OpenAI.

• Um banco de dados e uma coleção MongoDB configurados para o MongoDB Vector Search se você planeja usar a pesquisa semântica. Para saber mais, consulte Criar um Índice do Atlas Vector Search .

Você deve estar familiarizado e, idealmente, ter concluído:

• Integre o MongoDB com o LangGraph.js (visualização geral, ponto de verificação e ferramentas de recuperação).

• Crie um agente de IA com o LangGraph.js e o MongoDB Atlas ( agente de ponta a ponta, pesquisa vetorial e memória de curto prazo).

Instalar dependências

Instale as dependências principais usadas no tutorial Crie um agente de IA, além do 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

O pacote @langchain/langgraph-checkpoint-mongodb inclui o checkpointer e o MongoDB Store para memória de longo prazo.

Configurar o armazenamento MongoDB

As Lojas LangGraph implementam a BaseStore interface com operações get putcomo,, delete e search para documentos JSON em namespaces hierá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;
}

Crie seu esquema de memória de longo prazo

A memória de longo prazo funciona melhor quando você modela fatores estáveis sobre seus usuários ou domínio.

Padrões comuns incluem:

• Perfis de usuário — função, experiência, equipe, localização. Preferências persistentes (por exemplo, tom, idioma, nível de produto).

• Restrições e políticas – Alergias, restrições de conformidade, limites de orçamento.

• Resumos do histórico de interações - Resumos de alto nível de sessões anteriores. Decisões que devem ser levadas adiante (por exemplo, "o usuário prefere o MongoDB Atlas ao autogerenciado").

Você pode armazená-los como documentos JSON simples ou como documentos com incorporações para pesquisa semântica.

Memórias de usuário persistentes

A API da loja MongoDB suporta as seguintes operações:

• put - armazenar ou atualizar um valor.

• get - recuperar um valor por namespace e chave.

• delete - remover um valor.

• search - recuperar valores por similaridade vetorial e/ou filtros de metadados.

Os tipos exatos do TypeScript podem ser diferentes, mas o código a seguir demonstra um padrão de uso típico no 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;
}

Adicione memória de longo prazo ao fluxo de trabalho do seu agente

Esta seção pressupõe que você já tenha um fluxo de trabalho de agente semelhante ao descrito em Crie um agente de IA com LangGraph.js e MongoDB Atlas, incluindo:

• Uma anotação GraphState com um campo messages.

• Um nó de ferramenta que chama a Vector Search do MongoDB usando incorporações da Voyage AI.

• Um nó de modelo de chat que decide se deseja chamar ferramentas ou responder diretamente.

• Um checkpointer MongoDBSaver para memória de curto prazo.

// 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 pesquisa semântica e incorporações automáticas para memória de longo prazo

Para tornar a memória de longo prazo pesquisável por significado, você pode:

1. Armazene cada memória como um documento que inclui:

   • Um resumo ou descrição de texto.

   • Metadados estruturados (por exemplo, userId, type, tags).

   • Um vetor de incorporação para pesquisa semântica.

2. Configure um índice MongoDB Vector Search no campo embedding para sua coleção de memória.

3. Use as incorporações Voyage AI ou o Voyage AutoEmbeddings (por meio da API Atlas Embedding e Reranking) para gerar incorporações para cada documento de memória antes de inseri-lo.

4. Use o método search interno em MongoDBStore, que chama $vectorSearch em sua coleção de memória, opcionalmente combinado com filtros de metadados como userId e type.

O código a seguir demonstra como usar o método search interno em MongoDBStore para encontrar recordações por similaridade semântica e filtros de metadados:

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

O método search aceita um prefixo de namespace e um objeto de opções com os seguintes campos:

• query - Uma string de texto para pesquisa semântica. O armazenamento usa o MongoDB Vector Search para encontrar memória que sejam semanticamente semelhantes à query.

• filter - Um objeto de filtro de metadados para restringir resultados (por exemplo, { type: "fact" }).

• limit - O número máximo de resultados a retornar (padrão: 10).

• offset - O número de resultados a ignorar para paginação (padrão: 0).

Quando usar memória de curto prazo versus memória de longo prazo

Use as diretrizes a seguir para escolher o mecanismo de memória adequado para cada parte do seu aplicação:

Em muitos aplicativos do mundo real, você:

• Use a memória de curto prazo para manter coerente a conversa atual.

• Use a memória de longo prazo para lembrar o usuário e detalhes importantes de conversas anteriores.

• Use as incorporações do MongoDB Vector Search e Voyage AI com o AutoEmbeddings para pesquisar memória semanticamente ao gerar respostas.

Próximos passos

• Siga o tutorial de ponta a ponta em Construir um agente de IA com o LangGraph.js e o MongoDB Atlas.

• Use esta página como referência para adicionar memória de longo prazo e pesquisa semântica além do seu agente existente.

• Explore os documentos da Voyage AI e a API de incorporação e reclassificação do Atlas para obter mais detalhes sobre incorporações e fluxos de trabalho de incorporação automática.

O MongoDB também fornece os seguintes recursos para desenvolvedores:

• Repositório do GitHub para desenvolvedores do MongoDB