エージェントにメモリを追加する

Overview

MongoDB Atlas Agent Engine のメモリはプロジェクトレベルで構成されます。プロジェクト内のすべてのエージェントは、同じメモリサービス、ストア、および設定を共有します。個々のエージェントのメモリは、 agent.yamlファイルで有効または無効にできます。

メモリを構成するには、 project-config.yamlファイルの memory: ブロックを編集し、必要なAPIキーをプロジェクトシークレットとしてアップロードして、エージェントを配置します。最初の配置後、再配置せずにメモリ設定を更新できます。

通信中に保存方法や抽出方法など、メモリの詳細については、エージェントメモリガイドを参照してください。

前提条件

開始する前に、次の前提条件があることを確認してください。

agent.yamlファイルと配置されたエージェント。使用を開始するには、「 Atlas Agent エンジンの使用を開始する」を参照してください。
agentengineCLI がインストールおよび認証されました。詳しくは、「インストールと認証」を参照してください。
メモリデータを保存するには、Atlas Flex（最小要件）、、以上の階層クラスター（推奨）。クラスターをプロビジョニングするには、「M10 M20Atlas リソースの設定」を参照してください。
- メモリデータとインデックス数が大きくなるにつれて対応するために、専用の M10 以上の階層クラスターを配置することをお勧めします。 Atlas Flex は、メモリサービスをサポートできる最低のクラスター層です。

注意

リンクされた Atlas クラスターが、メモリに必要な検索インデックスとベクトル検索インデックスを作成できない場合、Atlas Agent Engine は Memory: waiting ステージで配置を停止し、Error: context deadline exceeded エラーメッセージを表示してタイムアウトすることがあります。

メモリを有効にする

エージェントのメモリを有効にするには、 agent.yamlファイルで features.memory: true を設定し、ローカル環境を起動する前に .envファイルに次の変数を追加します。

VOYAGE_API_KEY: メモリ埋め込みの生成に必要です。
MONGOMEM_DB_NAME: 任意。メモリサーバーが書き込むMongoDBデータベース名。デフォルトは mdb_memory_<project-id> です。

メモリには、次のセクションで説明する 2 レベルのプロジェクト構造が必要です。 agentengine create コマンドを使用してプロジェクトをスキャフォールディングする場合、CLI はこの構造を生成します。

注意

TypeScript エージェントは同じ方法を使用してメモリを有効にします。 TypeScriptエージェントは、プラットフォームリクエストを処理しているときにのみ app.memoryクライアントにアクセスします。このコンテキスト外でメモリを読み取りまたは書き込みするには、@mongodb-js/agent-engine-sdk-memoryパッケージの Memoryクライアントを使用します。このクライアントはHTTP経由でメモリサーバーに直接接続します。

メモリのプロジェクト構造

プロジェクトルートには、メモリ構成を保存する project-config.yamlファイルがあります。 agent.yamlファイルを含む各ワークスペースは、プロジェクトルートのサブフォルダーです。次の例は、メモリ構成に関する予想されるプロジェクト構造を示しています。

my-project/
├── project-config.yaml
└── my-workspace/
    └── agent.yaml

project-config.yamlファイルには、プロジェクトのメモリサーバーを構成する memory: セクションがあります。次の例は、使用可能なメモリ構成オプションとそのデフォルトオプションを示しています。

