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_countsaat membuat instance Agent Platform untuk menyertakan lebih banyak revisi historis dalam logika konsolidasi.

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