Interfaz de memoria unificada para Atlas Agent Engine (TypeScript). Equivalente al paquete agent-engine-sdk-memory de Python: los agentes TypeScript leen y escriben en el servidor de memoria a través de las mismas rutas, con memoria que persiste entre turnos y sesiones.
Instalar
npm install @mongodb-js/agent-engine-sdk-memory
La fachada Memory
Memory expone todos los tipos de memoria detrás de una interfaz independiente del medio de transporte:
Tipo | Guardar | Lea |
|---|---|---|
La conversación gira (STM) |
| (fuentes |
Semántico (hechos) |
|
|
Episódico (conversaciones) |
|
|
Taxonómico (base de conocimientos) |
|
|
Procedimientos (instrucciones) |
|
|
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 modos
La interfaz es la misma en ambos casos; solo difiere la forma en que se proporcionan la URL, la autenticación y la identidad.
HTTP-directo (autónomo/fuera de la plataforma)
Un cliente autónomo para scripts, pruebas y código que se ejecutan fuera de la plataforma. Se configura mediante argumentos del constructor o variables de entorno AGENTIC_MEMORY_*.
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 a la cuenta de servicio (si se establece, se utiliza la URL de la puerta de enlace alojada). |
| Dirección del servidor. |
| Establecer => Rutas Gateway con ámbito de proyecto; vacío => Rutas OE planas. |
Vinculado a la aplicación (dentro de un agente desplegado)
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 entrypoint await 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 la plataforma (necesita el OE_URL del contexto de ejecución).
Presupuesto de tokens de contexto
buildContext({ maxTokens }) Establece un presupuesto opcional para la construcción del contexto (no un costo de obtención). Tras la recuperación y la clasificación, el servidor resta una reserva de formato de token 500 y, a continuación, selecciona de forma voraz bloques de memoria completos que se ajusten al resto. Los valores positivos iguales o inferiores a 500 no dejan presupuesto para memorias. Los valores superiores a 500 aún pueden generar un contexto vacío cuando ningún bloque se ajusta. metadata.token_count informa únicamente de la salida formateada y excluye la reserva. Omita maxTokens para mantener la configuración predeterminada 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 informa que los tipos de memoria personalizados están deshabilitados en la implementación. Un 404 estructurado de tipo desconocido genera MemoryBadRequestError. Reintentos de transporte 502/503/504 hasta tres veces.
Desarrollo
npm install npm test # vitest npm run build # tsc