Agent- engine-sdk-memory

解決される問題

メモリは、エージェントが LM を使用して行った対話から永続的な学習者向けに結果を抽出することで、重要な結果、対話、手順、語彙の永続的な保存をエージェントに提供し、それ自体を保存するものを入力します。抽出自体は、構成した LM によって行われます。

プラットフォームに配置されたエージェントの場合、これには接続はいずれも必要ありません。ランタイムは、エージェントワークフローが実行される際に短期間メモリにされる各設定を記録し、昇格と抽出がバックグラウンドで非同期に進行されるため、ファクターが抽出されている間は応答をブロックするものはありません。耐久性があるものをすでに認識しているエージェントは、それを見つけるために抽出を待つ必要はありません。save_semantic やその他のタイプの書込み (write) を使用して、係数を直接書込むことができます。

バックグラウンドでの読み取りはいずれの方法で行われます。エージェントは一度に 1 種類の結果を追跡できます。学習した内容は search_semantic、その前に発生したことは search_episodes、タームが意味する内容は search_taxonomic、どのように行われたかは discover_procedures になります結果自体。

あるいは、ジョブ全体を渡すこともできます。 build_context_from_sources はソースごとに 1 つの仕様を採用し、それぞれが独自の 取得モード、フィルター、候補数を宣言し、その後はすべてのソースから独自のタームですべてのソースから検索し、結果をランク付けして重複を除外し、それらをトークンバケットに削除します。次のプロンプトにドロップするコンテキストの単一ブロック。 build_context は、すべてのソースに対して 1 つのモードと 1 つのフィルターで同じを行います。それぞれが異なる必要がある場合、ソースごとの形式は に達します。

2 つのレイヤー

メモリは、ものが存在する時間とその作成方法によって分裂。

短縮メモリ（SPM）は、未加工の通信です。つまり、1 回の実行ごとに 1 回のレコードで、セッションにスコープが設定され、発生時に書込まれます。記載されたすべての内容を順番に書込み (write) して完了するのはコストがかかります。

長期記憶は、異なる質問に答えるため、4 つの形状に分割されます。

プロジェクトは、4 つの形状に収まらないドメイン レコードのカスタムタイプを宣言することもできます。

書込みがメモリになる方法

長期メモリを手動で書き込むことはありませんが、可能です。通常のパスは次のとおりです。

record_turn(...)          you write turns as the conversation happens
      │
      ▼   turns accumulate into a session
   snapshot                a contiguous run of turns, summarised
      │
      ▼   an LLM reads the snapshot and extracts what is durable
  semantic · episodic · procedural · taxonomic

抽出は非同期であり、バックグラウンドで実行されるため、record_turn は高速書込みを維持します。そのため、ある対話で学習された係数は、次のオンではなく、次のユーザで利用できます。

以降に設計に値する影響は、最近の状況は SPM を通じてすぐに表示され、抽出された知識は若干後で表示されます。先ほど選んだ内容が必要な場合は、 stmに質問してください。

抽出に失敗した場合

バックグラウンド抽出は埋め込みサービス、抽出 LM、およびデータベースに依存しており、これらのいずれかは失敗する可能性があります。書込み (write) は、以下のものから分離されています。返されたときに record_turn が成功し、下流で発生した状況にかかわらず、

バックグラウンドでは、失敗したステップは 1 つの質問によって分類されます。リクエストが変更されずに条件が変化するか？環境障害（ネットワークエラー、プロバイダーの停止、レート制限、ローテーション中のAPIキー）は、障害に合わせてバックオフで自動的に再試行されます。ネットワーク バックアップは 秒以内に再試行され、キーは人間によってローテーションされるため、より遅くなります。コンテンツによって決まります失敗は、再試行によって結果が変更されないため、再試行されません。これらは永久にループするのではなく、サーバー側に記録され、演算子が確認できるようにします。

