Membuat kenangan

Agent Platform Memory Bank memungkinkan Anda membuat memori jangka panjang dari percakapan antara pengguna dan agen Anda. Proses ini terjadi secara otomatis saat dipicu, mengekstrak informasi berharga untuk interaksi mendatang.

Dokumen ini menjelaskan cara kerja pembuatan memori, cara menyesuaikan ekstraksi memori dengan topik, dan cara memicu permintaan pembuatan memori.

Untuk mengetahui informasi tentang cara menyiapkan lingkungan Anda, lihat Menyiapkan Memory Bank.

Memahami pembuatan memori

Memory Bank mengekstrak memori dari data sumber dan mengumpulkan memori secara mandiri untuk koleksi memori tertentu (ditentukan oleh scope) dengan menambahkan, memperbarui, dan menghapus memori seiring waktu.

Saat Anda memicu pembuatan memori, Memory Bank akan melakukan operasi berikut:

  • Ekstraksi: Mengekstrak informasi tentang pengguna dari percakapan mereka dengan agen. Hanya informasi yang cocok dengan setidaknya satu topik memori instance Anda yang akan dipertahankan.

  • Konsolidasi: Mengidentifikasi apakah memori yang ada dengan cakupan yang sama harus dihapus atau diperbarui berdasarkan informasi yang diekstrak. Bank Memori memeriksa apakah memori baru tidak duplikatif atau kontradiktif sebelum menggabungkannya dengan memori yang ada. Jika memori yang ada tidak tumpang-tindih dengan informasi baru, memori baru akan dibuat.

    • Secara default, Memory Bank akan mempertimbangkan semua memori yang ada untuk cakupan yang sama selama konsolidasi. Jika Anda ingin membatasi memori yang memenuhi syarat untuk konsolidasi secara lebih terperinci menggunakan metadata, gunakan strategi penggabungan metadata REQUIRE_EXACT_MATCH.

    • Secara default, hanya revisi memori terbaru yang digunakan untuk perbandingan. Untuk mengidentifikasi tren jangka panjang dengan lebih baik dan mengonfirmasi data, Anda dapat meningkatkan revisions_per_candidate_count saat membuat instance Agent Platform untuk menyertakan lebih banyak revisi historis dalam logika konsolidasi.

Algoritma pembuatan memori

Anda dapat memeriksa langkah-langkah perantara pembuatan memori dan melihat perubahan memori di beberapa permintaan menggunakan revisi memori. Setiap revisi mencakup output perantara dari langkah ekstraksi (extracted_memories) dan langkah konsolidasi akhir (fact) untuk setiap permintaan pembuatan memori.

list(client.memory_banks.memories.revisions.list(
  name="projects/.../locations/.../reasoningEngines/.../memories/.../revisions/..."))

"""
[
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/456",
    fact="This is my updated fact",
    extracted_memories=[
      IntermediateExtractedMemory(
        fact='This is the output of extraction for a single request.'
      ),
    ],
    ...
  ),
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/123",
    fact="This is my original fact",
    extracted_memories=[
      IntermediateExtractedMemory(
        fact='This is my original fact.'
      ),
    ],
    ...
  )
]
"""

Topik memori

