기억 가져오기

메모리 뱅크를 사용하면 필요에 따라 다양한 작업을 사용하여 저장된 기억을 검색할 수 있습니다. 단일 기억을 가져오거나, 모든 기억을 나열하거나, 유사성 검색으로 범위 기반 검색을 실행할 수 있습니다.

이 문서에서는 Agent Platform SDK를 사용하여 이러한 가져오기 작업을 사용하는 방법을 설명합니다.

에이전트 개발 키트 (ADK)를 사용하는 경우 에이전트가 이러한 호출을 자동으로 오케스트레이션할 수 있습니다. ADK 빠른 시작을 참조하세요.

시작하기 전에

이 페이지의 단계를 완료하려면 먼저 메모리 뱅크 설정의 단계를 완료해야 합니다.

가져오기 작업

생성된 기억을 가져오는 옵션은 다음과 같습니다.

  • 기억 가져오기: Agent Platform SDK를 사용하여 단일 기억의 전체 콘텐츠를 가져옵니다.

  • 기억 검색: Agent Platform SDK를 사용하여 범위 기반 기억 검색을 사용하여 기억을 검색합니다. 유사 검색을 사용하거나 범위 내의 모든 기억을 검색합니다.

  • 기억 나열: Agent Platform SDK를 사용하여 기억을 나열합니다.

기억 가져오기

GetMemories을 사용하여 단일 기억의 전체 콘텐츠를 가져옵니다.

memory = client.memory_banks.memories.get(
    name="MEMORY_NAME")

다음을 바꿉니다.

  • MEMORY_NAME: 'projects/.../locations/.../reasoningEngines/.../memories...' 형식의 정규화된 기억 이름

범위 기반 검색을 사용하여 기억 가져오기

RetrieveMemories를 사용하여 특정 범위의 기억을 검색할 수 있습니다. 검색 요청과 정확히 동일한 범위 (순서와 관계 없음)의 기억만 반환됩니다. 예를 들어 {"user_id": "123"}을 사용하여 특정 사용자로 범위가 지정된 모든 기억을 검색할 수 있습니다. 반환된 기억이 없으면 메모리 뱅크에 제공된 범위의 기억이 없는 것입니다.

기억의 범위는 기억가 생성되거나 만들어질 때 정의되며 변경할 수 없습니다.

RetrieveMemories를 사용하여 특정 범위에 대해 다음 작업을 실행할 수 있습니다.

특정 범위의 기억이 많은 경우 유사 검색을 사용하여 유사 검색 파라미터를 제공하여 가장 유사한 기억만 검색할 수 있습니다. 메모리 뱅크는 유사 검색을 실행할 때 요청과 정확히 동일한 범위의 기억만 고려합니다. 유사성 검색은 기억의 사실과 요청의 검색어 간에 임베딩 벡터를 비교합니다.

반환된 기억은 가장 유사한 기억 (유클리드 거리가 가장 짧음)에서 가장 유사하지 않은 기억 (유클리드 거리가 가장 큼) 순으로 정렬됩니다.

results = client.memory_banks.memories.retrieve(
    name=memory_bank.name,
    scope=SCOPE,
    similarity_search_params={
        "search_query": "QUERY",
        # Optional. Defaults to 3.
        "top_k": 3
    }
)
# RetrieveMemories returns a pager. You can use `page` to retrieve memories.

results.page

"""
Returns:

[
    RetrieveMemoriesResponseRetrievedMemory(
      memory=Memory(
        name="projects/.../locations/.../reasoningEngines/.../memories/...",
        ...
        fact="This is a fact."
      },
      distance=0.5
    ),
    RetrieveMemoriesResponseRetrievedMemory(
      memory=Memory(
        name="projects/.../locations/.../reasoningEngines/.../memories/...",
        ...
        fact="This is another fact."
      },
      distance=0.7
    ),
]
"""

다음을 바꿉니다.

  • QUERY: 유사 검색을 실행할 쿼리. 예를 들어 대화의 마지막 사용자 턴을 쿼리로 사용할 수 있습니다.

  • SCOPE: 유사성 검색의 범위를 나타내는 사전. 예를 들면 {"user_id": "123"}입니다. 요청과 범위가 동일한 기억만 고려됩니다.

모든 기억 검색

유사성 검색 파라미터가 제공되지 않으면 RetrieveMemories는 현재 대화와의 유사성과 관계없이 제공된 범위가 있는 모든 기억을 반환합니다.

results = client.memory_banks.memories.retrieve(
    name=memory_bank.name,
    scope=SCOPE
)
# RetrieveMemories returns a pager. You can use `page` to retrieve up to 100 memories per page.

results.page

"""
Returns:

[
    RetrieveMemoriesResponseRetrievedMemory(
      memory=Memory(
        name="projects/.../locations/.../reasoningEngines/.../memories/...",
        ...
        fact="This is a fact."
      }
    ),
    RetrieveMemoriesResponseRetrievedMemory(
      memory=Memory(
        name="projects/.../locations/.../reasoningEngines/.../memories/...",
        ...
        fact="This is another fact."
      }
    ),
]
"""

다음을 바꿉니다.

  • SCOPE: 검색 범위를 나타내는 사전. 예를 들면 {"user_id": "123"}입니다. 요청과 범위가 동일한 기억만 반환됩니다.

기억 나열

