memoria del SDK del motor del agente

El problema que resuelve

La memoria proporciona a un agente un almacén persistente de los hechos, conversaciones, procedimientos y vocabulario relevantes, y lo alimenta extrayendo información aprendida y duradera de las conversaciones que el agente mantiene con un LLM. La extracción la realiza un LLM que usted configura.

Para un agente implementado en la plataforma, no se requiere cableado. El entorno de ejecución registra cada conversación en la memoria a corto plazo mientras se ejecuta el flujo de trabajo del agente, y la promoción y extracción se realizan de forma asíncrona en segundo plano, por lo que nada bloquea una respuesta mientras se procesa un dato. Un agente que ya conoce algo persistente no tiene que esperar a que se extraiga para encontrarlo: puede escribir el dato directamente con save_semantic y las demás escrituras tipadas.

La relectura funciona en ambos sentidos. Un agente puede buscar un tipo de hecho a la vez: search_semantic para lo que ha aprendido, search_episodes para lo que sucedió antes, search_taxonomic para lo que significa un término, discover_procedures para cómo se hace algo, y manejar los resultados por sí mismo.

O bien, puede delegar todo el trabajo. build_context_from_sources toma una especificación por fuente, cada una declarando su propio modo de recuperación, filtro y recuento de candidatos, luego recupera de cada fuente según sus propios términos, clasifica y elimina duplicados de los resultados en conjunto, los recorta a un presupuesto de tokens y devuelve un único bloque de contexto para insertar en la siguiente solicitud. build_context hace lo mismo con un modo y un filtro para cada fuente; utilice el formulario por fuente cuando necesite que difieran.

Dos capas

La memoria se divide según la duración de las cosas y su forma.

La memoria a corto plazo (MCP) es la conversación en estado puro: un registro por turno, limitado a una sesión, escrito a medida que sucede. Es fácil de escribir y completar: todo lo dicho, en orden.

La memoria a largo plazo es lo que sobrevive a la conversación, destilada en cuatro formas porque responden a diferentes preguntas:

Los proyectos también pueden declarar tipos personalizados para los registros de dominio en los que las cuatro formas no encajan.

Cómo los escritos se convierten en memoria

No se escribe la memoria a largo plazo a mano, aunque se puede. El camino normal es:

record_turn(...)          you write turns as the conversation happens
      │
      ▼   turns accumulate into a session
   snapshot                a contiguous run of turns, summarised
      │
      ▼   an LLM reads the snapshot and extracts what is durable
  semantic · episodic · procedural · taxonomic

La extracción es asíncrona y se ejecuta en segundo plano, por lo que record_turn sigue siendo una escritura rápida. Por lo tanto, un dato aprendido en una conversación está disponible para la siguiente, no para el siguiente turno.

La consecuencia que merece la pena tener en cuenta en el diseño: los giros recientes son visibles inmediatamente a través de la memoria a corto plazo, el conocimiento extraído aparece un poco más tarde. Pide stm cuando necesites lo que se acaba de decir.

Cuando falla la extracción

La extracción en segundo plano depende de un servicio de incrustación, un LLM de extracción y la base de datos, y cualquiera de ellos puede fallar. Tus escrituras están aisladas de eso: record_turn tuvo éxito cuando devolvió su respuesta, independientemente de lo que ocurra después.

En segundo plano, un paso fallido se clasifica mediante una pregunta: ¿puede cambiar la condición sin que cambie la solicitud? Los fallos ambientales (errores de red, interrupciones del proveedor, límites de velocidad, una clave API en rotación) se reintentan automáticamente con un retardo, ajustado al fallo: un fallo de red se reintenta en segundos, un problema de credenciales más lentamente, ya que las claves son rotadas por personas. Los fallos determinados por el contenido no se reintentan, porque un reintento no puede cambiar el resultado; se registran en el servidor, donde los operadores pueden verlos, en lugar de entrar en un bucle infinito.

