Memori agen AI antar sesi: berkas kemajuan, log keputusan, git, dan skrip init

Mengapa agen tidak ingat apa-apa

Model tidak menyimpan keadaan di antara eksekusi. Semua yang «diketahui» agen tentang tugas Anda ada di jendela konteks sesi saat ini: berkas yang sudah dibaca, keluaran perintah, dan percakapan dengan Anda. Ketika sesi ditutup atau konteks penuh, sesi baru mulai dari nol dan hanya melihat apa yang tertulis di disk.

Gambaran yang berguna: seorang insinyur brilian yang setiap pagi datang ke kantor dengan ingatan yang sudah dihapus. Ia akan cepat memahami kode, tetapi tidak akan ingat varian arsitektur mana yang kemarin dipilih, mengapa yang lain ditolak, dan dalam keadaan apa tesnya. Tanpa catatan, ia menghabiskan lima belas sampai dua puluh menit untuk meraba-raba dan besar kemungkinan membangun ulang sesuatu yang sudah sengaja Anda tolak.

Karena itu memori agen AI bukan sifat dari model, melainkan bagian dari harness: kumpulan berkas dan aturan yang Anda rancang sendiri. Kabar baiknya, tidak perlu basis data vektor atau layanan khusus. Beberapa berkas Markdown, git, dan disiplin sudah cukup.

Mengapa jendela konteks yang besar tidak menyelesaikan masalah

Orang sering berpikir cukup menunggu model dengan jendela yang lebih besar. Tetapi tugas yang kompleks akan mengisi jendela berapa pun ukurannya: agen membaca basis kode, mengumpulkan riwayat keputusan, menerima keluaran tes yang bertele-tele, dan menyimpan seluruh dialog. Kebutuhan tumbuh seiring jendela. Ini masalah arsitektur, bukan soal volume.

Ada efek kedua. Mendekati batas jendela, banyak model mulai terburu-buru menyelesaikan: melewatkan pemeriksaan, memilih solusi sederhana alih-alih yang benar. Anthropic menggambarkan pengamatan ini untuk model-model mereka, dan kekuatan efeknya berbeda antar model. Sesi panjang di ambang batas konteks bukan hanya berisiko kehilangan informasi, tetapi juga berisiko menurunkan kualitas kerja.

Kompaksi: apa yang dipertahankan dan apa yang hilang

Kompaksi adalah pemampatan bagian awal dialog menjadi ringkasan singkat untuk memberi ruang di sesi yang sama. Di Claude Code perintahnya adalah /compact, dan pemampatan juga terjadi otomatis ketika mendekati batas. Sebaliknya, /clear menghapus riwayat dan memulai percakapan dari awal.

Masalah kompaksi adalah ringkasannya biasanya mempertahankan «apa» dan kehilangan «mengapa». Kode yang sudah jadi tetap ada di berkas, tetapi penalaran — mengapa dipilih varian B, mengapa tidak memakai pustaka itu, mengapa optimasi sengaja dilewati — terpampat menjadi beberapa kata atau hilang sama sekali. Langkah agen berikutnya lalu «memperbaiki» keputusan yang disengaja, karena alasannya sudah tidak terlihat.

Aturan praktis tanpa metrik yang rumit: ketika tugas sudah menghabiskan sekitar 60% jendela, berhentilah menulis kode dan siapkan serah terima. Jika konteks baru terpakai 40% dan akhir tugas sudah dekat, kompaksi sudah cukup.

Empat artefak yang membentuk memori agen

Alih-alih berharap pada memori model, buatlah buku catatan kerja. Ada empat bagian, dan masing-masing punya peran sendiri.

1. PROGRESS.md — kita sekarang di mana.
2. DECISIONS.md — mengapa dibuat begini, bukan begitu.
3. Commit git — titik simpan keadaan yang gratis.
4. Protokol pergantian shift di AGENTS.md — apa yang dilakukan saat datang dan saat pergi.

PROGRESS.md: berkas kemajuan

Menjawab satu pertanyaan: dalam keadaan apa proyek sekarang. Agen membacanya pertama kali di awal sesi dan memperbaruinya terakhir sebelum pergi. Berkasnya pendek dan ditulis ulang, bukan terus ditambah: sejarahnya hidup di git.

# PROGRESS.md

## Tujuan saat ini
Pencarian katalog produk (fitur search-01)

## Keadaan
- HEAD: 4f2a9c1
- make check: hijau, 142/142 tes
- Selesai: indeks di PostgreSQL (tsvector), endpoint GET /search
- Terverifikasi: unit-test + permintaan curl manual untuk 3 kueri

