The Archive — Memory at Agent Valley

1. Pengantar

Minggu pertama menanyakan siapa yang mengatakan apa yang sedang berjalan. Minggu kedua menanyakan siapa yang memutuskan apa yang akan dijalankan berikutnya. Minggu ketiga menanyakan apa yang ditinggalkan oleh lari. Minggu ini percakapan berakhir, dan pertanyaannya adalah apa yang bertahan — dan ternyata jenis benda yang dibicarakan menentukan ke mana benda itu akan pergi.

Arsip adalah tempat lembah muncul saat terjadi kesalahan. Menara yang mencatat semuanya, dan Vesper, sang arsiparis, di meja di lantai dasar. Lentera Anda padam di malam hari. Pergi dan tanyalah.

Dia adalah teman yang baik. Sebulan kemudian, dia juga senang bertemu dengan Anda.

Rekaman bukanlah ingatan.

Kalimat tersebut adalah seluruh lab. Anda akan mendakinya dalam empat anak tangga, dan setiap anak tangga adalah lantai menara:

berdering	lantai	apa yang diingatnya	apa yang membuatnya
1	meja, dan lantai	kunjungan ini	session.state · SqliteSessionService
2	lantai dua, laci Anda	pengunjung ini	awalan user:
3	lantai tiga, menara	apa yang dikatakan	Memory Bank Vertex AI
4	lantai empat, musim	seluruh lembah	BigQuery

Setiap anak tangga yang naik adalah karena sesuatu jatuh dari anak tangga di bawahnya.

Anda sudah mengetahui lima cara pelupa seorang arsiparis, karena setiap cara tersebut pernah terjadi pada Anda saat panggilan dukungan:

	apa yang dia katakan	apa yang salah
~~1~~	~~Bisa berikan referensi itu lagi?~~	~~lupa dalam satu percakapan~~ — minggu ketiga memperbaikinya
~~2~~	~~Kami telah mengalihkan Anda. Mulai dari awal.~~	~~histori hilang bersama proses~~ — minggu ketiga juga memperbaiki hal ini
3	Selamat datang. Ada yang bisa saya bantu?	kepada seseorang yang memiliki kasus yang belum selesai dari bulan lalu
4	Dapatkah Anda mendeskripsikan kerusakannya?	dia melihat lentera terakhir kali
5	Kita belum pernah melihat ini sebelumnya.	tiga puluh satu orang telah bertanya musim ini

Baris ketiga adalah minggu ini. Kegagalan terjadi dalam tiga cara yang berbeda — kunjungan baru (bab 2), kalimat tanpa garis pada slip (bab 3), dan arsip yang hanya ada di dalam proses (bab 4) — dan setiap cara adalah bab. Baris keempat diserahkan kepada Anda: look() di archive/agent.py adalah tempat dia membaca tanda dari foto. Baris kelima adalah bab 5, dan bersifat opsional.

Anda tidak memerlukan minggu satu hingga tiga. Agen adalah model dengan petunjuk dan beberapa alat. Segala sesuatu yang lain, minggu ini sudah jelas.

Anda akan menulis tiga baris, dan setiap baris adalah konsep memori:

baris	Apa itu
tool_context.state[CASE] = case	ditulis oleh kode, bukan oleh percakapan
CASE = "user:case"	awalan adalah seumur hidup
found = await ctx.search_memory(query)	kebijakan panggilan balik — yang diajukan tidak diingat

Ada satu lagi baris yang sudah tersedia untuk Anda baca — kebijakan penulisan, await ctx.add_events_to_memory(...) — dan di bab 3 Anda akan membaca apa yang dilakukannya sebelum menulis baris yang menggunakannya.

Dua anak tangga lainnya bukan pengeditan sama sekali: Anda membangun menara (Agent Engine yang menghosting Memory Bank) dan kode yang sama terhubung ke menara tersebut dengan sendirinya, serta Anda memuat gudang (BigQuery), menempatkan grafik di atasnya, dan memberikan dua kueri yang diatur kepada agen yang sama — satu berdasarkan makna, satu berdasarkan koneksi.

Setiap bab menjalankan loop yang sama, dan loop ini akan Anda gunakan pada agen Anda sendiri: baca kode → tulis baris → lihat di menara. Tidak ada yang rusak saat pertama kali dijalankan, tidak ada yang dimulai ulang, dan tidak ada yang di-Ctrl+C: setiap pengeditan akan diambil pada pesan berikutnya, dan menghubungkan menara adalah satu baris dalam file yang dibaca ulang oleh Arsip pada setiap permintaan. Menara adalah gambar yang digambar ulang: menara membaca file yang sama yang Anda edit, dan memiliki tiga tombol — 🌙 mengakhiri hari, 🗓 memulai kunjungan berikutnya, 🔥 melupakan Anda. Semua hal lainnya yang Anda lakukan dalam kode dan terminal.

Dua tempat, dan mereka tidak pernah berganti pekerjaan: tab 1 adalah terminal, tab 2 adalah Arsip. Workbench (adk web) muncul persis satu kali, di bab 1, untuk melihat status sesi mentah, lalu Anda selesai menggunakannya. Setiap 👉 di bawah menunjukkan jenisnya. 👉💻 adalah tab 1, 👉🖥 adalah tab 2, 👉🔬 adalah workbench. 👉📖 adalah membuka file dan membaca — tidak ada yang perlu diubah — dan 👉✏️ adalah salah satu jenis langkah yang mengedit. Setiap kali langkah-langkah memberi tahu Anda untuk mengucapkan sesuatu kepada Vesper, pesan persisnya ada di blok tepat di bawahnya — salin apa adanya. Bagian yang judulnya diakhiri dengan — hanya baca tidak perlu diketik, ditempel, atau diklik: kode di dalamnya sudah ada di repo dan sudah berjalan, dicetak untuk Anda baca.

Kalimat di atas pintu Vesper adalah kalimat yang ada di bagian atas. Kalimat yang mengakhiri minggu ini adalah kalimat penutup minggu keempat seluruh musim:

Fakta dan preferensi berada di toko yang berbeda.

2. 🧰 Penyiapan

• Apa — arahkan ke project atau tempel kunci, instal, dan buktikan bahwa toolchain berwarna hijau.
• Mengapa — tidak ada yang di-boot di sini. Setiap server dimulai tepat sebelum langkah yang memerlukannya, jadi saat layar terbuka, Anda tahu perintah mana yang memilikinya.
• Cara — satu skrip yang membuat project, satu skrip yang menginstal dan mengarahkan Anda ke Vertex AI, dan satu skrip pra-penerbangan yang membaca kode Anda dan memberi tahu Anda posisi Anda.

Semua yang ada di lab ini berjalan di Cloud Shell — Python, uv, dan gcloud sudah diinstal di sana, dan Gemini dapat diakses melalui Vertex AI menggunakan kredensial Anda sendiri. Tidak ada kunci API di mana pun dalam lab ini, dan tidak ada yang perlu diinstal di laptop Anda.

Ada satu hal yang tidak dapat diberikan oleh lab ini: project Google Cloud dengan penagihan yang diaktifkan. Langkah 1 memberi Anda akun yang dapat membayar; langkah 4 mengubah akun tersebut menjadi project — atau mengambil project Agent Valley yang sudah Anda buat pada minggu pertama, minggu kedua, atau minggu ketiga. Lakukan secara berurutan — setiap langkah setelah 4 membaca project yang ditentukan oleh langkah 4.

1 · Dapatkan akun dengan penagihan (~1 menit)

🌐 Lakukan langkah ini sebelum melakukan hal lain. Login dengan Akun Google yang penagihannya diaktifkan. Akun apa pun yang demikian akan berfungsi. Jika akun Anda tidak memiliki akun penagihan, mulai uji coba gratis; uji coba ini akan memberi Anda akun penagihan, yang diperlukan untuk langkah 4.

2 · Buka Cloud Shell (~1 menit)

🌐 Klik Activate Cloud Shell di bagian atas Konsol Google Cloud — ikon ini berbentuk terminal di header.

🌐 Klik Open Editor (ikon folder terbuka dengan pensil). Tindakan ini akan membuka Cloud Shell Editor dengan file explorer di sebelah kiri — di sinilah Anda bekerja setiap kali langkah ditandai 👉✏️.

🌐 Jika Anda diminta untuk memberikan otorisasi kapan saja hari ini, klik Authorize untuk melanjutkan.

🌐 Buka terminal di dalam editor — yaitu tab 1, dan setiap langkah 👉💻 dijalankan di sana kecuali jika dinyatakan lain. Tab 2 adalah Arsip, dan Anda membukanya di bab 1, tepat sebelum langkah yang memerlukannya. Jika terminal belum berada di bagian bawah layar, buka dengan View → Terminal:

🌐 Periksa akun yang Anda gunakan untuk login — akun tersebut harus sama dengan akun yang digunakan di langkah 1:

gcloud auth list