Esto se aplica a toda la ruta de extracción, no solo a sus extremos. Un paso que falla ya no produce un resultado vacío sin más: o bien se reintenta, o bien se registra para que los operadores puedan actuar en consecuencia.

Un elemento inutilizable no implica el descarte del resto. Si una memoria no puede incrustarse —su contenido es demasiado extenso para el modelo o el proveedor la rechaza—, esa memoria se sigue almacenando y las demás del mismo lote no se ven afectadas. Lo que le falta a la memoria almacenada es un vector. En la práctica:

• Todavía se encuentra mediante la búsqueda text y mediante hybrid; el sistema híbrido combina ambas clasificaciones, por lo que la parte de texto aún lo muestra.

• No se encuentra mediante la búsqueda semantic, que solo compara vectores.

Esta es una buena razón para preferir hybrid como modo de recuperación predeterminado. Ya es la mejor opción para identificadores exactos y palabras poco comunes, y además significa que un recuerdo que no se pudo incrustar aún llega a usted.

Lo que esto significa para un agente:

• Una interrupción del servicio retrasa la extracción de información; no se pierden los turnos. La memoria a corto plazo se escribe de forma síncrona y no se ve afectada: siga solicitando stm cuando necesite lo que se acaba de decir.

• Los reintentos tienen un límite: si una interrupción de una dependencia dura más que ellos, se detiene el proceso de reintentos en lugar de entrar en un bucle indefinido, y el fallo se registra en lugar de descartarse.

• Ninguno de estos problemas se manifiesta como un error a través del SDK. Los fallos de extracción son responsabilidad del servidor; la señal visible para el SDK son los recuerdos extraídos que aún no aparecen en la recuperación, o que aparecen en la búsqueda de texto e híbrida, pero no en la semántica.

Cómo funciona la lectura

La prosa recopilada o los propios documentos: dos cuestiones distintas.

``build_context_from_sources(...)`` es la función que se debe usar por defecto. Se le proporciona una consulta y un presupuesto de tokens; recupera los datos de los tipos de memoria especificados, clasifica los resultados, elimina los duplicados cercanos, los ajusta al presupuesto y devuelve un resultado que se puede usar directamente en una solicitud. Todo el proceso de recuperación se realiza con una sola llamada, y requiere una especificación por fuente, por lo que los modos y filtros se configuran por fuente en lugar de una sola vez para todas.

La recuperación de información puede realizarse de tres maneras. semantic compara incrustaciones y encuentra elementos con el mismo significado; text compara palabras y encuentra elementos con la misma expresión; hybrid ejecuta ambos métodos y combina las clasificaciones. Generalmente, la opción híbrida es la más adecuada por defecto: la búsqueda vectorial por sí sola no detecta identificadores exactos ni palabras poco frecuentes, mientras que la búsqueda de texto por sí sola no detecta paráfrasis.

``build_context(...)`` es el constructor más simple: la misma canalización, pero un modo y un filtro se aplican a cada fuente que lee.

``search(...)`` y las búsquedas por tipo (search_semantic, search_episodes, etc.) devuelven registros clasificados en lugar de prosa ensamblada, para cuando quieras inspeccionarlos o procesarlos tú mismo.

¿Qué abarca un recuerdo?

Cada registro lleva la identidad con la que fue escrito, y cada lectura se filtra por esa identidad en la consulta de la base de datos, en lugar de posteriormente. Los campos son: organización, usuario, proyecto, sesión y, opcionalmente, el agente, además de un parámetro de visibilidad que determina si un registro es privado para su usuario o si puede ser leído por un público más amplio.

Esto es importante por una razón práctica: una búsqueda o build_context limitada a un usuario no revelará la memoria privada de otro usuario, ya que la restricción forma parte de la consulta y no es un filtro aplicado a sus resultados. Por lo tanto, bind(...) no es una conveniencia, sino la forma de declarar el ámbito dentro del cual operan las lecturas y escrituras posteriores, y si se hace incorrectamente, se escribe la memoria de un usuario bajo la identidad de otro.

