/ /

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

Fachada de memória unificada para Atlas Agent Engine (TypeScript). A contraparte do pacote Python agent-engine-sdk-memory : os agentes TypeScript leem e gravam no servidor de memória por meio das mesmas rotas, com memória que persiste após ativações e sessões.

Instalar

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

A face `Memory`

Memory expõe cada tipo de memória atrás de uma superfície independente de transporte:

Tipo	Escrever	Leia
Viramentos de conversa (STM)	`recordTurn`	(feeds `buildContext`)
Semântica (fatos)	`saveSemantic`	`searchSemantic`, `getSemantic`
Capilar (conversas)	`saveEpisode`	`searchEpisodes`, `listEpisodes`
Tributário (base de conhecimento)	`saveTaxonomic`	`searchTaxonomic`, `getTaxonomicTerm` , `listDomains`
Processual (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 face é igual em ambos; apenas como o URL, a autenticação e a identidade são fornecidos difere.

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

Um cliente independente para scripts, testes e código executado fora da plataforma. Configure via construtor args ou AGENTIC_MEMORY_* env vars.

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 à conta de serviço (retorna ao 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 (definindo ambas as lanças). Crie um token com `agentengine service-account create` mais a troca de token OAuth mostrada no README do SDK do Python.
`AGENTIC_MEMORY_BASE_URL`	Endereço de backend.
`AGENTIC_MEMORY_PROJECT_ID`	Set => rotas de gateway no escopo do projeto; empty => rotas OE planas.

Vinculado à aplicação (dentro de um agente implementado)

O código do agente usa app.memory (de @mongodb-js/agent-engine-sdk-langgraph). A identidade vem do contexto da solicitação do ambiente e as chamadas são roteadas pelo proxy de memória do mecanismo de orquestração - sem tokens para gerenciar, sem threading 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?" });

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

Orçamentação de token de contexto

buildContext({ maxTokens }) define um orçamento bruto opcional para a construção de contexto (não um custo de busca). Após a recuperação e a classificação, o servidor subtrai uma reserva de formatação de 500-token e, em seguida, seleciona avidamente chunks de memória inteiros que cabem no restante. Valores positivos iguais ou inferiores a 500 não deixam orçamento para recordações. Valores acima de 500 ainda podem gerar um contexto vazio quando nenhum chunk se encaixa. metadata.token_count reporta somente a saída formatada 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 install
npm test      # vitest
npm run build # tsc

Voltar

Referência da API