memory:
  # Memory-server log level. One of: debug | info | warning | error |
  # critical.
  log_level: info
  # Voyage AI embeddings.
  # The Voyage API key is NOT set here — upload it as a project
  # secret with:
  #   agentengine secret set VOYAGE_API_KEY <value>
  voyage:
    model: "voyage-4-large"
    dimension: 1024
  # Short-term memory write-path behavior.
  short_term:
    # Embed each turn's content when it is written (only when the
    # caller supplies no embedding), so it is searchable by
    # relevance immediately instead of waiting for background
    # embedding. Adds embedding latency to the write.
    embed_on_write: false
  # LLM used for background extraction.
  # The API key is NOT set here — upload it as a project secret. If
  # your agent already uses a supported LLM connection, upload that
  # same key under the shared LLM_API_KEY name so the agent and
  # extraction reuse one secret:
  #   agentengine secret set LLM_API_KEY <value>
  # Otherwise, upload a provider-named key instead, for example:
  #   agentengine secret set OPENAI_API_KEY <value>
  extraction_llm:
    provider: openai  # one of: openai | anthropic | gemini | cerebras
    model: null       # overrides the provider's default model
    base_url: null    # optional: route requests through a gateway
                       # or proxy instead of the provider's default
                       # endpoint. Required only for gateway
                       # connections; omit to call the provider
                       # directly.
    api_key_secret: null  # optional: the name of the project secret
                           # that holds the extraction LLM's API key.
                           # One of: LLM_API_KEY, OPENAI_API_KEY,
                           # ANTHROPIC_API_KEY, GEMINI_API_KEY, or
                           # CEREBRAS_API_KEY. If omitted, extraction
                           # checks provider-named keys before
                           # LLM_API_KEY.
    auth_header: null  # optional: the header the gateway expects for
                        # the API key. One of: authorization (Bearer)
                        # or api-key. Omit for native provider
                        # authentication.
  background_extraction:
    snapshot:
      max_messages: 20
      stale_minutes: 3
      embed_stm_before_promotion: true
      topic_shift_enabled: false
      topic_shift_threshold: 0.35
      delete_promoted: false
      ttl_days: 30
  # Extraction pipeline. Add memory types to the 'enabled' list to
  # turn extraction on, for example:
  #   enabled:
  #     - semantic
  #     - episodic
  # Valid types: semantic, episodic, taxonomic, entity, preferences,
  # procedural.
  # NOTE: Removing the 'enabled' line entirely re-enables ALL types.
  # Keep it as [] to extract nothing.
  extraction:
    enabled: []

配置されたプロジェクトのメモリ構成をアップロードして同期するには、「メモリの構成」を参照してください。

プロジェクト構造の移行

プロジェクトでプロジェクトルートに agent.yaml がある平面構造を使用している場合は、メモリを有効にする前に 2 レベル構造に移行してください。平面構造は非推奨です。

平面構造を移行するには、次の手順を実行します。

プロジェクトルート内にワークスペースフォルダーを作成します。

次の例では、my-workspace という名前のフォルダーを作成します。

mkdir my-workspace

ワークスペースファイルを新しいフォルダーに移動します。

次のコマンドを実行して、agent.yamlファイル、エージェントソースファイル、.envファイルをワークスペースフォルダーに移動します。

mv agent.yaml my-workspace/
mv .env my-workspace/

`project-config.yaml`プロジェクトルートにファイルを作成します。

次のサンプルファイルproject-config.yaml は、memory: セクションの構成を示しています。

memory:
  log_level: info
  voyage:
    model: "voyage-4-large"
    dimension: 1024
  short_term:
    embed_on_write: false
  extraction_llm:
    provider: openai
    model: null
    base_url: null
    api_key_secret: null

更新された構造を確認します。

プロジェクトが次の構造と一致していることを確認します。

my-project/
├── project-config.yaml
└── my-workspace/
    └── agent.yaml

ローカル環境を起動します。

プロジェクトルートから次のコマンドを実行します。

agentengine dev up

メモリを構成する

配置されたプロジェクトのメモリ構成をアップロードおよび同期するには、agentengine memory コマンドを使用します。メモリ構成はプロジェクトにスコープが設定されています。1 つの構成ドキュメントがプロジェクト内のすべてのエージェントに適用されます。

ローカル開発用にメモリを構成するには、「メモリの有効化」を参照してください。

構成コマンドシンタックス

agentengine memory configure コマンドは、エージェントディレクトリから project-config.yamlファイルを読み取り、memory: セクションを抽出して、Atlas Agent エンジンにアップロードします。コマンドは、アップロードする前にターゲットプロジェクトを確認します。

重要

将来のリリースでは、agentengine memory configure コマンドのサポートが廃止されます。代わりに、プラットフォームはUIを介したメモリ管理をサポートします。

次の例は、メモリ構成をアップロードするためのコマンド構文を示しています。

agentengine memory configure <path> [--project-id <id> --org-id <id> --base-url <url>]

あるいは、次の例に示すように、agentic memory configure コマンドを使用して --context フラグのみを渡すこともできます。

agentengine memory configure <path> [--context <name>]

警告

project-config.yamlファイルにmemory: キーが含まれていない場合、コマンドはエラーを返します。 memory: キーがない場合、既存の構成は削除されません。

次の表では、使用可能なフラグについて説明しています。