これは、その外側のエッジだけでなく、抽出パス全体に適用されます。失敗するステップが、暗黙的に空の結果を生成することはなくなりました。再試行されるか、演算子がそのステップを実行できる場所で記録されます。

使用できない項目が 1 つある場合でも、残りは破棄されません。メモリを1つ埋め込むことができない場合でも（その内容がモデルに対して長すぎるか、プロバイダーが拒否した場合）、そのメモリは引き続き保存され、同じバッチする内の他のメモリには影響しません。保存されたメモリに欠落しているものはベクトルです。実際には、次のとおりです。

• ただし、text 検索では引き続き見つかり、hybrid では両方のランキングが組み合わされているため、テキスト側には引き続き表示されます。

• semanticベクトルのみを比較する 検索では見つかりません。

これは、デフォルトの取得モードとして hybrid を使用するのに十分な理由です。正確な識別子やまれに単語を指定した場合はすでにこの方法が最適であり、埋め込むことができなかったメモリも引き続きユーザーに到達することを意味します。

これはエージェントにとってどのような意味がありますか:

• プロバイダーが停止時と、抽出された知識が遅延します。オンになっている場合は、カウントはありません。 SPM は同期的に書き込まれ、影響を受けません。検索結果の内容が必要な場合は、常に stm を要求し、

• 再試行には制限があります。依存停止時が停止してから、無期限にループ処理するのではなく再試行が停止し、失敗は破棄されるのではなく記録されます。

• これはいずれ SDK を介してエラーとして表示されることはありません。抽出の失敗はサーバー側の問題です。 SDKが可視的なシグナルは、検索では（まだ）表示されないメモリ、またはテキスト検索とハイブリッド検索では表示されるがセマンティック検索ではないメモリを抽出します。

読み取りの仕組み

、またはレコード自体に が適用されるか、2 つの異なる質問が含まれます。

``Build_context_from_sources(...)`` は、デフォルトで に到達する 1 つです。クエリとトークンの予算を指定します。名前を付けたメモリ型全体で検索され、結果がランク付けされ、ほぼ重複が削除され、予算が削減され、プロンプトに直接入力できるものが返されます。これは 1 つの呼び出しの背後にある取得パイプライン全体であり、ソースごとに 1 つの仕様を必要とするため、モードとフィルターはすべてに 1 回ではなく、ソースごとに設定されます。

取得は 3 つの方法に一致します。semantic は埋め込みを比較し、同じ平均ものを見つけます。text は単語を照合し、同じ意味を含むものを見つけます。 hybridは と の両方を実行し、ランキングを統合します。ハイブリッドは通常、正しいデフォルトです。ベクトル検索のみでは完全な識別子とまれな単語が欠落し、テキスト検索のみではパラフレーズが欠落します。

``Build_context(...)`` は、より単純なビルダであり、同じパイプラインですが、読み取られるすべてのソースに 1 つのモードと 1 つのフィルターが適用されます。

``search(...)`` およびタイプごとの検索（search_semantic 、search_episodes など）では、自分で検査または後処理したい場合に、構築されたプロトタイプではなく、ランク付けされたレコードが返されます。

メモリの範囲

すべてのレコードには書き込みが行われた ID が記載され、すべての読み取りはその後ではなくデータベースクエリでその ID によってフィルタリングされます。フィールドは、組織、 ユーザー 、プロジェクト、 セッション 、およびオプションのエージェントと、レコードがユーザーのプライベートか、より一般的に読み取れるかを決定する可視性です。

これは実質的な理由で、ユーザーにスコープが設定された検索や build_context では、別のユーザーのプライベートメモリは表示されません。制約は結果に適用されるフィルターではなく、クエリの一部であるためです。したがって、bind(...) は便宜的ではありません。これは、後続の読み取りと書込みがその内で動作するスコープを宣言し、それが別のユーザーの ID の下であるユーザーのメモリを誤って書込む方法です。

user_id とvisibility は異なる質問に答えます

user_id は、レコードが であるメモリを含みます。visibility は、以下に達する距離です。

