スタンドアロン メモリ サービスの使用

メモリ専用のプロジェクトを作成します。

メモリ専用のプロジェクトを足場 するには、次のコマンドを実行します。 "My Project" をプロジェクト名に置き換えます。

agentengine create --memory-only --name "My Project"

コマンドは、project-config.yamlファイルのみを含み、agent.yamlファイルとワークスペースは含まれないプロジェクトディレクトリを生成します。

プラットフォームでプロジェクトを作成および選択します。

1. 以下のコマンドを実行して、プロジェクトを登録します。このコマンドは、新しいプロジェクトIDを出力します。

   agentengine project create "My Project"

2. 新しいプロジェクトをアクティブとして選択します。 <project-id> を、前のコマンドによって出力されたプロジェクトIDに置き換えます。

   agentengine auth login --project-id <project-id>

メモリ設定を構成します。

1. project-config.yamlファイルを開き、memory: ブロックの下にシークレット名と抽出プロバイダーを設定します。

2. 次のコマンドを実行して、プロジェクトに必要なシークレットを設定します。

   agentengine secret set MONGODB_URI --value "<value>" --project-id <project-id>
   agentengine secret set VOYAGE_API_KEY --value "<value>" --project-id <project-id>
   agentengine secret set ANTHROPIC_API_KEY --value "<value>" --project-id <project-id>

   以下のプレースホルダー値を置き換えます。

   • <value>: シークレットの値。

     • MONGODB_URI: Atlas クラスターの接続文字列。

     • VOYAGE_API_KEY: 投票AIキー。

     • ANTHROPIC_API_KEY: LM プロバイダーのキー。

   • <project-id>: agentengine project create コマンドによって返されたプロジェクトオブジェクトID 。このフラグは、メモリ専用ワークフローに agents.yamlファイルが含まれていないために必要です。

   別のプロバイダーを使用する場合は、ANTHROPIC_API_KEY を LM プロバイダーのキー名に置き換えます。

3. メモリ構成を保存します。

   agentengine memory configure

メモリサーバーをプロビジョニングします。

メモリのランタイムを開始し、準備ができるまで待ちます。

agentengine memory apply --wait

サービス アカウントを作成し、アクセス トークンを取得します。

1. 以下のコマンドを実行して、プロジェクトのサービス アカウントを作成します。

   agentengine service-account create memory-service --project-id <project-id> --role PROJECT_OWNER

   <project-id> プレースホルダーをプロジェクトIDに置き換えます。コマンド出力からクライアントIDとクライアントシークレットを保存します。 Atlas Agent Engine はクライアントシークレットを 1 回だけ表示します。

2. 次のコマンドを実行して、クライアントIDとクライアントシークレットをアクセス トークンと交換します。

   export 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)

   <client-id> プレースホルダーをクライアントIDに置き換えます。 curl はクライアントシークレットを反復せずに入力するよう要求します。

   Tip

   アクセス トークンの有効期間は 1 時間です。現在のトークンの有効期限が切れる前に新しいトークンをリクエストします。

Python SDK をインストールします。

前のステップでエクスポートしたアクセス トークンを使用して、プラットフォームのプライベート レジストリから agent-engine-sdk-memoryパッケージをインストールします。

pip install agent-engine-sdk-memory \
  --extra-index-url "https://ignore:$ACCESS_TOKEN@agentengine.mongodb.com/api/v1/packages/python/simple"

uv pip install agent-engine-sdk-memory \
  --extra-index-url "https://ignore:$ACCESS_TOKEN@agentengine.mongodb.com/api/v1/packages/python/simple"

URL はusername:password形式を使用します。レジストリは パスワードフィールドのアクセス トークンのみを使用して認証するため、 ignore はプレースホルダーユーザー名です。 $ACCESS_TOKEN は、前の手順でエクスポートしたアクセス トークンに解決されます。

セッションのコンテキストを記録および取得してください。

