Você pode integrar o MongoDB ao Vercel AI SDK, uma estrutura TypeScript para criar aplicativos e agentes de IA. A integração está disponível no pacote @mongodb-developer/vercel-ai-memory npm e fornece memória persistente apoiada MongoDB para os agentes. A integração inclui os seguintes níveis de memória:
Memória da sessão: armazena as voltas de conversa da sessão atual
Memória semântica: armazena conhecimento de longo prazo sobre entidades nomeadas, como pessoas e preferências do usuário
Memória de procedimentos: armazena conhecimento prático, como tarefas e fluxos de trabalho
Memória capsular: armazena registros dos principais eventos e resultados
Memória Scratchpad: armazena anotações de trabalho temporárias que você pode promover para gravações periódicas
A integração do MongoDB armazena memória no MongoDB, cria índices do MongoDB Vector Search automaticamente e aplica uma política de retenção para cada nível de memória. Você pode gerar incorporações com um modelo do lado do cliente ou pode utilizar a Incorporação Automatizada do Atlas para gerá-las do lado do servidor.
Começar
Para concluir um tutorial que configura o Vercel AI SDK para usar o MongoDB, consulte Introdução à integração do MongoDB Vercel AI SDK.
Instalação
Para instalar o fornecedor de memória MongoDB para o Vercel AI SDK, execute o seguinte comando:
npm install @mongodb-developer/vercel-ai-memoryO pacote exige os pacotes ai, mongodb e zod como dependências. Esta página também faz referência aos modelos de incorporação da Voyage AI, que exigem o pacotevoyage-ai-provider. Para instalar essas dependências, execute o seguinte comando:
npm install ai mongodb zod voyage-ai-providerObservação
A integração é compatível com o Vercel AI SDK v6 e v7.
Uso
Esta seção descreve como criar um agente que usa o provedor de memória MongoDB .
Criar um provedor de memória
Para criar um provedor de memória do MongoDB , chame o método createMongoDBMemory() e passe a string de conexão do MongoDB e um modelo de incorporação como argumentos. Selecione a aba Voyage AI ou OpenAI para visualizar um exemplo que utiliza o provedor de modelo de incorporação correspondente:
Para usar um modelo de incorporação da Voyage AI, instale o pacotevoyage-ai-provider. As chaves de API do Voyage AI que você cria no Atlas exigem o endpoint do MongoDB Voyage AI, que você especifica com a opção baseURL do método createVoyage(). Para saber como criar uma chave de API do modelo Voyage AI, consulte Gerenciar chaves de API do modelo Voyage AI.
O exemplo a seguir cria um fornecedor de memória que usa um modelo de incorporação do Voyage AI:
import { createMongoDBMemory } from '@mongodb-developer/vercel-ai-memory'import { createVoyage } from 'voyage-ai-provider'
const voyage = createVoyage({ apiKey: process.env.VOYAGE_API_KEY, baseURL: 'https://ai.mongodb.com/v1',})
const mongodbMemory = createMongoDBMemory({ uri: process.env.MONGODB_URI!, embedder: voyage.embeddingModel('voyage-4'),})O exemplo a seguir cria um provedor de memória que usa um modelo de incorporação OpenAI:
import { createMongoDBMemory } from '@mongodb-developer/vercel-ai-memory'import { openai } from '@ai-sdk/openai'
const mongodbMemory = createMongoDBMemory({ uri: process.env.MONGODB_URI!, embedder: openai.embedding('text-embedding-3-small'),})O fornecedor se conecta ao MongoDB no primeiro uso da ferramenta. Para conectar e criar os índices de pesquisa antes da primeira solicitação, chame o método connect(). Para fechar a conexão MongoDB quando seu aplicação for desligado, chame o método close().
Crie um agente
Para conectar o fornecedor de memória ao seu agente, chame o fornecedor de memória do MongoDB e passe argumentos userId e sessionId. Em seguida, passe as ferramentas de memória para o seu agente. O exemplo a seguir cria um agente cujas ferramentas de memória têm como escopo um usuário e uma sessão:
import { openai } from '@ai-sdk/openai'import { ToolLoopAgent } from 'ai'
const agent = new ToolLoopAgent({ model: openai('gpt-4.1'), tools: mongodbMemory({ userId: 'alice', sessionId: 'sess-001' }),})Cada camada de memória armazena e recupera memória com escopo para esses identificadores. Para usar os valores userId e sessionId que você passou para o método createMongoDBMemory(), chame o provedor de memória do MongoDB sem argumentos.
Configurar o provedor de memória
Esta seção descreve como personalizar o provedor de memória MongoDB definindo parâmetros do método createMongoDBMemory().
Incorporando modos
Os comandos semantic_search, procedural_search e episodic_search executam queries de pesquisa vetorial para recuperar memória. Antes de executar uma pesquisa vetorial, a integração incorpora o texto da query.
O Atlas permite dois modos de incorporação:
Incorporação manual: Gere vetores de incorporação no lado do cliente com um modelo de incorporação que você especifica.
embedding automatizada: o MongoDB incorpora texto no lado do servidor sem precisar gerá-lo manualmente. Para aprender mais, consulte Embedding automatizada.
Selecione a aba Atlas Automated Embedding para permitir que o Atlas incorpore o texto de query automaticamente ou selecione a aba Client embedding model para visualizar o comportamento de incorporação padrão:
Para permitir que o Atlas gere e gerencie incorporações automaticamente, passe o parâmetro autoEmbed para o método createMongoDBMemory(). O exemplo a seguir mostra esta configuração:
import { createMongoDBMemory } from '@mongodb-developer/vercel-ai-memory'
const mongodbMemory = createMongoDBMemory({ uri: process.env.MONGODB_URI!, autoEmbed: { model: 'voyage-4' },})Nesse modo, a integração armazena o texto de origem, cria índices vetoriais para o tipo autoEmbed e emite queries $vectorSearch com uma string de texto sem formatação. A incorporação automatizada do Atlas não requer uma chave de API incorporada ou um pipeline de incorporação do cliente .
Observação
A incorporação automatizada requer uma organização Atlas que tenha o Voyage AI habilitado. Em clusters dedicados (M10 e maiores), você deve habilitar o auto-scaling de armazenamento.
Para gerar incorporações no cliente, passe o parâmetro embedder para o método createMongoDBMemory(). O exemplo a seguir mostra essa configuração e usa um modelo de incorporação OpenAI:
import { createMongoDBMemory } from '@mongodb-developer/vercel-ai-memory'import { openai } from '@ai-sdk/openai'
const mongodbMemory = createMongoDBMemory({ uri: process.env.MONGODB_URI!, embedder: openai.embedding('text-embedding-3-small'),})O parâmetro embedder aceita qualquer modelo que implemente a interface do Vercel AI SDK EmbeddingModel, incluindo modelos da OpenAI, Cohere e Google. Você também pode usar os modelos de incorporação do Voyage AI por meio do pacotevoyage-ai-provider. Para visualizar os fornecedores disponíveis, consulte Fornecedores de SDK de IA na documentação do SDK de Vercel AI. A integração detecta o número de dimensões vetoriais automaticamente, portanto, você não as configura.
Topologia de dados
Por padrão, a integração armazena memória no banco de dados agent_memory e usa a coleção padrão e os nomes de índice descritos na seção Coleções e índices . Para personalizar os nomes do banco de dados, da collection e do índice, passe o parâmetro topology para o método createMongoDBMemory().
O exemplo a seguir fornece nomes personalizados para a sessão e camadas de memória semântica:
createMongoDBMemory({ uri: process.env.MONGODB_URI!, embedder: voyage.embeddingModel('voyage-4'), topology: { dbName: 'my_app', collections: { session: 'agent_sessions', semantic: 'agent_facts', }, vectorIndexNames: { semantic: 'agent_facts_vs', }, },})Políticas de retenção
Para controlar quando as memória expiram, você pode definir uma política de retenção para cada tipo de memória. Passe o parâmetro retention para o método createMongoDBMemory() para configurar as políticas de retenção.
Ao configurar uma política, especifique um campo mode e os campos adicionais que o modo exige. A tabela a seguir descreve os modos disponíveis e seus campos:
Modo | Campos | Descrição |
|---|---|---|
| necessário: | Memórias nunca expiram. |
| Necessário: | As memória expiram após o número de segundos que o campo |
| Obrigatório: | O time-to-live (TTL) aplica-se apenas a recordações com um valor de |
| Necessário: | A função |
O exemplo a seguir configura uma política de retenção para gravações semânticas, armazenando apenas gravações importantes após uma semana:
createMongoDBMemory({ uri: process.env.MONGODB_URI!, embedder: voyage.embeddingModel('voyage-4'), retention: { semantic: { mode: 'ttl+importance', ttlSeconds: 604800, minImportance: 6 }, },})Modos de memória de sessão
A memória de sessão suporta os dois modos a seguir, ambos apoiados pela mesma coleção:
modo orientado por ferramentas: O modelo decide quando salvar e recuperar as reviravoltas da sessão
modo orientado por gancho: o tempo de execução salva e recupera as mudanças de sessão automaticamente
Selecione a aba Tool-driven ou Hook-driven para ver um exemplo de código correspondente:
No modo orientado a ferramentas, o modelo salva e lê voltas de sessão chamando os comandos session_append e session_recent por meio da ferramenta de memória. Este modo é o mais simples de configurar, mas o modelo pode optar por não salvar uma curva ou carregar colunas anteriores. Use o modo orientado a ferramentas para protótipos e demostrações, onde a simplicidade é uma prioridade mais alta do que um registro completo de conversa.
O exemplo a seguir gera uma resposta e permite que o modelo decida quando salvar a curva:
const result = await agent.generate({ prompt: 'My name is Alice and I am a marine biologist. Remember that.',})No modo guiado por gancho, o tempo de execução lê os gráficos anteriores antes de cada chamada de modelo e grava cada usuário, assistente e ferramenta após a conclusão do loop da ferramenta, independentemente do que o modelo decidir. Recomendamos que você use este modo em produção.
Para ocultar os comandos de sessão do modelo e manter a collection de sessão disponível, defina a opção hideToolCommands do parâmetro topology como ['session']. O exemplo a seguir restaura a transcrição da sessão no gancho prepareCall e persiste a cada mudança no gancho onFinish:
import { createMongoDBMemory } from '@mongodb-developer/vercel-ai-memory'import { openai } from '@ai-sdk/openai'import { ToolLoopAgent, isLoopFinished } from 'ai'import { z } from 'zod'
const mongodbMemory = createMongoDBMemory({ uri: process.env.MONGODB_URI!, embedder: openai.embedding('text-embedding-3-small'), topology: { hideToolCommands: ['session'] },})
const agent = new ToolLoopAgent({ model: openai('gpt-4o-mini'),
callOptionsSchema: z.object({ userId: z.string(), sessionId: z.string(), prompt: z.string(), }),
prepareCall: async ({ options, prompt: _p, messages: _m, ...settings }) => { const { userId, sessionId, prompt } = options! const history = await mongodbMemory.loadSession({ userId, sessionId }) return { ...settings, tools: mongodbMemory({ userId, sessionId }), messages: [...history, { role: 'user', content: prompt }], experimental_context: { userId, sessionId, prompt }, } },
onFinish: mongodbMemory.onFinish(), stopWhen: isLoopFinished(),})O método loadSession() retorna as voltas anteriores do usuário e do assistente, que você adiciona ao início do campomessages. O método onFinish() persiste no prompt do usuário e em cada mensagem do assistente e da ferramenta. A integração armazena a ferramenta como registros de transcrição, mas não os reproduz como resultados da ferramenta.
As outras camadas de memória permanecem sob o controle do modelo em ambos os modos. O modelo deve selecionar quais memória semântica, processual e escalonada deve ser salva e recuperada, em vez de escrever a cada volta.
Comandos da ferramenta de memória
A integração fornece uma única ferramenta memory que aceita um campo command e envia o comando para a camada de memória correspondente. A tabela a seguir descreve os comandos disponíveis para cada nível:
Nível de memória | Comandos | Descrição |
|---|---|---|
Sessão |
| O comando |
Semântico |
| O comando |
Processual |
| O comando |
Episódico |
| O comando |
Rascunho |
| The |
Qualquer nível |
| O comando |
O modelo escolhe quais comandos chamar, então você não define explicitamente o campocommand . No entanto, você pode consultar os comandos nas instruções do seu agente. O exemplo a seguir mostra um agente cujas instruções especificam quais comandos usar:
const agent = new ToolLoopAgent({ model: openai('gpt-4.1'), tools: mongodbMemory({ userId: 'alice', sessionId: 'sess-001' }), instructions: `You are an assistant with persistent memory. At the start of each session, call session_recent to restore context. Save important facts with semantic_save. If the user asks you to forget something, call memory_forget.`,})Collections e índices
No primeiro uso, a integração cria as seguintes collections no seu banco de dados:
collection | Política de retenção padrão | Índice vetorial |
|---|---|---|
| O modo | none |
| O modo |
|
| O modo |
|
| O modo |
|
| O modo | none |
The integration also creates an expire_at TTL index on each collection, which expires each memory at the time stored in its expire_at field. The memory_forget command and the dynamic retention mode set this field to expire memories.
Observação
Os índices do MongoDB Vector Search são construídos de forma assíncrona. Em um novo banco de dados, aguarde alguns segundos para que os índices sejam criados antes de pesquisar.
Recursos adicionais
Para saber mais sobre como usar o Vercel AI SDK com o MongoDB, consulte os seguintes recursos:
Documentação doSDK do Vercel AI
@mongodb-developer/vercel-ai-memory npm pacote
vercel-ai-memory Repositório do GitHub