Alat memori

Alat memori memungkinkan Claude untuk menyimpan dan mengambil informasi lintas percakapan melalui direktori file memori. Claude dapat membuat, membaca, memperbarui, dan menghapus file yang bertahan antar sesi, memungkinkannya membangun pengetahuan dari waktu ke waktu tanpa menyimpan semuanya dalam jendela konteks.

Alat memori beroperasi di sisi klien—Anda mengontrol di mana dan bagaimana data disimpan melalui infrastruktur Anda sendiri.

Kasus penggunaan

• Mempertahankan konteks proyek lintas beberapa eksekusi agen
• Belajar dari interaksi, keputusan, dan umpan balik masa lalu
• Membangun basis pengetahuan dari waktu ke waktu
• Memungkinkan pembelajaran lintas percakapan di mana Claude meningkat pada alur kerja berulang

Cara kerjanya

Ketika diaktifkan, Claude secara otomatis memeriksa direktori memorinya sebelum memulai tugas. Claude dapat membuat, membaca, memperbarui, dan menghapus file dalam direktori /memories untuk menyimpan apa yang dipelajarinya saat bekerja, kemudian mereferensikan memori tersebut dalam percakapan masa depan untuk menangani tugas serupa dengan lebih efektif atau melanjutkan dari tempat terakhir berhenti.

Karena ini adalah alat sisi klien, Claude melakukan panggilan alat untuk melakukan operasi memori, dan aplikasi Anda mengeksekusi operasi tersebut secara lokal. Ini memberi Anda kontrol penuh atas di mana dan bagaimana memori disimpan. Untuk keamanan, Anda harus membatasi semua operasi memori ke direktori /memories.

Contoh: Bagaimana panggilan alat memori bekerja

Ketika Anda meminta Claude untuk membantu dengan tugas, Claude secara otomatis memeriksa direktori memorinya terlebih dahulu. Berikut adalah tampilan interaksi tipikal:

1. Permintaan pengguna:

"Bantu saya merespons tiket layanan pelanggan ini."

2. Claude memeriksa direktori memori:

"Saya akan membantu Anda merespons tiket layanan pelanggan. Biarkan saya memeriksa memori saya untuk konteks sebelumnya."

Claude memanggil alat memori:

{
  "type": "tool_use",
  "id": "toolu_01C4D5E6F7G8H9I0J1K2L3M4",
  "name": "memory",
  "input": {
    "command": "view",
    "path": "/memories"
  }
}

3. Aplikasi Anda mengembalikan konten direktori:

{
  "type": "tool_result",
  "tool_use_id": "toolu_01C4D5E6F7G8H9I0J1K2L3M4",
  "content": "Directory: /memories\n- customer_service_guidelines.xml\n- refund_policies.xml"
}

4. Claude membaca file yang relevan:

{
  "type": "tool_use",
  "id": "toolu_01D5E6F7G8H9I0J1K2L3M4N5",
  "name": "memory",
  "input": {
    "command": "view",
    "path": "/memories/customer_service_guidelines.xml"
  }
}

5. Aplikasi Anda mengembalikan konten file:

{
  "type": "tool_result",
  "tool_use_id": "toolu_01D5E6F7G8H9I0J1K2L3M4N5",
  "content": "<guidelines>\n<addressing_customers>\n- Always address customers by their first name\n- Use empathetic language\n..."
}

6. Claude menggunakan memori untuk membantu:

"Berdasarkan pedoman layanan pelanggan Anda, saya dapat membantu Anda menyusun respons. Silakan bagikan detail tiket..."

Model yang didukung

Alat memori tersedia pada:

• Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
• Claude Sonnet 4 (claude-sonnet-4-20250514)
• Claude Haiku 4.5 (claude-haiku-4-5-20251001)
• Claude Opus 4.1 (claude-opus-4-1-20250805)
• Claude Opus 4 (claude-opus-4-20250514)

Memulai

Untuk menggunakan alat memori:

1. Sertakan header beta context-management-2025-06-27 dalam permintaan API Anda
2. Tambahkan alat memori ke permintaan Anda
3. Implementasikan handler sisi klien untuk operasi memori

Penggunaan dasar

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --header "anthropic-beta: context-management-2025-06-27" \
    --data '{
        "model": "claude-sonnet-4-5",
        "max_tokens": 2048,
        "messages": [
            {
                "role": "user",
                "content": "Saya sedang mengerjakan web scraper Python yang terus crash dengan error timeout. Berikut adalah fungsi yang bermasalah:\n\n```python\ndef fetch_page(url, retries=3):\n    for i in range(retries):\n        try:\n            response = requests.get(url, timeout=5)\n            return response.text\n        except requests.exceptions.Timeout:\n            if i == retries - 1:\n                raise\n            time.sleep(1)\n```\n\nTolong bantu saya debug ini."
            }
        ],
        "tools": [{
            "type": "memory_20250818",
            "name": "memory"
        }]
    }'

Perintah alat

Implementasi sisi klien Anda perlu menangani perintah alat memori ini:

view

Menampilkan konten direktori atau konten file dengan rentang baris opsional:

{
  "command": "view",
  "path": "/memories",
  "view_range": [1, 10]  // Opsional: lihat baris tertentu
}

create

Membuat atau menimpa file:

{
  "command": "create",
  "path": "/memories/notes.txt",
  "file_text": "Catatan rapat:\n- Membahas timeline proyek\n- Langkah selanjutnya didefinisikan\n"
}

str_replace

Mengganti teks dalam file:

{
  "command": "str_replace",
  "path": "/memories/preferences.txt",
  "old_str": "Warna favorit: biru",
  "new_str": "Warna favorit: hijau"
}

insert

Menyisipkan teks pada baris tertentu:

{
  "command": "insert",
  "path": "/memories/todo.txt",
  "insert_line": 2,
  "insert_text": "- Tinjau dokumentasi alat memori\n"
}

delete

Menghapus file atau direktori:

{
  "command": "delete",
  "path": "/memories/old_file.txt"
}

rename

Mengganti nama atau memindahkan file/direktori:

{
  "command": "rename",
  "old_path": "/memories/draft.txt",
  "new_path": "/memories/final.txt"
}

Panduan prompting

Kami secara otomatis menyertakan instruksi ini ke prompt sistem ketika alat memori disertakan:

PENTING: SELALU LIHAT DIREKTORI MEMORI ANDA SEBELUM MELAKUKAN HAL LAIN.
PROTOKOL MEMORI:
1. Gunakan perintah `view` dari alat `memory` Anda untuk memeriksa kemajuan sebelumnya.
2. ... (kerjakan tugas) ...
     - Saat Anda membuat kemajuan, catat status / kemajuan / pemikiran dll dalam memori Anda.
ASUMSIKAN INTERUPSI: Jendela konteks Anda mungkin direset kapan saja, jadi Anda berisiko kehilangan kemajuan yang tidak dicatat dalam direktori memori Anda.

Jika Anda mengamati Claude membuat file memori yang berantakan, Anda dapat menyertakan instruksi ini:

Catatan: saat mengedit folder memori Anda, selalu usahakan untuk menjaga kontennya tetap terkini, koheren dan terorganisir. Anda dapat mengganti nama atau menghapus file yang tidak lagi relevan. Jangan buat file baru kecuali diperlukan.

Anda juga dapat memandu apa yang Claude tulis ke memori, misalnya, "Hanya tulis informasi yang relevan dengan <topik> dalam sistem memori Anda."

Pertimbangan keamanan

Berikut adalah masalah keamanan penting saat mengimplementasikan penyimpanan memori Anda:

Informasi sensitif

Claude biasanya akan menolak untuk menuliskan informasi sensitif dalam file memori. Namun, Anda mungkin ingin mengimplementasikan validasi yang lebih ketat yang menghilangkan informasi yang berpotensi sensitif.

Ukuran penyimpanan file