ListMemories를 사용하여 범위 기반 필터링 없이 메모리 뱅크에서 기억을 가져옵니다. 범위 기반 검색의 경우 RetrieveMemories를 대신 사용합니다. ListMemories는 지연 시간이 짧은 검색에는 권장되지 않습니다.

pager = client.memory_banks.memories.list(name=memory_bank.name)
for page in pager:
  print(page)

기억 필터링

이 섹션에서는 필터를 사용하여 가져올 기억을 제한하는 방법을 설명합니다. 다음을 기준으로 필터링할 수 있습니다.

메타데이터 필터링과 시스템 필드 필터링은 모두 동일한 요청에서 사용할 수 있습니다.

메타데이터로 필터링

기억을 만들거나 업데이트하거나 생성할 때 저장된 기억에 구조화된 메타데이터를 적용할 수 있습니다.

import datetime

from agentplatform import types

metadata = {
    "my_string_key": types.MemoryMetadataValue(string_value="my_string_value"),
    "my_double_key": types.MemoryMetadataValue(double_value=123.456),
    "my_boolean_key": types.MemoryMetadataValue(bool_value=True),
    "my_timestamp_key": types.MemoryMetadataValue(
        timestamp_value=datetime.datetime(
            2027, 1, 1, 12, 30, 00, tzinfo=datetime.timezone.utc
        )
    ),
}

client.memory_banks.memories.create(
  ...,
  config={"metadata": metadata}
)

client.memory_banks.memories.update(
  ...,
  config={"metadata": metadata}
)

client.memory_banks.memories.generate(
  ...,
  config={"metadata": metadata}
)

filter_groups 속성을 사용하여 기억을 검색할 때 이 메타데이터를 필터링할 수 있습니다. 메타데이터 필터는 논리합 표준형 (DNF)으로 정의되며, 이는 논리곱(AND)의 논리합(OR)인 논리식입니다.

예를 들어 다음 요청은 메타데이터 ({"my_string_key": {"string_value": "my_value"}} AND {"my_double_key": {"double": 1.23}}) 또는 {"my_string_key": {"string_value": "other"}}를 포함하는 기억을 검색합니다.

딕셔너리

results = client.memory_banks.memories.retrieve(
  ...,
  config={
    # Each element of `filter_groups` is combined using OR logic.
    "filter_groups": [
      {
        # Each element of `filters` is combined using AND logic.
        "filters": [
          {
            "key": "my_string_key",
            "value": {"string_value": "my_value"}
          },
          {
            "key": "my_double_key",
            "value": {"double_value": 1.23}
          }
        ]
      },
      {
        "filters": [
          {
            "key": "my_string_key",
            "value": {"string_value": "other"}
          }
        ]
      }
    ]
  }
)

클래스 기반

from agentplatform import types

results = client.memory_banks.memories.retrieve(
  ...,
  config=types.RetrieveMemoriesConfig(
    # Each element of `filter_groups` is combined using OR logic.
    filter_groups=[
      types.MemoryConjunctionFilter(
        # Each element of `filters` is combined using AND logic.
        filters=[
          types.MemoryFilter(
            key="my_string_key",
            value=types.MemoryMetadataValue(string_value="my_value")
          ),
          types.MemoryFilter(
            key="my_double_key",
            value=types.MemoryMetadataValue(double_value=1.23)
          )
        ]
      ),
      types.MemoryConjunctionFilter(
        filters=[
          types.MemoryFilter(
            key="my_string_key",
            value=types.MemoryMetadataValue(string_value="other")
          )
        ]
      )
    ]
  )
)

시스템 필드로 필터링

EBNF 시스템 필드에는 create_time, update_time, fact, and topics가 포함됩니다.

EBNF 구문에는 필터 문자열을 구성할 때 다음과 같은 요구사항이 있습니다.

  • 필터를 결합하려면 AND 및 OR을 사용합니다.
  • 문자열은 큰따옴표 "를 사용해야 합니다.
  • 날짜/시간 필드 (create_time 등)는 ISO 8601 날짜/시간을 나타내는 큰따옴표로 묶인 문자열 또는 Unix Epoch의 마이크로초를 나타내는 숫자 필드를 사용합니다.

예를 들어 다음 필터를 사용하여 fact에 하위 문자열 'allergies'가 포함되고 update_time이 2026년 1월 1일 이후인 기억을 가져올 수 있습니다.

filter_string = 'fact=~".*allergies.*" AND update_time>="2026-01-01T00:00:00Z"'

client.memory_banks.memories.retrieve(
  ...,
  config={"filter": filter_string}
)

client.memory_banks.memories.list(
  ...,
  config={"filter": filter_string}
)

주제별 필터링

생성된 기억에는 관련 기억 주제가 자동으로 라벨링됩니다.

관리되는 주제를 필터링하려면 topics.managed_memory_topic을 필드 이름으로 사용하고 예상되는 ManagedTopicEnum을 값으로 사용합니다(예: topics.managed_memory_topic: USER_PREFERENCES).

커스텀 주제를 필터링하려면 topics.custom_memory_topic_label을 필드 이름으로 사용하고 예상되는 주제의 라벨을 값으로 사용합니다(예: topics.custom_memory_topic_label: custom-label).

filter_string = "topics.managed_memory_topic: USER_PREFERENCES " + \
"OR topics.custom_memory_topic_label: custom-label"

client.memory_banks.memories.retrieve(
  ...,
  config={"filter": filter_string}
)

client.memory_banks.memories.list(
  ...,
  config={"filter": filter_string}
)