Mengambil kenangan

Memory Bank memungkinkan Anda mengambil memori tersimpan menggunakan berbagai operasi, bergantung pada kebutuhan Anda. Anda dapat mengambil satu kenangan, mencantumkan semua kenangan, atau melakukan pengambilan berbasis cakupan dengan penelusuran kesamaan.

Dokumen ini menjelaskan cara menggunakan operasi pengambilan ini menggunakan Agent Platform SDK.

Jika Anda menggunakan Agent Development Kit (ADK), agen Anda dapat mengoordinasikan panggilan ini secara otomatis untuk Anda. Lihat Panduan memulai ADK.

Sebelum memulai

Untuk menyelesaikan langkah-langkah di halaman ini, Anda harus menyelesaikan langkah-langkah di Menyiapkan untuk Bank Memori terlebih dahulu.

Operasi pengambilan

Anda memiliki opsi berikut untuk mengambil kenangan yang dibuat:

  • Mendapatkan memori: Mendapatkan konten lengkap satu memori menggunakan Agent Platform SDK.

  • Mengambil memori: Menggunakan Agent Platform SDK, ambil memori menggunakan pengambilan memori berbasis cakupan. Mengambil kenangan menggunakan penelusuran kesamaan atau semua kenangan dalam cakupan.

  • Mencantumkan kenangan: Mencantumkan kenangan menggunakan Agent Platform SDK.

Dapatkan kenangan

Gunakan GetMemories untuk mendapatkan konten lengkap dari satu kenangan:

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

Ganti kode berikut:

  • MEMORY_NAME: Nama memori yang sepenuhnya memenuhi syarat dalam format "projects/.../locations/.../reasoningEngines/.../memories...".

Mengambil kenangan menggunakan pengambilan berbasis cakupan

Anda dapat menggunakan RetrieveMemories untuk mengambil kenangan untuk cakupan tertentu. Hanya memori yang memiliki cakupan yang sama persis (terlepas dari urutan) dengan permintaan pengambilan yang ditampilkan. Misalnya, Anda dapat mengambil semua kenangan yang dicakup untuk pengguna tertentu dengan menggunakan {"user_id": "123"}. Jika tidak ada memori yang ditampilkan, Memory Bank tidak memiliki memori untuk cakupan yang diberikan.

Cakupan kenangan ditentukan saat kenangan dibuat atau dihasilkan dan bersifat tetap.

Anda dapat menggunakan RetrieveMemories untuk melakukan operasi berikut untuk cakupan tertentu:

Untuk kasus ketika Anda memiliki banyak kenangan untuk cakupan tertentu, Anda dapat menggunakan penelusuran kesamaan untuk mengambil hanya kenangan yang paling mirip dengan memberikan parameter penelusuran kesamaan. Memory Bank hanya mempertimbangkan kenangan yang memiliki cakupan yang sama persis dengan permintaan saat melakukan penelusuran kesamaan. Penelusuran kemiripan membandingkan vektor sematan antara fakta memori dan kueri penelusuran permintaan.

Kenangan yang ditampilkan diurutkan dari yang paling mirip (jarak Euclidean terpendek) hingga yang paling tidak mirip (jarak Euclidean terpanjang):

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
    ),
]
"""

Ganti kode berikut:

  • QUERY: Kueri yang akan digunakan untuk melakukan penelusuran kesamaan. Misalnya, Anda dapat menggunakan giliran percakapan terakhir pengguna sebagai kueri.

  • SCOPE: Kamus, yang mewakili cakupan untuk penelusuran kemiripan. Contoh, {"user_id": "123"}. Hanya kenangan dengan cakupan yang sama seperti permintaan yang dipertimbangkan.

Mengambil semua kenangan

Jika tidak ada parameter penelusuran kemiripan yang diberikan, RetrieveMemories akan menampilkan semua kenangan yang memiliki cakupan yang diberikan, terlepas dari kemiripannya dengan percakapan saat ini.

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."
      }
    ),
]
"""

Ganti kode berikut:

  • SCOPE: Kamus yang mewakili cakupan untuk pengambilan. Contoh, {"user_id": "123"}. Hanya kenangan dengan cakupan yang sama dengan permintaan yang akan ditampilkan.

Mencantumkan kenangan

Gunakan ListMemories untuk mengakses kenangan dari Bank Memori Anda tanpa pemfilteran berbasis cakupan. Untuk pengambilan berbasis cakupan, gunakan RetrieveMemories. ListMemories tidak direkomendasikan untuk pengambilan latensi rendah.

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

Memfilter kenangan

Bagian ini menjelaskan cara menggunakan filter untuk membatasi kenangan yang diambil. Anda dapat memfilter berdasarkan:

  • Metadata menggunakan atribut filter_groups untuk pengambilan berbasis cakupan.

  • Kolom sistem menggunakan filter. Kolom sistem mencakup topics, create_time, update_time, dan fact kenangan.

Pemfilteran kolom metadata dan sistem dapat digunakan dalam permintaan yang sama.

Memfilter menurut metadata

Saat membuat, memperbarui, atau membuat kenangan, Anda dapat menerapkan metadata terstruktur ke kenangan yang disimpan:

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}
)

Anda dapat memfilter metadata ini saat mengambil kenangan menggunakan atribut filter_groups. Filter metadata ditentukan dalam bentuk normal disjungtif (DNF), yang merupakan ekspresi logis OR dari AND.

Misalnya, permintaan berikut akan mengambil kenangan yang menyertakan metadata ({"my_string_key": {"string_value": "my_value"}} DAN {"my_double_key": {"double": 1.23}}) ATAU {"my_string_key": {"string_value": "other"}}.

Kamus

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"}
          }
        ]
      }
    ]
  }
)

Berbasis kelas

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")
          )
        ]
      )
    ]
  )
)

Memfilter menurut kolom sistem

Anda dapat memfilter kolom sistem menggunakan atribut filter, yang mengharapkan nilai string menggunakan sintaksis EBNF. Kolom sistem mencakup create_time, update_time, fact, dan topics.

Sintaksis EBNF memiliki persyaratan berikut saat membuat string filter:

  • Untuk menggabungkan filter, gunakan AND dan OR.
  • String harus menggunakan tanda kutip ganda ".
  • Kolom tanggal & waktu (seperti create_time) menggunakan string yang mewakili tanggal & waktu ISO 8601 yang diapit tanda petik ganda atau kolom numerik yang mewakili mikrodetik dari epoch unix.

Misalnya, filter berikut dapat digunakan untuk mengambil kenangan saat fact mencakup substring "alergi" dan update_time setelah 1 Januari 2026.

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}
)

Memfilter menurut topik

Kenangan yang dibuat otomatis diberi label dengan topik kenangan yang relevan.

Untuk memfilter topik terkelola, gunakan topics.managed_memory_topic sebagai nama kolom dan ManagedTopicEnum yang diharapkan sebagai nilai, seperti topics.managed_memory_topic: USER_PREFERENCES.

Untuk memfilter topik kustom, gunakan topics.custom_memory_topic_label sebagai nama kolom dan label topik yang diharapkan sebagai nilai, seperti 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}
)