このページは Cloud Translation API によって翻訳されました。

思い出を生成する

Memory Bank を使用すると、ユーザーとエージェントの会話から長期記憶を構築できます。このページでは、メモリー生成の仕組み、メモリーの抽出方法をカスタマイズする方法、メモリー生成をトリガーする方法について説明します。

メモリ生成について

Memory Bank は、ソースデータから思い出を抽出し、特定の思い出のコレクション（scope で定義）の思い出を、時間の経過とともに思い出を追加、更新、削除することで自己キュレーションします。

メモリ生成をトリガーすると、Memory Bank は次のオペレーションを実行します。

抽出: エージェントとの会話からユーザーに関する情報を抽出します。インスタンスのメモリトピックの少なくとも 1 つに一致する情報のみが保持されます。
統合: 抽出された情報に基づいて、同じスコープの既存の思い出を削除または更新するかどうかを特定します。Memory Bank は、新しい記憶が重複していないか、矛盾していないかを確認してから、既存の記憶と統合します。既存の思い出が新しい情報と重複しない場合は、新しい思い出が作成されます。

メモリーは、ソースコンテンツのテキスト、インラインファイル、ファイルデータからのみ抽出できます。関数呼び出しやレスポンスなど、他のすべてのコンテンツは、思い出の生成時に無視されます。

思い出は、ユーザーが提供した画像、動画、音声から抽出できます。マルチモーダル入力によって提供されたコンテキストが、Memory Bank によって今後のやり取りに有益であると判断された場合、入力から抽出された情報を含むテキストメモリが作成されることがあります。たとえば、ユーザーが「これは私の犬です」というテキストとともにゴールデンレトリバーの画像を提供すると、Memory Bank は「私の犬はゴールデンレトリバーです」などの記憶を生成します。

思い出のトピック

「メモリトピック」は、Memory Bank が有意義と判断し、生成されたメモリとして保持すべきと判断した情報を特定します。Memory Bank は、次の 2 種類のメモリトピックをサポートしています。

管理対象トピック: ラベルと手順は Memory Bank によって定義されます。指定する必要があるのは、マネージドトピックの名前だけです。次に例を示します。

辞書

memory_topic = {
    "managed_memory_topic": {
        "managed_topic_enum": "USER_PERSONAL_INFO"
    }
}

クラスベース

from vertexai.types import ManagedTopicEnum
from vertexai.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from vertexai.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic

memory_topic = MemoryTopic(
    managed_memory_topic=ManagedMemoryTopic(
        managed_topic_enum=ManagedTopicEnum.USER_PERSONAL_INFO
    )
)

カスタムトピック: メモリーバンクインスタンスの設定時に、ラベルと手順を定義します。これらは、Memory Bank の抽出ステップのプロンプトで使用されます。次に例を示します。

辞書

memory_topic = {
    "custom_memory_topic": {
        "label": "business_feedback",
        "description": """Specific user feedback about their experience at
the coffee shop. This includes opinions on drinks, food, pastries, ambiance,
staff friendliness, service speed, cleanliness, and any suggestions for
improvement."""
    }
}

クラスベース

from vertexai.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from vertexai.types import MemoryBankCustomizationConfigMemoryTopicCustomMemoryTopic as CustomMemoryTopic

memory_topic = MemoryTopic(
    custom_memory_topic=CustomMemoryTopic(
        label="business_feedback",
        description="""Specific user feedback about their experience at
the coffee shop. This includes opinions on drinks, food, pastries, ambiance,
staff friendliness, service speed, cleanliness, and any suggestions for
improvement."""
    )
)

カスタムトピックを使用する場合は、会話からメモリーを抽出する方法を示す少量のサンプルも提供することをおすすめします。

デフォルトでは、Memory Bank は次のすべてのマネージドトピックを保持します。