"Topik memori" mengidentifikasi informasi yang dianggap bermakna oleh Memory Bank dan oleh karena itu harus dipertahankan sebagai memori yang dihasilkan. Memory Bank mendukung dua jenis topik memori:

  • Topik terkelola: Label dan petunjuk ditentukan oleh Memory Bank. Anda hanya perlu memberikan nama topik terkelola. Contoh:

    Kamus

    memory_topic = {
        "managed_memory_topic": {
            "managed_topic_enum": "USER_PERSONAL_INFO"
        }
    }
    

    Berbasis kelas

    from agentplatform.types import ManagedTopicEnum
    from agentplatform.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
    from agentplatform.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic
    
    memory_topic = MemoryTopic(
        managed_memory_topic=ManagedMemoryTopic(
            managed_topic_enum=ManagedTopicEnum.USER_PERSONAL_INFO
        )
    )
    
  • Topik kustom: Label dan petunjuk ditentukan oleh Anda saat menyiapkan instance Memory Bank. Contoh ini akan digunakan dalam perintah untuk langkah ekstraksi Memory Bank. Contoh:

    Kamus

    memory_topic = {
        "custom_memory_topic": {
            "label": "business_feedback",
            "description": """Specific user feedback about their experience
            at the coffee shop. This includes opinions on drinks, food,
            pastries, ambiance, staff friendliness, service speed,
            cleanliness, and any suggestions for improvement."""
        }
    }
    

    Berbasis kelas

    from agentplatform.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
    from agentplatform.types import MemoryBankCustomizationConfigMemoryTopicCustomMemoryTopic as CustomMemoryTopic
    
    memory_topic = MemoryTopic(
        custom_memory_topic=CustomMemoryTopic(
            label="business_feedback",
            description="""Specific user feedback about their experience at
            the coffee shop. This includes opinions on drinks, food,
            pastries, ambiance, staff friendliness, service speed,
            cleanliness, and any suggestions for improvement."""
        )
    )
    

    Saat menggunakan topik kustom, sebaiknya berikan juga contoh few-shot untuk menunjukkan cara mengekstrak memori dari percakapan Anda.

Secara default, Memory Bank mempertahankan semua topik terkelola berikut:

  • Informasi pengguna (USER_PERSONAL_INFO): Informasi penting tentang pengguna, seperti nama, hubungan, hobi, dan tanggal penting. Misalnya, "Saya bekerja di Google" atau "Ulang tahun pernikahan saya pada 31 Desember".

  • Preferensi pengguna (USER_PREFERENCES): Hal yang disukai, tidak disukai, gaya, atau pola yang disukai, baik yang dinyatakan maupun yang tersirat. Misalnya, "Saya lebih suka kursi tengah".

  • Peristiwa percakapan utama dan hasil tugas (KEY_CONVERSATION_DETAILS): Pencapaian atau kesimpulan penting dalam dialog. Misalnya, "Saya memesan tiket pesawat pulang pergi antara JFK dan SFO. Saya berangkat pada 1 Juni 2025 dan kembali pada 7 Juni 2025."

  • Petunjuk eksplisit untuk mengingat/melupakan (EXPLICIT_INSTRUCTIONS): Informasi yang secara eksplisit diminta oleh pengguna untuk diingat atau dilupakan oleh agen. Misalnya, jika pengguna mengatakan "Ingat bahwa saya terutama menggunakan Python", Memory Bank akan menghasilkan memori seperti "Saya terutama menggunakan Python".

Hal ini setara dengan menggunakan kumpulan topik memori terkelola berikut:

Kamus

  memory_topics = [
      {"managed_memory_topic": {"managed_topic_enum": "USER_PERSONAL_INFO"}},
      {"managed_memory_topic": {"managed_topic_enum": "USER_PREFERENCES"}},
      {"managed_memory_topic": {"managed_topic_enum": "KEY_CONVERSATION_DETAILS"}},
      {"managed_memory_topic": {"managed_topic_enum": "EXPLICIT_INSTRUCTIONS"}},
  ]

Berbasis kelas

from agentplatform.types import ManagedTopicEnum
from agentplatform.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from agentplatform.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic

memory_topics = [
  MemoryTopic(
      managed_memory_topic=ManagedMemoryTopic(
          managed_topic_enum=ManagedTopicEnum.USER_PERSONAL_INFO)),
  MemoryTopic(
      managed_memory_topic=ManagedMemoryTopic(
          managed_topic_enum=ManagedTopicEnum.USER_PREFERENCES)),
  MemoryTopic(
      managed_memory_topic=ManagedMemoryTopic(
          managed_topic_enum=ManagedTopicEnum.KEY_CONVERSATION_DETAILS)),
  MemoryTopic(
      managed_memory_topic=ManagedMemoryTopic(
          managed_topic_enum=ManagedTopicEnum.EXPLICIT_INSTRUCTIONS)),
]

Jika Anda ingin menyesuaikan topik yang dipertahankan Memory Bank, tetapkan topik memori dalam konfigurasi penyesuaian saat menyiapkan Memory Bank.

