記憶リビジョン

Agent Platform メモリーバンクは、メモリ リビジョン リソースを介してメモリのバージョン履歴を自動的に保持します。メモリーが作成または変更されるたびに、新しい不変のリビジョンが保存されます。これにより、情報の進化と各ステップで抽出された内容が透明化されます。

このドキュメントでは、メモリとそのリビジョンのライフサイクルについて説明し、リビジョンのリスト表示、取得、ロールバックなどのオペレーションについて説明します。

メモリの生成の詳細については、メモリを生成するをご覧ください。

メモリとそのリビジョンのライフサイクル

データソースとメモリ リビジョン

メモリは、直接(CreateMemory、UpdateMemory、DeleteMemory をそれぞれ使用)または動的に(GenerateMemories を使用)作成、更新、削除できます。メモリ リビジョン リソースは、すべてのミューテーション オペレーションにわたるメモリリソースの完全なバージョン履歴を提供します。メモリが作成または変更されるたびに、新しい不変のリビジョンが自動的に保存されます。これにより、メモリがどのように進化したか、また(メモリ生成の場合)各ステップで抽出および統合された特定の情報を把握できます。

すべてのメモリリソースには、1 つ以上の子メモリ リビジョン リソースが関連付けられています。

  • Memory リソースには、常に情報の現在の統合された状態が反映されます。1 つのメモリに、複数のリクエストとデータソースから派生したデータが反映されることがあります。

    Memory(
        create_time=datetime.datetime(...),
        fact='This is my current memory content after consolidation',
        name='projects/.../locations/.../reasoningEngines/../memories/...',
        scope={
          'my_scope_key': 'my_scope_value'
        },
        topics=[
          MemoryTopicId(
            managed_memory_topic=<ManagedTopicEnum.USER_PERSONAL_INFO: 'USER_PERSONAL_INFO'>
          ),
        ],
        update_time=datetime.datetime(...)
    )
    
  • MemoryRevisions リソースは、親メモリの過去の状態を表します。各リビジョンは、ミューテーション イベント時のメモリのスナップショットです。GenerateMemories を使用してメモリが変更された場合、リビジョンには、メモリの既存のコンテンツと統合される前にデータソース(extracted_memories)から抽出された情報も含まれます。

    MemoryRevision(
        create_time=datetime.datetime(...),
        expire_time=datetime.datetime(...),
        extracted_memories=[
          IntermediateExtractedMemory(
            fact='This information was extracted from my data source'
          ),
        ],
        fact='This is my current memory content after consolidation',
        name='projects/.../locations/.../reasoningEngines/.../memories/.../revisions/...'
    )
    

    メモリの修正はデフォルトで有効になっています。メモリ リビジョンを無効にするには、メモリ リビジョンを無効にするをご覧ください。

メモリーの作成

メモリは、CreateMemory を使用して直接作成することも、GenerateMemories を使用して動的に作成することもできます。メモリ生成では、同じスコープの同様の情報をカバーする既存のメモリがない場合にメモリが作成されます。

# Direct creation using CreateMemory
client.memory_banks.memories.create(name=memory_bank_name, ...)

# Dynamic creation using GenerateMemory
client.memory_banks.memories.generate(name=memory_bank_name, ...)

メモリが作成されると、1 つの Memory リソースと子 MemoryRevision が作成されます。

client.memory_banks.memories.get(name=memory_name)
"""
Memory(
  name="projects/123/locations/us-central1/reasoningEngines/456/memories/789",
  fact="This is my original fact.",
  ...
)
"""

list(client.memory_banks.memories.revisions.list(name=memory_name))
"""
[
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/123",
    fact="This is my original fact",
    ...
  )
]
"""

メモリーの更新

メモリは、UpdateMemory を使用して直接更新することも、GenerateMemories を使用して動的に更新することもできます。メモリ生成では、統合プロセスで、新しい情報が同じスコープの既存のすべてのメモリと重複している、補完している、または矛盾していると判断された場合に、メモリが動的に更新されます。

# Direct update using UpdateMemory
client.memory_banks.memories.update(name=memory_name, ...)

# Dynamic update using GenerateMemories
client.memory_banks.memories.generate(name=memory_bank_name, ...)

メモリが更新されると、既存の Memory リソースが更新され、新しい子 MemoryRevision が作成されます。