レコードが書き込まれたプロジェクト外で可視性値に達することはありません。メモリはプロジェクトごとに 保存されるため、プロジェクト境界は可視性を超えるものではありません。org は履歴名であり、1 人のユーザーに制限されていないことを意味します。他のプロジェクトに表示されます）。

この 2 つのは独立しており、読み取りでは と として結合され、 または としては使用されません。指定するフィールドごとに、クエリに等価条件が 1 つずつ追加されます。省略する各フィールドはその次元を制約しないままにします。

3 行目は、すべてをリッスンする配列です。search_semantic(query, user_id="user_1", visibility="org") は、user_1 のメモリと組織の を平均ではありません。これは「user_1 が所有する org に表示されるメモリ」を意味します。これは制約のみを含む場合よりも小さいです。和集合はありません 。共有知識とユーザーのプライベートメモリを読み取るには、2 回の呼び出しを行い、結果を自分でマージします。

ホストされたプラットフォーム

マネージド サービス。サービスアカウント アクセス トークンとプロジェクトID を渡します。

agentengine CLI を使用してトークンを最小化します。サービス アカウントを一度だけ作成します。クライアントシークレットは 1 回だけ表示されるため、すぐに保存します。

agentengine service-account create my-agent --project-id <your-project-id> --role AGENT_DEVELOPER

次に、クライアントIDとシークレットを交換し、有効期間の短い（1 時間）のアクセス トークンを交換します（クライアントシークレットのプロンプトをカーソルが非表示になるため、 シェル履歴からは非表示になります）。