個人情報（USER_PERSONAL_INFO）: ユーザーに関する重要な個人情報（名前、関係、趣味、重要な日付など）。たとえば、「私は Google で働いています」、「結婚記念日は 12 月 31 日です」などです。
ユーザーの好み（USER_PREFERENCES）: 明示的または暗黙的な好み、嫌いなもの、好みのスタイル、パターン。たとえば、「真ん中の席がいいです」と入力します。
会話の重要なイベントとタスクの結果（KEY_CONVERSATION_DETAILS）: 会話内の重要なマイルストーンまたは結論。たとえば、「JFK と SFO 間の往復航空券を予約しました。2025 年 6 月 1 日に出発し、2025 年 6 月 7 日に帰国します。」
明示的な記憶 / 忘却の指示（EXPLICIT_INSTRUCTIONS）: エージェントに記憶または忘却を明示的に指示する情報。たとえば、ユーザーが「私は主に Python を使用していることを覚えておいて」と言うと、Memory Bank は「私は主に Python を使用している」というメモを生成します。

これは、次のマネージドメモリトピックのセットを使用するのと同等です。

辞書

  memory_topics = [
      {"managed_memory_topic": {"managed_topic_enum": "USER_PERSONAL_INFO"}},
      {"managed_memory_topic": {"managed_topic_enum": "USER_PREFERENCES"}},
      {"managed_memory_topic": {"managed_topic_enum": "KEY_CONVERSATION_DETAILS"}},
      {"managed_memory_topic": {"managed_topic_enum": "EXPLICIT_INSTRUCTIONS"}},
  ]

クラスベース

from vertexai.types import ManagedTopicEnum
from vertexai.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from vertexai.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic

memory_topics = [
  MemoryTopic(
      managed_memory_topic=ManagedMemoryTopic(
          managed_topic_enum=ManagedTopicEnum.USER_PERSONAL_INFO)),
  MemoryTopic(
      managed_memory_topic=ManagedMemoryTopic(
          managed_topic_enum=ManagedTopicEnum.USER_PREFERENCES)),
  MemoryTopic(
      managed_memory_topic=ManagedMemoryTopic(
          managed_topic_enum=ManagedTopicEnum.KEY_CONVERSATION_DETAILS)),
  MemoryTopic(
      managed_memory_topic=ManagedMemoryTopic(
          managed_topic_enum=ManagedTopicEnum.EXPLICIT_INSTRUCTIONS)),
]

Memory Bank で保持するトピックをカスタマイズする場合は、Memory Bank の設定時にカスタマイズ構成でメモリトピックを設定します。

思い出を生成する

このガイドで説明する手順を完了するには、まず Memory Bank の設定の手順に沿って操作する必要があります。

セッションの終了時またはセッション内の定期的な間隔で GenerateMemories を使用して、メモリ生成をトリガーできます。メモリ生成では、ソースの会話から重要なコンテキストを抽出し、同じスコープの既存のメモリと組み合わせます。たとえば、{"user_id": "123", "session_id": "456"} などのスコープを使用してセッションレベルのメモリを作成できます。同じスコープのメモリは統合して、まとめて取得できます。

GenerateMemories を呼び出す場合は、Agent Engine セッションまたは JSON 形式で直接、ソース会話を指定する必要があります。

JSON 形式

Agent Engine Sessions とは異なるセッションストレージを使用している場合は、ソースの会話を JSON 形式で直接指定します。

client.agent_engines.memories.generate(
    name=agent_engine.api_resource.name,
    direct_contents_source={
      "events": EVENTS
    },
    scope=SCOPE,
    config={
        "wait_for_completion": True
    }
)

次のように置き換えます。

EVENTS: コンテンツ辞書のリスト。次に例を示します。

[
  {
    "content": {
      "role": "user",
      "parts": [
        {"text": "I'm work with LLM agents!"}
      ]
    }
  }
]

SCOPE: 生成されたメモリの範囲を表す辞書。例: {"session_id": "MY_SESSION"}統合の対象となるのは、同じスコープのメモリのみです。

Agent Engine セッション

Agent Engine Sessions を使用すると、Memory Bank はセッションイベントをメモリ生成のソース会話として使用します。

生成された記憶の範囲を設定するため、Memory Bank はデフォルトでセッションからユーザー ID を抽出して使用します。たとえば、セッションの user_id が「123」の場合、メモリのスコープは {"user_id": "123"} として保存されます。scope を直接指定することもできます。この場合、セッションの user_id をスコープとして使用する設定はオーバーライドされます。

client.agent_engines.memories.generate(
  name=agent_engine.api_resource.name,
  vertex_session_source={
    "session": "SESSION_NAME"
  },
  # Optional when using Agent Engine Sessions. Defaults to {"user_id": session.user_id}.
  scope=SCOPE,
  config={
      "wait_for_completion": True
  }
)