Dua cara untuk membuka file. Setiap langkah 👉✏️ memberi nama file seperti archive/agent.py. File explorer di sebelah kiri akan mengarahkan Anda ke sana — agent-valley-archive → archive → agent.py — atau ketik cloudshell edit ~/agent-valley-archive/archive/agent.py di terminal dan file akan terbuka di editor di atasnya. Gunakan yang Anda sukai; lab ini memberi nama jalur karena tidak ambigu tentang file mana yang dimaksud.

Blok mana yang Anda ketik? Blok yang ditandai bash adalah perintah untuk terminal, dan selalu dimulai dengan cd sehingga Anda dapat menempelkannya ke tab mana pun. Blok yang ditandai console bukan sesuatu yang Anda ketik — ini adalah output yang akan Anda lihat. Blok tanpa bahasa di dalamnya selalu merupakan sesuatu yang perlu disalin: di bawah 👉🖥 atau 👉🔬, blok tersebut adalah pesan untuk Vesper, dan di bawah 👉✏️, blok tersebut adalah cuplikan yang perlu ditempelkan ke dalam file.

Hanya baca. Bagian yang judulnya diakhiri dengan — hanya baca tidak memiliki apa pun yang perlu diketik, ditempel, atau diklik. python dan sql di dalamnya adalah kode yang sudah ada di repo dan sudah berjalan — atau, di bab 5, sudah berjalan di dalam skrip — dan kode tersebut dicetak sehingga Anda dapat membaca fungsinya. Setiap bagian tersebut dibuka dengan catatan yang menyatakan demikian.

3 · Ikuti lab (~1 menit)

💻 Clone repo — ini adalah repo Archive, bukan repo minggu pertama, minggu kedua, atau minggu ketiga:

cd ~
git clone https://github.com/cuppibla/agent-valley-archive
cd agent-valley-archive

4 · Buat project Anda — atau gunakan kembali project dari minggu sebelumnya (~2 menit)

💻 Satu skrip menemukan akun penagihan Anda, membuat project di akun tersebut, dan mengarahkan Cloud Shell ke project tersebut. Jika Anda mengerjakan minggu pertama, minggu kedua, atau minggu ketiga, project Agent Valley akan ditemukan terlebih dahulu dan ditawarkan untuk digunakan kembali — pilih ya dan tidak ada project kedua yang dapat ditagih:

cd ~/agent-valley-archive
./setup_project.sh

👀 Harapkan ✓ untuk akun penagihan yang dipilihnya, ✓ untuk project yang dibuat atau digunakan ulang, dan akhiran seperti:

cd ~/agent-valley-archive
Project ready: agent-valley-4271
  Next:  ./setup_codelab.sh

agent-valley-4271 adalah project ID Anda — ID Anda akan memiliki digit yang berbeda. Empat hal terjadi di sana:

penagihan	menggunakan akun [YYYY-MM-DD] GDP Credit: terbaru jika Anda memilikinya, dan akun penagihan terbuka lainnya jika tidak ada akun
project	mencari project Agent Valley yang sudah Anda miliki — minggu pertama, minggu kedua, atau minggu ketiga — dan menawarkan untuk menggunakannya kembali; jika tidak, project akan membuat agent-valley-XXXX dan menautkan akun penagihan tersebut ke project
memilih	menulis ID ke ~/project_id.txt dan menjalankan gcloud config set project, sehingga tidak ada yang meminta Anda mengetiknya setelah ini
waits	polling hingga proyek benar-benar diizinkan untuk ditayangkan, hingga dua menit

🌐 Project yang sama kini ada di konsol — ID-nya ada di kartu Project info di Dasbor:

Mengapa ia menunggu di akhir? Project Google Cloud yang dibuat beberapa detik yang lalu belum diizinkan untuk ditayangkan: kebijakan IAM-nya masih diterapkan, dan panggilan akan kembali 403 IAM_PERMISSION_DENIED. Itulah satu-satunya hal yang kemungkinan besar salah dalam penyiapan ini, dan bukan masalah penagihan atau izin — baris di atas sudah membuktikan bahwa project ada dan penagihan ditautkan. Skrip menyerap penantian tersebut di sini sehingga panggilan model langsung di langkah 5 tidak masuk ke dalamnya. Project yang digunakan kembali dari minggu sebelumnya tidak perlu menunggu sama sekali; project tersebut telah diizinkan untuk ditayangkan selama berminggu-minggu.

Aman untuk dijalankan ulang. Jika terjadi masalah, cukup jalankan ./setup_project.sh lagi. ~/project_id.txt akan dibaca terlebih dahulu dan project tersebut akan dilanjutkan selama masih ada, dengan menautkan penagihan ke project tersebut jika bagian tersebut belum selesai, sehingga project kedua tidak akan ditinggalkan begitu saja.

No open billing account? Skrip berhenti di sana, sebelum mengubah hal lain, dan mencetak apa yang harus dilakukan. Sembilan dari sepuluh kali, Cloud Shell login sebagai akun yang berbeda dengan akun yang memiliki penagihan — bandingkan gcloud auth list dengan langkah 1.

Could not create a project? Beberapa akun, terutama akun perusahaan, tidak diizinkan untuk membuat project, dan setiap akun memiliki kuota project. Skrip mencetak petunjuk konsol untuk membuatnya secara manual; setelah Anda memilikinya, masukkan ID ke ~/project_id.txt dan jalankan kembali ./setup_project.sh, lalu project tersebut akan mengadopsi project itu.

5 · Menginstal dan mengarahkan ke Vertex AI (~3 menit)

💻 Instal uv, ekspor tiga variabel yang mengirim ADK ke Vertex AI, dan jalankan penyiapan:

cd ~/agent-valley-archive
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.local/bin/env
export GOOGLE_GENAI_USE_VERTEXAI=TRUE
export GOOGLE_CLOUD_PROJECT=$(gcloud config get project)
export GOOGLE_CLOUD_LOCATION=global
./setup_codelab.sh

$(gcloud config get project) memiliki sesuatu untuk dikembalikan karena langkah 4 telah menyetelnya. Itulah alasan mengapa langkah 4 dilakukan terlebih dahulu.

Mengapa global, bukan wilayah? Gemini di Vertex menyajikan lab ini dari kuota bersama dinamis — tidak ada throughput yang disediakan, sehingga satu region yang sibuk dapat menjawab 429 RESOURCE_EXHAUSTED tanpa kesalahan Anda. global memanfaatkan kapasitas di seluruh region, bukan hanya satu region. Menara di bab 4 adalah pengecualian: Memory Bank bersifat regional, sehingga mendapatkan MEMORY_BANK_LOCATION=us-central1 sendiri sementara traffic generatif Anda tetap berada di global.

setup_codelab.sh bersifat idempoten — aman untuk dijalankan kembali beberapa kali. Metode ini melakukan lima hal, secara berurutan:

api	membaca project yang dipilih pada langkah 4 dan mengaktifkan aiplatform.googleapis.com (Vertex AI, dan Agent Engine yang menghosting Memory Bank) dan bigquery.googleapis.com (gudang chapter 5) di project tersebut
uv env	uv venv membuat .venv, atau menggunakan kembali yang sudah ada, lalu uv sync menginstal persis apa yang disematkan uv.lock — google-adk, google-genai, dan semua yang ada di bawahnya
lahan	menjalankan npm ci di site/ — Arsip itu sendiri adalah aplikasi Next.js — sehingga bash valley.sh di bab 1 tidak perlu didownload lagi; dilewati jika paket sudah ada
.env	menulis variabel yang dibaca lab — GOOGLE_GENAI_USE_VERTEXAI, GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION, MEMORY_BANK_LOCATION, dan BQ_DATASET, serta tidak ada kunci API di mana pun
model check	melakukan satu panggilan nyata ke Gemini, sehingga project yang buruk akan gagal di sini saat penyiapan, bukan nanti di dalam bab

Mengapa .env penting saat Anda baru saja mengekspor variabel tersebut? Karena ADK memuat .env over ekspor shell Anda — file tersebut akan menang. setup_codelab.sh menulis global di sana untuk Anda, tetapi .env adalah hal yang sebenarnya memutuskan endpoint mana yang Anda tuju. Bab 4 menambahkan satu baris lagi ke file yang sama, AGENT_ENGINE, dan menuliskannya untuk Anda — dan Arsip membaca ulang file pada setiap permintaan, sehingga baris tersebut berlaku tanpa perlu memulai ulang apa pun.

Kunci API sudah cukup untuk memulai. Bab 1 hingga 3 juga berjalan di kunci AI Studio dalam .env. Bab 4 membangun menara — Vertex AI Memory Bank — dan gudang bab 5 adalah BigQuery. Itu adalah layanan Google Cloud, jadi bab 4 dan 5 memerlukan project dengan penagihan yang diaktifkan, yang persis seperti yang baru saja Anda lakukan di langkah 4.

6 · Buktikan bahwa ini ramah lingkungan (~1 mnt)

💻 Jalankan pra-penerbangan — setiap tanda centang adalah pemeriksaan yang sebenarnya, bukan tebakan:

cd ~/agent-valley-archive
uv run python scripts/preflight.py