user_id y visibility responden preguntas diferentes

user_id es de quién es la memoria un registro. visibility es hasta dónde llega:

Ningún valor de visibilidad se extiende fuera del proyecto en el que se escribió el registro. La memoria se almacena por proyecto, por lo que la visibilidad no puede traspasar los límites de un proyecto. org es un nombre histórico y significa "no restringido a un solo usuario", no "visible para otros proyectos".

Ambos son independientes y, al leerlos, se combinan como "y",nunca como "o". Cada campo que proporcione agrega una condición de igualdad más a la consulta; cada campo que omita deja esa dimensión sin restricciones:

La tercera fila es la que sorprende. search_semantic(query, user_id="user_1", visibility="org") no significa “los recuerdos del usuario_1 más los de la organización”. Significa “los recuerdos visibles para la organización que posee el usuario_1”, que es menor que cualquiera de las restricciones por separado. No hay unión: para leer el conocimiento compartido y la memoria privada de un usuario, realice dos llamadas y combine los resultados usted mismo.

La plataforma alojada

El servicio gestionado. Proporcione un token de acceso a la cuenta de servicio y el ID de su proyecto.

Genera el token con la CLI agentengine. Crea una cuenta de servicio una sola vez; el secreto del cliente se muestra solo una vez, así que guárdalo inmediatamente:

agentengine service-account create my-agent --project-id <your-project-id> --role AGENT_DEVELOPER

Luego, intercambie el ID de cliente y el secreto por un token de acceso de corta duración (1 horas) (curl solicita el secreto del cliente para que no quede registrado en el historial de la shell):

