Memori Agen

Sebelum mulai, pastikan empat hal ini sudah akrab bagimu:

• Tool use, yaitu putaran tool_use / tool_result. Topik Tool Use (Function Calling) di bidang ini adalah titik mulainya, karena menulis dan membaca memori sebenarnya adalah panggilan tool.
• API tanpa keadaan: setiap permintaan membawa seluruh riwayat, dan tak ada yang diingat di sisi model.
• Token: kira-kira berapa token yang dihabiskan prompt, riwayat, dan hasil tool. Konteks diukur dalam token, bukan dalam jumlah pesan.
• Python 3.10 atau lebih baru untuk contoh kode dengan SDK resmi anthropic.

Cara terbaik memahami masalah memori adalah mengalaminya sendiri. Coba percobaan kecil ini:

1. Kirim dua permintaan terpisah ke model: "Nama saya Rina.", lalu "Siapa nama saya?". Jawaban kedua tak tahu namamu, karena permintaan itu tak membawa yang pertama.
2. Kirim ulang dengan riwayat lengkap. Sekarang ia "ingat".
3. Hitung token riwayatnya setelah 20 giliran yang masing-masing memanggil tool berkas.

Kesimpulannya: semua "ingatan" adalah teks yang kamu kirim ulang, dan teks itu terus bertambah panjang.

Teori lebih mudah dipahami bila langsung dipakai. Ambil satu agen yang sedang atau ingin kamu bangun, lalu isi tabel ini:

Sebagai contoh, untuk agen perpustakaan: memori kerja adalah riwayat percakapan saat ini; episodik adalah log peminjaman yang pernah diproses; semantik adalah profil anggota (genre favorit, lama pinjaman) dan katalog; prosedural adalah prompt sistem dan kode tool-nya.

CoALA mencatat bahwa memori prosedural agen bahasa ada dua: yang tersirat di bobot model dan yang tersurat di kode agen. Mengubah bobot jarang dilakukan; mengubah kode dan prompt jauh lebih sering, dan itu juga termasuk "belajar".

Riwayat percakapan adalah memori jangka pendek agen. Ia perlu dikelola sebelum menabrak batas konteks, dan ada tiga cara umum:

• Potong jendela: simpan N giliran terakhir saja. Murah, tetapi fakta dari awal percakapan hilang.
• Ringkas: ganti giliran lama dengan ringkasan. Intinya bertahan, tetapi detail hilang.
• Pisahkan per thread: LangGraph menyimpan memori jangka pendek per thread (satu alur percakapan) lewat checkpointer, sehingga percakapan bisa dilanjutkan dan tidak bercampur dengan percakapan lain.

Hati-hati dengan dua jebakan:

1. Jangan memotong di tengah pasangan tool_use / tool_result; keduanya wajib berpasangan dan berurutan.
2. Pada model dengan preserved thinking, mengedit giliran lama di sisi klien bisa membatalkan blok thinking sesudahnya. Pengelolaan konteks di sisi server, yaitu context editing dan compaction, tak membatalkannya.

Latihan: tulis fungsi yang memotong riwayat ke N giliran terakhir tanpa memisahkan pasangan tool apa pun.

Hasil tool sering menjadi bagian terbesar konteks, padahal jarang dibutuhkan lagi setelah diproses, seperti tumpukan fotokopi yang sudah dibaca di meja kerja. Strategi clear_tool_uses_20250919 merapikannya di sisi server: begitu ambangnya terlampaui, hasil tool tertua dibuang. Begini cara mengaktifkannya:

response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    betas=["context-management-2025-06-27"],
    tools=[{"type": "memory_20250818", "name": "memory"}],
    context_management={
        "edits": [
            {
                "type": "clear_tool_uses_20250919",
                "trigger": {"type": "input_tokens", "value": 30000},
                "keep": {"type": "tool_uses", "value": 3},
                "clear_at_least": {"type": "input_tokens", "value": 5000},
                "exclude_tools": ["memory"],  # hasil memory tool tak pernah dibuang
            }
        ]
    },
    messages=messages,
)