Menggunakan metadata selama konsolidasi

Anda dapat melampirkan metadata ke kenangan yang dihasilkan. Metadata memungkinkan Anda menyimpan informasi terstruktur (string, double, boolean, atau stempel waktu) bersama dengan fakta memori. Hal ini berguna untuk memfilter atau mengelola siklus proses memori.

Kamus

import datetime

client.memory_banks.memories.generate(
    ...,
    config={
        "metadata": {
            "my_string_key": {"string_value": "my_string_value"},
            "my_double_key": {"double_value": 123.456},
            "my_boolean_key": {"bool_value": True},
            "my_timestamp_key": {
                "timestamp_value": datetime.datetime(
                    2027, 1, 1, 12, 30, 00, tzinfo=datetime.timezone.utc
                )
            }
        },
        "metadata_merge_strategy": "MERGE"
    },
)

Berbasis kelas

import datetime

from agentplatform import types

client.memory_banks.memories.generate(
    ...,
    config=types.GenerateMemoriesConfig(
        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
                )
            ),
        },
        metadata_merge_strategy=types.MemoryMetadataMergeStrategy.MERGE,
    )
)

Dengan menggunakan metadata_merge_strategy, Anda dapat mengontrol cara metadata baru berinteraksi dengan memori yang ada selama konsolidasi:

  • MERGE: (Default) Menggabungkan metadata baru dengan metadata yang ada. Jika kunci sudah ada, nilai baru akan menimpa nilai lama.

  • OVERWRITE: Ganti metadata memori yang diperbarui dengan metadata baru.

  • REQUIRE_EXACT_MATCH: Batasi konsolidasi ke memori yang memiliki metadata yang sama persis dengan permintaan. Jika suatu kenangan tidak memiliki metadata yang sama, kenangan tersebut tidak memenuhi syarat untuk penggabungan dan tidak akan diperbarui.

Membuat kenangan untuk subset topik

Secara default, pembuatan memori mengekstrak data untuk semua topik memori yang Anda konfigurasi saat menyiapkan instance Memory Bank. Untuk permintaan GenerateMemories tertentu, Anda dapat membatasi ekstraksi ke subset topik yang dikonfigurasi. Untuk mengonfigurasi topik yang diizinkan, gunakan kolom allowed_topics.

Kamus

client.memory_banks.memories.generate(
    ...,
    config={
        "allowed_topics": [
            {"managed_memory_topic": "USER_PERSONAL_INFO"},
            {"custom_memory_topic_label": "business_feedback"}
        ]
    },
)

Berbasis kelas

from agentplatform import types

client.memory_banks.memories.generate(
    ...,
    config=types.GenerateMemoriesConfig(
        allowed_topics=[
            types.MemoryTopicId(
                managed_memory_topic=types.ManagedTopicEnum.USER_PERSONAL_INFO
            ),
            types.MemoryTopicId(
                custom_memory_topic_label="business_feedback"
            )
        ]
    )
)

Memicu pembuatan memori

Anda dapat memicu pembuatan memori menggunakan salah satu metode berikut:

  • GenerateMemories: Serap data ke Bank Memori dan segera picu pembuatan memori. Metode ini berguna jika Anda ingin membuat memori pada titik waktu tertentu, seperti di akhir sesi atau pada interval reguler dalam sesi.
  • IngestEvents: Serap data ke Memory Bank secara terus-menerus dan biarkan Memory Bank memprosesnya saat kriteria pemicu Anda terpenuhi. Metode ini berguna saat Anda memiliki aliran peristiwa yang berkelanjutan dan ingin Memory Bank menangani buffering secara otomatis serta memicu pembuatan memori berdasarkan volume atau waktu. Untuk mengetahui informasi selengkapnya, lihat Menyerap peristiwa.

Pembuatan memori mengekstrak konteks penting dari percakapan sumber dan menggabungkannya dengan memori yang ada untuk cakupan yang sama. Misalnya, Anda dapat membuat memori tingkat sesi menggunakan cakupan seperti {"user_id": "123", "session_id": "456"}. Memori dengan cakupan yang sama dapat digabungkan dan diambil bersama-sama.

