Fachada unificada de memoria para el motor de agente de Atlas (Typescript). La contraparte del paquete Python agent-engine-sdk-memory: los agentes Typescript leen y guardan en el servidor de memoria a través de las mismas rutas, con memoria que persiste a través de turnos y sesiones.
Instalar
npm install @mongodb-js/agent-engine-sdk-memoryLa fachada Memory
Memory expone todos los tipos de memoria a través de una única superficie independiente del transporte:
Tipo | Guardar | Lea |
|---|---|---|
Turnos de conversación (STM) |
| (fuentes |
Semántica (hechos) |
|
|
Episódico (conversaciones) |
|
|
Taxonómico (Base de Conocimiento) |
|
|
Procedimental (guías prácticas) |
|
|
Tipos personalizados (declarados por proyecto) |
|
|
Unificado | — |
|
Todos los métodos son asíncronos. La identidad (userId / sessionId) se resuelve en cada llamada: a partir del argumento, luego de un contexto vinculado y, finalmente, del contexto ambiental del entorno de ejecución. Las operaciones de tipo personalizado son la excepción: no contienen campos de identidad (la plataforma asigna la organización, el proyecto y el usuario a partir de la solicitud), por lo que no resuelven la identidad del lado del cliente y requieren un backend que pueda asignarla (rutas de Gateway con ámbito de proyecto o un entorno de ejecución con ámbito de ejecución).
Dos modas
La fachada es la misma en ambos; solo difiere la forma en que se proporcionan la URL, la autenticación y la identidad.
HTTP-direct (autónomo / fuera de la plataforma)
Un cliente autocontenido para script, pruebas y código que se ejecuta fuera de la plataforma. Configurar mediante argumentos del constructor o AGENTIC_MEMORY_* variables de entorno.
import { Memory } from "@mongodb-js/agent-engine-sdk-memory";
const memory = new Memory({ serviceAccountToken: process.env.AGENTIC_MEMORY_SERVICE_ACCOUNT_TOKEN, // service-account access token projectId: "my-project", // set => project-scoped Gateway routes}); // unset => flat OE routes
await memory.saveSemantic({ text: "favorite color is teal", label: "favorite_color", userId: "u1", metadata: { channel: "web", priority: "high" }, // optional caller-supplied metadata});const hits = await memory.searchSemantic({ query: "color", userId: "u1" });await memory.close();Env var | Propósito |
|---|---|
| Token de acceso de la cuenta de servicio (recurre a la URL de puerta de enlace host cuando se establece). |
| Dirección del backend. |
| Establecido: rutas de puerta de enlace del ámbito del proyecto; vacío: rutas OE planas. |
Vinculado a la aplicación (dentro de un agente implementado)
El código del agente utiliza app.memory (de @mongodb-js/agent-engine-sdk-langgraph). La identidad proviene del contexto de la solicitud ambiental y las llamadas se enrutan a través del proxy de memoria del motor de orquestación; no hay tokens que administrar, ni subprocesos userId:
// inside a tool or entrypointawait app.memory.saveSemantic({ text: "prefers email over SMS", label: "contact_pref" });const context = await app.memory.buildContext({ query: "how does the user like to be contacted?" });La memoria vinculada a la aplicación solo es accesible mientras se maneja una solicitud de plataforma (necesita el OE_URL del contexto de ejecución).
Presupuesto de tokens de contexto
buildContext({ maxTokens }) fija un presupuesto bruto opcional de construcción de contexto (no es un costo de recuperación). Después de la recuperación y la clasificación, el servidor resta una reserva de formato de 500tokens y, a continuación, selecciona de forma voraz fragmentos de memoria completos que quepan en el resto. Los valores positivos en o por debajo de 500 no dejan presupuesto para recuerdos. Los valores superiores a 500 aún pueden generar un contexto vacío cuando ningún fragmento encaja. metadata.token_count informa solo de la salida con formato y excluye la reserva. Omitir maxTokens para mantener el valor por defecto del servidor.
Errors
Los errores tipados permiten a los llamadores ramificarse en el modo de fallo: MemoryAuthError (401/403), MemoryRouteNotFoundError (404 con una sugerencia de forma de ruta), MemoryBadRequestError, MemoryServerError (5xx / cuerpo incorrecto), MemoryConnectionError, MemoryNotSupportedError (brecha de capacidad) y MemoryIdentityError (no se pudo resolver un campo de identidad requerido). MemoryNotSupportedError cubre tanto las brechas del lado del cliente como, en las rutas de tipo personalizado, las brechas de capacidad que solo la plataforma puede informar: un 404/405 simple (la plataforma es demasiado antigua para servir la ruta) o el 400 estructurado de la puerta de enlace que informa tipos de memoria personalizados deshabilitados en la implementación. Un 404 estructurado de tipo desconocido genera MemoryBadRequestError. Reintentos de transporte 502/503/504 hasta tres veces.
Desarrollo
npm installnpm test # vitestnpm run build # tsc