Aplikasimu tetap menyimpan riwayat utuh. Pemangkasan terjadi sebelum prompt sampai ke model, dan respons melaporkannya di context_management.applied_edits.

Bila yang membengkak adalah percakapan itu sendiri, bukan hasil tool, compaction mengganti giliran lama dengan ringkasan yang ditulis Claude di server. Dokumentasi Claude menempatkannya sebagai strategi utama untuk percakapan panjang. Ada dua cara memakainya, dan keduanya masih beta:

Seni compaction ada pada memilih apa yang dibuang. Saran Anthropic bagi yang menulis peringkas sendiri: maksimalkan recall lebih dulu, yaitu pastikan semua yang relevan tertangkap, baru tingkatkan presisi. Claude Code, misalnya, mempertahankan keputusan arsitektur, bug yang belum terselesaikan, dan detail implementasi, lalu melanjutkan dengan ringkasan itu ditambah lima berkas yang terakhir diakses.

Cara paling sederhana dengan SDK Python: BetaLocalFilesystemMemoryTool menyimpan berkas di disk, dan Tool Runner memutar putarannya untukmu:

memori = BetaLocalFilesystemMemoryTool(base_path="./data-memori")  # berkas di ./data-memori/memories

runner = client.beta.messages.tool_runner(
    model="claude-opus-5-5",
    max_tokens=16000,
    tools=[memori],
    messages=[{"role": "user", "content": "Ingat: saya suka novel sejarah dan selalu meminjam 14 hari."}],
)
akhir = runner.until_done()

Definisi tool-nya cukup {"type": "memory_20250818", "name": "memory"}, tanpa skema, karena skemanya milik Anthropic dan modelnya sudah dilatih memakainya.

Coba jalankan dua kali di dua proses berbeda. Sesi pertama menulis /memories/anggota-a9.md; sesi kedua membacanya kembali, lengkap dengan nomor baris selebar enam karakter dan tab, sesuai dokumentasi.

Untuk proyek yang berlangsung berhari-hari, dokumentasi memory tool menyarankan pola multisesi. Sesi pertama menyiapkan log kemajuan dan daftar fitur. Setiap sesi berikutnya membacanya lebih dulu, dan setiap sesi berakhir dengan memperbarui log. Tandai fitur selesai hanya setelah diverifikasi dari ujung ke ujung.

Rumus Generative Agents ternyata cukup ringkas untuk ditulis dalam Python murni:

def ambil(memori: list[dict], kueri: list[float], jam_sekarang: float, k: int = 2) -> list[str]:
    recency = normal([0.995 ** (jam_sekarang - m["jam_terakhir_dibaca"]) for m in memori])
    importance = normal([m["penting"] for m in memori])            # 1..10, dinilai model
    relevance = normal([kosinus(m["vektor"], kueri) for m in memori])
    skor = [r + i + v for r, i, v in zip(recency, importance, relevance)]
    urut = sorted(range(len(memori)), key=lambda n: skor[n], reverse=True)
    return [f"{skor[n]:.2f}  {memori[n]['teks']}" for n in urut[:k]]

normal() adalah normalisasi min-max ke 0–1, dan kosinus() menghitung kemiripan kosinus. Dengan tiga memori contoh dan kueri tentang selera baca anggota, keluarannya:

2.56  Anggota A-9 suka novel sejarah
1.54  Anggota A-9 terlambat mengembalikan buku sekali

"Perpustakaan tutup hari Senin" (1,00) tak terambil walaupun paling baru dibaca, karena ia tak penting dan tak relevan dengan kuerinya. Di sini terlihat bagaimana tiga komponen saling menyeimbangkan.

Latihan: ubah bobot relevance menjadi 2 dan lihat urutan mana yang berubah. Bobot yang sama hanyalah pilihan makalahnya, bukan hukum.

Dua keputusan desain ini paling sering keliru, padahal akibatnya terasa lama.

Kapan menulis. Di jalur utama, agen menulis sebelum menjawab: memorinya segera tersedia, tetapi pengguna menunggu lebih lama dan agen menanggung beban keputusan tambahan. Di latar, proses terpisah menulis memori dari percakapan yang sudah lewat: tak ada penantian, tetapi memorinya datang terlambat.