👀 Pra-penerbangan menanyakan satu pertanyaan kepada model untuk membuktikan bahwa kredensial Anda berfungsi, memeriksa apakah paket Arsip sudah ada, lalu membaca kode Anda dan mencetak progres minggu ini:

cd ~/agent-valley-archive
  desk      ▢ the slip      · write_down writes nothing         chapter 1 · EDIT ONE
  floor 1   ✓ the file      · SqliteSessionService              chapter 1, read only
  floor 2   ▢ the drawer    · CASE = "case"                     chapter 2 · EDIT TWO
  floor 3   ✓ what was said · closing time files the day        chapter 3, read only
  floor 3   ▢ the asking    · recall never looks                chapter 3 · EDIT THREE
  floor 3   ▢ the tower     · InMemoryMemoryService             chapter 4 · built, not edited
  floor 3   ✓ the rules     · USER_PREFERENCES, LANTERN_CONTEXT chapter 4, read only

Tiga sudah dicentang. Itulah yang hanya Anda baca. Tiga adalah garis yang Anda tulis; satu adalah menara yang Anda bangun. Jalankan pra-pemeriksaan lagi kapan saja di lab dan alat ini akan memberi tahu Anda posisi Anda — alat ini membaca file Anda, bukan daftar periksa.

3. Sesi, Status, SqliteSessionService

• Apa — tulis satu baris; mulai workbench sekali dan lihat pengisian slip; lalu hal yang sama di menara; lalu baca mengapa ia bertahan di malam hari.
• Mengapa — hal pertama yang perlu diketahui tentang memori adalah bahwa tidak ada yang diingat dengan sendirinya. Seseorang menulisnya.
• How — satu baris di agent.py, lalu jangan ubah apa pun.

EDIT SATU

👉📖 Buka archive/agent.py dan temukan write_down. Baca hingga 👉:

    case = dict(tool_context.state.get(CASE, {}))
    if case.get(field):
        return {"already_written": {field: case[field]}}
    case[field] = value
    # 👉 EDIT ONE — chapter 1. She heard you. Nothing was written. Delete the
    #    "# " in front of the next line, then save — the slip is session state,
    #    and state is written by code, never by the conversation:
    # tool_context.state[CASE] = case
    return {"written": {field: value}}

Fungsi ini membangun slip dalam dict lokal, lalu menampilkannya — dan dict lokal akan berakhir dengan panggilan. Jalankan seperti apa adanya dan Vesper akan mendengar Anda dengan sempurna: empat panggilan write_down diaktifkan, masing-masing menjawab "written", dan status sesi tetap kosong, karena tidak ada yang pernah mencapainya. Dia mendengarmu. Tidak ada yang ditulis.

👉✏️ Masih di archive/agent.py, di dalam write_down: hapus # di depan satu baris — # dan spasi setelahnya. Sebelum:

    case[field] = value
    # 👉 EDIT ONE — chapter 1. She heard you. Nothing was written. Delete the
    #    "# " in front of the next line, then save — the slip is session state,
    #    and state is written by code, never by the conversation:
    # tool_context.state[CASE] = case
    return {"written": {field: value}}

Setelah:

    case[field] = value
    # 👉 EDIT ONE — chapter 1. She heard you. Nothing was written. Delete the
    #    "# " in front of the next line, then save — the slip is session state,
    #    and state is written by code, never by the conversation:
    tool_context.state[CASE] = case
    return {"written": {field: value}}

Simpan.

Slip diisi

👉💻 Mulai workbench. Ini adalah satu-satunya saat Anda membukanya di lab — ini adalah satu-satunya jendela yang menampilkan status sesi sebagai JSON mentah:

cd ~/agent-valley-archive
uv run adk web . --allow_origins="*"

--allow_origins="*" tidak bersifat opsional. Pratinjau Web Cloud Shell memproksi browser Anda, sehingga tanpa itu, UI akan dimuat, lalu pesan pertama Anda akan berhenti dengan 403 kosong. Pertahankan . di akhir juga; kode ini yang menempatkan archive dalam daftar aplikasi.

👉🔬 Buka workbench dengan Web Preview → Preview on port 8000 (tombol Web Preview adalah ikon mata di atas jendela di kanan atas Cloud Shell). Pilih archive, dan sebelum Anda mengetik apa pun, klik State di panel kiri.

👀 Kosong. Belum ada yang mengatakan apa pun.

👉🔬 Sekarang ucapkan ini, semuanya dalam satu pesan:

Hi! My lantern keeps going out at night. My case number is k7f2, and there's a little q7 stamped on the base.

👀 Empat chip write_down diaktifkan — klik salah satunya dan baca JSON: "written": {"no": "k7f2"}. Sekarang klik State lagi.

case   {"no": "k7f2", "item": "lantern", "mark": "q7",
        "symptom": "keeps going out at night"}

👀 Kosong, lalu penuh, di dalam satu pesan. Itulah yang dia ingat, dan hal itu tidak muncul dengan sendirinya. Anda menulis baris yang menuliskannya. Itulah seluruh mekanisme: fungsi biasa yang menulis ke tool_context.state, dan petunjuk yang menyuruhnya untuk menggunakannya setiap kali pengunjung mengatakan sesuatu yang sesuai dengan baris pada kertas.

👉🔬 Tanyakan padanya:

What's my case number?

👀 k7f2. Dia membacanya dari kertas. Tanpa EDIT ONE, dia akan memintanya dari Anda — baris pertama daftar dukungan, di dalam satu percakapan.

Dua penjaga tersebut adalah slip yang berupa formulir kertas: empat garis pendek, yang masing-masing ditulis satu kali. Mereka lebih penting daripada yang terlihat. Tanpa itu, model menemukan bahwa ia dapat menuangkan seluruh percakapan ke dalam symptom, dan bab 3 — bab yang intinya adalah ketergelinciran tidak memiliki garis untuk itu — diam-diam berhenti menjadi benar. Bentuk toko diterapkan oleh kode yang menuliskannya, atau tidak diterapkan.

Satu baris, tanpa demo. Apa yang ada dalam percakapan, belum tentu dapat dijangkau oleh kode Anda. Slip ini untuk kode. Simpan ide itu; lab ini tidak pernah memperdebatkannya, lab ini hanya terus menjadi benar.

Mengapa perintah dibuat dalam kode. Buka house() tepat di bawah. ADK akan mengganti {case} dalam instruksi string biasa langsung dari status sesi — tetapi bab 2 mengubah name kunci tersebut, dan {case} yang ada dalam teks juga harus diedit. Satu pengeditan, satu tempat.

Sekarang, pergi ke menara

👉💻 Anda telah selesai menggunakan workbench — biarkan tetap berjalan atau tutup tabnya; bagian lab lainnya ada di Arsip. Buka tab terminal kedua (tab 2 — Arsip):

cd ~/agent-valley-archive
bash valley.sh

sh: line 1: next: command not found? Arsip adalah aplikasi Next.js, dan baris tersebut berarti paketnya tidak lengkap — biasanya npm install yang terputus saat pertama kali, sehingga menyisakan folder site/node_modules tanpa next di dalamnya. Jalankan bash valley.sh lagi: akan mencari program biner next, bukan folder, dan menginstal ulang jika tidak ada. Untuk melakukannya secara manual: cd ~/agent-valley-archive/site && npm ci, lalu bash valley.sh.

👉🖥 Buka Arsip dengan Web Preview → Change port, ketik 3440, lalu klik Change and Preview. 3440 tidak ada dalam daftar cepat Pratinjau Web — 8080 adalah defaultnya — jadi Anda harus menyetelnya secara manual sekali ini. Tekan ▶ Mulai, lalu Arsip. Anda berada di depan pintu. Pilih siapa pun yang datang untuk bertanya — nama dan spesies — lalu masuk.

👀 Satu bangunan. Vesper berada di meja di lantai dasar, dan di sanalah Anda berbicara. Di atasnya: lantai satu, lantai dua, lantai tiga, dan loteng gelap. Empat anak tangga adalah empat lantai. Hewan peliharaan Anda duduk di lantai dasar, karena itulah jarak yang telah Anda daki. Kolom di samping gambar menjelaskan apa yang ada di setiap lantai saat ini — empat toko yang sama seperti tabel di pengantar, dalam urutan yang sama. Tidak ada tombol di sebelah kanan.

👉🖥 Tempelkan empat hal yang sama ke dalam kotak di bawah percakapan — pesan ini persis — lalu tekan Enter:

Hi! My lantern keeps going out at night. My case number is k7f2, and there's a little q7 stamped on the base.

👀 Perhatikan meja. Kertas akan menulis sendiri, satu baris dalam satu waktu — pada gambar, dan sepenuhnya di bawah kertas di sampingnya. Alat yang sama, status yang sama: menara hanya menggambar apa yang ditulis write_down, dan akan terus melakukannya selama sisa lab.

Dia mengingat semalam — hanya baca

Hanya baca. Satu baris untuk dilihat, tidak ada yang perlu diubah: kunjungan ada dalam file, bukan dalam proses.