次のように置き換えます。

SESSION_NAME: セッション名。
（省略可）SCOPE: 生成されたメモリのスコープを表すディクショナリ。例: {"session_id": "MY_SESSION"}統合の対象となるのは、同じスコープのメモリのみです。指定しない場合は、{"user_id": session.user_id} が使用されます。

GenerateMemories は長時間実行オペレーションです。オペレーションが完了すると、AgentEngineGenerateMemoriesOperation に生成されたメモリーのリストが含まれます（生成された場合）。

AgentEngineGenerateMemoriesOperation(
  name="projects/.../locations/.../reasoningEngines/.../operations/...",
  done=True,
  response=GenerateMemoriesResponse(
    generatedMemories=[
      GenerateMemoriesResponseGeneratedMemory(
        memory=Memory(
          "name": "projects/.../locations/.../reasoningEngines/.../memories/..."
        ),
        action="CREATED",
      ),
      GenerateMemoriesResponseGeneratedMemory(
        memory=Memory(
          "name": "projects/.../locations/.../reasoningEngines/.../memories/..."
        ),
        action="UPDATED",
      ),
      GenerateMemoriesResponseGeneratedMemory(
        memory=Memory(
          "name": "projects/.../locations/.../reasoningEngines/.../memories/..."
        ),
        action="DELETED",
      ),
    ]
  )
)

生成された各メモリには、そのメモリで実行された action が含まれます。

CREATED: 新しい思い出が追加されたことを示します。これは、既存の思い出では捉えられなかった新しいコンセプトを表します。
UPDATED: 既存のメモリが更新されたことを示します。これは、メモリが新しく抽出された情報と同様のコンセプトをカバーしている場合に発生します。メモリーの事実は新しい情報で更新されることもあれば、そのままの場合もあります。
DELETED: 会話から抽出された新しい情報と矛盾する情報が含まれていたため、既存のメモリが削除されたことを示します。

CREATED または UPDATED メモリの場合、GetMemories を使用してメモリのコンテンツ全体を取得できます。DELETED のメモリを取得すると、404 エラーが発生します。

バックグラウンドで思い出を生成する

GenerateMemories は長時間実行オペレーションです。デフォルトでは、client.agent_engines.generate_memories はブロッキング関数であり、オペレーションが完了するまでポーリングを続行します。生成された思い出を手動で確認する場合や、生成された思い出についてエンドユーザーに通知する場合は、メモリ生成をブロックオペレーションとして実行すると便利です。

ただし、本番環境のエージェントでは、通常、メモリ生成を非同期プロセスとしてバックグラウンドで実行します。ほとんどの場合、クライアントは現在の実行の出力を使用する必要がないため、レスポンスを待つために追加のレイテンシが発生する必要はありません。メモリ生成をバックグラウンドで実行する場合は、wait_for_completion を False に設定します。

client.agent_engines.memories.generate(
    ...,
    config={
        "wait_for_completion": False
    }
)

事前に抽出されたメモリーを統合する

メモリバンクの自動抽出プロセスを使用する代わりに、事前に抽出した思い出を直接提供することもできます。直接ソースの思い出は、同じスコープの既存の思い出と統合されます。これは、エージェントまたは人間がメモリの抽出を担当し、メモリバンクの統合を利用して重複や矛盾するメモリがないようにしたい場合に便利です。

client.agent_engines.memories.generate(
    name=agent_engine.api_resource.name,
    direct_memories_source={"direct_memories": [{"fact": "FACT"}]},
    scope=SCOPE
)

次のように置き換えます。

FACT: 既存のメモリと統合する必要がある事前抽出されたファクト。次のようなリストで、最大 5 個の事前抽出されたファクトを指定できます。
```
{"direct_memories": [{"fact": "fact 1"}, {"fact": "fact 2"}]}
```
SCOPE: 生成されたメモリの範囲を表す辞書。例: {"session_id": "MY_SESSION"}統合の対象となるのは、同じスコープのメモリのみです。

思い出を生成する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

メモリ生成について

思い出のトピック

辞書

クラスベース

辞書

クラスベース

辞書

クラスベース

思い出を生成する

JSON 形式

Agent Engine セッション

バックグラウンドで思い出を生成する

事前に抽出されたメモリーを統合する

次のステップ

思い出を生成する