## Penghambat
- Belum ada data morfologi untuk bahasa Kazakh — menunggu keputusan

## Langkah berikutnya
Tambahkan paginasi ke GET /search, kriteria: tes untuk halaman 2

Perhatikan empat kolom yang cukup untuk serah terima: hash commit, proporsi tes yang lolos, penghambat, dan langkah berikutnya. Jika sesi baru tidak bisa melanjutkan pekerjaan secara pasti hanya dari berkas ini, berarti templatenya kurang satu kolom.

DECISIONS.md: log keputusan

Menyimpan «mengapa» yang hilang saat kompaksi. Format catatannya: keputusan, alasan, apa yang ditolak dan mengapa, serta batasan.

## 2026-03-14 — Cache pengaturan pengguna di Redis
- Keputusan: Redis, TTL 5 menit, invalidasi aktif saat penulisan.
- Alasan: dibaca di setiap permintaan, volume datanya kecil.
- Ditolak: materialized view di PostgreSQL — perubahannya terlalu sering,
  biaya pemeliharaannya tidak sebanding.
- Batasan: jangan cache pengaturan pembayaran.

Baris paling berharga di sini adalah «Ditolak». Baris inilah yang mencegah sesi berikutnya «mengoptimalkan» keputusan kembali ke varian yang sudah dipertimbangkan dan dibuang. Log keputusan, berbeda dengan berkas kemajuan, hanya bertambah: catatan lama tidak dihapus, melainkan ditandai sebagai digantikan oleh catatan baru.

Riwayat git sebagai titik simpan

Commit adalah snapshot keadaan bervesi yang sudah menjadi bagian dari pekerjaan. Agen bisa membaca git log dan git diff untuk memulihkan apa yang berubah. Agar riwayat berfungsi sebagai memori, pesan commit harus menjelaskan maksud, bukan menceritakan ulang diff.

# buruk
git commit -m "update search.py"

# baik
git commit -m "search: indeks tsvector sebagai pengganti LIKE

LIKE '%q%' tidak memakai indeks, pada 200 ribu produk kueri 1,8 detik.
Paginasi belum dibuat, lihat PROGRESS.md."

Commit kecil yang sering, setelah setiap tes hijau, juga memberi titik kembali. Jika sesi melenceng, lebih mudah kembali ke keadaan terverifikasi terakhir daripada mengurai perubahan yang setengah jadi.

Protokol pergantian shift di AGENTS.md

Berkas keadaan tidak berguna jika agen tidak tahu keberadaannya. Karena itu di berkas instruksi utama (AGENTS.md atau CLAUDE.md) ditulis protokol singkat: apa yang dilakukan saat datang dan saat pergi.

## Datang ke shift
1. Baca PROGRESS.md dan DECISIONS.md.
2. Cari tugas aktif di .agent/feature_list.json.
3. Jalankan make check — pastikan repositori konsisten.
4. Lanjutkan dari «Langkah berikutnya», jangan membuka kembali yang sudah diputuskan.

## Pergi dari shift
1. Jalankan make check, commit keadaan hijau.
2. Perbarui PROGRESS.md: HEAD, tes, penghambat, langkah berikutnya.
3. Tambahkan keputusan baru ke DECISIONS.md.
4. Jangan meninggalkan pekerjaan setengah jadi di working tree.

Protokol sebaiknya tetap singkat: cukup beberapa baris di berkas instruksi, bukan dokumen panjang tersendiri.

Skrip init: mempercepat awal sesi

Agar agen tidak perlu menyusun gambaran sendiri, sediakan satu skrip yang memeriksa lingkungan dan mencetak keadaan. Skrip harus idempoten — boleh dijalankan berkali-kali — dan diakhiri dengan pesan kesiapan yang jelas.

#!/usr/bin/env bash
set -euo pipefail

echo "== 1. Lingkungan =="
command -v uv >/dev/null || { echo "FAIL: uv belum terpasang"; exit 1; }
uv sync --frozen

echo "== 2. Repositori =="
if [ -n "$(git status --porcelain)" ]; then
  echo "WARN: working tree kotor"
else
  echo "OK: bersih"
fi
echo "HEAD: $(git log -1 --oneline)"

echo "== 3. Pemeriksaan =="
make check

echo "== 4. Keadaan =="
cat PROGRESS.md

echo "Siap bekerja"

Dengan protokol kedatangan, cukup satu baris: «jalankan scripts/init.sh». Di Claude Code, langkah ini bisa diotomatisasi dengan hook pada awal sesi (event SessionStart), tetapi tanpa hook pun agen akan menjalankan skrip mengikuti instruksi di berkas.