👉📖 Buka archive/service.py dan baca satu baris:

DB = str(Path(__file__).resolve().parents[1] / "archive.db")
_sessions = SqliteSessionService(DB)

Apa yang Anda tulis, dan apa itu

baris	Apa itu	tempatnya berada
tool_context.state[CASE] = case	status sesi — ditulis oleh kode, dibaca oleh petunjuk	meja · session.state
SqliteSessionService(DB) — Anda hanya membacanya	penyimpanan sesi — kunjungan dalam file, bukan dalam proses	lantai satu · archive.db

Anak tangga ini mencapai satu kunjungan, dan bertahan hingga waktu tutup. Cookie ini tidak bertahan saat kunjungan berikutnya.

4. Negara Bagian Pengguna

• Apa — kembali sebulan kemudian; selipnya sudah hilang. Lima karakter, dan dia akan mengikuti Anda.
• Mengapa — sesi adalah satu kunjungan. Kunjungan berikutnya adalah sesi baru, dan belum pernah melihat sesi terakhir.
• How — lima karakter dalam state.py.

👉🖥 Tekan 🗓 sebulan kemudian. Itu adalah sesi baru untuk pengunjung yang sama — seperti cara memulai percakapan baru pada minggu ketiga.

Selamat datang di Arsip. Ada yang bisa saya bantu?

👉🖥 Lihat menara. Lantai satu memiliki buku lain — kunjungan ini. Laci di lantai dua kosong. Kertas di atas meja kosong.

👀 Alasan: slip ditulis ke dalam status sesi, dan sesi adalah kunjungan ini. Mengubah kunjungan, mengubah sesi. Tidak ada yang diteruskan karena tidak ada yang diperintahkan. Kunjungan terakhir masih ada dalam file — yaitu buku pertama lantai satu — tetapi slip ditulis di bawah kunci yang berlaku untuk satu kunjungan.

EDIT DUA

👉✏️ Buka archive/state.py. Temukan 👉. Sebelum:

# 👉 EDIT TWO — chapter 2. Five characters. A key with no prefix lives for one
#    visit; `user:` follows the visitor into every visit after this.
CASE = "case"

Setelah:

CASE = "user:case"

Simpan. Tidak ada mulai ulang — Archive mengimpor ulang kode Anda di setiap pesan.

👉🖥 Tempelkan lagi empat hal yang sama — pesan ini persis:

Hi! My lantern keeps going out at night. My case number is k7f2, and there's a little q7 stamped on the base.

👉🖥 Kemudian, tekan 🗓 sebulan kemudian lagi — tombol yang sama seperti sebelumnya.

👀 Laci di lantai dua memiliki nama Anda, dan keempat kolom tersebut ada di dalamnya. Kertas di atas meja adalah empat baris yang sama — dikeluarkan dari laci saat Anda masuk. Hewan peliharaan Anda telah pindah ke lantai atas. Kunci yang sama, setiap kunjungan, satu nilai: itulah tugas awalan.

Awalan adalah masa berlaku.

awalan	berapa lama ia hidup	lantai yang mana
(tidak ada)	kunjungan ini	meja
user:	setiap kunjungan yang dilakukan pengunjung ini	lantai dua, laci Anda
app:	semua orang, selamanya	bagian dari lantai empat
temp:	giliran ini saja — bahkan tidak pernah menaiki tangga	—

Satu meja, empat laci. Bab ini membahas salah satunya.

Dia sekarang mengenal Anda

👉🖥 Kunjungan ini benar-benar baru dan Anda belum mengatakan apa pun di dalamnya. Tanyakan padanya:

What did I bring in last time?

👀 Saya mencatat bahwa Anda membawa lentera, kasus k7f2. Perangkat ini ditandai dengan q7 dan Anda menyebutkan bahwa perangkat ini terus mati pada malam hari. Setiap kata itu keluar dari laci, bukan percakapan — kunjungan ini hanya berisi satu pesan, dan pesan tersebut tidak menyebutkan apa pun. Itulah status tingkat pengguna yang melakukan tugasnya: kunci user: ada sebelum pengunjung mengucapkan sepatah kata pun, pada setiap kunjungan yang mereka lakukan.

Laci berisi empat baris yang ada di slip, dan tidak ada yang lain. Apa yang Anda katakan yang tidak memiliki garis pada slip — apa yang Anda coba, mengapa Anda peduli, apakah Anda menginginkan yang baru — tidak akan ke mana-mana, dan sebulan kemudian hilang. Laci melintasi bulan. Kalimat tidak. Bab 3 membahas hal itu.

Apa yang Anda tulis, dan apa itu

baris	Apa itu	tempatnya berada
CASE = "user:case"	awalan adalah seumur hidup — kunci yang sama, yang dicakup ke pengunjung, bukan kunjungan	floor dua · user: state

Anak tangga ini menjangkau satu pengunjung. Panel mengikuti Anda; percakapan tetap tidak.

5. InMemoryMemoryService

• Apa — baca baris yang mencatat hari, tulis baris yang bertanya; lalu satu waktu penutup dan satu pertanyaan.
• Mengapa — slip adalah formulir. Formulir memiliki garis yang Anda berikan. Orang tidak berbicara dalam baris — dan mencatat apa yang mereka katakan hanya setengah dari mengingatnya.
• Bagaimana — baca file; satu baris di recall; lalu satu 🌙, satu 🗓, satu pertanyaan.

Aktivitasnya dalam perjalanan pulang — hanya baca

Hanya baca. Ini adalah kebijakan penulisan — satu baris yang dibaca dalam bab ini dan tidak pernah berubah. Baris yang Anda tulis dalam bab ini adalah bacaan, lebih jauh ke bawah.

👉📖 Buka archive/agent.py dan temukan file. Ini adalah node yang berjalan saat hari berakhir — saat Anda menekan 🌙 cukup untuk hari ini:

async def file(ctx: Context, node_input: Any):
    t0 = time.monotonic()
    n = len(ctx.session.events)

    await ctx.add_events_to_memory(events=ctx.session.events, custom_metadata=FILING)

    return closing(ctx, t0, n)       # says what got written, and how long it waited

Satu baris. Seluruh hari — setiap peristiwa kunjungan ini — masuk ke layanan memori, dengan FILING yang diteruskan. Itulah kebijakan penulisan: apa yang disimpan (hari) dan kapan (waktu tutup). ADK memberi Anda kata kerja, add_events_to_memory, dan tidak ikut dalam pengambilan keputusan.

File tidak diingat

Baris tersebut menempatkan hari di rak. Tidak ada yang diambil dari sana. Rak yang penuh dengan kartu sama sekali tidak membantu jika tidak ada yang melihatnya — dan saat kode dikirim, tidak ada yang melihatnya: recall, node yang berjalan sebelum Vesper pada setiap pertanyaan, tidak menanyakan apa pun kepada menara. Penyimpanan yang tidak dapat Anda ingat pada saat yang tepat bukanlah memori; itu adalah log. Bagian yang mencari adalah bagian lainnya, dan Anda yang akan menuliskannya.

EDIT TIGA — permintaan

👉📖 Di archive/agent.py, temukan recall — fungsi tepat di atas file. Ini adalah node fungsi biasa yang berjalan sebelum Vesper pada setiap pertanyaan — bukan model yang memutuskan kapan harus mencari, yang berarti waktu saat tidak menemukan apa pun juga terlihat. Baca hingga 👉:

    if query.strip():
        try:
            # 👉 EDIT THREE — chapter 3. Filed is not remembered: the cards are on
            #    the shelf and nobody is looking at them. Delete the "# " in front
            #    of the next line, then save:
            # found = await ctx.search_memory(query)
            pass
        except ValueError:
            # no memory service wired on this runner — degrade, do not crash
            pass

👉✏️ Masih di archive/agent.py, di dalam recall: hapus # di depan satu baris — # dan spasi setelahnya. Sebelum:

        try:
            # 👉 EDIT THREE — chapter 3. Filed is not remembered: the cards are on
            #    the shelf and nobody is looking at them. Delete the "# " in front
            #    of the next line, then save:
            # found = await ctx.search_memory(query)
            pass
        except ValueError:

Setelah:

        try:
            # 👉 EDIT THREE — chapter 3. Filed is not remembered: the cards are on
            #    the shelf and nobody is looking at them. Delete the "# " in front
            #    of the next line, then save:
            found = await ctx.search_memory(query)
            pass
        except ValueError:

Biarkan pass di tempatnya — sekarang tidak melakukan apa pun, karena found sudah None di atas.

Simpan. Tidak ada mulai ulang.

Dua baris, dua kebijakan — dan Anda menulis salah satunya. Kebijakan penulisan menentukan apa yang disimpan dan kapan (waktu tutup, sepanjang hari). Kebijakan mengingat menentukan kapan harus melihat dan dengan apa (setiap pertanyaan, pertanyaan itu sendiri). ADK memberi Anda kata kerja — add_events_to_memory, search_memory — dan tidak termasuk dalam kebijakan. Itulah bagian yang tepat, dan itulah alasan mengapa permintaan itu harus Anda tulis.

