메모리 버전

메모리 뱅크는 메모리 버전 리소스를 통해 메모리의 버전 기록을 자동으로 유지합니다. 메모리가 생성되거나 수정될 때마다 새로운 변경 불가능한 버전이 저장되어 정보가 어떻게 발전하는지, 각 단계에서 무엇이 추출되었는지 투명하게 확인할 수 있습니다.

이 문서에서는 메모리 및 버전의 수명 주기를 설명하고 버전 나열, 가져오기, 롤백과 같은 작업을 설명합니다.

메모리 생성에 대한 자세한 내용은 메모리 생성을 참고하세요.

메모리 및 버전의 수명 주기

데이터 소스 및 메모리 수정사항

메모리는 직접 (CreateMemory, UpdateMemory, DeleteMemory 사용) 또는 동적(GenerateMemories 사용)으로 생성, 업데이트 또는 삭제할 수 있습니다. 메모리 버전 리소스는 모든 변경 작업에서 메모리 리소스의 전체 버전 기록을 제공합니다. 메모리가 생성되거나 수정될 때마다 새로운 변경 불가능한 버전이 자동으로 저장됩니다. 이를 통해 메모리가 어떻게 발전했는지, (메모리 생성의 경우) 각 단계에서 어떤 특정 정보가 추출되고 통합되었는지 투명하게 확인할 수 있습니다.

모든 메모리 리소스에는 하나 이상의 연결된 하위 메모리 버전 리소스가 있습니다.

  • Memory 리소스는 항상 정보의 현재 통합된 상태를 반영합니다. 단일 메모리는 여러 요청 및 데이터 소스의 파생 데이터를 반영할 수 있습니다.

    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=memory_bank_name, ...)

# Dynamic creation using GenerateMemory
client.agent_engines.memories.generate_memories(name=memory_bank_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=memory_bank_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=memory_bank_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/... 형식의 메모리 리소스 이름

메모리를 생성할 때 연결된 버전에 적용되는 버전 라벨을 제공할 수 있습니다. 라벨은 임의의 키-값 쌍입니다. 예를 들어 메모리를 생성하는 데 사용된 데이터 소스의 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 = 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일입니다. 메모리 뱅크 인스턴스에 대한 모든 요청 또는 각 개별 요청에 대해 만료를 구성할 수 있습니다. 메모리 버전이 만료되면 검사하거나 롤백할 수 없습니다.

인스턴스를 설정할 때 메모리 뱅크 인스턴스에 대한 모든 요청에 대해 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
)