Pertimbangkan untuk melacak ukuran file memori dan mencegah file tumbuh terlalu besar. Pertimbangkan untuk menambahkan jumlah maksimum karakter yang dapat dikembalikan perintah baca memori, dan biarkan Claude melakukan paginasi melalui konten.

Kedaluwarsa memori

Pertimbangkan untuk membersihkan file memori secara berkala yang tidak diakses dalam waktu yang lama.

Perlindungan path traversal

Pertimbangkan perlindungan ini:

• Validasi bahwa semua path dimulai dengan /memories
• Resolve path ke bentuk kanoniknya dan verifikasi mereka tetap dalam direktori memori
• Tolak path yang mengandung urutan seperti ../, ..\\, atau pola traversal lainnya
• Perhatikan urutan traversal yang dikodekan URL (%2e%2e%2f)
• Gunakan utilitas keamanan path bawaan bahasa Anda (misalnya, pathlib.Path.resolve() dan relative_to() Python)

Penanganan error

Alat memori menggunakan pola penanganan error yang sama dengan alat editor teks. Error umum termasuk file tidak ditemukan, error izin, dan path tidak valid.

Menggunakan dengan Context Editing

Alat memori dapat dikombinasikan dengan context editing, yang secara otomatis membersihkan hasil alat lama ketika konteks percakapan tumbuh melampaui ambang batas yang dikonfigurasi. Kombinasi ini memungkinkan alur kerja agentik jangka panjang yang sebaliknya akan melebihi batas konteks.

Bagaimana mereka bekerja bersama

Ketika context editing diaktifkan dan percakapan Anda mendekati ambang batas pembersihan, Claude secara otomatis menerima notifikasi peringatan. Ini mendorong Claude untuk menyimpan informasi penting dari hasil alat ke dalam file memori sebelum hasil tersebut dibersihkan dari jendela konteks.

Setelah hasil alat dibersihkan, Claude dapat mengambil informasi yang disimpan dari file memori kapan pun diperlukan, secara efektif memperlakukan memori sebagai perpanjangan dari konteks kerjanya. Ini memungkinkan Claude untuk:

• Melanjutkan alur kerja kompleks multi-langkah tanpa kehilangan informasi penting
• Mereferensikan pekerjaan dan keputusan masa lalu bahkan setelah hasil alat dihapus
• Mempertahankan konteks yang koheren lintas percakapan yang akan melebihi batas jendela konteks tipikal
• Membangun basis pengetahuan dari waktu ke waktu sambil menjaga jendela konteks aktif tetap dapat dikelola

Contoh alur kerja

Pertimbangkan proyek refactoring kode dengan banyak operasi file:

1. Claude melakukan banyak edit pada file, menghasilkan banyak hasil alat
2. Saat konteks tumbuh dan mendekati ambang batas Anda, Claude menerima peringatan
3. Claude merangkum perubahan yang dibuat sejauh ini ke file memori (misalnya, /memories/refactoring_progress.xml)
4. Context editing membersihkan hasil alat yang lebih lama secara otomatis
5. Claude melanjutkan bekerja, mereferensikan file memori ketika perlu mengingat perubahan apa yang sudah diselesaikan
6. Alur kerja dapat berlanjut tanpa batas, dengan Claude mengelola konteks aktif dan memori persisten

Konfigurasi

Untuk menggunakan kedua fitur bersama:

response = client.beta.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=4096,
    messages=[...],
    tools=[
        {
            "type": "memory_20250818",
            "name": "memory"
        },
        # Alat lain Anda
    ],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_tool_uses_20250919",
                "trigger": {
                    "type": "input_tokens",
                    "value": 100000
                },
                "keep": {
                    "type": "tool_uses",
                    "value": 3
                }
            }
        ]
    }
)

Anda juga dapat mengecualikan panggilan alat memori dari dibersihkan untuk memastikan Claude selalu memiliki akses ke operasi memori terbaru:

context_management={
    "edits": [
        {
            "type": "clear_tool_uses_20250919",
            "exclude_tools": ["memory"]
        }
    ]
}