Jam tutup

👉🖥 Sebutkan tiga hal yang tidak memiliki garis pada slip. Satu atau tiga pesan:

I read by it at night, so night is exactly when I need it.
I've tried hanging it higher. No change.
I don't want a new one — it was a gift.

👉🖥 Kemudian, tekan 🌙 cukup sekian untuk hari ini.

👀 Perhatikan meja. Ketiga benda yang Anda sebutkan terlepas dari alas dan melayang ke atas, lalu mendarat di lantai tiga. Di bagian kartu di samping menara, kartu tersebut dicantumkan — satu kartu untuk setiap pesan yang Anda kirim, ditandai quote, kalimat Anda kata demi kata, dan dalam proses ini di atasnya. Lampu di meja akan tetap menyala hingga mereka mendarat.

Apa itu FILING. Kamus kecil di bagian atas file: {"wait_for_completion": True, ...}. Dialah yang menyerahkan menara bersama dengan hari. Mengapa harus menunggu: bentuk singkat, add_session_to_memory(), mencatat hari di latar belakang dan fakta mungkin tidak ada untuk sementara waktu — menara akan menggambar lantai yang belum terisi. Bab 4 kembali ke kamus ini.

Sebulan kemudian, dia tahu

👉🖥 Tekan 🗓 sebulan kemudian, lalu tanyakan:

What have I already tried?

👀 Anda mencoba menggantungnya lebih tinggi — tetapi tidak membantu. Dia tahu. Slip tidak memiliki baris untuk itu dan tidak pernah memilikinya, sehingga laci tidak dapat menjawabnya; recall menemukan kartu, menulisnya ke ctx.state["recalled"], dan instruksinya berbunyi demikian. Satu baris adalah perbedaannya.

Dan semuanya ada di benaknya

Lihat di bagian kartu di samping menara: dalam proses ini. Saat ini, memori adalah InMemoryMemoryService — kamus di dalam bash valley.sh, dan akan ada selama proses tersebut berjalan. Tutup menara malam ini dan buka besok: buku ada di lantai satu, laci ada di lantai dua, dan lantai tiga gelap. Kasus ini tetap ada dalam file. Apa yang Anda katakan ada dalam proses, dan prosesnya sudah selesai.

Persistensi bukan memori.

Ada dua hal yang salah dengan lantai tiga saat ini: masih dalam proses, dan menggunakan kata-kata Anda sendiri — kutipan, bukan fakta. Bab berikutnya akan memperbaiki keduanya, tanpa kode sama sekali.

Apa yang Anda baca, apa yang Anda tulis, dan apa itu

baris	Apa itu	tempatnya berada
await ctx.add_events_to_memory(events, custom_metadata=FILING) — Anda hanya membacanya	kebijakan penulisan — sepanjang hari, pada waktu tutup	floor three · the memory service
found = await ctx.search_memory(query) — EDIT TIGA	kebijakan mengingat — setiap pertanyaan, sebelum dia menjawab	recall() → ctx.state["recalled"]

Anak tangga ini mencapai apa yang dikatakan — dan menyimpannya dalam kamus di dalam satu proses, dengan kata-kata Anda sendiri. Kedua bagian tersebut salah, dan bab berikutnya memperbaikinya tanpa kode sama sekali.

6. MemoryBank

• Apa — satu skrip membangun Bank Memori; dua baris yang sudah Anda miliki mulai menulis fakta ke dalamnya dan membacanya kembali.
• Mengapa — layanan memori adalah layanan. Lokasi arsip adalah keputusan deployment, bukan keputusan agen. Anda dapat mengubahnya tanpa memengaruhi agen.
• Bagaimana — jalankan make_tower.py, ucapkan tiga kalimat, tekan 🌙, tekan 🗓, ajukan satu pertanyaan. Kemudian, lihat penulisan dan pembacaan hanya baca.

Membangun menara

Tingkat tiga di bab 3 adalah kamus Python di dalam bash valley.sh. Memory Bank adalah versi terkelola dari lantai tersebut: berada di instance Agent Engine di project Anda, menyimpan fakta yang disarikan dari hari itu, bukan kalimat Anda, dan menemukannya berdasarkan makna, bukan berdasarkan kata-kata yang sama. Anda tidak perlu men-deploy Vesper ke Agent Engine untuk menggunakannya. Instance yang tidak memiliki apa pun yang di-deploy di dalamnya tetap menghosting Bank Memori, dan itulah yang dibangun skrip: menara tanpa penghuni, yang satu-satunya tugasnya adalah menyimpan kartu.

👉💻 Di tab 1 (sekitar satu menit):

cd ~/agent-valley-archive
uv run python scripts/make_tower.py

👀 Perkiraan:

  building the tower in YOUR_PROJECT / us-central1 — about a minute...
  built, with the two topics in archive/topics.py configured on it.

  resource: projects/.../locations/us-central1/reasoningEngines/6792...
  AGENT_ENGINE written to .env

  Next — nothing to restart. The Archive reads .env on every message:
    look at floor three — under the cards it now says Memory Bank.
    (adk web, if you use it:  --memory_service_uri "agentengine://projects/.../reasoningEngines/6792...")

Satu panggilan SDK, agent_engines.create(), dan satu baris yang ditulis ke dalam .env. Arsip membaca ulang file tersebut pada setiap permintaan, jadi tidak ada yang perlu dimulai ulang.

Jika skrip menolak. Memory Bank adalah layanan Vertex AI: layanan ini memerlukan project Google Cloud dengan penagihan aktif dan aiplatform.googleapis.com diaktifkan — kunci AI Studio tidak dapat menjangkaunya. Skrip mencetak bagian mana yang tidak ada.

Lihat cara kerjanya

👉🖥 Lihat lantai tiga — menara akan digambar ulang dengan sendirinya dalam beberapa detik. Di bagian kartu, kini tertulis Memory Bank, dan galeri kosong: tiga kutipan dari bab 3 sedang dalam proses, dan ini bukan prosesnya. Ucapkan tiga kalimat lagi, satu pesan atau tiga:

I read by it at night, so night is exactly when I need it.
I've tried hanging it higher. No change.
I don't want a new one — it was a gift.

👉🖥 Tekan 🌙 itu saja untuk hari ini. Waktu penutupan sekarang sekitar delapan detik — menara sedang mengekstrak. Kemudian, lihat lantai tiga.

👀 Kartu tersebut bukan kalimat Anda. Mereka mengatakan hal-hal seperti Saya menggunakan lentera untuk membaca di malam hari, dan lentera tersebut terus mati dan Saya sudah mencoba menggantung lentera lebih tinggi, yang masing-masing ditandai fact dengan tanggal. Distilasi. Yang masuk adalah percakapan. Yang keluar adalah fakta.

👉🖥 Tekan 🗓 sebulan kemudian — kunjungan baru, jadi tidak ada lagi yang Anda katakan dalam percakapan — dan tanyakan hal ini, pertanyaan yang tidak memiliki satu kata pun dengan kartu:

Should I just get a different lamp?

👀 Karena ini adalah hadiah, Anda menyebutkan bahwa Anda tidak ingin mengganti lentera — dan Anda sudah mencoba menggantungnya lebih tinggi. Setiap kata itu berasal dari kartu, dan hanya kartu yang dapat memberitahunya: kunjungan ini adalah satu pesan lama. Penelusuran kemiripan. Menara mencocokkan makna, bukan kata-kata — pertanyaan mengatakan lampu dan berbeda, kartu mengatakan lentera dan ganti. Dan sekarang sudah keluar dari proses: matikan menara malam ini dan kartu akan tersedia besok, karena kartu tersebut berada di Agent Engine, bukan di bash valley.sh.

Lihat di konsol. Konsol Google Cloud → telusuri "Agent Engine" → agent-valley-archive-tower → Memory Bank. Fakta yang disarikan dari kunjungan Anda dapat diperiksa di sana — memori yang dapat Anda audit di luar kode apa pun.

Penulisan dan pembacaan — hanya baca

Hanya baca — tidak ada yang perlu diketik. Kedua baris di bawah sudah ada di archive/agent.py dan sudah berkomunikasi dengan menara; tower_service sudah ada di archive/service.py. Bagian ini menjelaskan apa yang mereka lakukan sekarang setelah pindah rumah.

Tidak ada yang berubah di archive/agent.py. Dua baris yang Anda temui di bab 3 melakukan semua itu; hanya layanan di baliknya yang berpindah.

Tulis — file, baris yang Anda baca di bab 3:

await ctx.add_events_to_memory(events=ctx.session.events, custom_metadata=FILING)

Di dalam benaknya, hal ini membuat kalimat Anda tetap utuh. Di Memory Bank, memories.generate adalah: model ekstraksi membaca hari dan menulis fakta di bawah (app_name, user_id) — pasangan yang sama yang mengunci laci, sehingga menara satu pengunjung adalah menara satu pengunjung. FILING adalah apa yang dia berikan bersama dengan hari:

FILING: dict[str, Any] = {
    "wait_for_completion": True,
    "allowed_topics": TOPICS,
}

wait_for_completion adalah delapan detik: ekstraksi adalah panggilan model, dan panggilan hanya ditampilkan jika fakta ada. allowed_topics adalah apa yang dapat dipertahankan — dua topik di archive/topics.py, USER_PREFERENCES, dan LANTERN_CONTEXT, yang dikonfigurasi di menara saat skrip membangunnya. Beri tahu dia apa yang Anda makan saat makan siang dan tidak diekstrak — bukan karena perintah memintanya untuk mengabaikannya, tetapi karena tidak ada topik yang sesuai untuknya. Apa yang tidak boleh diingat diputuskan pada saat penulisan, bukan dalam perintah.

Bacaan — recall, baris yang Anda tulis sebagai EDIT TIGA:

found = await ctx.search_memory(query)

Dalam benaknya, ini menghitung kata-kata yang dibagikan. Di Memory Bank, memories.retrieve dengan pertanyaan yang disematkan: fakta terdekat dalam cakupan pengunjung ini akan muncul, sehingga pertanyaan yang tidak memiliki kata-kata dari kartu dapat menemukan kartu yang tepat.

Apa yang memindahkan mereka — tower_service di archive/service.py, hanya baca:

def tower_service(engine: str) -> BaseMemoryService:
    """The memory service for a tower name — or, with none, for her head."""
    if engine:
        from google.adk.memory import VertexAiMemoryBankService

        return VertexAiMemoryBankService(
            project=os.environ["GOOGLE_CLOUD_PROJECT"],                      # which project
            location=os.environ.get("MEMORY_BANK_LOCATION", "us-central1"),   # where it lives
            agent_engine_id=engine.split("/")[-1],                           # WHICH tower
        )
    return InMemoryMemoryService()

Tiga parameter, dan akan menggantikan InMemoryMemoryService di Runner(memory_service=...). Penulisan dan pembacaan tidak berubah berdasarkan karakter. Hanya rumah yang dipindahkan — dan nama rumah berada dalam satu baris di .env.

dalam benaknya (bab 3)	Memory Bank (bab ini)
berada dalam proses	berada di Agent Engine dalam project Anda, dan bertahan lebih lama dari setiap proses
mempertahankan kalimat Anda	menyimpan fakta yang diekstrak dari hari itu, masing-masing dalam topik
menemukan berdasarkan kata yang sama	menemukan berdasarkan arti
menambahkan	menggabungkan — fakta yang bertentangan dengan fakta lama akan merevisinya

Hak untuk dilupakan

👉🖥 Tekan 🔥 lupakan saya, di bawah kotak pesan.

👀 Tiga lantai menjadi gelap dan satu tidak:

	apa yang dipegangnya	setelah 🔥
lantai tiga, kartu	apa yang dia ingat — fakta yang disarikan Memory Bank dari kunjungan Anda	hilang — memories.delete, satu kartu dalam satu waktu
lantai dua, laci	user:case, slip yang mengikuti pengunjung ini dari kunjungan ke kunjungan	dihapus
meja, slip	salinan kasus kunjungan ini	dihapus
lantai satu, buku	kunjungan itu sendiri — satu sesi di archive.db per kunjungan, setiap pesannya	tidak berubah — jumlah tidak bergerak

Buku tersebut adalah catatan: bahwa kunjungan terjadi, pada hari apa, dan apa yang dikatakan di dalamnya. Kartu dan panel adalah kenangan: apa yang dia dapatkan dari kunjungan tersebut dan dibawa ke kunjungan berikutnya. Permintaan untuk dilupakan adalah tentang ingatan — fakta yang diperoleh tentang seseorang, dan status yang mengikutinya. Apakah catatan kunjungan juga dihapus atau tidak adalah keputusan terpisah, yang dibuat karena alasan terpisah — jejak audit, histori dukungan — dan lab ini sengaja mempertahankannya, sehingga Anda dapat melihat keduanya terpisah di depan Anda: catatan dan memori bukanlah hal yang sama, dan melupakan salah satunya tidak memengaruhi yang lain. Itulah kalimat di atas pintu Vesper, yang terlihat dari sisi lain.

Abstraksi memori ADK memiliki add_events_to_memory dan search_memory. Tidak ada opsi hapus. Proses melupakan adalah tindakan tata kelola, bukan tindakan agen, sehingga berada di aplikasi — archive/tower.py, memories.delete di klien mentah — tempat model tidak dapat menjangkaunya secara tidak sengaja. Apakah agen dapat melupakan sesuatu adalah sesuatu yang Anda desain, sama seperti apakah agen dapat mengingat sesuatu.

Yang Anda bangun dan baca, serta apa itu

hal	Apa itu	tempatnya berada
make_tower.py → AGENT_ENGINE di .env — dibuat, tidak diedit, tidak ada yang dimulai ulang	layanan memori, sebagai layanan: keputusan deployment, di luar agen	Vertex AI Memory Bank di Agent Engine
tower_service(engine) — Anda hanya membacanya	slot Runner(memory_service=...) yang sama, rumah yang berbeda	archive/service.py
"allowed_topics": TOPICS di FILING — hanya baca	apa yang dapat dipertahankan, diputuskan pada saat penulisan, bukan dalam perintah	archive/topics.py + konfigurasi menara
🔥 → memories.delete — ditekan, tidak ditulis	melupakan adalah tindakan aplikasi; API memori ADK tidak memiliki penghapusan	archive/tower.py

Anak tangga ini mencapai apa yang dikatakan. Satu hari berlalu; satu fakta muncul — yang disarikan dari apa yang diizinkan oleh topik — dan buku di lantai satu tidak pernah berpindah.

7. GraphRAG

Opsional.

• Apa — satu skrip memuat masa lalu lembah ke BigQuery, membuat embedding di dalam gudang dan menempatkan grafik di atas tabel tanpa memindahkan baris; lalu dua pertanyaan untuk Vesper, yang memiliki dua kueri yang diatur untuknya: satu untuk apa yang terdengar serupa, satu untuk apa yang terhubung.
• Mengapa — terdengar sama tidak sama dengan terhubung. Vektor menemukan tempat untuk mencari; grafik menemukan apa yang terlampir; dan jawaban harus membawa jalur yang dilaluinya.
• Bagaimana — bash scripts/season.sh, sekali. Semua hal lainnya dalam bab ini bersifat hanya baca.

Menara Vesper dicakup untuk Anda — (app_name, user_id) — berdasarkan konstruksi. Kunjungan orang lain bukanlah ingatannya, dan mencarinya lebih keras tidak akan mengubah hal itu. Mereka adalah milik lembah, dan lembah menyimpannya di gudang. Tiga puluh satu pengunjung musim ini datang karena lentera q7 padam di malam hari, dan salah satu dari mereka menemukan penyebabnya. Bab ini memuat gudang tersebut dan memberikan dua kueri tetap ke dalamnya.

Graph RAG

RAG adalah ambil, lalu buat: temukan data yang tepat, berikan kepada model, biarkan model menjawab dari data tersebut. RAG biasa mengambil berdasarkan kemiripan — sematkan pertanyaan, tarik catatan terdekat. Hal ini menemukan hal-hal yang terdengar seperti pertanyaan, dan di sinilah menara di chapter 4 berhenti. Graph RAG menambahkan langkah pengambilan kedua yang mengikuti tepi — kunci, yang sudah dimiliki gudang — dari kesamaan apa pun yang ditemukan, hingga apa pun yang terlampir padanya. Kedua langkah tersebut menjawab pertanyaan yang berbeda, dan bab ini membuat Anda mengajukan keduanya:

langkah	pertanyaan yang dijawabnya	cara	dalam bab ini
kemiripan	di mana saya harus mencarinya?	menyematkan pertanyaan, VECTOR_SEARCH	season_search — saat pengunjung tidak membawa tanda
traversal	apa yang terhubung ke sana?	MATCH jalur melalui grafik properti	season_known_issue — satu tetap MATCH
pembuatan	Apa yang harus saya katakan kepada tamu?	model, dengan jalur sebagai kutipannya	jawabannya

Menjalankan aplikasi

Musim dikirimkan sebagai CSV biasa di season/ — pengunjung, item, permintaan, perbaikan, musim — seperti yang diekspor oleh sistem dukungan. Satu skrip akan membawanya ke gudang, dan hanya skrip itu yang Anda jalankan di bab ini.

👉💻 Di tab 1 (sekitar tiga menit; mencetak setiap langkah saat berjalan, dan berhenti pada langkah pertama yang gagal):

cd ~/agent-valley-archive
bash scripts/season.sh

👀 Saat berakhir, lantai empat di menara akan menyala, dan legenda di sampingnya bertuliskan buka.