Bentuk memori semantik.

Untuk memori episodik, bentuk yang paling praktis adalah contoh few-shot: simpan contoh tugas yang berhasil, lalu ambil yang paling mirip dengan masukan saat ini.

Latihan: untuk agen perpustakaan, putuskan apakah preferensi anggota disimpan sebagai profil atau koleksi, dan tulis alasanmu dalam dua kalimat.

Sub-agen adalah teknik memori yang sering terlupa. Bayangkan seorang manajer yang mengutus asisten membaca seratus dokumen, lalu hanya menerima ringkasan satu halaman. Begitu pula di sini: alih-alih menyimpan semua hasil penjelajahan di konteksnya sendiri, agen utama mengirim tugas terfokus ke sub-agen yang punya konteks bersih. Menurut Anthropic, setiap sub-agen boleh memakai puluhan ribu token untuk menjelajah, tetapi hanya mengembalikan ringkasan padat, sering 1.000 sampai 2.000 token.

Sub-agen layak dipakai untuk:

• riset yang membaca banyak sumber tetapi hanya butuh kesimpulannya;
• pencarian di basis kode besar;
• tugas paralel yang hasil antaranya tak berguna bagi agen utama.

Sebaliknya, jangan pakai sub-agen untuk tugas yang membutuhkan semua detail penjelajahan di satu tempat, atau yang sub-tugasnya saling bergantung erat. Setiap sub-agen menambah biaya, dan menambah satu titik tempat informasi bisa hilang saat diringkas.

Latihan: rancang satu tugas untuk agen perpustakaan yang layak didelegasikan ke sub-agen, dan tentukan format ringkasan yang harus dikembalikannya.

Memori ditulis berdasarkan permintaan model, jadi perlakukan setiap operasinya sebagai masukan yang belum dipercaya.

• Kurung jalur. Setiap jalur harus diawali /memories, diresolusi ke bentuk kanonik, dan tetap di bawah direktori memori. Penangan bawaan SDK (BetaLocalFilesystemMemoryTool) menolak ../../, ..\..\ gaya Windows, dan /etc/passwd. %2e%2e%2f tidak didekode, sehingga hanya menjadi nama berkas aneh di dalam direktori memori.
• Pisahkan per pengguna. Awalan /memories dipetakan ke direktori atau kunci milik satu pengguna, bukan direktori bersama.
• Saring data sensitif. Model biasanya menolak menulis rahasia, tetapi validasi di penangan memberi jaminan yang lebih kuat.
• Batasi ukuran dan umur. Batasi besar berkas dan keluaran view; hapus berkas yang lama tak diakses.
• Waspadai keracunan memori. Isi dari halaman web atau email yang ditulis ke memori akan dibaca lagi di sesi berikutnya. Tandai asalnya, dan jangan menulis instruksi dari sumber tak tepercaya sebagai memori prosedural.

Memori yang tak pernah diukur cenderung tumbuh liar. Lima uji ini memberitahumu apakah memori agenmu benar-benar bekerja:

1. Recall lintas sesi. Tanamkan fakta di sesi 1, lalu tanyakan di sesi 2 di proses baru. Berapa persen yang benar?
2. Fakta yang berubah. Ubah preferensi di sesi 3. Apakah sesi 4 memakai yang baru, atau memori lama dan baru saling bertentangan?
3. Pengambilan. Untuk sekumpulan kueri dengan jawaban yang diketahui, apakah memori yang benar masuk k teratas?
4. Biaya. Berapa token per giliran untuk memori yang dimasukkan, dan berapa yang dihemat context editing atau compaction (usage, context_management.applied_edits)?
5. Keamanan. Uji serangan jalur dan isi beracun setiap kali penangannya berubah.

Kabar baiknya, uji 1, 3, dan 5 bisa berjalan tanpa model sungguhan, karena penyimpanan, pengambilan, dan penangannya adalah kode biasa. Simpan anggaran API untuk uji 2 dan 4, yang memang bergantung pada perilaku model.