/ /

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

Atlas Agent Engine（TypeScript）の統合メモリファジー。 Pythonagent-engine-sdk-memory パッケージのカウンター部分: タイプエージェントは、から読み取り、メモリサーバーに書込み (write) するだけで同じルートを使用し、タームやセッションにまたが保存されるメモリを使用します。

インストール

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

`Memory`ファサード

Memory は、1 つのトランスポートに依存しないサーバーの背後ですべてのメモリ型を公開します。

タイプ	書込み	読み取り
変換変換（SSTM）	`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_* env 変数を使用して構成します。

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`	=====================================================================プロジェクトスコープの Gateway ルート空の =========================================================平面 OA ルート。

アプリバウンド（配置されたエージェント内）

エージェントコードは 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を省略します。

Errors

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

開発

npm install
npm test      # vitest
npm run build # tsc

戻る

API リファレンス