Apa yang disimpan di memori agen dan apa yang tidak

Kesalahan terbesar adalah mengubah memori menjadi tempat sampah. Setiap baris yang dibaca agen saat mulai memakan ruang konteks, dan hal yang tidak penting mengaburkan yang penting.

Pisahkan juga berdasarkan umur. Aturan proyek jarang berubah dan berlaku untuk semua tugas, jadi tempatnya di berkas instruksi utama. Keadaan berubah setiap sesi, jadi tempatnya di berkas kemajuan. Jika keduanya dicampur, berkas instruksi cepat membengkak dengan catatan usang.

Sesi pertama: inisialisasi sebagai fase tersendiri

Memori antar sesi tidak banyak membantu jika sesi pertama sudah kacau. Gambaran yang sering terjadi: Anda menulis di repositori kosong «tambahkan pencarian», lalu setengah jam kemudian ternyata framework tesnya salah konfigurasi dan format migrasinya keliru. Pencarian sudah ada, tetapi fondasinya rapuh.

Penyebabnya, implementasi dan inisialisasi mengoptimalkan hal yang berbeda: yang pertama mengejar jumlah fitur jadi di sesi ini, yang kedua mengejar kecepatan dan keandalan semua sesi berikutnya. Agen cenderung ke hasil yang terlihat, yaitu kode. Karena itu inisialisasi sebaiknya dipisah menjadi sesi tersendiri dengan kriteria selesai yang jelas dalam empat syarat.

• Bisa dijalankan: make setup dan make dev berfungsi dari clone yang bersih.
• Bisa diverifikasi: ada make test dan minimal satu tes nyata yang lolos.
• Kemajuan terlihat: berkas keadaan ada dan bisa dibaca.
• Pekerjaan bisa diambil alih: ada daftar tugas dengan kriteria penerimaan.

Jika Anda sering memulai proyek baru, buat template repositori: Makefile, framework tes, kerangka AGENTS.md, folder .agent/, scripts/init.sh, linter, dan CI. Dengan begitu inisialisasi hanya tinggal menangani kekhasan proyek tertentu.

Cara memeriksa bahwa memori berfungsi

Metrik paling jujur adalah waktu dari mulainya sesi baru sampai perubahan kode pertama yang bermakna. Tanpa artefak, biasanya lima belas sampai dua puluh menit untuk meraba-raba; dengan serah terima yang baik, dua sampai tiga menit. Ukur sekali sebelum dan sesudah, dan Anda akan tahu apakah disiplin ini sepadan.

Cara kedua adalah tes cold start. Buka sesi baru, tulis «lanjutkan», lalu ajukan lima pertanyaan: apa tujuan saat ini, dalam keadaan apa tesnya, keputusan apa yang sudah diambil untuk topik kunci dan mengapa, apa yang menjadi penghambat, dan apa langkah berikutnya. Jika agen menjawab kelimanya dari berkas, tanpa tebakan, memori sudah tersusun dengan benar. Setiap jawaban yang ragu menunjukkan kolom yang kurang di template.

Kesalahan umum

• Berkas kemajuan hanya terus bertambah. Setelah sebulan ada ratusan baris riwayat. Tulis ulang berkas sesuai keadaan sekarang; riwayat ada di git.
• Tidak ada baris «ditolak». Log keputusan tanpa varian yang ditolak tidak melindungi dari perdebatan yang berulang.
• Agen memperbarui keadaan «dengan perkiraan». Tulis bagaimana sesuatu diverifikasi: perintah dan hasilnya, bukan «semuanya berjalan».
• Serah terima dilakukan di ambang batas konteks. Mendekati batas jendela agen sudah terburu-buru; mulailah handoff lebih awal, sekitar 60%.
• Working tree kotor saat pergi. Perubahan setengah jadi yang belum di-commit membingungkan sesi berikutnya.

Ringkasnya

Memori agen AI antar sesi dibangun di atas berkas, bukan di atas model: PROGRESS.md menyimpan keadaan terkini, DECISIONS.md menyimpan alasan dan varian yang ditolak, commit git menjadi titik simpan dengan penjelasan maksud, dan protokol shift di AGENTS.md memastikan semuanya dibaca dan diperbarui. Skrip init memangkas awal sesi menjadi satu perintah, dan tes cold start menunjukkan apakah catatannya sudah cukup. Log kerja agen dan kontrak bootstrap dibahas dengan praktik nyata dalam kursus harness engineering.