client.memory_banks.memories.get(name=memory_name)
"""
Memory(
  name="projects/123/locations/us-central1/reasoningEngines/456/memories/789",
  fact="This is my updated fact.",
  ...
)
"""

list(client.memory_banks.memories.revisions.list(name=memory_name))
"""
[
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/456",
    fact="This is my updated fact",
    ...
  ),
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/123",
    fact="This is my original fact",
    ...
  )
]
"""

メモリーの削除

メモリは、DeleteMemory を使用して直接使用することも、GenerateMemories を使用して動的に使用することもできます。メモリ生成では、統合プロセスで新しい情報が同じスコープの既存の情報を無効にすると判断された場合、メモリは動的に削除されます。

# Direct deletion using UpdateMemory
client.memory_banks.memories.delete(name=memory_name, ...)

# Dynamic delete using GenerateMemories
client.memory_banks.memories.generate(name=memory_bank_name, ...)

メモリが削除されると、既存の Memory リソースが削除され、新しい子 MemoryRevision が作成されます。最新のメモリ リビジョンの fact は、削除ミューテーションを反映しているため、空です。

client.memory_banks.memories.get(name=memory_name)
"""
404 Not Found.
"""

list(client.memory_banks.memories.revisions.list(name=memory_name))
"""
[
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/789",
    fact="",
    ...
  ),
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/456",
    fact="This is my updated fact",
    ...
  ),
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/123",
    fact="This is my original fact",
    ...
  )
]
"""

子メモリのリビジョンにアクセスできるのは、親メモリの削除後 48 時間以内です。この復元期間中は、メモリ リビジョンの検査を続行できます。また、以前のリビジョンにロールバックすることで、メモリを復元できます。

記憶リビジョン オペレーション

このセクションでは、メモリのリビジョンを検査し、メモリを以前のリビジョンにロールバックする方法について説明します。

リビジョンを一覧表示する

メモリ リビジョンは、 Google Cloud コンソールまたは Agent Platform SDK で確認できます。

コンソール

Google Cloud コンソールでメモリ リビジョンを表示するには、aiplatform.memoryRevisions.list 権限(roles/aiplatform.memoryViewer と roles/aiplatform.memoryUser に含まれています)が必要です。エクスプレス モードでは使用できません。

  1. Google Cloud コンソールでインスタンスを開きます。

    • スタンドアロンの Memory Bank インスタンス: Agent Platform の [Memory Bank] ページに移動し、インスタンスをクリックします。

      Memory Bank に移動

    • Agent Runtime にデプロイされたエージェント: Agent Platform の [デプロイ] ページに移動し、エージェントをクリックします。

      [デプロイメント] に移動

  2. [思い出] タブを開きます。

    • 非構造化メモリ: メモリ行で、その他の操作メニュー()> [リビジョンを表示] をクリックします。
    • 構造化プロファイル(スタンドアロン インスタンス): [構造化] を選択し、完全なスコープを選択します。プロファイルの行で [表示] をクリックして [メモリの詳細] を開き、メモリファクトの [リビジョンを表示] をクリックします。

    リビジョン パネルには、各リビジョンの [作成日時]、[有効期限]、[事実]、[コンテキスト] フィールドが表示されます。

Agent Platform SDK

ListMemoryRevisions を使用して、メモリに属するすべてのメモリ リビジョンを返します。

list(client.memory_banks.memories.revisions.list(name=MEMORY_NAME))

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

  • MEMORY_NAME: メモリのリソース名。形式は projects/.../locations/.../reasoningEngines/.../memories/... です。

メモリを生成するときに、関連するリビジョンに適用されるリビジョン ラベルを指定できます。ラベルは任意の Key-Value ペアです。たとえば、メモリの生成に使用されたデータソースの ID でリビジョンにラベルを付け、このラベルでリビジョンをフィルタできます。

response = client.memory_banks.memories.generate(
    ...,
    config={
        "revision_labels": {
            "data_source": "321"
        }
    }
)

list(client.memory_banks.memories.revisions.list(
    name=MEMORY_NAME,
    config={
      "filter": "labels.data_source=\"321\""
    }
))
"""
[
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/123",
    labels={
      "data_source": "123"
    }
    ...
  )
]
"""

リビジョンを取得する

GetMemoryRevision を使用して、個々のメモリ リビジョンを取得します。

