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

Atlas エージェントエンジン (Typescript) 用の統合 Memory ファサード。Python agent-engine-sdk-memory パッケージの対応物です。Typescript エージェントは、ターンやセッション間で永続化されるメモリを使用して、同じルートを通じて Memory サーバーから読み取り、書き込み (write) を行います。

インストール

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

The `Memory` facade

Memory 1つのトランスポートアグノスティックなサーフェースを介して、すべてのメモリタイプを公開します。

タイプ	書込み	読み取り
会話ターン (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 を解決せず、それをスタンプできるバックエンド（プロジェクトスコープ指定された Gateway ルート、または実行スコープ指定されたランタイム）。

2つのモード

どちらもファサードは同じですが、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`	サービスアカウントのアクセストークン（設定されている場合は、ホストするGateway URLにフォールバックします）。`AGENTIC_MEMORY_API_KEY` は非推奨のエイリアスです。引き続き機能しますが、`DeprecationWarning` を出力し、新しい変数と競合します（両方を設定するとスローされます）。`agentengine service-account create` と Python SDK README に示されている OAuth トークン交換を使用してトークンを作成します。
`AGENTIC_MEMORY_BASE_URL`	バックエンドアドレス。
`AGENTIC_MEMORY_PROJECT_ID`	設定されている場合は、プロジェクト範囲のゲートウェイルートが使用されます。空の場合は、フラット 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を省略します。

Errors

型指定されたエラーにより、呼び出し元は障害モードでブランチします。MemoryAuthError（401/403）、MemoryRouteNotFoundError（ルートシェイプヒント付きの 404）、MemoryBadRequestError、MemoryServerError（5x /ハードボディ）、MemoryConnectionError、MemoryNotSupportedError（機能ギャップ）、MemoryIdentityError（必須 IDフィールドを解決できませんでした）。 MemoryNotSupportedError はクライアント側のギャップと、カスタムタイプのルートでは、プラットフォームのみが報告できる機能のギャップをカバーします。最低の 404/405（プラットフォームが古くてルートを提供できない）またはゲートウェイの構造化された 400配置で無効になっているカスタムメモリタイプを報告する }。構造化不明タイプ 404 は MemoryBadRequestError を発生させます。トランスポートの再試行: 502/503/504 は最大 3 回。

開発

npm installnpm test      # vitestnpm run build # tsc

戻る

参考文献

API リファレンス