Flag	説明
`--context`	ターゲットプラットフォームベースURL、組織、プロジェクトを識別する保存済みコンテキストの名前。保存したコンテキストを表示するには、`agentic context list` を実行します。
`--project-id`	プロジェクトID 。省略した場合、コマンドはローカル認証状態のプロジェクトを使用します。このフラグを設定する場合は、`--org-id` フラグと `--base-url` フラグも設定する必要があります。
`--org-id`	組織ID。 `--project-id` フラグを使用する場合は必須です。
`--base-url`	プラットフォームベースURL。 `--project-id` フラグを使用する場合は必須です。
`--yes`	確認プロンプトをスキップします。このフラグは、継続的統合（CI）環境で使用します。

注意

メモリ構成はシークレットストアではありません。非シークレット設定のみを project-config.yamlファイルに保存します。 APIキー、接続文字列、その他の認証情報には、agentengine secret set コマンドを使用します。 Atlas Agent Engine は、一般的な秘密パターンに一致する値を含むアップロードを拒否します。

初期メモリ構成

メモリを有効にして初めて配置する前に、次の手順を実行します。

`memory:`ファイル内のブロックを編集します。`project-config.yaml`

project-config.yamlプロジェクトルートでを開き、メモリ設定を構成します。使用可能なオプションを表示するには、「メモリ用のプロジェクト構造」を参照してください。

必要なシークレットをアップロードします。

次のコマンドを実行してシークレットをアップロードし、プロジェクトスコープのシークレットを対象とするには --project-scope フラグを含めます。

agentengine secret set VOYAGE_API_KEY --project-scope
agentengine secret set LLM_API_KEY --project-scope

agentic create --llm <provider> --memory コマンドでプロジェクトをスキャフォールディングし、サポートされている LM プロバイダーを選択した場合、CLI はすでに project-config.yamlファイルに extraction_llm.api_key_secret: LLM_API_KEY を追加しています。これはエージェントの .envファイルが使用するシークレット名と同じであるため、アップロードにより、エージェントとメモリ抽出の両方にキーが提供されます。

注意

OPENAI_API_KEY や ANTHROPIC_API_KEY などのプロバイダー名キーは引き続き使用できます。明示的な api_key_secret 値がない場合、抽出は LLM_API_KEY より前のプロバイダー名キーをチェックします。メモリにエージェントからの別の認証情報が必要な場合、または複数のプロバイダーのキーがあり、1 つを選択する場合は、api_key_secretフィールドを明示的に設定します。

api_key_secret を LLM_API_KEY 以外の値に設定する場合は、代わりに前のコマンドの LLM_API_KEY をその名前に置き換えます。

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

プロジェクトルートから次のコマンドを実行して、project-config.yamlファイルから memory: ブロックを Atlas Agent Engine にアップロードします。

agentengine memory configure

エージェントを配置します。

次のコマンドを実行して、エージェントを配置し、メモリサーバーをプロビジョニングします。

agentengine deploy

deployment コマンドは保留中のメモリ構成を同期し、プロジェクトランタイムの一部としてメモリサーバーをプロビジョニングします。

メモリ構成の更新

メモリ構成の変更には、エージェントを再配置する必要はありません。更新されたメモリ設定を実行中の配置に適用するには、次の手順を実行します。

新しいメモリ設定で `memory:`ファイル内の `project-config.yaml`ブロックを編集します。

更新された構成を保存します。

プロジェクトルートから次のコマンドを実行します。

agentengine memory configure

構成を適用します。

agentengine memory apply

agentengine memory apply コマンドはメモリサーバーを再起動し、新しい構成を登録します。プラットフォームは構成変更を非同期に配信し、ポッドが再起動するとき、または更新された構成がスタートアップに適用されたときに変更を有効にします。保存された構成がまだ同期されていない場合、agentengine deploy コマンドは次回の配置プロセスの一部として構成を同期します。

カスタムメモリ型の宣言

カスタムメモリタイプは、4 つの組み込みメモリタイプに対応していないドメイン固有のレコードを保存します。カスタムメモリ型を宣言して使用するには、次の手順を実行します。

カスタムタイプを宣言します。

project-config.yamlファイルの memory: セクションに custom_memory_types: ブロックを追加します。次の例では、カスタム customer_profile 型を作成しています。

memory:
  custom_memory_types:           # Custom memory types (max 5)
    - name: customer_profile
      collection: profiles
      tags:
        - name: location
        - name: tier
        - name: profile.location  # One level of nested tag keys

各カスタムメモリ型には、次のフィールドがあります。

name:（必須）タイプ名。値は小文字で始まり、小文字、数字、アンダースコアのみを含める必要があります。組み込み型名を使用したり、長さが 64文字を超えることはできません。
collection:（必須）タイプのレコードを保存するプロジェクトのメモリデータベース内のコレクション。
tags:（任意）フィルタ可能なタグキー、タイプごとに最大 10 個。タグキーは、ドット表記を使用して最大 1 レベル（profile.location など）までネストできます。タグの値は、空でない文字列、数値、またはブール値でない必要があります。