client.memory_banks.memories.revisions.get(name=MEMORY_REVISION_NAME)

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

  • MEMORY_REVISION_NAME: 取得するメモリ リビジョンのリソース名。形式は projects/.../locations/.../reasoningEngines/.../memories/.../revisions/... です。

思い出をロールバックする

RollbackMemory を使用して、メモリを以前のリビジョンにロールバックします。

client.memory_banks.memories.rollback(
    name="MEMORY_NAME",
    target_revision_id="REVISION_ID"
)

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

  • MEMORY_NAME: 更新するメモリのリソース名。形式は projects/.../locations/.../reasoningEngines/.../memories/... です。

  • REVISION_ID: ロールバック先のリビジョンの ID。これは、メモリ リビジョン リソース名の最後のセグメントです(projects/MyProject/locations/us-central1/reasoningEngines/123/memories/456/revisions/789 の 789 など)。

GenerateMemories によって行われたメモリの変更を元に戻すには、メモリを変更前のリビジョンにロールバックします。メモリ生成レスポンスには、更新または削除された各メモリの以前のリビジョン(previous_revision)への参照が含まれます。

operation = client.memory_banks.memories.generate(
  ...
)

# Rollback the first generated memory to the previous revision.
client.memory_banks.memories.rollback(
    name=operation.response.generated_memories[0].memory.name,
    target_revision_id=operation.response.generated_memories[0].previous_revision
)

記憶リビジョンを無効にする

メモリの修正はデフォルトで有効になっています。メモリ リビジョンは、Memory Bank インスタンスへのすべてのリクエストに対して無効にすることも、個々のリクエストに対して無効にすることもできます。メモリリビジョンが無効になっている場合、メモリが変更されてもメモリリビジョンは作成されません。

Memory Bank インスタンスへのすべてのリクエストでメモリ リビジョンをオフにするには、 Google Cloud コンソール([構成] > [保持]、またはデプロイされたエージェントの [サービス構成] > [メモリバンク])または Agent Platform SDK を使用します。

memory_bank = client.memory_banks.create(
  managed_semantic_memory_config={
    "disable_memory_revisions": True
  }
)

リクエストを送信するときに、リクエスト レベルでメモリの修正を無効にできます。

生成

client.memory_banks.memories.generate(
  ...,
  "config": {
    "disable_memory_revisions": True
  }
)

作成

client.memory_banks.memories.create(
  ...,
  "config": {
    "disable_memory_revisions": True
  }
)

更新

client.memory_banks.memories.update(
  ...,
  "config": {
    "disable_memory_revisions": True
  }
)

リビジョン有効期限

メモリ リビジョンは永続的に保持されるわけではありません。リビジョンの有効期限を設定するか、デフォルトの有効期限を使用する必要があります。デフォルトの有効期間(TTL)は 365 日です。有効期限は、Memory Bank インスタンスへのすべてのリクエストに対して構成することも、個々のリクエストに対して構成することもできます。メモリ リビジョンの有効期限が切れると、検査やロールバックに使用できなくなります。

Memory Bank インスタンスへのすべてのリクエストの変更履歴 TTL は、 Google Cloud コンソール([構成] > [保持]、またはデプロイされたエージェントの [サービス構成] > [Memory Bank])または Agent Platform SDK で構成できます。

client.memory_banks.create(
  managed_semantic_memory_config={
    "ttl_config": {
      # Persist memory revisions for 30 days after they're created.
      "revision_ttl": f"{30 * 60 * 60 * 24}s"
    }
  }
)

リクエスト レベルで各メモリ リビジョンの TTL を構成するには、リクエストに revision_expire_time または revision_ttl を含めます。

TTL

config = {
    # Persist memory revisions for 30 days after they're created.
    "revision_ttl": f"{30 * 60 * 60 * 24}s"
}

client.memory_banks.memories.create(
  ...,
  config=config
)

client.memory_banks.memories.update(
  ...,
  config=config
)

client.memory_banks.memories.generate(
  ...,
  config=config
)

有効期限

import datetime

config = {
    "revision_expire_time": datetime.datetime.now(tz=datetime.timezone.utc) + datetime.timedelta(weeks=3)
}

client.memory_banks.memories.create(
  ...,
  config=config
)

client.memory_banks.memories.update(
  ...,
  config=config
)

client.memory_banks.memories.generate(
  ...,
  config=config
)