ACCESS_TOKEN=$(curl --fail-with-body --silent --show-error      --user <client-id>      --data grant_type=client_credentials      https://agentengine.mongodb.com/api/v1/oauth/token | jq -er .access_token)

memory = Memory(service_account_token="<your-access-token>", project_id="<your-project-id>")

プラットフォームは認証情報をプロジェクトに固定するため、一致しない project_id は拒否されます。空白の service_account_token では ValueError が発生します。

api_key （および AGENTIC_MEMORY_API_KEY）は、引き続き非推奨のエイリアスとして受け入れられ、DeprecationWarning を出力します。新しい入力とレガシー入力の両方を渡すと、ValueError が発生します。プロジェクトAPIキーはHTTP経由で最小化できなくなったため、新しい統合にはサービス アカウント トークンを使用する必要があります。

地域開発

スタックagentengine dev up の起動など、ユーザーが実行するバックエンドにポイントします。

memory = Memory(base_url="http://localhost:8080")

ローカル開発では、project_id を空のままにします。

プラットフォームエージェント内（アプリバウンド）

エージェントがAtlas Agent EngineMemory で実行されている場合、 の構築や接続は一切 されません 。プラットフォームは、ID、テナンシー、トランスポートがすでにバインドされている、準備ができた、ワイヤ済みのインスタンスを挿入します。アプリケーション コードは、上記の入力をいずれも渡しません。ランタイムが渡す ハンドルを使用します。 ID（ユーザー、セッション、組織、プロジェクト）は周囲のランタイム コンテキストから解決されるため、操作は直接呼び出せます。

# `memory` is supplied by the platform runtime — do not construct it.
memory.record_turn(role="user", content="I'm allergic to penicillin.")
context = memory.build_context(query="What medications should I avoid?")
# bind(...) is still available to scope a call chain to a specific identity.

アプリバインドされたパスには、いくつかの機能的なギャップがあります（ツール呼び出し / モデルはメタデータを変換し、一部のリスト形式の読み取り）。 「各接続がサポートする内容」の アプリバウンド 列と、`docs/capability-matrix.md

Env 変数はフォールバックです

引数を省略すると、各入力も AGENTIC_MEMORY_* 環境変数にフォールバックします。明示的な引数は常に選出されます。引数なしの Memory() は、環境から 3 つすべてを読み取ります。

ルーティングの仕組み

project_id は、呼び出しの場所を決定します。認証は行われません。

• project_id を設定すると、SDK はプロジェクトのルート /api/v1/projects/{project_id}/memory/* を呼び出します。

• 空のままにすると、SDK はバックエンドを直接 /api/v1/memory/* 呼び出します。

project_id が設定されているが、ローカルバックエンドなどのバックエンドに一致するルートがない場合、呼び出しは `MemoryRouteNotFoundError <:#errors+gt: を、設定解除のヒントとともに発生させます。その逆も保持されます。 project_id を使用せずにホストされているサービスをターゲットにし、それを設定するヒント付きで 404s を呼び出します。

高度: 認証済み直接バックエンド

認証とルーティングは独立しているため、project_id が空の状態で service_account_token を渡すことができます。その後 SDK は認証済み呼び出しを直接ルートで base_url のバックエンドに直接送信し、プロジェクトパスをスキップします。これは、ホストされているオーケストレーション エンジン（UE）が直接アクセスするのに適しています。

各接続がサポートする内容

機能は、認証ではなく呼び出しがルーティングされる場所に基づきます。

`MemoryNotSupportedErrorサポートされていない呼び出しでは、既知のバックエンドごとのギャップに対するネットワークリクエストの前、またはプラットフォームのみが報告できる機能の相違に関する応答後に、 <:#errors+gt:__s が発生します。（ エラー を参照）、サイレント障害または未加工のHTTPエラー。タイプ固有のCRUDに関するアプリバウンド ギャップを含む、バックエンドごとの完全な参照は、`docs/capability-matrix.md <.docs/Capability-matrix.md> にあります。

アプリバウンドエージェントは、上記すべての例外です。配置された プラットフォームエージェント内では、プラットフォームは準備ができた runtime を挿入するため、アプリケーションコードはこれらの入力をいずれも渡しません。

後で変更することはできません

構成の一部の部分は実質的に書込み (write) オンス ので、メモリの書込みを開始する前に決定します。

• メタデータ パーティション キー - 宣言されたフィルタ可能な属性。一度宣言されたキーは、削除したり、そのタイプを変更したりすることはできません。

• カスタム メモリ型宣言 - 型が受け入れられると、そのコレクションとタグセットはconfig APIを通じて編集または削除できなくなります。代わりに新しい型名を宣言します。

• 検索インデックス - は、インデックスがまだ存在しない場合にのみプロビジョニングされます。サーバーが起動した後にパーティションキーを追加しても、既存のインデックスは再構築されません。ドリフトがログに記録され、その後新しいキーのフィルターは暗黙で無視されるのではなく、データベースで失敗します。インデックスの再作成は 手動操作です。

ログ レベル、抽出 LVM、および有効な抽出タイプは変更して再適用できます。埋め込みモデルまたは次元を変更するには、既存のメモリを移行して再埋め込みする必要があります。次元の変更にはベクトル検索インデックスの再構築も必要です。

書込みの可視性の設定

すべての書き込みには visibility が必要です。タイプは異なる方法で使用されるため、デフォルトはメモリタイプによって異なります。

分類メモリのデフォルトは org です。ドメイン語彙は定義で共有されているためです。タームとその意味は、1 人のユーザーのプライベートプロジェクトであることはほぼありません。その他のすべてのデフォルトは private であるため、特に明示がない限り、保存する ファセット は学習されたユーザーに限定されます。

record_turn は例外です。visibility は必要ありませんが、user_id も必要ありません。セッションの結果は常にバインドされたユーザーとセッションの下に書き込まれるため、 が記録される前に bind(...) ください。呼び出しごとにユーザーをオンに設定する方法はありません。

# Private to user_1 — the default.
session.save_semantic(text="Prefers window seats.", label="seat-preference")
# Readable across the whole organization.
session.save_semantic(
    text="Refunds over $500 need manager approval.",
    label="refund-policy",
    visibility="org",
)

読み取りのスコープ設定

読み取りでは、visibility が設定されていない状態のままになるため、解決される ID によってのみ制約されます（通常はバインドされた user_id）。これはパーソナライズに適したデフォルトです。どの可視性でも、ユーザーが所有するすべてを取得します。

共有知識にアクセスするには、可視性とを渡し、ここでは と ルール バイトを渡します。 にバインドされたハンドルも引き続きuser_id="user_1" user_idに貢献するため、ユーザー_1 が所有する org に表示されるレコードのみが読み取られます。

session = memory.bind(MemoryRequestContext(user_id="user_1", session_id="thread_123"))
session.search_semantic("refund policy", visibility="org")   # user_1 AND org

user_id=NoneNoneを渡しても、拡大はありません。 または空白の引数はすべての階層で指定されていないとしてカウントされるため、限界値に該当します。 の境界がないハンドルを持つすべてのユーザーで読み取ります。user_id

# The original handle is unbound, so it carries no user_id.
memory.search_semantic("refund policy", visibility="org")
# Or bind only the parts you want.
thread = memory.bind(MemoryRequestContext(session_id="thread_123"))
thread.search_semantic("refund policy", visibility="org")

したがって、ユーザー自分の履歴とチームの共有知識の両方を必要とする支援は、2 回の読み取りを発行し、それらをマージします。

personal = session.search_semantic(query, top_k=5)                       # user_1, any visibility
shared = memory.search_semantic(query, visibility="org", top_k=5)        # org-wide, any owner

自分のメタデータを読む

record_turn は任意の metadata ディレクティブを受け取り、短期間の検索では、チャンクの独自のスロットにそれが返されます（chunk.metadata["metadata"]）。キーはプラットフォームの有効フィールド（session_id、role、turn_seq、...）とは別に保持されるため、 のキーは他のキーのキーと競合することはありません。キーに名前を付けることができます role または session_id を使用し、自分の値を返します。

衝突安全性がカバーしない 2 つの制限。値はラウンドトリップに耐えられる必要があるため、 JSONでシリアル化可能で、正のサイズである必要があります。また、キーをフィルタリング可能にするには、メタデータパーティションキーとして宣言可能である必要があります。ドットで区切られた各セグメントは ^[a-z][a-z0-9_]{0,63}$と一致する必要があり、最大 1 つのドットが許可され、いくつかの名前が予約されます（org_id 、 、 、project_id user_idagent_idcontent、embedding 、embedding_model_id 、 、created_at ）。その形状の外側にあるキーTier $foo（ 、 、a.b.c ）は引き続き保存および返されますが、フィルタリングはできません。

空のディレクティブはメタデータなしとして扱われます。metadata={} はチャンクに metadata スロットなしでタームを記録するため、呼び出し元で何も提供されない場合は chunk.metadata.get("metadata", {}) でそれを読み取ります。セマンティック メモリは同じように動作するため、1 つの読み取りパスが両方をカバーできます。時系列、分類、手順は同じように動作します。書き込んだディレクティブは chunk.metadata["metadata"] の下に返され、空の はスロットが存在しないことを意味します。エポックは 1 つの例外です。互換性フィルターは、citation_score、llm_confidence_score、および combined_score がまとめて含まれている場合、その形状は移行前の内部ブロブと一致するため、関連のないキーを含むディレクティブ全体を削除します。取得には、chunk.metadata["contextual_metadata"] が含まれる場合もあります。これはユーザーのデータではなく、プラットフォーム独自の抽出アーティファクトであり、依存する必要がある契約の一部ではありません。

短期間メモリはセッションにスコープが設定されているため、書込みと読み取りは同じ名前を付ける必要があります（一度バインドしてそれを渡します）。

from agent_engine_sdk_memory import (
    Memory,
    MemoryRequestContext,
    MemorySource,
    RetrievalMode,
    SourceSpec,
)
session_id = "session-42"
memory = Memory(base_url="http://localhost:8080").bind(
    MemoryRequestContext(user_id="user-1", session_id=session_id)
)
memory.record_turn(
    role="user",
    content="The engagement is green and the rollout continues.",
    metadata={"engagement_id": "eng-alpha", "tier": 2},
)
context = memory.build_context_from_sources(
    query="what is the engagement status?",
    sources=[
        SourceSpec(
            source=MemorySource.STM,
            mode=RetrievalMode.HYBRID,
            metadata_filter={"metadata.engagement_id": "eng-alpha"},
        )
    ],
    session_id=session_id,
    include_memories=True,
)
for chunk in context.selected_memories or []:
    print(chunk.metadata["metadata"]["engagement_id"])

Atlas Search は書き込みを非同期にインデックス化するため、 の直後に発行された読み取りでは、タームがまだ表示されない可能性があります。

スペルの違いを 1 つ認識する必要があります。これはネストされたディレクティブやchunk.metadata["metadata"]["engagement_id"] 内で読み取りますが、修飾インデックスパス でフィルタリングします。ネストを確認します。このフィルターは保存済みドキュメントに対処します。ここでのディレクティブは実際に{"metadata.engagement_id": ...}metadata の下に存在します。

要求されるパスを一覧表示するエラーで拒否されるため、このエラーが答えを提供します。

フィルタ可能なメタデータは最初にプロジェクトに対して宣言する必要があります。上記のengagement_id metadata_partition_keyは の下に表示され、 はshort_term metadata_partition_indexにリストされている必要があります。 「 フィルタ可能なメタデータの使用 」で「 フィルタ可能なメタデータの宣言 」を参照してください。

パッケージ レイアウト

agent_engine_sdk_memory/
├── memory.py        # Memory — the public, transport-free facade
├── protocol.py      # MemoryRequestContext, MemoryRuntime + MemoryCrudClient seams
├── identity.py      # resolve_identity — call arg > bind ctx > runtime ctx
├── errors.py        # MemoryIdentityError + the typed transport-error family
├── models.py        # Pydantic models for memory requests/responses
├── validation.py    # require_positive_max_tokens — public build_context guard
├── _transport.py    # _HttpTransport — shared retry / error-mapping / lifecycle
├── _http_runtime.py # _HttpMemoryRuntime — the workflow ops + per-backend profiles
├── _direct_crud.py  # empty-tenancy MemoryCrudClient over the shared transport
├── _wire.py         # custom-type request-body builders shared by the CRUD clients
├── _tag_syntax.py   # client-side custom-type name + tag-syntax checks
├── _client.py       # MemoryClient — internal HTTP client for the Memory Server API
└── _denylist.py     # do-not-add dependency denylist (see below)

Memory はトランスポートフリーです。ワークフロー操作（record_turn、build_context、検索、discover_procedures）を挿入された MemoryRuntime に、タイプ固有のCRUDを挿入された MemoryCrudClient に委任します。パブリック サーバーは tests/test_package_contract.py のスナップショット テストによって固定されています。 MemoryClient は内部のままです。呼び出しごとのテナンシー（org_id、ボディレベル project_id）は公開署名に表示されることはありません。パブリック サーバー上でのみの project_id は、リクエスト本文ではなくURLに入力されるオプションのコンストラクターのルートシェイプ セレクターです。

依存関係拒否リスト

pydantic + httpx のみの制約は強制されており、強制されています。 _denylist.py は既知の重いディストリビューションとインポート名（lang、fastapi、pymongo、...）を一覧表示します。パッケージをインポートするとそれらが sys.modules にプルされると、tests/test_package_contract.py は失敗します。

使用しています。

agent-engine-runner-shared はこのパッケージをワークスペース依存関係として宣言し、agent_engine_runner_shared/memory.py に内部 MemoryClient を構築して、その実行コンテキスト検索を execution_id_provider 呼び出し可能として渡します。これにより、このパッケージがプラットフォーム コードをインポートしなくても、リクエストごとの実行 ID ヘッダーは動作します。