Membuat kenangan

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, lihat Penyiapan untuk Memory Bank.

Memahami pembuatan memori

Memory Bank mengekstrak memori dari data sumber dan mengkurasi sendiri memori 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 disimpan.

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

  • Secara default, Memory Bank akan mempertimbangkan semua kenangan yang ada untuk cakupan yang sama selama penggabungan. Jika Anda ingin membatasi memori yang memenuhi syarat untuk penggabungan 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.

Anda dapat memeriksa langkah-langkah perantara pembuatan memori dan melihat bagaimana memori berubah 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 apa yang dianggap bermakna oleh Memory Bank sehingga 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. Keduanya 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 kenangan 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): Suka, tidak suka, gaya, atau pola yang dinyatakan atau tersirat. Misalnya, "Saya lebih suka tempat duduk di tengah".

• Peristiwa percakapan utama dan hasil tugas (KEY_CONVERSATION_DETAILS): Pencapaian atau kesimpulan penting dalam dialog. Misalnya, "Saya memesan tiket pesawat untuk perjalanan 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:

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

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 di 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, ganda, boolean, atau stempel waktu) bersama dengan fakta memori. Hal ini berguna untuk memfilter atau mengelola siklus proses kenangan.

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

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 interaksi metadata baru dengan kenangan yang ada selama penggabungan:

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

• OVERWRITE: Mengganti metadata kenangan yang diperbarui dengan metadata baru.

• REQUIRE_EXACT_MATCH: Membatasi penggabungan ke kenangan yang memiliki metadata yang sama persis dengan permintaan. Jika tidak memiliki metadata yang sama, kenangan tidak memenuhi syarat untuk digabungkan 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.

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

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: Menyerap data ke Memory Bank dan memicu pembuatan memori secara langsung. Metode ini berguna jika Anda ingin membuat memori pada titik waktu tertentu, seperti di akhir sesi atau pada interval reguler dalam sesi.
• IngestEvents: Menyerap data ke Bank Memori secara berkelanjutan dan membiarkan Bank Memori memprosesnya saat kriteria pemicuan 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 utama 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 dibuat, jika ada:

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 kenangan yang dihasilkan menyertakan action yang dilakukan pada kenangan tersebut:

• CREATED: Menunjukkan bahwa kenangan baru telah ditambahkan, yang merepresentasikan konsep baru yang tidak tercakup oleh kenangan 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 kenangan CREATED atau UPDATED, Anda dapat menggunakan GetMemories untuk mengambil konten lengkap kenangan. 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. Mengeksekusi pembuatan memori sebagai operasi pemblokiran berguna saat Anda ingin memeriksa memori yang dibuat secara manual atau memberi tahu pengguna akhir tentang memori yang dibuat.

Namun, untuk agen produksi, Anda biasanya ingin menjalankan pembuatan memori di latar belakang sebagai proses asinkron. Dalam sebagian besar kasus, klien tidak perlu menggunakan output untuk proses saat ini, sehingga tidak perlu menambah latensi saat menunggu respons. Jika Anda ingin pembuatan memori dieksekusi 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 memberikan data sumber bagi pembuatan memori:

• Menyediakan peristiwa langsung di payload.

• Menyediakan peristiwa menggunakan Sesi Agent Platform.

• Berikan fakta yang telah diekstrak sebelumnya untuk menggabungkannya dengan memori yang ada untuk cakupan yang sama.

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

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.

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

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

Menggunakan Sesi Agent Platform sebagai sumber data

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

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

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

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.

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
)

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 kenangan yang telah diekstrak sebelumnya. Kenangan sumber langsung akan digabungkan dengan kenangan 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 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 kenangan yang dihasilkan. Contoh, {"session_id": "MY_SESSION"}. Hanya memori dengan cakupan yang sama yang dipertimbangkan untuk konsolidasi.

Menggunakan input multimodal

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

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

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

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

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