ACCESS_TOKEN=$(curl --fail-with-body --silent --show-error      --user <client-id>      --data grant_type=client_credentials      https://agentengine.mongodb.com/api/v1/oauth/token | jq -er .access_token)

memory = Memory(service_account_token="<your-access-token>", project_id="<your-project-id>")

La plataforma vincula tus credenciales a su proyecto, por lo que un project_id que no coincida será rechazado. Un service_account_token en blanco generará un ValueError.

api_key (y AGENTIC_MEMORY_API_KEY) siguen siendo aceptados como un alias obsoleto y emiten un DeprecationWarning; pasar tanto la entrada nueva como la antigua genera ValueError. Las claves de API del proyecto ya no se pueden generar a través de HTTP, por lo que las nuevas integraciones deben usar un token de cuenta de servicio.

Desarrollo local

Señala un backend que ejecutes tú mismo, como por ejemplo el stack agentengine dev up que se inicia.

memory = Memory(base_url="http://localhost:8080")

Deje project_id vacío para el desarrollo local.

Dentro de un agente de plataforma (vinculado a la aplicación)

Cuando su agente se ejecuta en Atlas Agent Engine, no necesita construir ni conectar Memory en absoluto; la plataforma inyecta una instancia lista y preconfigurada, con la identidad, el tenencia y el transporte ya vinculados. El código de la aplicación no pasa ninguna de las entradas anteriores; utiliza el identificador que le proporciona el entorno de ejecución. La identidad (usuario, sesión, organización, proyecto) se resuelve a partir del contexto de ejecución ambiental, por lo que las operaciones se pueden llamar directamente:

# `memory` is supplied by the platform runtime — do not construct it.
memory.record_turn(role="user", content="I'm allergic to penicillin.")
context = memory.build_context(query="What medications should I avoid?")
# bind(...) is still available to scope a call chain to a specific identity.

La ruta vinculada a la aplicación tiene algunas brechas de capacidad (llamada a herramienta / metadatos de cambio de modelo y algunas lecturas de estilo de lista); consulte la columna Vinculada a la aplicación en Qué admite cada conexión y `docs/capability-matrix.md `__.

Las variables de entorno son una alternativa.

Cada entrada también recurre a una variable de entorno AGENTIC_MEMORY_* cuando se omite el argumento. Un argumento explícito siempre tiene prioridad. Memory() sin argumentos lee los tres del entorno.

Cómo funciona el enrutamiento

project_id decide a dónde van las llamadas. La autenticación nunca lo hace.

• Establece project_id y el SDK llamará a las rutas de tu proyecto, /api/v1/projects/{project_id}/memory/*.

• Déjelo vacío y el SDK llamará directamente al backend, /api/v1/memory/*.

Si project_id está configurado pero el backend no tiene una ruta coincidente, como un backend local, la llamada genera `MemoryRouteNotFoundError <#errors>`__ con una sugerencia para desconfigurarlo. Lo contrario también es cierto. Diríjase al servicio alojado sin project_id y la llamada 404s con una sugerencia para configurarlo.

Avanzado: backend directo autenticado

La autenticación y el enrutamiento son independientes, por lo que puedes pasar un service_account_token con project_id vacío. El SDK envía entonces las llamadas autenticadas directamente al backend en base_url, a través de las rutas directas, omitiendo la ruta del proyecto. Esto resulta ideal para un motor de orquestación (OE) alojado al que se accede directamente.

Lo que respalda cada conexión

Las capacidades dependen del enrutamiento de la llamada, no de la autenticación.

Una llamada no compatible genera `MemoryNotSupportedError <#errors>`__ — antes de cualquier solicitud de red para brechas conocidas por backend, o después de la respuesta para brechas de capacidad que solo la plataforma puede informar (ver Errores) — nunca un fallo silencioso o un error HTTP sin procesar. La referencia completa por backend, incluidas las brechas limitadas a la aplicación en CRUD específicos del tipo, se encuentra en `docs/capability-matrix.md `__.

Los agentes vinculados a la aplicación son la excepción a todo lo anterior. Dentro de un agente de plataforma implementado, la plataforma inyecta un runtime listo, por lo que el código de la aplicación no pasa ninguna de estas entradas.

Configuración que no podrás cambiar más adelante.

Algunas partes de la configuración son prácticamente de escritura única, así que decídalas antes de empezar a escribir en la memoria:

• Claves de partición de metadatos: los atributos filtrables declarados. Una vez declarada, no se puede eliminar una clave ni cambiar su tipo.

• Declaraciones de tipos de memoria personalizados: una vez que se acepta un tipo, su colección y conjunto de etiquetas no se pueden editar ni eliminar a través de la API de configuración; en su lugar, declare un nuevo nombre de tipo.

• Losíndices de búsqueda se aprovisionan solo si no existen previamente. Agregar una clave de partición después de que el servidor se haya iniciado no reconstruye el índice existente; se registra la discrepancia y, en lugar de ignorarse silenciosamente, se produce un error al aplicar un filtro a la nueva clave en la base de datos. Recrear el índice es una operación manual.

El nivel de registro, el modelo de lógica descriptiva (LLM) de extracción y los tipos de extracción habilitados pueden modificarse y reaplicarse. Cambiar el modelo de incrustación o la dimensión requiere migrar y volver a incrustar las memorias existentes; los cambios de dimensión también requieren reconstruir los índices de búsqueda vectorial.

Establecer la visibilidad en una escritura

Cada escritura requiere un visibility. El valor predeterminado difiere según el tipo de memoria, ya que los tipos se utilizan de manera diferente:

La memoria taxonómica se establece por defecto en org porque el vocabulario de un dominio se comparte por definición; un término y su significado rara vez son información privada de un solo usuario. Todo lo demás se establece por defecto en private, por lo que un dato que guardes estará restringido al usuario del que se aprendió, a menos que indiques lo contrario.

record_turn es la excepción: no toma ni visibility ni user_id. Un turno de conversación siempre se escribe bajo el usuario y la sesión vinculados, por lo que bind(...) antes de grabar los turnos; no hay una forma por llamada de establecer el usuario en un turno.

# Private to user_1 — the default.
session.save_semantic(text="Prefers window seats.", label="seat-preference")
# Readable across the whole organization.
session.save_semantic(
    text="Refunds over $500 need manager approval.",
    label="refund-policy",
    visibility="org",
)

Analizando una lectura

Las lecturas dejan visibility sin definir, por lo que solo están limitadas por la identidad que se resuelve, normalmente la vinculada user_id. Ese es el valor predeterminado adecuado para la personalización: se obtiene todo lo que posee el usuario, con cualquier nivel de visibilidad.

Para alcanzar el conocimiento compartido se pasa una visibilidad, y aquí entra en juego la regla. Un identificador vinculado a user_id="user_1" sigue contribuyendo a que user_id, por lo que esto solo lee los registros visibles para la organización que posee el usuario_1:

session = memory.bind(MemoryRequestContext(user_id="user_1", session_id="thread_123"))
session.search_semantic("refund policy", visibility="org")   # user_1 AND org

Pasar user_id=None no lo amplía. Un None o un argumento en blanco se considera "no proporcionado" en cada nivel, por lo que se aplica el valor vinculado. Leer todos los usuarios con un identificador que no tenga un límite user_id:

# The original handle is unbound, so it carries no user_id.
memory.search_semantic("refund policy", visibility="org")
# Or bind only the parts you want.
thread = memory.bind(MemoryRequestContext(session_id="thread_123"))
thread.search_semantic("refund policy", visibility="org")

Así, un asistente que necesita tanto el historial del usuario como el conocimiento compartido del equipo realiza dos lecturas y las combina:

personal = session.search_semantic(query, top_k=5)                       # user_1, any visibility
shared = memory.search_semantic(query, visibility="org", top_k=5)        # org-wide, any owner

Leyendo tus propios metadatos

record_turn toma un diccionario opcional metadata, y la recuperación a corto plazo lo devuelve en su propio espacio en el fragmento: chunk.metadata["metadata"]. Tus claves se mantienen separadas de los campos de turno de la plataforma (session_id, role, turn_seq, …) en lugar de mezclarse con ellos, por lo que una clave tuya nunca entra en conflicto con una de las suyas; puedes nombrar una clave role o session_id y leer tu propio valor.

Dos limitaciones que la seguridad contra colisiones no cubre. Los valores deben sobrevivir al viaje de ida y vuelta, por lo que deben ser serializables en JSON y tener un tamaño razonable. Además, para que una clave sea filtrable, debe poder declararse como una clave de partición de metadatos: cada segmento separado por puntos debe coincidir con ^[a-z][a-z0-9_]{0,63}$, se permite como máximo un punto y se reservan algunos nombres (org_id, project_id, user_id, agent_id, content, embedding, embedding_model_id, created_at). Una clave que no cumpla con este formato —Tier, $foo, a.b.c— se almacena y se devuelve, pero no se puede filtrar.

Un diccionario vacío se trata como si no hubiera metadatos: metadata={} registra el turno sin una ranura metadata en el fragmento, así que léalo con chunk.metadata.get("metadata", {}) si el llamador no hubiera proporcionado ninguna. La memoria semántica se comporta de forma idéntica, lo que permite que una ruta de lectura cubra ambas. Episódico, taxonómico y procedimental se comportan de la misma manera: el diccionario que escribes se devuelve bajo chunk.metadata["metadata"], y uno vacío significa que no hay ninguna ranura. Episódico es la única excepción: un filtro de compatibilidad descarta todo el diccionario, incluidas las claves no relacionadas, si resulta que contiene citation_score, llm_confidence_score y combined_score juntos, ya que esa forma también coincide con un blob interno previo a la migración. La recuperación también puede llevar chunk.metadata["contextual_metadata"]; ese es el artefacto de extracción de la propia plataforma, no tus datos, y no forma parte de ningún contrato del que debas depender.

La memoria a corto plazo está limitada a una sesión, por lo que la escritura y la lectura deben nombrar la misma: vincularla una sola vez y pasarla:

from agent_engine_sdk_memory import (
    Memory,
    MemoryRequestContext,
    MemorySource,
    RetrievalMode,
    SourceSpec,
)
session_id = "session-42"
memory = Memory(base_url="http://localhost:8080").bind(
    MemoryRequestContext(user_id="user-1", session_id=session_id)
)
memory.record_turn(
    role="user",
    content="The engagement is green and the rollout continues.",
    metadata={"engagement_id": "eng-alpha", "tier": 2},
)
context = memory.build_context_from_sources(
    query="what is the engagement status?",
    sources=[
        SourceSpec(
            source=MemorySource.STM,
            mode=RetrievalMode.HYBRID,
            metadata_filter={"metadata.engagement_id": "eng-alpha"},
        )
    ],
    session_id=session_id,
    include_memories=True,
)
for chunk in context.selected_memories or []:
    print(chunk.metadata["metadata"]["engagement_id"])

Atlas Search indexa la escritura de forma asíncrona, por lo que una lectura realizada inmediatamente después puede que aún no vea el turno.

Una diferencia ortográfica que conviene tener en cuenta: se lee el nombre sin formato dentro del diccionario anidado, chunk.metadata["metadata"]["engagement_id"], pero se filtra por la ruta del índice cualificado, {"metadata.engagement_id": ...}. Ambos reconocen el anidamiento: el filtro se dirige al documento almacenado, donde el diccionario reside realmente bajo metadata.

El filtrado por nombre simple se rechaza con un error que enumera las rutas aceptadas, por lo que ese error le da la respuesta.

Primero se deben declarar los metadatos filtrables para el proyecto: engagement_id debe aparecer debajo de metadata_partition_key, y short_term debe figurar en metadata_partition_index. Consulte la sección "Declaración de metadatos filtrables" en "Uso".

Diseño del paquete

agent_engine_sdk_memory/
├── memory.py        # Memory — the public, transport-free facade
├── protocol.py      # MemoryRequestContext, MemoryRuntime + MemoryCrudClient seams
├── identity.py      # resolve_identity — call arg > bind ctx > runtime ctx
├── errors.py        # MemoryIdentityError + the typed transport-error family
├── models.py        # Pydantic models for memory requests/responses
├── validation.py    # require_positive_max_tokens — public build_context guard
├── _transport.py    # _HttpTransport — shared retry / error-mapping / lifecycle
├── _http_runtime.py # _HttpMemoryRuntime — the workflow ops + per-backend profiles
├── _direct_crud.py  # empty-tenancy MemoryCrudClient over the shared transport
├── _wire.py         # custom-type request-body builders shared by the CRUD clients
├── _tag_syntax.py   # client-side custom-type name + tag-syntax checks
├── _client.py       # MemoryClient — internal HTTP client for the Memory Server API
└── _denylist.py     # do-not-add dependency denylist (see below)

Memory es libre de transporte: delega las operaciones del flujo de trabajo (record_turn, build_context, las búsquedas, discover_procedures) a un MemoryRuntime inyectado, y el CRUD específico del tipo a un MemoryCrudClient inyectado. La superficie pública se congela mediante una prueba de instantánea en tests/test_package_contract.py; MemoryClient permanece interna. La tenencia por llamada (org_id, project_id a nivel de cuerpo nunca aparece en una firma pública; el único project_id en la superficie pública es el selector de forma de ruta del constructor opcional, que va en la URL, no en un cuerpo de solicitud.

Lista de denegación de dependencias

La restricción pydantic + httpx solamente se aplica, no es una aspiración. _denylist.py enumera las distribuciones conocidas de gran tamaño y los nombres de importación (langchain, fastapi, pymongo, …), y tests/test_package_contract.py falla si la importación del paquete incluye alguno de ellos en sys.modules.

¿Quién lo usa?

agent-engine-runner-shared Declara este paquete como una dependencia del espacio de trabajo y construye el MemoryClient interno en agent_engine_runner_shared/memory.py, pasando su búsqueda de contexto de ejecución como una función invocable execution_id_provider para que los encabezados de ID de ejecución por solicitud funcionen sin que este paquete importe ningún código de plataforma.