@mongodb-js/agent-engine-sdk-memory

Fachada de memória unificada para o mecanismo de agente do Atlas (Typescript). A contraparte do pacote agent-engine-sdk-memory do Python: os agentes do Typescript leem e gravam no servidor de memória por meio das mesmas rotas, com memória que persiste entre turnos e sessões.

Instalar

npm install @mongodb-js/agent-engine-sdk-memory

The `Memory` facade

Memory expõe todos os tipos de memória por trás de uma única superfície agnóstica de transporte:

Tipo	Escrever	Leia
Turnos de conversa (STM)	`recordTurn`	(feeds `buildContext`)
Semântico (fatos)	`saveSemantic`	`searchSemantic`, `getSemantic`
Episódica (conversas)	`saveEpisode`	`searchEpisodes`, `listEpisodes`
Taxonômica (Base de Conhecimento)	`saveTaxonomic`	`searchTaxonomic`, `getTaxonomicTerm` , `listDomains`
Procedural (como fazer)	`saveProcedure`	`discoverProcedures`, `getProcedure`
Tipos personalizados (declarados por projeto)	`save`	`retrieve`
Unificado	—	`buildContext`, `search`

Todos os métodos são assíncronos. A identidade (userId / sessionId) é resolvida por chamada — do argumento, depois de um contexto vinculado e, em seguida, do contexto ambiente do tempo de execução. As operações de tipo personalizado são a exceção: elas não carregam campos de identidade — a plataforma carimbos org, projeto e user da solicitação — então não resolvem a identidade do lado do cliente e exigem um backend que possa carimbos (project- rotas de gateway com escopo definido ou um tempo de execução com escopo de execução).

Dois modos

A fachada é a mesma em ambos; apenas a forma como a URL, a autenticação e a identidade são fornecidas é diferente.

HTTP-direct (autônomo / fora da plataforma)

Um cliente independente para script, testes e código executado fora da plataforma. Configure por meio de argumentos de construtor ou variáveis de ambiente 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
`AGENTIC_MEMORY_SERVICE_ACCOUNT_TOKEN`	Token de acesso da conta de serviço (recorre à URL do Gateway hospedado quando definido). `AGENTIC_MEMORY_API_KEY` é um alias obsoleto: ele ainda funciona, imprime um `DeprecationWarning` e entra em conflito com a nova variável (definir ambos gera um erro). Crie um token com `agentengine service-account create` mais a troca de token OAuth mostrada no README do SDK Python.
`AGENTIC_MEMORY_BASE_URL`	Endereço de backend.
`AGENTIC_MEMORY_PROJECT_ID`	Definido => rotas de Gateway com escopo de projeto; vazio => rotas de OE planas.

Vinculado ao aplicativo (dentro de um agente implantado)

O código do agente usa app.memory (de @mongodb-js/agent-engine-sdk-langgraph). A identidade vem do contexto da solicitação ambiente e das chamadas roteadas por meio do proxy de memória do mecanismo de orquestração — sem tokens para gerenciar, sem userId threading:

// 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?" });

A memória vinculada ao aplicativo pode ser acessada somente durante o tratamento de uma solicitação de plataforma (ela precisa do OE_URL do contexto de execução).

Limite de tokens de contexto

buildContext({ maxTokens }) define um orçamento opcional de construção de contexto bruto (não um custo de busca). Após a recuperação e classificação, o servidor subtrai uma reserva de formatação de 500tokens e, em seguida, seleciona de forma gananciosa partes de memória inteiras que cabem no restante. Valores positivos iguais ou inferiores a 500 não deixam orçamento para memórias. Valores acima de 500 ainda podem gerar um contexto vazio quando nenhuma parte se encaixa. metadata.token_count relata apenas a saída em formato e exclui a reserva. Omita maxTokens para manter o padrão do servidor.

Errors

Typed errors let callers branch on failure mode: MemoryAuthError (401/403), MemoryRouteNotFoundError (404 with a route-shape hint), MemoryBadRequestError, MemoryServerError (5xx / bad body), MemoryConnectionError, MemoryNotSupportedError (capability gap), and MemoryIdentityError (a required identity field could not be resolved). MemoryNotSupportedError covers both client-side gaps and, on the custom-type routes, capability gaps only the platform can report: a bare 404/405 (platform too old to serve the route) or the gateway's structured 400 reporting custom memory types disabled on the deployment. A structured unknown-type 404 raises MemoryBadRequestError. Transport retries 502/503/504 up to three times.

Desenvolvimento

npm installnpm test      # vitestnpm run build # tsc

Voltar

Referências

Referência da API