GenerateMemories adalah operasi yang berjalan lama. Setelah operasi selesai, GenerateMemoriesOperation akan berisi daftar kenangan yang dihasilkan, jika ada yang dihasilkan:

GenerateMemoriesOperation(
  name="projects/.../locations/.../reasoningEngines/.../operations/...",
  done=True,
  response=GenerateMemoriesResponse(
    generatedMemories=[
      GenerateMemoriesResponseGeneratedMemory(
        memory=Memory(
          "name": "projects/.../locations/.../reasoningEngines/.../memories/..."
        ),
        action="CREATED",
      ),
      GenerateMemoriesResponseGeneratedMemory(
        memory=Memory(
          "name": "projects/.../locations/.../reasoningEngines/.../memories/..."
        ),
        action="UPDATED",
      ),
      GenerateMemoriesResponseGeneratedMemory(
        memory=Memory(
          "name": "projects/.../locations/.../reasoningEngines/.../memories/..."
        ),
        action="DELETED",
      ),
    ]
  )
)

Setiap memori yang dihasilkan menyertakan action yang dilakukan pada memori tersebut:

  • CREATED: Menunjukkan bahwa memori baru telah ditambahkan, yang mewakili konsep baru yang tidak tercakup dalam memori yang ada.

  • UPDATED: Menunjukkan bahwa memori yang ada telah diperbarui, yang terjadi jika memori tersebut mencakup konsep yang serupa dengan informasi yang baru diekstrak. Fakta memori dapat diperbarui dengan informasi baru atau tetap sama.

  • DELETED: Menunjukkan bahwa memori yang ada telah dihapus, karena informasinya bertentangan dengan informasi baru yang diekstrak dari percakapan.

Untuk memori CREATED atau UPDATED, Anda dapat menggunakan GetMemories untuk mengambil konten lengkap memori. Pengambilan memori DELETED menghasilkan error 404.

Membuat kenangan di latar belakang

GenerateMemories adalah operasi yang berjalan lama. Secara default, client.memory_banks.memories.generate adalah fungsi pemblokiran yang melakukan polling operasi hingga operasi selesai. Menjalankan pembuatan memori sebagai operasi pemblokiran akan membantu jika Anda ingin memeriksa memori yang dihasilkan secara manual atau memberi tahu pengguna akhir tentang memori yang dihasilkan.

Namun, untuk agen produksi, Anda biasanya ingin menjalankan pembuatan memori di latar belakang sebagai proses asinkron. Pada umumnya, klien tidak perlu menggunakan output untuk operasi saat ini, sehingga tidak perlu menimbulkan latensi tambahan saat menunggu respons. Jika Anda ingin pembuatan memori dijalankan di latar belakang, tetapkan wait_for_completion ke False:

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

Sebagai alternatif untuk memanggil GenerateMemories secara asinkron, Anda dapat menggunakan IngestEvents, yang memisahkan penyerapan peristiwa dari pembuatan memori dan memproses peristiwa di latar belakang secara default.

Sumber data

Ada beberapa cara untuk menyediakan data sumber untuk pembuatan memori:

Saat Anda memberikan peristiwa langsung dalam payload atau menggunakan Sesi, informasi akan diekstrak dari percakapan dan digabungkan dengan memori yang ada. Jika Anda hanya ingin mengekstrak informasi dari sumber data ini, Anda dapat menonaktifkan konsolidasi:

client.memory_banks.memories.generate(
    ...
    config={
        "disable_consolidation": True
    }
)

Menggunakan peristiwa dalam payload sebagai sumber data

Gunakan direct_contents_source jika Anda ingin membuat kenangan menggunakan acara yang disediakan langsung dalam payload. Informasi yang bermakna diekstrak dari peristiwa ini dan digabungkan dengan informasi yang ada untuk cakupan yang sama. Pendekatan ini dapat digunakan jika Anda menggunakan penyimpanan sesi yang berbeda dari Sesi Agent Platform.

Kamus

Peristiwa harus menyertakan kamus Content.

