Puedes integrar MongoDB con el SDK de IA de Vercel, un framework de TypeScript para crear aplicaciones y agentes de IA. La integración está disponible en el paquete npm @mongodb-developer/vercel-ai-memory y proporciona memoria persistente respaldada por MongoDB para los agentes. La integración incluye los siguientes niveles de memoria:
Memoria de sesión: Almacena los turnos de conversación de la sesión actual.
Memoria semántica: Almacena conocimiento a largo plazo sobre entidades nombradas, como personas y preferencias de usuario.
Memoria procedimental: Almacena conocimientos prácticos, como tareas y flujos de trabajo.
Memoria episódica: Almacena registros de eventos y resultados clave.
Memoria de bloc de notas: Almacena notas de trabajo temporales que puedes convertir en recuerdos episódicos.
La integración con MongoDB almacena la memoria en MongoDB, crea automáticamente índices de búsqueda vectorial de MongoDB y aplica una política de retención a cada nivel de memoria. Puede generar incrustaciones con un modelo del lado del cliente o utilizar Atlas Automated Embedding para generarlas en el servidor.
Empezar
Para completar un tutorial que configure el SDK de Vercel AI para usar MongoDB, consulte la sección "Primeros pasos con la integración del SDK de Vercel AI con MongoDB".
Instalación
Para instalar el proveedor de memoria de MongoDB para el SDK de IA de Vercel, ejecute el siguiente comando:
npm install @mongodb-developer/vercel-ai-memoryEl paquete requiere los paquetes ai, mongodb y zod como dependencias. Esta página también hace referencia a los modelos de incrustación de Voyage AI, que requieren el paquete voyage-ai-provider. Para instalar estas dependencias, ejecute el siguiente comando:
npm install ai mongodb zod voyage-ai-providerNota
La integración es compatible con Vercel AI SDK v6 y v7.
Uso
Esta sección describe cómo crear un agente que utilice el proveedor de memoria de MongoDB.
Crear un proveedor de memoria
Para crear un proveedor de memoria de MongoDB, llame al método createMongoDBMemory() y pase como argumentos su cadena de conexión de MongoDB y un modelo de incrustación. Seleccione la pestaña Voyage AI o OpenAI para ver un ejemplo que utiliza el proveedor de modelo de incrustación correspondiente:
Para usar un modelo de incrustación de Voyage AI, instale el paquete voyage-ai-provider. Las claves de API de Voyage AI que cree en Atlas requieren el punto final de MongoDB de Voyage AI, que se especifica con la opción baseURL del método createVoyage(). Para obtener información sobre cómo crear una clave de API de Voyage AI, consulte Administrar claves de API de modelos de Voyage AI.
El siguiente ejemplo crea un proveedor de memoria que utiliza un modelo de incrustación de 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'),})El siguiente ejemplo crea un proveedor de memoria que utiliza un modelo de incrustación de 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'),})El proveedor se conecta a MongoDB la primera vez que se utiliza la herramienta. Para conectarse y crear los índices de búsqueda antes de la primera solicitud, llame al método connect(). Para cerrar la conexión a MongoDB cuando se cierre la aplicación, llame al método close().
Crea un Agente
Para conectar el proveedor de memoria a su agente, llame al proveedor de memoria de MongoDB y pase los argumentos userId y sessionId. A continuación, pase las herramientas de memoria a su agente. El siguiente ejemplo crea un agente cuyas herramientas de memoria están limitadas a un usuario y una sesión:
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 nivel de memoria almacena y recupera recuerdos asociados a estos identificadores. Para usar los valores userId y sessionId que pasó al método createMongoDBMemory(), llame al proveedor de memoria de MongoDB sin argumentos.
Configurar el proveedor de memoria
Esta sección describe cómo personalizar el proveedor de memoria de MongoDB configurando los parámetros del método createMongoDBMemory().
Modos de incrustación
Los comandos semantic_search, procedural_search y episodic_search ejecutan consultas de búsqueda vectorial para recuperar recuerdos. Antes de ejecutar una búsqueda vectorial, la integración inserta el texto de la consulta.
Atlas admite dos modos de integración:
Incorporación manual: Generar vectores de incorporación en el lado del cliente con un modelo de incorporación que especifiques.
Incrustación automatizada: MongoDB incrusta texto del lado del servidor sin necesidad de generarlo manualmente. Para aprender más, consulta Incrustación automatizada.
Seleccione la pestaña Atlas Automated Embedding para permitir que Atlas incruste automáticamente el texto de la consulta, o seleccione la pestaña Client embedding model para ver el comportamiento de incrustación predeterminado:
Para permitir que Atlas genere y gestione incrustaciones automáticamente, pase el parámetro autoEmbed al método createMongoDBMemory(). El siguiente ejemplo muestra esta configuración:
import { createMongoDBMemory } from '@mongodb-developer/vercel-ai-memory'
const mongodbMemory = createMongoDBMemory({ uri: process.env.MONGODB_URI!, autoEmbed: { model: 'voyage-4' },})En este modo, la integración almacena el texto fuente, crea índices vectoriales para el tipo autoEmbed y realiza consultas $vectorSearch con una cadena de texto sin formato. Atlas Automated Embedding no requiere una clave de API de incrustación ni una canalización de incrustación del cliente.
Nota
La integración automatizada requiere una organización Atlas que tenga Voyage AI habilitado. En clústeres dedicados (M10 y superiores), debe habilitar el escalado automático de almacenamiento.
Para generar incrustaciones en el cliente, pase el parámetro embedder al método createMongoDBMemory(). El siguiente ejemplo muestra esta configuración y utiliza un modelo de incrustación de 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'),}) El parámetro embedder acepta cualquier modelo que implemente la interfaz EmbeddingModel del SDK de IA de Vercel, incluidos modelos de OpenAI, Cohere y Google. También puede usar modelos de incrustación de Voyage AI a través del paquete voyage-ai-provider. Para ver los proveedores disponibles, consulte Proveedores del SDK de IA en la documentación del SDK de IA de Vercel. La integración detecta automáticamente el número de dimensiones del vector, por lo que no es necesario configurarlas.
Topología de datos
Por defecto, la integración almacena los recuerdos en la base de datos agent_memory y utiliza los nombres de colección e índice predeterminados descritos en la sección Colecciones e índices. Para personalizar los nombres de la base de datos, la colección y el índice, pase el parámetro topology al método createMongoDBMemory().
El siguiente ejemplo proporciona nombres personalizados para los niveles de memoria de sesión y 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 retención
Para controlar cuándo caducan los recuerdos, puede establecer una política de retención para cada tipo de recuerdo. Pase el parámetro retention al método createMongoDBMemory() para configurar las políticas de retención.
Al configurar una política, especifique un campo mode y los campos adicionales que requiere el modo. La siguiente tabla describe los modos disponibles y sus campos:
Modo | Campos | Descripción |
|---|---|---|
| obligatorio: | Los recuerdos nunca caducan. |
| Obligatorio: | Las memorias caducan después del número de segundos que especifica el campo |
| Obligatorio: | El tiempo de vida (TTL) se aplica solo a las memorias con un valor |
| Obligatorio: | La función |
El siguiente ejemplo configura una política de retención para memorias semánticas, almacenando solo las memorias importantes después de una semana:
createMongoDBMemory({ uri: process.env.MONGODB_URI!, embedder: voyage.embeddingModel('voyage-4'), retention: { semantic: { mode: 'ttl+importance', ttlSeconds: 604800, minImportance: 6 }, },})Modos de memoria de sesión
La memoria de sesión admite los dos modos siguientes, ambos respaldados por la misma colección:
Modo controlado por herramientas: El modelo decide cuándo guardar y recuperar los turnos de sesión.
Modo controlado por gancho: El entorno de ejecución guarda y recupera automáticamente los cambios de sesión.
Seleccione la pestaña Tool-driven o Hook-driven para ver un ejemplo de código correspondiente:
En el modo controlado por herramientas, el modelo guarda y lee los turnos de la sesión mediante los comandos session_append y session_recent a través de la herramienta de memoria. Este modo es el más sencillo de configurar, pero el modelo podría optar por no guardar un turno o cargar los anteriores. Utilice el modo controlado por herramientas para prototipos y demostraciones, donde la simplicidad sea más importante que un registro completo de la conversación.
El siguiente ejemplo genera una respuesta y permite al modelo decidir cuándo guardar el turno:
const result = await agent.generate({ prompt: 'My name is Alice and I am a marine biologist. Remember that.',})En el modo controlado por ganchos, el entorno de ejecución lee los turnos anteriores antes de cada llamada al modelo y escribe cada turno de usuario, asistente y herramienta una vez finalizado el bucle de herramientas, independientemente de lo que decida el modelo. Recomendamos utilizar este modo en producción.
Para ocultar los comandos de sesión del modelo manteniendo disponible la colección de sesiones, establezca la opción hideToolCommands del parámetro topology en ['session']. El siguiente ejemplo restaura la transcripción de la sesión en el hook prepareCall y la mantiene en cada iteración del hook 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(),})El método loadSession() devuelve los turnos anteriores del usuario y del asistente, que se añaden al inicio del campo messages. El método onFinish() guarda el mensaje del usuario y todos los mensajes del asistente y de la herramienta. La integración almacena los turnos de la herramienta como registros de transcripción, pero no los reproduce como resultados de la herramienta.
Los demás niveles de memoria permanecen bajo el control del modelo en ambos modos. El modelo debe seleccionar qué recuerdos semánticos, procedimentales y episódicos guardar y recuperar, en lugar de escribirlos en cada turno.
Comandos de la herramienta de memoria
La integración proporciona una única herramienta memory que acepta un campo command y envía el comando al nivel de memoria correspondiente. La siguiente tabla describe los comandos disponibles para cada nivel:
Nivel de memoria | Comandos | Descripción |
|---|---|---|
sesión |
| El comando |
Semántico |
| El comando |
Procedimental |
| El comando |
Episódico |
| El comando |
Bloc de notas |
| El comando |
Cualquier nivel |
| El comando |
El modelo elige qué comandos ejecutar, por lo que no es necesario configurar explícitamente el campo command. Sin embargo, puede hacer referencia a los comandos en las instrucciones de su agente. El siguiente ejemplo muestra un agente cuyas instrucciones especifican qué 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.`,})Colecciones e índices
En el primer uso, la integración crea las siguientes colecciones en su base de datos:
Colección | Política de retención por defecto | Índice vectorial |
|---|---|---|
| El modo | Ninguno |
| El modo |
|
| El modo |
|
| El modo |
|
| El modo | Ninguno |
La integración también crea un índice TTL expire_at en cada colección, que hace que cada memoria caduque en el momento almacenado en su campo expire_at. El comando memory_forget y el modo de retención dynamic configuran este campo para que las memorias caduquen.
Nota
Los índices de MongoDB Vector Search se crean de forma asíncrona. En una base de datos nueva, espere unos segundos a que se creen los índices antes de realizar una búsqueda.
Recursos adicionales
Para obtener más información sobre cómo usar el SDK de IA de Vercel con MongoDB, consulte los siguientes recursos:
Documentación delSDK de IA de Vercel
Paquete npm@mongodb-developer/vercel-ai-memory
Repositorio de GitHub devercel-ai-memory