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

メモリリビジョン

このページでは、Vertex AI Agent Engine Memory Bank のメモリリビジョンリソースの作成と管理の方法について説明します。

思い出とそのリビジョンのライフサイクル

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

メモリは、直接（それぞれ 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.agent_engines.memories.create(name=agent_engine_name, ...)

# Dynamic creation using GenerateMemory
client.agent_engines.memories.generate_memories(name=agent_engine_name, ...)

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

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

list(client.agent_engines.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.agent_engines.memories.update(name=memory_name, ...)

# Dynamic update using GenerateMemories
client.agent_engines.memories.generate_memories(name=agent_engine_name, ...)

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

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

list(client.agent_engines.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.agent_engines.memories.delete(name=memory_name, ...)

# Dynamic delete using GenerateMemories
client.agent_engines.memories.generate_memories(name=agent_engine_name, ...)

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

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

list(client.agent_engines.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 時間までしかアクセスできません。この復元期間中は、メモリリビジョンを検査し続けることができ、以前のリビジョンにロールバックすることでメモリを復元できます。

メモリリビジョンオペレーション

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

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

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

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

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

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

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

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

list(client.agent_engines.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.agent_engines.memories.revisions.get(name=MEMORY_REVISION_NAME)

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

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

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

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

client.agent_engines.memories.rollback(
    name=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.agent_engines.memories.generate(
  ...
)

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

メモリリビジョンの無効化

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

インスタンスの設定時に、Memory Bank インスタンスに対するすべてのリクエストでメモリリビジョンを無効にできます。

client.agent_engines.create(
  config={
    "context_spec": {
      "memory_bank_config": {
        "disable_memory_revisions": True
      }
    }
  }
)

リクエストを送信するときに、リクエストレベルでメモリリビジョンを無効にできます。

生成

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

作成

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

更新

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

リビジョンの有効期限

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

インスタンスの設定時に、Memory Bank インスタンスに対するすべてのリクエストの TTL を構成できます。

client.agent_engines.create(
  config={
    "context_spec": {
      "memory_bank_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.agent_engines.memories.create(
  ...,
  config=config
)

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

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

有効期限

import datetime

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

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

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

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

メモリ リビジョン コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

思い出とそのリビジョンのライフサイクル

思い出の作成

思い出の更新

メモリーの削除

メモリ リビジョン オペレーション

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

リビジョンを取得する

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

メモリ リビジョンの無効化

生成

作成

更新

リビジョンの有効期限

TTL

有効期限

メモリリビジョン

メモリリビジョンオペレーション

メモリリビジョンの無効化