events =  [
  {
    "content": {
      "role": "user",
      "parts": [
        {"text": "I work with LLM agents!"}
      ]
    }
  }
]

client.memory_banks.memories.generate(
    name=memory_bank.name,
    direct_contents_source={
      "events": EVENTS
    },
    # For example, `scope={"user_id": "123"}`.
    scope=SCOPE,
    config={
        "wait_for_completion": True
    }
)

Ganti kode berikut:

  • SCOPE: Kamus, yang mewakili cakupan memori yang dihasilkan. Contoh, {"session_id": "MY_SESSION"}. Hanya memori dengan cakupan yang sama yang dipertimbangkan untuk konsolidasi.

Berbasis kelas

Peristiwa harus menyertakan objek Content.

from google import genai
from agentplatform import types

events = [
  types.GenerateMemoriesRequestDirectContentsSourceEvent(
    content=genai.types.Content(
      role="user",
      parts=[
        genai.types.Part.from_text(text="I work with LLM agents!")
      ]
    )
  )
]

client.memory_banks.memories.generate(
    name=memory_bank.name,
    direct_contents_source={
      "events": events
    },
    # For example, `scope={"user_id": "123"}`.
    scope=SCOPE,
    config={
        "wait_for_completion": True
    }
)

Ganti kode berikut:

  • SCOPE: Kamus, yang mewakili cakupan memori yang dihasilkan. Contoh, {"session_id": "MY_SESSION"}. Hanya memori dengan cakupan yang sama yang dipertimbangkan untuk konsolidasi.

Menggunakan Sesi Agent Platform sebagai sumber data

Dengan Sesi, Memory Bank menggunakan peristiwa sesi sebagai percakapan sumber untuk pembuatan memori.

Untuk menentukan cakupan memori yang dihasilkan, Memory Bank mengekstrak dan menggunakan ID pengguna dari sesi secara default. Misalnya, cakupan memori disimpan sebagai {"user_id": "123"} jika user_id sesi adalah "123". Anda juga dapat memberikan scope secara langsung, yang akan menggantikan penggunaan user_id sesi sebagai cakupan.

Kamus

client.memory_banks.memories.generate(
  name=memory_bank.name,
  vertex_session_source={
      # For example, projects/.../locations/.../reasoningEngines/.../sessions/...
      "session": "SESSION_NAME"
  },
  # Optional when using Sessions. Defaults to {"user_id": session.user_id}.
  scope=SCOPE,
  config={
      "wait_for_completion": True
  }
)

Ganti kode berikut:

  • SESSION_NAME: Nama sesi yang sepenuhnya memenuhi syarat.

  • (Opsional) SCOPE: Kamus, yang mewakili cakupan memori yang dihasilkan. Contoh, {"session_id": "MY_SESSION"}. Hanya memori dengan cakupan yang sama yang dipertimbangkan untuk konsolidasi. Jika tidak diberikan, {"user_id": session.user_id} akan digunakan.

Berbasis kelas

from agentplatform import types

client.memory_banks.memories.generate(
  name=memory_bank.name,
  vertex_session_source=types.GenerateMemoriesRequestVertexSessionSource(
      # For example, projects/.../locations/.../reasoningEngines/.../sessions/...
      session="SESSION_NAME"
  ),
  # Optional when using Sessions. Defaults to {"user_id": session.user_id}.
  scope=SCOPE,
  config={
      "wait_for_completion": True
  }
)

Secara opsional, Anda dapat memberikan rentang waktu yang menunjukkan peristiwa mana dalam Sesi yang harus disertakan. Jika tidak diberikan, semua peristiwa dalam Sesi akan disertakan.

Kamus

import datetime

client.memory_banks.memories.generate(
  name=memory_bank.name,
  vertex_session_source={
      "session": "SESSION_NAME",
      # Extract memories from the last hour of events.
      "start_time": datetime.datetime.now(tz=datetime.timezone.utc) - datetime.timedelta(seconds=24 * 60),
      "end_time": datetime.datetime.now(tz=datetime.timezone.utc)
  },
  scope=SCOPE
)

Berbasis kelas