アプリケーションに、次のコードを追加して、クライアントを作成し、ユーザー ID をバインドし、切り替えが発生したときにレコード、後でのやり取りで関連コンテキストを検索します。

from agent_engine_sdk_memory import (
    Memory,
    MemoryRequestContext,
)
# Create the client using your access token.
memory = Memory(service_account_token="<your-access-token>")
# Bind the user and session for this conversation.
chat = memory.bind(
    MemoryRequestContext(
        user_id="user_1",
        session_id="thread_123",
    )
)
# Record turns as they happen.
chat.record_turn(
    role="user",
    content="I always fly out of Boston.",
)
chat.record_turn(
    role="assistant",
    content="Got it, Boston is saved as your home airport.",
)
# In a later conversation, recall what matters.
later = memory.bind(
    MemoryRequestContext(
        user_id="user_1",
        session_id="thread_456",
    )
)
context = later.build_context(
    query="Where should the flight book from?"
)
hits = later.search("home airport", top_k=5)

ローカル メモリプロジェクト の足場

次のコマンドを実行して、ローカル開発用のメモリ専用プロジェクトを実行します。 "My Project" をプロジェクト名に置き換えます。

agentengine create --memory-only --name "My Project"

コマンドは、memory_only を true に設定し、 メモリ構成スキーマを指定する project-config.yamlファイルを書き込みます。

このコマンドは、agent.yamlファイル、 agents/ディレクトリ、またはエージェントランタイム コードを生成しません。 --memory-only フラグは、--template、--llm、--memory、または --open-egress フラグと組み合わせて使用できません。

環境変数を構成します。

プロジェクトディレクトリに .envファイルを作成し、ファイルに次の変数を設定します。

• VOYAGE_API_KEY: 投票AI埋め込みに必要

• LVM プロバイダーキー（ANTHROPIC_API_KEY など）: project-config.yaml でバックグラウンド抽出が有効になっている場合に必要です

MONGODB_URI 変数を設定する必要はありません。 agentengine dev up コマンドは、バンドルされているローカルMongoDBコンテナを自動的にプロビジョニングし、接続します。代わりに外部のMongoDBインスタンスを使用する場合は、この変数を設定します。

ローカルスタックを起動します。

プロジェクトディレクトリから、次のコマンドを実行してローカル メモリスタックを起動します。

agentengine dev up

メモリ専用のプロジェクトの場合、このコマンドは次のコンテナのみを起動します。

• mongodb: Atlas と互換性のあるMongoDB のローカルインスタンス

• memory-server: メモリ ランタイム サービス

• oe: SDK が接続するローカル 組織化エンジンのプロキシ

コマンド出力には、ローカルの oe サービスと memory-server サービスの URL が含まれます。後のステップで使用する oe URLをコピーします。

ローカルスタックを管理するには、次のコマンドを使用します。

agentic-platform-memoryパッケージをインストールします。

agentic-platform-memoryパッケージをインストールするには、次のコマンドを実行します。

pip install agentic-platform-memory

SDK をローカルスタックに接続します。

Pythonアプリケーションディレクトリに移動します。このディレクトリは、最初のステップで作成したプロジェクトディレクトリとは別にすることができます。

次に、次のコードをアプリケーションに追加してローカルスタックに接続します。 http://localhost:<oe-port> を、agentengine dev up コマンド出力からコピーしたURLに置き換えます。

from agentic_platform_memory import Memory, MemoryRequestContext
# Set the base_url to the local oe URL printed by "agentengine dev up".
memory = Memory(base_url="http://localhost:<oe-port>")
# Bind conversation identity.
session = memory.bind(
    MemoryRequestContext(
        user_id="user_123",
        session_id="session_456",
    )
)
# Record a turn.
session.record_turn(role="user", content="I prefer window seats on flights.")
# Build context.
context = session.build_context(
    query="What seat preferences are known?",
    enabled_sources={"stm", "semantic", "episodic"},
)
print(context.formatted_context)