Atlas 에이전트 엔진(Typescript)을 위한 통합 메모리 파사드입니다. Python agent-engine-sdk-memory 패키지의 대응물: Typescript 에이전트는 동일한 경로를 통해 Memory Server에서 읽고 쓰기 (write)를 수행하며, 턴과 세션 전반에 걸쳐 지속되는 메모리를 사용합니다.
설치
npm install @mongodb-js/agent-engine-sdk-memoryThe Memory facade
Memory 트랜스포트 에 구에 받지 않는 단일 표면을 통해 모든 메모리 유형을 노출합니다.
유형 | 쓰기 | 읽기 |
|---|---|---|
대화 턴(STM) |
| (피드 |
의미론적(사실) |
|
|
에피소드형(대화) |
|
|
분류학적(지식 기반) |
|
|
절차(방법) |
|
|
사용자 지정 유형(프로젝트별로 선언됨) |
|
|
통합 | — |
|
모든 메서드는 비동기 입니다. 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 | 목적 |
|---|---|
| 서비스 계정 액세스 토큰(설정된 경우 호스팅된 Gateway URL로 대체됨). |
| 백엔드 주소입니다. |
| 설정된 경우 => 프로젝트 범위의 게이트웨이 경로; 비어 있는 경우 => 플랫 OE 경로. |
앱 바운드(배포된 에이전트 내부)
에이전트 코드가 app.memory(@mongodb-js/agent-engine-sdk-langgraph에서)을(를) 사용합니다. ID는 앰비언트 요청 컨텍스트에서 가져오고 호출은 오케스트레이션 엔진의 메모리 프록시를 통해 라우팅되며, 관리 할 토큰이나 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?" });앱 바인딩된 메모리는 플랫폼 요청 처리하는 동안에만 연결할 수 있습니다(실행 컨텍스트의 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 installnpm test # vitestnpm run build # tsc