import datetime

from agentplatform import types

client.memory_banks.memories.generate(
  name=memory_bank.name,
  vertex_session_source=types.GenerateMemoriesRequestVertexSessionSource(
      session="SESSION_NAME",
      # Extract memories from the last hour of events.
      start_time=datetime.datetime.now(tz=datetime.timezone.utc) - datetime.timedelta(seconds=24 * 60),
      end_time=datetime.datetime.now(tz=datetime.timezone.utc)
  ),
  scope=SCOPE
)

Menggabungkan memori yang telah diekstrak sebelumnya

Sebagai alternatif untuk menggunakan proses ekstraksi otomatis Memory Bank, Anda dapat langsung memberikan memori yang telah diekstrak sebelumnya. Memori sumber langsung akan digabungkan dengan memori yang ada untuk cakupan yang sama. Hal ini dapat berguna jika Anda ingin agen atau human-in-the-loop bertanggung jawab untuk mengekstrak memori, tetapi Anda tetap ingin memanfaatkan konsolidasi Memory Bank untuk memastikan tidak ada memori yang duplikat atau kontradiktif.

client.memory_banks.memories.generate(
    name=memory_bank.name,
    direct_memories_source={"direct_memories": [{"fact": "FACT"}]},
    scope=SCOPE
)

Ganti kode berikut:

  • FACT: Fakta yang telah diekstrak sebelumnya yang harus digabungkan dengan memori yang ada. Anda dapat memberikan hingga 5 fakta yang telah diekstrak sebelumnya dalam daftar seperti berikut:

    {"direct_memories": [{"fact": "fact 1"}, {"fact": "fact 2"}]}
    
  • SCOPE: Kamus, yang mewakili cakupan memori yang dihasilkan. Contoh, {"session_id": "MY_SESSION"}. Hanya memori dengan cakupan yang sama yang dipertimbangkan untuk penggabungan.

Menggunakan input multimodal

Anda dapat mengekstrak memori dari input multimodal. Namun, memori hanya diekstrak dari teks, file inline, dan data file dalam konten sumber. Semua konten lainnya, termasuk panggilan fungsi dan respons, akan diabaikan saat membuat memori.

Memori dapat diekstrak dari gambar, video, dan audio yang disediakan oleh pengguna. Jika konteks yang diberikan oleh input multimodal dinilai oleh Bank Memori bermakna untuk interaksi di masa mendatang, memori tekstual dapat dibuat, termasuk informasi yang diekstrak dari input. Misalnya, jika pengguna memberikan gambar golden retriever dengan teks "Ini saya", Memory Bank akan menghasilkan memori seperti " saya adalah golden retriever".

Misalnya, Anda dapat memberikan gambar dan konteks untuk gambar dalam payload:

Kamus

with open(file_name, "rb") as f:
    inline_data = f.read()

events =  [
  {
    "content": {
      "role": "user",
      "parts": [
        {"text": "This is my dog"},
        {
          "inline_data": {
            "mime_type": "image/jpeg",
            "data": inline_data
          }
        },
        {
          "file_data": {
            "file_uri": "gs://cloud-samples-data/generative-ai/image/dog.jpg",
            "mime_type": "image/jpeg"
          }
        },
      ]
    }
  }
]

Berbasis kelas

from google import genai
from agentplatform import types

with open(file_name, "rb") as f:
    inline_data = f.read()

events = [
  types.GenerateMemoriesRequestDirectContentsSourceEvent(
    content=genai.types.Content(
      role="user",
      parts=[
        genai.types.Part.from_text(text="This is my dog"),
        genai.types.Part.from_bytes(
          data=inline_data,
          mime_type="image/jpeg",
        ),
        genai.types.Part.from_uri(
          file_uri="gs://cloud-samples-data/generative-ai/image/dog.jpg",
          mime_type="image/jpeg",
        )
      ]
    )
  )
]

Langkah berikutnya

Panduan

Pelajari cara mengambil kenangan yang dibuat dan diupload.

Panduan

Pelajari cara menyiapkan Memory Bank.

Panduan

Pelajari cara memeriksa revisi memori.