Jika langkah 7 mencetak tidak memiliki izin untuk mengakses atau menggunakan endpoint. Itulah peran yang baru saja diberikan oleh langkah 6, yang masih dipropagasi; skrip menunggunya — hingga sekitar dua menit, 15 detik setiap kali, dan mengatakan demikian. Jika gagal, jalankan skrip lagi; semuanya di dalamnya bersifat idempoten. Hingga langkah 8 selesai, lantai empat tetap terkunci dan dia akan mengatakan bahwa musimnya belum ada di gudang.

Yang dibangunnya — hanya baca

Hanya baca — tidak ada yang perlu dijalankan. Setiap pernyataan di bawah sudah berjalan di dalam scripts/season.sh, dalam urutan ini. Kode tersebut dicetak untuk dibaca, bukan untuk ditempelkan ke bq; skrip adalah satu-satunya hal yang akan dijalankan dalam bab ini.

1 · Data, dengan jenis. Satu bucket, lima tabel, satu bq load per tabel dengan skema eksplisit. Ini adalah gudang; kolom memiliki nama dan jenis:

bq load --replace --source_format=CSV --skip_leading_rows=1 archive.asks gs://.../asks.csv id:STRING,visitor_id:STRING,item_id:STRING,day:STRING,season:STRING,said:STRING

👀 Harapkan 34 bertanya: tiga puluh satu lentera, dan tiga hal lain yang salah musim ini, jadi jumlah baris bukanlah jumlah lentera.

2 · Arti, di tempat. Koneksi memungkinkan BigQuery memanggil Vertex AI; lalu model sematan adalah satu pernyataan, dan setiap permintaan disematkan di tempatnya — tanpa ekspor, tanpa pipeline:

CREATE OR REPLACE MODEL archive.embedder REMOTE WITH CONNECTION `US.vertex_conn`
  OPTIONS (ENDPOINT = "gemini-embedding-001");

CREATE OR REPLACE TABLE archive.ask_embeddings AS
  SELECT id, content, ml_generate_embedding_result AS embedding
  FROM ML.GENERATE_EMBEDDING(MODEL archive.embedder, (SELECT id, said AS content FROM archive.asks));

👀 Expect 34, 3072 — setiap permintaan kini berupa vektor 3072 dimensi, di samping tabel asalnya. Kemudian, skrip mengajukan satu pertanyaan berdasarkan maknanya:

SELECT base.content, ROUND(distance, 3) AS distance
FROM VECTOR_SEARCH(TABLE archive.ask_embeddings, "embedding",
  (SELECT ml_generate_embedding_result FROM ML.GENERATE_EMBEDDING(
     MODEL archive.embedder, (SELECT "the flame keeps dying on me once the sun is down" AS content))),
  top_k => 3)

👀 Harapan (terverifikasi): tiga salinan it keeps cutting out after dark, which is the only time I need it — jarak 0.648. Tidak ada satu kata pun yang sama dengan pertanyaan. Itulah langkah kesamaan: menemukan tempat untuk melihat. Tidak ada satu pun yang mengatakan apakah ketiga pengunjung tersebut terhubung ke lentera pengunjung ini.

3 · Koneksi, yang diletakkan di atas tabel. Kelima tabel tersebut sudah berupa grafik — tidak ada yang membuatnya; mereka hanya menjalankan lembah. Tabel yang barisnya adalah sesuatu adalah tabel node: pengunjung, item, perbaikan. Tabel yang barisnya adalah relation adalah tabel tepi: permintaan adalah satu pengunjung yang membawa satu item. Dan items adalah keduanya — lentera adalah sebuah benda, dan mark-nya adalah yang mengikatnya ke batch. Satu-satunya tabel yang tidak dikirimkan pada musim ini adalah batch itu sendiri: tidak ada yang mencatat "q7" sebagai baris, itulah kesamaan tiga puluh satu baris. Satu SELECT DISTINCT dan sudah ada. Dua langkah terakhir skrip:

CREATE OR REPLACE TABLE archive.marks AS SELECT DISTINCT mark FROM archive.items;

CREATE OR REPLACE PROPERTY GRAPH archive.season_graph
  NODE TABLES (
    archive.visitors AS Visitor KEY (id)   PROPERTIES (id, name, species),
    archive.items    AS Item    KEY (id)   PROPERTIES (id, kind, mark),
    archive.marks    AS Mark    KEY (mark) PROPERTIES (mark),
    archive.fixes    AS Fix     KEY (mark) PROPERTIES (mark, what, found_by, day))
  EDGE TABLES (
    archive.asks  AS asked   KEY (id)   SOURCE KEY (visitor_id) REFERENCES Visitor (id)
                                        DESTINATION KEY (item_id) REFERENCES Item (id)
                                        PROPERTIES (day, season, said),
    archive.items AS stamped KEY (id)   SOURCE KEY (id) REFERENCES Item (id)
                                        DESTINATION KEY (mark) REFERENCES Mark (mark),
    archive.fixes AS fixed   KEY (mark) SOURCE KEY (mark) REFERENCES Mark (mark)
                                        DESTINATION KEY (mark) REFERENCES Fix (mark))

Membacanya sebagai peta:

(Visitor) ──asked──▶ (Item) ──stamped──▶ (Mark) ──fixed──▶ (Fix)
 who came             what they          the batch          what was wrong
                      brought            it belongs to      with the batch

Tidak ada baris yang dipindahkan. Grafik properti di BigQuery adalah tampilan dengan arah: tabel tetap berada di tempatnya; pernyataan menunjukkan kolom mana yang merupakan kunci dan kolom mana yang merupakan panah. Lepaskan grafik dan tabel tidak akan berubah.

Kemudian, jalan kaki:

SELECT * FROM GRAPH_TABLE(archive.season_graph
  MATCH (m:Mark)<-[:stamped]-(i:Item)<-[a:asked]-(v:Visitor)
  WHERE m.mark = "q7"
  OPTIONAL MATCH (m)-[:fixed]->(f:Fix)
  RETURN m.mark AS mark, COUNT(DISTINCT v.id) AS visitors,
         COUNT(DISTINCT a.said) AS things_said, ANY_VALUE(f.what) AS fix)

👀 Harapkan, di project dengan pemesanan Enterprise:

mark  visitors  things_said  fix
q7    31        10           the wicks in the q7 batch were dipped too shallow — they drown in the oil and starve in an hour

Dalam project on-demand biasa, satu pernyataan ini ditolak — catatan setelah kotak ini menjelaskan alasannya — dan skrip mengatakan demikian dan selesai. Dia tetap mendapatkan baris yang sama persis.

Itulah GQL — bahasa kueri grafik ISO, MATCH yang mungkin Anda kenal dari database grafik lain — di dalam SELECT biasa. Polanya adalah kalimat: mulai dari tanda; mundur ke setiap item yang diberi tanda; kembali lagi ke siapa pun yang bertanya tentang setiap item; dan jika tanda memiliki perbaikan, maju satu langkah ke tanda tersebut. OPTIONAL MATCH adalah yang membuat tanda tanpa perbaikan tidak hilang — tiga tanda musim ini tidak memiliki perbaikan. Tiga puluh satu baris yang sama adalah tiga gabungan di SQL; yang ditambahkan oleh kueri grafik adalah bahwa bentuk penelusuran dapat dibaca dari pernyataan, dan bentuk tersebut adalah yang akan dia berikan kepada pengunjung sebagai kutipan.

Edisi. Kueri grafik BigQuery — GRAPH_TABLE — memerlukan reservasi Enterprise atau Enterprise Plus. Di project on-demand biasa, penelusuran ditolak dengan pesan Kueri BigQuery Graph memerlukan reservasi dengan edisi Enterprise atau Enterprise Plus. Skrip mencetak dan menyelesaikan tugas tersebut, karena tabel dan grafik sudah ada, dan alatnya kemudian menelusuri baris yang sama seperti tiga gabungan SQL — asks ⋈ items ⋈ visitors ⟕ fixes — dan menunjukkannya di kolom walked. Jawabannya dan jalurnya akan sama. Jika CREATE PROPERTY GRAPH itu sendiri ditolak, alat akan menjawab locked dengan langkah yang harus dijalankan, bukan menebak.

Cara dia membacanya — hanya baca

Hanya baca. Dua fungsi dan satu konstanta, sudah ada di archive/season/__init__.py. Vesper memanggil mereka; Anda tidak.

👉📖 Buka archive/season/__init__.py. Dua fungsi dan satu konstanta, dan tidak ada yang menggunakan kueri. Konstanta pertama — ini adalah seluruh penelusuran:

GQL = """
SELECT * FROM GRAPH_TABLE(`{ds}.season_graph`
  MATCH (m:Mark)<-[:stamped]-(i:Item)<-[a:asked]-(v:Visitor)
  WHERE m.mark = @mark AND a.season = @season
  OPTIONAL MATCH (m)-[:fixed]->(f:Fix)
  RETURN v.name AS who, a.said AS said, a.day AS day, f.what AS what, f.found_by AS found_by)
ORDER BY day"""

👀 Baca baris MATCH sebagai kalimat, dengan mengikuti panah:

potongan	dalam kata-kata
(m:Mark)	mulai di tanda — q7
<-[:stamped]-(i:Item)	kembali ke setiap item yang diberi stempel
<-[a:asked]-(v:Visitor)	kembali lagi kepada siapa pun yang menanyakan setiap item
OPTIONAL MATCH (m)-[:fixed]->(f:Fix)	dan, jika tanda memiliki perbaikan, maju satu langkah ke tanda tersebut
@mark, @season	hanya dua hal yang bervariasi — model mengisi salah satunya, dan tidak pernah menulis jalan

• GQL — MATCH yang baru saja Anda baca, dengan @mark dan @season sebagai parameter. Ini adalah satu-satunya jalan yang bisa dia lakukan.
• season_search(text) — VECTOR_SEARCH dari pernyataan 2, digabungkan kembali dengan siapa yang mengatakannya dan tanda pada apa yang mereka bawa. Tugasnya adalah memberi tahu tempat untuk mencari.
• season_known_issue(mark, season) — menjalankan GQL. Satu tanda masuk; jumlah, apa yang dikatakan, penyebabnya, siapa yang menemukannya, dan jalur keluar.
• SQL — sama seperti tiga gabungan, hanya dijalankan saat edisi project menolak GRAPH_TABLE; alat akan menunjukkannya di walked.

Dia hanya memegang kedua file ini setelah gudang ada: tools_for_vesper() di archive/agent.py menyerahkannya kepadanya saat season.is_open() benar, dan layanan mengimpor ulang file tersebut di setiap pesan. Sebelum skrip, lantai empat terkunci dan dia tidak dapat mencapainya sama sekali — deskripsi masalah Anda sendiri tidak akan pernah disalahartikan sebagai pertanyaan tentang masalah orang lain.

Vesper tidak pernah menulis GQL, dan tidak pernah menulis SQL. Kedua pernyataan sudah ditetapkan; model menyediakan satu parameter. Baca instruksinya di agent.py: diberi tanda, berjalan. Jika tidak ada, telusuri terlebih dahulu, ambil tanda yang dibawa oleh kecocokan terdekat, lalu berjalan — dan jangan pernah menyajikan apa yang terdengar serupa sebagai bukti apa pun. Itulah tabel di bagian atas bab, sebagai kebijakan: vektor menemukan tempat untuk mencari, grafik menemukan apa yang terhubung, model menjawab dengan jejak kutipan. Kalimat ini juga merupakan kalimat minggu ketiga di ruangan baru: model mengisi formulir, kode memindahkan percikan.

Tanyakan padanya

👉🖥 Tingkat empat sudah dibuka di menara. Tanyakan arah jalan kepadanya seperti yang dilakukan pengunjung lainnya:

Has anyone else had a q7 lantern go out at night?

👀 Dia menjawab — tiga puluh satu orang lainnya... sebagian besar mengatakan bahwa api menyala rendah dan padam setelah satu jam... Berang-berang Marlow menemukan bahwa sumbu dicelupkan terlalu dangkal — dan baris terakhir jawabannya adalah jalur. Berikut outputnya — baca, jangan kirimkan kembali kepadanya:

mark q7 → 31 visits this season → 10 different things said → the wicks in the q7 batch were dipped too shallow — they drown in the oil and starve in an hour

Jalur adalah kutipan. Setiap lompatan di dalamnya adalah tepi dalam grafik, dan tepi adalah kunci, sehingga siapa pun dapat melaluinya lagi dan mendapatkan tiga puluh satu yang sama. Skor kemiripan tidak dapat diakses lagi oleh siapa pun. Jika dia mengatakan, tepat sebelum jalur, bahwa baris kembali melalui tiga gabungan karena project tidak memiliki reservasi grafik, maka edisi project Anda menolak GRAPH_TABLE — baris dan jalur sama.

👉🖥 Sekarang hapus tanda tersebut — kirim ini:

Has anyone else had a lantern that keeps dying once the sun is down?

👀 Dia mencapai angka tiga puluh satu yang sama, dan jalur yang sama. Yang berubah adalah jalannya: season_search berjalan lebih dulu, menemukan lima pengunjung yang terdengar serupa — masing-masing membawa q7 — mengambil tanda itu, dan baru kemudian berjalan. Serupa tidak terhubung; serupa adalah tempat untuk mencari.

Asal angka tiga puluh satu. Bab 1 hingga 4 menghasilkan setiap fakta yang mereka gunakan, itulah sebabnya lab ini berdiri sendiri. Bab ini mengirimkan masa lalu lembah sebagai data — bukan sebagai jalan pintas, tetapi karena itulah definisinya. Memori institusional adalah memori orang lain, dan berdasarkan konstruksinya, Anda tidak ada di sana.

Apa yang dimuat, dan apa itu

hal	Apa itu	tempatnya berada
bq load dengan skema eksplisit — dijalankan, tidak ditulis	gudang: kolom dengan nama dan jenis	archive.visitors / items / asks / fixes / seasons
ML.GENERATE_EMBEDDING + VECTOR_SEARCH	langkah kesamaan — tempat mencari	archive.ask_embeddings, model embedder
CREATE PROPERTY GRAPH — tidak ada baris yang dipindahkan	langkah penelusuran — apa yang terhubung; tabel menjadi node dan panah	archive.season_graph
GQL di archive/season/__init__.py — satu parameter	satu-satunya jalan yang mungkin ia lalui; jalur tersebut adalah kutipan	season_known_issue(mark)

Beberapa lusin pengunjung bukanlah alasan untuk membeli gudang. Yang diajarkan dalam bab ini adalah bentuk kueri — bukan skala. Perbesar grafik ini seribu kali dan MATCH tidak akan berubah satu karakter pun.

8. Tutup

Tiga jalur, satu menara, satu gudang — empat lantai. Tidak ada yang dimulai ulang.

anak tangga	apa yang Anda lakukan	apa yang dibeli
ONE	tool_context.state[CASE] = case — pengeditan	kesalahan yang ada: status ditulis oleh kode
DUA	CASE = "user:case" — pengeditan	laci yang mengikuti pengunjung
pengarsipan	await ctx.add_events_to_memory(..., custom_metadata=FILING) — dibaca, tidak ditulis	apa yang dikatakan, disimpan
TIGA	found = await ctx.search_memory(query) — pengeditan	apa yang disimpan, diminta — yang diajukan tidak diingat
menara	make_tower.py, lalu AGENT_ENGINE di .env — dibuat dan terhubung oleh satu jalur, tidak ada yang dimulai ulang	menara yang menyuling, dan bertahan di malam hari
aturan	allowed_topics dalam FILING — dibaca, tidak ditulis	hanya yang harus disimpan
musim	season.sh — dimuat, disematkan di tempat, grafik yang ditumpuk di atasnya, berjalan dengan satu MATCH	kunjungan orang lain, berdasarkan makna dan koneksi

Bagian yang diganti

ADK 2	apa yang akan Anda tulis sebagai gantinya	biayanya
session.state + satu alat, disimpan oleh SqliteSessionService	dict di samping loop chat, di-pickle ke disk sendiri	model tidak dapat membacanya, dan Anda menulis resume dan penguncian
imbuhan user:	tabel pengguna dan gabungan di setiap giliran	memutuskan tempat kunci berada, setiap saat
add_events_to_memory + search_memory di node fungsi	cron yang membuang transkrip, dan model yang memutuskan kapan harus melihat	tidak ada yang diekstrak, tidak ada yang disuling — dan Anda tidak pernah melihat saat tidak terlihat
VertexAiMemoryBankService + allowed_topics	penyimpanan vektor, perintah ekstraksi, tugas penggabungan, dan "jangan ingat trivia" dalam perintah	tiga layanan, dan aturan ini berlaku hingga model merasa sebaliknya
VECTOR_SEARCH + satu GQL tetap MATCH	mengekspor, menyematkan di tempat lain, database grafik, tugas sinkronisasi, dan penulisan SQL model	data keluar dari gudang untuk dipahami, dan Anda mengetahui gabungan mana yang ditebak saat pelanggan melakukannya

Tiga pertanyaan, berhenti di jawaban ya pertama

1. Apakah hal ini akan penting besok? Tidak → jangan simpan apa pun. Hal ini muncul dan hilang dalam percakapan.
2. Dapatkah fungsi memeriksanya? Ya → laci. Kode menuliskannya, setiap giliran membacanya, dan tidak ada kalimat yang dapat mengubahnya.
3. Selain itu → menara. Disarikan dari apa yang dikatakan, dicari saat diminta, direvisi oleh apa yang dikatakan selanjutnya.

Satu kalimat

Rekaman bukanlah ingatan. Memori adalah catatan ditambah dua keputusan — apa yang harus disimpan, dan kapan harus dicari — dan jenis memori menentukan lantai mana yang akan dituju.

Fakta dan preferensi berada di toko yang berbeda.

👀 Setiap lantai diterangi. Hewan peliharaan Anda berada di bagian atas. Stempel Arsip ada di paspor, dan minggu kelima membuka Pasar Malam — tempat Nix menjalankan panggung secara lisan, secara real time, dan semua yang diketahui menara akan menyertai Anda.