記憶リビジョン

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.memory_banks.memories.create(name=memory_bank_name, ...)

# Dynamic creation using GenerateMemory
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 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 時間までです。この復元期間中は、メモリ リビジョンを検査し続けることができます。また、以前のリビジョンにロールバックすることで、メモリを復元できます。

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

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

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

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 = 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 日です。有効期限は、メモリバンク インスタンスへのすべてのリクエストに対して構成することも、個々のリクエストに対して構成することもできます。メモリ リビジョンの有効期限が切れると、検査やロールバックはできなくなります。

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

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
)