Overview
La memoria en el motor de agentes de MongoDB Atlas se configura a nivel de proyecto. Todos los agentes de un proyecto comparten el mismo servicio de memoria, almacenamiento y configuración. Puede habilitar o deshabilitar la memoria para agentes individuales en su archivo agent.yaml.
Para configurar la memoria, edite el bloque memory: en su archivo project-config.yaml, cargue las claves API necesarias como secretos del proyecto e implemente su agente. Después de la implementación inicial, puede actualizar la configuración de memoria sin necesidad de volver a implementar.
Para obtener más información sobre la memoria, incluyendo cómo se almacena y se extrae durante las conversaciones, consulte la guía de Memoria del Agente.
Requisitos previos
Asegúrese de cumplir con los siguientes requisitos previos antes de comenzar:
Un archivo
agent.yamly un agente desplegado. Para comenzar, consulte la sección "Primeros pasos con el motor de agentes de Atlas".La interfaz de línea de comandos
agentenginese instaló y autenticó correctamente. Para obtener más información, consulte Instalación y autenticación.Se requiere un clúster Atlas Flex (requisito mínimo),
M10,M20o de nivel superior (recomendado) para almacenar los datos de memoria. Para configurar un clúster, consulte la sección "Configurar recursos de Atlas".- Recomendamos implementar un clúster dedicado de nivel
M10o superior para dar cabida a sus datos de memoria y al número de índices a medida que aumenten. Atlas Flex es el nivel de clúster más bajo que puede admitir el servicio de memoria.
Nota
Si el clúster de Atlas vinculado no puede crear los índices de búsqueda y búsqueda vectorial que requiere la memoria, el motor del agente de Atlas detiene la implementación en la etapa Memory: waiting y podría agotar el tiempo de espera con un mensaje de error Error: context deadline exceeded.
Habilitar memoria
Para habilitar la memoria para su agente, configure features.memory: true en su archivo agent.yaml, luego agregue las siguientes variables a su archivo .env antes de iniciar el entorno local:
VOYAGE_API_KEY: Necesario para generar incrustaciones de memoria.MONGOMEM_DB_NAME: Opcional. El nombre de la base de datos MongoDB en la que escribe el servidor de memoria. Por defecto esmdb_memory_<project-id>.
Memory requiere la estructura de proyecto de dos niveles descrita en la siguiente sección. Si utiliza el comando agentengine create para generar la estructura básica de su proyecto, la interfaz de línea de comandos (CLI) la generará automáticamente.
Nota
Los agentes de TypeScript habilitan la memoria mediante el mismo método. Un agente de TypeScript accede al cliente app.memory solo mientras gestiona una solicitud de plataforma. Para leer o escribir en la memoria fuera de ese contexto, utilice el cliente Memory del paquete @mongodb-js/agent-engine-sdk-memory, que se conecta directamente al servidor de memoria a través de HTTP.
Estructura del proyecto para la memoria
La raíz de tu proyecto contiene un archivo project-config.yaml que almacena la configuración de memoria. Cada espacio de trabajo, que contiene un archivo agent.yaml, es una subcarpeta de la raíz del proyecto. El siguiente ejemplo muestra la estructura de proyecto esperada para la configuración de memoria:
my-project/ ├── project-config.yaml └── my-workspace/ └── agent.yaml
El archivo project-config.yaml contiene una sección memory: que configura el servidor de memoria para su proyecto. El siguiente ejemplo muestra las opciones de configuración de memoria disponibles y sus opciones predeterminadas:
memory: # Memory-server log level. One of: debug | info | warning | error | # critical. log_level: info # Voyage AI embeddings. # The Voyage API key is NOT set here — upload it as a project # secret with: # agentengine secret set VOYAGE_API_KEY <value> voyage: model: "voyage-4-large" dimension: 1024 # Short-term memory write-path behavior. short_term: # Embed each turn's content when it is written (only when the # caller supplies no embedding), so it is searchable by # relevance immediately instead of waiting for background # embedding. Adds embedding latency to the write. embed_on_write: false # LLM used for background extraction. # The API key is NOT set here — upload it as a project secret. If # your agent already uses a supported LLM connection, upload that # same key under the shared LLM_API_KEY name so the agent and # extraction reuse one secret: # agentengine secret set LLM_API_KEY <value> # Otherwise, upload a provider-named key instead, for example: # agentengine secret set OPENAI_API_KEY <value> extraction_llm: provider: openai # one of: openai | anthropic | gemini | cerebras model: null # overrides the provider's default model base_url: null # optional: route requests through a gateway # or proxy instead of the provider's default # endpoint. Required only for gateway # connections; omit to call the provider # directly. api_key_secret: null # optional: the name of the project secret # that holds the extraction LLM's API key. # One of: LLM_API_KEY, OPENAI_API_KEY, # ANTHROPIC_API_KEY, GEMINI_API_KEY, or # CEREBRAS_API_KEY. If omitted, extraction # checks provider-named keys before # LLM_API_KEY. auth_header: null # optional: the header the gateway expects for # the API key. One of: authorization (Bearer) # or api-key. Omit for native provider # authentication. background_extraction: snapshot: max_messages: 20 stale_minutes: 3 embed_stm_before_promotion: true topic_shift_enabled: false topic_shift_threshold: 0.35 delete_promoted: false ttl_days: 30 # Extraction pipeline. Add memory types to the 'enabled' list to # turn extraction on, for example: # enabled: # - semantic # - episodic # Valid types: semantic, episodic, taxonomic, entity, preferences, # procedural. # NOTE: Removing the 'enabled' line entirely re-enables ALL types. # Keep it as [] to extract nothing. extraction: enabled: []
Para cargar y sincronizar la configuración de memoria de un proyecto implementado, consulte Configurar memoria.
Migrar la estructura del proyecto
Si su proyecto utiliza una estructura plana con agent.yaml en la raíz del proyecto, migre a la estructura de dos niveles antes de habilitar la memoria. La estructura plana está obsoleta.
Para migrar su estructura plana, siga los siguientes pasos:
Crea un archivo project-config.yaml en la raíz del proyecto.
El siguiente archivo de ejemplo project-config.yaml muestra la configuración de la sección memory::
memory: log_level: info voyage: model: "voyage-4-large" dimension: 1024 short_term: embed_on_write: false extraction_llm: provider: openai model: null base_url: null api_key_secret: null
Configurar memoria
Utilice los comandos agentengine memory para cargar y sincronizar la configuración de memoria de su proyecto para los proyectos desplegados. La configuración de memoria tiene alcance de proyecto: un único documento de configuración se aplica a todos los agentes del proyecto.
Para configurar la memoria para el desarrollo local, consulte la sección Habilitar memoria.
Sintaxis del comando de configuración
El comando agentengine memory configure lee un archivo project-config.yaml del directorio del agente, extrae la sección memory: y la carga en el motor del agente Atlas. El comando confirma el proyecto de destino antes de la carga.
Importante
En una futura actualización se eliminará la compatibilidad con el comando agentengine memory configure. En su lugar, la plataforma admitirá la gestión de memoria a través de la interfaz de usuario.
El siguiente ejemplo muestra la sintaxis del comando para cargar la configuración de memoria:
agentengine memory configure <path> [--project-id <id> --org-id <id> --base-url <url>]
Como alternativa, puede utilizar el comando agentic memory configure y pasar solo el indicador --context, como se muestra en el siguiente ejemplo:
agentengine memory configure <path> [--context <name>]
Advertencia
Si el archivo project-config.yaml no contiene una clave memory:, el comando devuelve un error. La ausencia de una clave memory: no elimina una configuración existente.
La siguiente tabla describe las banderas disponibles:
Flag | Descripción |
|---|---|
| El nombre de un contexto guardado que identifica la URL base de la plataforma de destino, la organización y el proyecto. Para ver sus contextos guardados, ejecute |
| ID del proyecto. Si se omite, el comando utiliza el proyecto del estado de autenticación local. Si activa este indicador, también debe activar los indicadores |
| ID de la organización. Obligatorio si utiliza la bandera |
| URL base de la plataforma. Obligatorio si utiliza la bandera |
| Omitir la solicitud de confirmación. Utilice esta opción en entornos de integración continua (CI). |
Nota
La configuración de memoria no es un almacén de secretos. Almacene únicamente la configuración no secreta en el archivo project-config.yaml. Utilice el comando agentengine secret set para claves de API, cadenas de conexión y otras credenciales. El motor del agente de Atlas rechaza las cargas que contienen valores que coinciden con patrones secretos comunes.
Configuración inicial de la memoria
Antes de su primera implementación con la memoria habilitada, realice los siguientes pasos:
Edita el bloque memory: en tu archivo project-config.yaml.
Abra project-config.yaml en la raíz del proyecto y configure los ajustes de memoria. Para ver las opciones disponibles, consulte Estructura del proyecto para la memoria.
Sube los secretos requeridos.
Ejecute los siguientes comandos para cargar los secretos e incluya la bandera --project-scope para seleccionar secretos con ámbito de proyecto:
agentengine secret set VOYAGE_API_KEY --project-scope agentengine secret set LLM_API_KEY --project-scope
Si configuraste tu proyecto con el comando agentic create --llm <provider> --memory y seleccionaste un proveedor LLM compatible, la CLI ya agregó extraction_llm.api_key_secret: LLM_API_KEY a tu archivo project-config.yaml. Este es el mismo nombre secreto que usa el archivo .env de tu agente, por lo que cargarlo una sola vez proporciona la clave tanto para el agente como para la extracción de memoria.
Nota
Aún puede usar claves con nombre de proveedor, como OPENAI_API_KEY o ANTHROPIC_API_KEY. Sin un valor api_key_secret explícito, la extracción verifica las claves con nombre de proveedor antes que LLM_API_KEY. Configure el campo api_key_secret explícitamente si la memoria requiere una credencial separada de su agente, o si tiene claves para varios proveedores y desea seleccionar una.
Si asigna a api_key_secret un valor distinto de LLM_API_KEY, reemplace LLM_API_KEY en el comando anterior con ese nombre.
Actualizar la configuración de memoria
Los cambios en la configuración de memoria no requieren volver a implementar el agente. Para aplicar la configuración de memoria actualizada a una implementación en ejecución, siga los siguientes pasos:
Edita el bloque memory: en tu archivo project-config.yaml con tu nueva configuración de memoria.
Abra project-config.yaml en la raíz del proyecto y configure los ajustes de memoria. Para ver las opciones disponibles, consulte Estructura del proyecto para la memoria.
Aplicar la configuración.
agentengine memory apply
El comando agentengine memory apply reinicia el servidor de memoria para que registre la nueva configuración. La plataforma implementa los cambios de configuración de forma asíncrona, y estos se aplican cuando el pod se reinicia o cuando se actualiza la configuración al iniciar el sistema. Si la configuración almacenada aún no se ha sincronizado, el comando agentengine deploy la sincroniza como parte del siguiente proceso de despliegue.
Declarar tipos de memoria personalizados
Los tipos de memoria personalizados almacenan registros específicos del dominio que no se corresponden con los cuatro tipos de memoria integrados. Para declarar y utilizar tipos de memoria personalizados, siga los siguientes pasos:
Declara tus tipos personalizados.
Agregue un bloque custom_memory_types: a la sección memory: de su archivo project-config.yaml. El siguiente ejemplo crea un tipo customer_profile personalizado:
memory: custom_memory_types: # Custom memory types (max 5) - name: customer_profile collection: profiles tags: - name: location - name: tier - name: profile.location # One level of nested tag keys
Cada tipo de memoria personalizada tiene los siguientes campos:
name(Obligatorio) El nombre del tipo. El valor debe comenzar con una letra minúscula y contener solo letras minúsculas, números y guiones bajos. No puede usar ninguno de los nombres de tipo predefinidos ni exceder los 64 caracteres de longitud.collection: (Obligatorio) La colección en la base de datos en memoria del proyecto que almacena los registros del tipo.tags: (Opcional) Claves de etiquetas filtrables, hasta diez por tipo. Una clave de etiqueta puede usar notación de punto para anidar hasta un nivel, comoprofile.location. Los valores de las etiquetas deben ser cadenas no vacías, números o booleanos.
Provisión de los nuevos tipos.
Ejecute los siguientes comandos para cargar la configuración actualizada y aplicarla al servidor de memoria, que aprovisiona cada nuevo tipo:
agentengine memory configure agentengine memory apply
Nota
Una vez que cargue una configuración que declare un tipo de memoria personalizado, no podrá editar ni eliminar la colección ni el conjunto de etiquetas de ese tipo. Para cambiar un tipo, declare un nuevo nombre de tipo.
Leer y escribir registros de memoria personalizados.
En su aplicación, utilice los métodos save() y retrieve() para escribir y leer registros de memoria personalizados:
memory.save( memory_type="customer_profile", content="Prefers direct vendor onboarding contact.", tags={"tier": "gold"}, ) hits = memory.retrieve( memory_type="customer_profile", query="How should we onboard this customer?", tags={"tier": "gold"}, top_k=5, )
Acceda a la memoria desde su agente
Al implementar un agente con memoria habilitada, la plataforma proporciona el cliente app.memory en el objeto de la aplicación. Utilice este cliente para leer y escribir en la memoria de su agente. La plataforma resuelve el usuario y la sesión actuales a partir del contexto de ejecución, por lo que no es necesario pasar explícitamente los argumentos user_id o session_id a app.memory.
Importante
Identidad de memoria de la cuenta de servicio
Cuando una cuenta de servicio invoca un agente implementado, el motor de agentes de Atlas utiliza la identidad de la propia cuenta de servicio como identidad de memoria en tiempo de ejecución. La plataforma ignora cualquier valor user_id del usuario final que proporcione la solicitud de invocación o el indicador agentengine invoke --user-id.
Las operaciones automáticas de grabación, extracción, consolidación y app.memory utilizan esta identidad resuelta. Como resultado, las invocaciones que se autentican a través de la misma cuenta de servicio comparten un ámbito de usuario de memoria.
Esta limitación se aplica únicamente a los agentes desplegados que invoca una cuenta de servicio. El servicio de memoria independiente, con ámbito de proyecto, no se ve afectado. Este servicio continúa aceptando valores explícitos de user_id y session_id del emisor.
Para aislar la memoria por usuario final, llame al servicio de memoria independiente desde su aplicación y pase los valores user_id y session_id explícitos en cada llamada. Para obtener más información, consulte la sección "Uso del servicio de memoria independiente".
Para acceder a la memoria de un agente agent-engine-sdk-langgraph, siga los pasos que se indican a continuación. Todas las plantillas de agentes de Atlas Agent Engine utilizan el paquete agent-engine-sdk-langgraph, por lo que estos pasos se aplican independientemente del caso de uso de su agente.
Acceda al cliente app.memory.
En el código de tu agente, recupera el cliente app.memory y úsalo para leer y escribir en la memoria. El siguiente ejemplo muestra cómo acceder a este cliente:
from agent_engine_sdk_langgraph import App app = App(app_name="support-agent") def build_graph(): # Your LangGraph state machine. ... # Later, in a request handler for a conversation turn: memory = app.memory
Recuperar el contexto relevante para el mensaje del usuario.
Utilice el método app.memory.build_context() para recuperar la memoria que sea relevante para un mensaje y formatéela como contexto, como se muestra en el siguiente ejemplo:
def handle_turn(user_message: str) -> str: ctx = memory.build_context( query=user_message, max_tokens=2000, ) prompt = f"{ctx.formatted_context}\n\nUser: {user_message}" return prompt
Nota
Para un agente desplegado, la plataforma registra automáticamente los turnos de conversación. No es necesario llamar a record_turn() para guardar los turnos de conversación.
Próximos pasos
Tras habilitar la memoria para su agente, puede probarlo localmente e implementarlo. Para obtener información sobre cómo probar su agente, consulte la sección «Probar el agente». Para obtener información sobre cómo implementar su agente, consulte la sección «Implementar».
Para utilizar la memoria de una aplicación que se ejecuta fuera del motor del agente de Atlas, consulte la guía "Uso de la aplicación de servicio de memoria independiente".