/ /

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

Atlas Agent Engine(TypeScript)을 위한 통합 메모리 파사드. Python agent-engine-sdk-memory 패키지 의 대응 제품: TypeScript 에이전트는 동일한 경로를 통해 메모리 서버에서 읽고 쓰기 (write) . 메모리는 턴과 세션 간에 유지됩니다.

설치

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

`Memory` 파사드

Memory 전송에 구애받지 않는 하나의 표면 뒤에 모든 메모리 유형을 노출합니다.

유형	쓰기	읽기
대화 회전(STM)	`recordTurn`	(피드 `buildContext`)
시맨틱(팩트)	`saveSemantic`	`searchSemantic`, `getSemantic`
간헐적(대화)	`saveEpisode`	`searchEpisodes`, `listEpisodes`
분류학적(지식 기반)	`saveTaxonomic`	`searchTaxonomic`, `getTaxonomicTerm`, `listDomains`
절차적(방법)	`saveProcedure`	`discoverProcedures`, `getProcedure`
사용자 지정 유형( 프로젝트 별로 선언됨)	`save`	`retrieve`
통합	—	`buildContext`, `search`

모든 메서드는 비동기 입니다. ID(userId / sessionId)는 인수, 바인딩된 컨텍스트, 런타임의 앰비언트 컨텍스트 순으로 호출별로 확인됩니다. 사용자 지정 유형 작업은 예외입니다. 즉, 요청 에서 플랫폼 스탬프 조직, 프로젝트 및 사용자와 같은 ID 필드가 없으므로 클라이언트 사이드 ID를 확인하지 않으며 이를 스탬프할 수 있는 백엔드 (project- 범위가 지정된 게이트웨이 경로 또는 실행 범위 런타임).

두 가지 모드

파사드는 둘 다 동일합니다. URL, 인증 및 ID가 제공되는 방식만 다릅니다.

HTTP-direct (독립형 /오프플랫폼)

플랫폼 외부에서 실행 스크립트, 테스트 및 코드를 위한 독립형 클라이언트 입니다. 생성자 인수 또는 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	목적
`AGENTIC_MEMORY_SERVICE_ACCOUNT_TOKEN`	서비스 계정 액세스 토큰( 설정하다 경우 호스팅된 게이트웨이 URL 로 대체됨). `AGENTIC_MEMORY_API_KEY`은(는) 더 이상 사용되지 않는 별칭으로, 여전히 작동하고 `DeprecationWarning`을 출력하고 새 변수와 충돌합니다(두 오류 모두 설정). Python SDK README에 표시된 `agentengine service-account create`와 OAuth 토큰 교환을 사용하여 토큰을 발행하세요.
`AGENTIC_MEMORY_BASE_URL`	백엔드 주소.
`AGENTIC_MEMORY_PROJECT_ID`	설정 => 프로젝트 범위 게이트웨이 경로. 비어 있음 => 플랫 OE 루트.

앱 바운드(배포된 에이전트 내부)

에이전트 코드가 app.memory(@mongodb-js/agent-engine-sdk-langgraph에서)을(를) 사용합니다. ID는 앰비언트 요청 컨텍스트에서 가져오고 호출은 오케스트레이션 엔진의 메모리 프록시를 통해 라우팅되며, 관리 할 토큰이나 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?" });

앱 바인딩된 메모리는 플랫폼 요청 처리하는 동안에만 연결할 수 있습니다(실행 컨텍스트의 OE_URL 필요).

컨텍스트 토큰 예산

buildContext({ maxTokens }) 선택 사항인 총 컨텍스트 구성 예산을 설정합니다( 가져오기 비용 아님). 검색 및 순위 지정 후 서버 500-토큰 서식 지정 예비비를 뺀 다음 나머지에 맞는 전체 메모리 청크를 탐욕적으로 선택합니다. 500 이하의 양수 값은 메모리를 위한 예산을 남기지 않습니다. 500를 초과하는 값은 청크 맞지 않을 때 빈 컨텍스트를 생성할 수 있습니다. metadata.token_count는 형식이 지정된 출력만 보고하고 예비는 제외합니다. 서버 기본값 유지하려면 maxTokens를 생략합니다.

오류

유형 오류는 호출자가 실패 모드 에서 분기할 수 있습니다: MemoryAuthError (401/403), MemoryRouteNotFoundError (라우트 모양 힌트가 있는 404), MemoryBadRequestError, MemoryServerError (5xx / 불량 본문), MemoryConnectionError, MemoryNotSupportedError(역량 격차), MemoryIdentityError(필수 ID 필드 확인할 수 없음). MemoryNotSupportedError은 클라이언트 사이드 격차를 모두 커버하며, 사용자 지정 유형 경로에서는 플랫폼만이 보고할 수 있는 역량 격차: 베어 404/405 (플랫폼이 너무 오래되어 경로를 제공 할 수 없음) 또는 게이트웨이의 구조화된 400 배포서버 시 비활성화된 사용자 지정 메모리 유형을 보고 . 구조화된 알 수 없는 유형의 404가 MemoryBadRequestError을 발생시킵니다. 전송은 502/503/504를 최대 3회 재시도합니다.

개발

npm install
npm test      # vitest
npm run build # tsc

돌아가기

API 참조