新しいタイプをプロビジョニングします。

次のコマンドを実行して更新された構成をアップロードし、メモリサーバーに適用し、各新しいタイプをプロビジョニングします。

agentengine memory configure
agentengine memory apply

注意

カスタムメモリ型を宣言する構成をアップロードした後は、その型のコレクションまたはタグセットを編集または削除することはできません。型を変更するには、代わりに新しい型名を宣言します。

カスタムメモリレコードの読み取りと書き込み。

アプリケーションで、save() メソッドと retrieve() メソッドを使用してカスタムメモリレコードの書込みと読み取りを行います。

memory.save(
    memory_type="customer_profile",
    content="Prefers direct vendor onboarding contact.",
    tags={"tier": "gold"},
)
hits = memory.retrieve(
    memory_type="customer_profile",
    query="How should we onboard this customer?",
    tags={"tier": "gold"},
    top_k=5,
)

エージェントからメモリにアクセスする

メモリを有効にしてエージェントを配置すると、プラットフォームはアプリケーションオブジェクトに app.memoryクライアントを提供します。このクライアントを使用して、エージェントからメモリを読み取り、書込みます。プラットフォームは現在のユーザーとセッションをランタイムコンテキストから解決するため、user_id または session_id 引数を app.memory に明示的に渡す必要はありません。

重要

サービスアカウントメモリ ID

サービスアカウントが配置されたエージェントを呼び出す場合、Atlas Agent Engine はサービスアカウントの ID をランタイムメモリの ID として使用します。プラットフォームは、呼び出しリクエストまたは agentengine invoke --user-id フラグが提供するエンドユーザーの user_id 値を無視します。

この解決済み ID は、自動変換、記録、抽出、統合、app.memory 操作で使用されます。その結果、同じサービスアカウントを認証する呼び出しは 1 つのメモリユーザースコープを共有します。

この制限は、サービスアカウントが呼び出す配置されたエージェントにのみ適用されます。スタンドアロンの、プロジェクトスコープのメモリサービスは影響を受けません。このサービスは、呼び出し元からの明示的な user_id と session_id 値を引き続き受け入れます。

エンドユーザーごとにメモリを分離するには、アプリケーションからスタンドアロンのメモリサービスを呼び出し、各呼び出しに明示的なuser_id とsession_id 値を渡します。詳しくは、「スタンドアロンメモリサービスの使用」を参照してください。

agent-engine-sdk-langgraphエージェントからメモリにアクセスするには、次の手順を実行します。すべての Atlas Agent Engineエージェントテンプレートは agent-engine-sdk-langgraphパッケージを使用するため、エージェントのユースケースに関係なくこれらの手順が適用されます。

`app.memory`クライアントにアクセスします。

エージェントコードで、app.memoryクライアントを取得し、それを使用してメモリの読み取りと書込みを行います。次の例は、このクライアントにアクセスする方法を示しています。

from agent_engine_sdk_langgraph import App
app = App(app_name="support-agent")
@app.entrypoint
def build_graph():
    # Your LangGraph state machine.
    ...
# Later, in a request handler for a conversation turn:
memory = app.memory

ユーザーのメッセージに関連するコンテキストを取得します。

次の例に示すように、app.memory.build_context() メソッドを使用して、メッセージに関連するメモリを取得し、それをコンテキストとして形式。

def handle_turn(user_message: str) -> str:
    ctx = memory.build_context(
        query=user_message,
        max_tokens=2000,
    )
    prompt = f"{ctx.formatted_context}\n\nUser: {user_message}"
    return prompt

長期メモリを直接書込みます。

ファクターをメモリに直接保存するには、save_* メソッドを使用します。次の例では、セマンティックメモリを書込み (write) しています。

memory.save_semantic(
    text="Prefers email over phone for support follow-ups.",
    label="contact_preference",
)

次のステップ

エージェントのメモリを有効にした後、エージェントをローカルでテストして配置できます。エージェントをテストする方法については、「エージェントをテストする」を参照してください。エージェントを配置する方法については、「配置」を参照してください。

Atlas Agent Engine の外部で実行されるアプリケーションのメモリを使用するには、「スタンドアロンメモリサービスアプリの使用」ガイドを参照してください。

戻る

エージェントメモリー

メモリの抽出