Alat memori

Alat memori memungkinkan Claude menyimpan dan mengambil informasi di seluruh percakapan dalam sebuah direktori file memori. Claude dapat membuat, membaca, memperbarui, dan menghapus file yang tetap ada di antara sesi, sehingga membangun pengetahuan dari waktu ke waktu tanpa menyimpan semuanya di dalam "context window" (jendela konteks).

Memori mendukung pengambilan konteks secara "just-in-time" (tepat waktu). Alih-alih memuat semua informasi yang relevan di awal, agen mencatat apa yang dipelajarinya dalam file memori dan membacanya kembali sesuai kebutuhan. Ini menjaga konteks aktif tetap terfokus pada tugas saat ini, yang penting untuk sesi jangka panjang yang jika tidak demikian akan membebani jendela konteks. Lihat Effective context engineering untuk pola yang lebih luas.

Alat memori beroperasi di sisi klien: Claude meminta operasi file, dan aplikasi Anda yang mengeksekusinya. Anda mengontrol di mana dan bagaimana data disimpan melalui infrastruktur Anda sendiri.



Kasus penggunaan

• Mempertahankan konteks proyek di beberapa sesi agen
• Menerapkan pelajaran dari interaksi, keputusan, dan umpan balik sebelumnya ke tugas baru
• Membangun basis pengetahuan dari waktu ke waktu



Cara kerjanya

Ketika alat memori diaktifkan, Claude secara otomatis memeriksa direktori memorinya sebelum memulai tugas. Saat bekerja, Claude menyimpan apa yang dipelajarinya dalam file di bawah /memories dan membacanya kembali di percakapan selanjutnya untuk melanjutkan pekerjaan sebelumnya.

Karena alat memori bersifat sisi klien, Claude hanya meminta operasi memori. Aplikasi Anda mengeksekusi setiap permintaan terhadap penyimpanan yang Anda kontrol dan mengembalikan hasilnya dalam blok tool_result (lihat Menangani panggilan alat). Path /memories adalah prefiks yang dipetakan oleh handler Anda ke penyimpanan nyata, seperti direktori per pengguna atau key dalam database. Memori sepenuhnya berada di aplikasi Anda. Percakapan selanjutnya melanjutkan dari memori yang sama ketika mengirimkan entri tools yang sama dan handler Anda melayani penyimpanan yang sama. Untuk keamanan, batasi semua operasi memori ke direktori /memories (lihat Perlindungan path traversal).



Contoh: Cara kerja panggilan alat memori

Interaksi yang umum terlihat seperti ini:

1. Permintaan pengguna:

"Help me respond to this customer service ticket."

2. Claude memeriksa direktori memori:

"I'll help you respond to the customer service ticket. Let me check my memory for any previous context."

Claude memanggil alat memori:

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

3. Aplikasi Anda mengembalikan isi direktori:

{
  "type": "tool_result",
  "tool_use_id": "toolu_01C4D5E6F7G8H9I0J1K2L3M4",
  "content": "Here're the files and directories up to 2 levels deep in /memories, excluding hidden items and node_modules:\n4.0K\t/memories\n1.5K\t/memories/customer_service_guidelines.xml\n2.0K\t/memories/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 isi file:

{
  "type": "tool_result",
  "tool_use_id": "toolu_01D5E6F7G8H9I0J1K2L3M4N5",
  "content": "Here's the content of /memories/customer_service_guidelines.xml with line numbers:\n     1\t<guidelines>\n     2\t<addressing_customers>\n     3\t- Always address customers by their first name\n     4\t- Use empathetic language\n..."
}

6. Claude menggunakan memori untuk membantu:

"Based on your customer service guidelines, I can help you craft a response. Please share the ticket details..."

Alat memori tersedia di semua model Claude 4 dan yang lebih baru. Untuk daftar lengkap alat yang disediakan Anthropic, lihat Referensi alat.



Memulai

Alat memori tersedia secara umum di Messages API: tidak diperlukan header beta. Menggunakannya memerlukan dua langkah:

1. Tambahkan alat memori ke permintaan Anda. Entri tools {"type": "memory_20250818", "name": "memory"} adalah keseluruhan konfigurasi: name harus berupa memory, dan Anda tidak mendefinisikan skema input untuk alat yang disediakan Anthropic.
2. Implementasikan handler sisi klien untuk setiap perintah memori. Handler Anda harus menolak path di luar /memories, jadi baca Perlindungan path traversal sebelum Anda menulisnya.



Penggunaan dasar

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=2048,
    messages=[
        {
            "role": "user",
            "content": "Help me respond to this customer service ticket.",
        }
    ],
    tools=[{"type": "memory_20250818", "name": "memory"}],
)

print(message)



Mengimplementasikan handler memori

Balasan Claude terhadap permintaan seperti yang sebelumnya diakhiri dengan blok tool_use yang meminta operasi memori, seperti view /memories. Aplikasi Anda mengeksekusi operasi tersebut dan mengembalikan hasilnya dalam blok tool_result, lalu mengirim percakapan kembali agar Claude dapat melanjutkan: ini adalah loop penggunaan alat standar.

Empat SDK menyediakan helper alat memori yang menangani antarmuka alat dan loop tersebut. Buat subclass dari BetaAbstractMemoryTool (Python dan C#), gunakan betaMemoryTool (TypeScript), atau implementasikan BetaMemoryToolHandler (Java) untuk mendukung memori dengan penyimpanan Anda sendiri, seperti file di disk, database, penyimpanan cloud, atau file terenkripsi. Python dan TypeScript juga menyertakan implementasi filesystem lokal siap pakai, BetaLocalFilesystemMemoryTool. Antarmuka helper dan tool-runner berada di namespace beta masing-masing SDK meskipun alat memori itu sendiri sudah tersedia secara umum. SDK Go dan Ruby tidak memiliki helper memori, sehingga contoh-contoh tersebut menjalankan loop penggunaan alat sendiri, dan PHP membungkus closure handler Anda dalam BetaRunnableTool generiknya. Ketiganya menggunakan penyimpanan dalam memori yang Anda ganti dengan penyimpanan Anda sendiri.

import anthropic
from anthropic.tools import BetaLocalFilesystemMemoryTool

client = anthropic.Anthropic()
memory = BetaLocalFilesystemMemoryTool(base_path="./memory")

runner = client.beta.messages.tool_runner(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Remember that customer Acme Corp prefers email follow-ups.",
        }
    ],
    tools=[memory],
)

final_message = runner.until_done()
print(final_message.content)

Penyimpanan dalam memori pada contoh Go, PHP, dan Ruby membuat contoh-contoh tersebut mandiri: masing-masing melakukan dispatch berdasarkan field command dalam input blok tool_use dan mengembalikan string yang dijelaskan di bawah Perintah alat. Handler produksi juga memerlukan validasi path yang dilewati oleh penyimpanan demonstrasi ini. Untuk contoh lengkap dari SDK itu sendiri, lihat:

• Python: examples/memory/basic.py
• TypeScript: examples/tools-helpers-memory.ts
• C#: MemoryToolExample
• Java: BetaMemoryToolExample.java



Perintah alat

Implementasi sisi klien Anda harus menangani perintah-perintah berikut. Spesifikasi ini menjelaskan perilaku dan string pengembalian yang direkomendasikan: Claude membaca teks apa pun yang terdapat dalam hasil alat Anda, jadi Anda dapat mengembalikan string yang berbeda jika aplikasi Anda membutuhkannya.



view

Menampilkan isi direktori atau isi file dengan rentang baris opsional:

{
  "command": "view",
  "path": "/memories/notes.txt",
  "view_range": [1, 10]
}

view_range bersifat opsional dan berlaku untuk tampilan file teks: [start_line, end_line] mengembalikan baris-baris tersebut, dan [start_line, -1] mengembalikan semuanya dari start_line hingga akhir file.



Nilai pengembalian

Untuk direktori: Kembalikan daftar yang menampilkan file dan direktori beserta ukurannya:

Here're the files and directories up to 2 levels deep in {path}, excluding hidden items and node_modules:
{size}\t{path}
{size}\t{path}/{filename1}
{size}\t{path}/{filename2}

• Mencantumkan file hingga kedalaman 2 level
• Menampilkan ukuran yang mudah dibaca manusia (misalnya, 5.5K, 1.2M)
• Mengecualikan item tersembunyi (file yang dimulai dengan .) dan node_modules
• Menggunakan karakter tab antara ukuran dan path

view pertama terhadap /memories pada penyimpanan kosong bukanlah error. Alat memori filesystem lokal dari SDK (BetaLocalFilesystemMemoryTool) membuat root memori sebelum panggilan pertama Claude dan mengembalikan header daftar diikuti oleh satu baris ukuran-dan-path untuk direktori kosong itu sendiri.

Untuk file: Kembalikan isi file dengan header dan nomor baris:

Here's the content of {path} with line numbers:
{line_numbers}{tab}{content}

Format nomor baris:

• Lebar: 6 karakter, rata kanan dengan padding spasi
• Pemisah: Karakter tab antara nomor baris dan konten
• Pengindeksan: Dimulai dari 1 (baris pertama adalah baris 1)
• Batas baris: File dengan lebih dari 999.999 baris harus mengembalikan error: "File {path} exceeds maximum line limit of 999,999 lines."

Contoh output:

Here's the content of /memories/notes.txt with line numbers:
     1	Hello World
     2	This is line two
    10	Line ten
   100	Line one hundred

Deskripsi alat Claude juga menyatakan bahwa view menampilkan file gambar (.jpg, .jpeg, dan .png) dan memotong tampilan teks dari file yang lebih panjang dari 16.000 karakter. Antisipasi panggilan view pada path gambar dan tampilan berentang lanjutan untuk file panjang.



Penanganan error

• File atau direktori tidak ada: "The path {path} does not exist. Please provide a valid path."



create

Membuat file baru:

{
  "command": "create",
  "path": "/memories/notes.txt",
  "file_text": "Meeting notes:\n- Discussed project timeline\n- Next steps defined\n"
}



Nilai pengembalian

• Berhasil: "File created successfully at: {path}"



Penanganan error

• File sudah ada: "Error: File {path} already exists"

Deskripsi alat Claude menyatakan bahwa create "membuat atau menimpa" file, jadi antisipasi panggilan create pada path yang sudah ada. Mengembalikan error adalah perilaku referensi, dan menimpa sebagai gantinya adalah pilihan implementasi yang valid.



str_replace

Mengganti teks dalam file:

{
  "command": "str_replace",
  "path": "/memories/preferences.txt",
  "old_str": "Favorite color: blue",
  "new_str": "Favorite color: green"
}

new_str bersifat opsional untuk str_replace: ketika dihilangkan, old_str dihapus tanpa pengganti.



Nilai pengembalian

• Berhasil: "The memory file has been edited." diikuti oleh cuplikan file yang telah diedit dengan nomor baris



Penanganan error

• File tidak ada: "Error: The path {path} does not exist. Please provide a valid path."
• Teks tidak ditemukan: "No replacement was performed, old_str `\{old_str}` did not appear verbatim in {path}."
• Teks duplikat: Ketika old_str muncul beberapa kali, kembalikan: "No replacement was performed. Multiple occurrences of old_str `\{old_str}` in lines: {line_numbers}. Please ensure it is unique"



Penanganan direktori

Jika path adalah direktori, kembalikan error "file does not exist".



insert

Menyisipkan teks pada baris tertentu:

{
  "command": "insert",
  "path": "/memories/todo.txt",
  "insert_line": 2,
  "insert_text": "- Review memory tool documentation\n"
}

insert_text disisipkan setelah baris insert_line, dan 0 menyisipkan di awal file.



Nilai pengembalian

• Berhasil: "The file {path} has been edited."



Penanganan error

• File tidak ada: "Error: The path {path} does not exist"
• Nomor baris tidak valid: "Error: Invalid `insert_line` parameter: {insert_line}. It should be within the range of lines of the file: [0, {n_lines}]"



Penanganan direktori

Jika path adalah direktori, kembalikan error "file does not exist".



delete

Menghapus file atau direktori:

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



Nilai pengembalian

• Berhasil: "Successfully deleted {path}"



Penanganan error

• File atau direktori tidak ada: "Error: The path {path} does not exist"



Penanganan direktori

Menghapus direktori dan semua isinya secara rekursif. Deskripsi alat memberi tahu Claude bahwa ia tidak dapat menghapus direktori /memories itu sendiri, jadi tolak delete yang path-nya adalah root memori.



rename

Mengganti nama atau memindahkan file atau direktori:

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



Nilai pengembalian

• Berhasil: "Successfully renamed {old_path} to {new_path}"



Penanganan error

• Sumber tidak ada: "Error: The path {old_path} does not exist"
• Tujuan sudah ada: Kembalikan error (jangan menimpa): "Error: The destination {new_path} already exists"



Penanganan direktori

Mengganti nama direktori. Deskripsi alat memberi tahu Claude bahwa ia tidak dapat mengganti nama direktori /memories itu sendiri, jadi tolak rename yang old_path-nya adalah root memori.



Panduan prompting

Ketika alat memori ada dalam tools permintaan Anda, API secara otomatis menambahkan instruksi ini ke prompt sistem. Anda tidak perlu mengirimkannya sendiri:

IMPORTANT: ALWAYS VIEW YOUR MEMORY DIRECTORY BEFORE DOING ANYTHING ELSE.
MEMORY PROTOCOL:
1. Use the `view` command of your `memory` tool to check for earlier progress.
2. ... (work on the task) ...
   - As you make progress, record status / progress / thoughts etc in your memory.
ASSUME INTERRUPTION: Your context window might be reset at any moment, so you risk losing any progress that is not recorded in your memory directory.

Deskripsi alat Claude sudah memberitahunya untuk menjaga direktori memori tetap terorganisir, jadi Anda tidak perlu mengulangi instruksi tersebut. Jika Claude masih membuat file memori yang berantakan, Anda dapat memperkuatnya dalam prompt Anda:

Note: when editing your memory folder, always try to keep its content up-to-date, coherent and organized. You can rename or delete files that are no longer relevant. Do not create new files unless necessary.

Anda juga dapat memandu apa yang Claude tulis ke memori. Misalnya: "Only write down information relevant to <topic> in your memory system."



Pertimbangan keamanan

Aplikasi Anda mengeksekusi setiap operasi file yang diminta Claude, jadi pengamanan berikut adalah tanggung jawab Anda:



Informasi sensitif

Claude biasanya menolak untuk menulis informasi sensitif ke file memori. Untuk jaminan yang lebih kuat, tambahkan validasi yang menghapus data sensitif sebelum handler Anda menulis file.



Ukuran penyimpanan file

Lacak ukuran file memori dan batasi seberapa besar file dapat bertambah. Pertimbangkan untuk membatasi berapa banyak karakter yang dikembalikan perintah view, dan biarkan Claude menelusuri sisanya dengan view_range.



Kedaluwarsa memori

Hapus secara berkala file memori yang sudah lama tidak diakses.



Perlindungan path traversal

Pertimbangkan pengamanan berikut:

• Validasi bahwa semua path dimulai dengan /memories
• Resolusikan path ke bentuk kanonisnya dan verifikasi bahwa path tetap berada di dalam direktori memori
• Tolak path yang berisi urutan seperti ../, ..\\, atau pola traversal lainnya
• Waspadai urutan traversal yang di-encode URL (%2e%2e%2f)
• Gunakan utilitas keamanan path bawaan bahasa Anda (misalnya, pathlib.Path.resolve() dan relative_to() di Python)



Penanganan error

Alat memori menggunakan pola penanganan error yang serupa dengan alat text editor. Pesan error setiap perintah tercantum di bawah Perintah alat. Untuk mengembalikan error ke Claude, atur is_error ke true pada hasil alat dan letakkan pesan di content:

{
  "type": "tool_result",
  "tool_use_id": "toolu_01C4D5E6F7G8H9I0J1K2L3M4",
  "content": "Error: The path /memories/notes.txt does not exist",
  "is_error": true
}



Integrasi context editing

Alat memori berpasangan dengan "context editing" (pengeditan konteks) untuk mengelola percakapan jangka panjang. Untuk detailnya, lihat Context editing.



Menggunakan dengan compaction

Alat memori juga dapat dipasangkan dengan compaction, yang meringkas konteks percakapan lama di sisi server. Context editing menghapus hasil alat tertentu di klien. Compaction secara otomatis meringkas seluruh percakapan di server ketika percakapan mendekati batas jendela konteks.

Untuk agen jangka panjang, pertimbangkan untuk menggunakan keduanya: compaction menjaga konteks aktif tetap kecil tanpa pembukuan sisi klien, dan memori mempertahankan informasi yang harus bertahan dari peringkasan.



Pola pengembangan perangkat lunak multi-sesi

Untuk proyek perangkat lunak yang mencakup beberapa sesi agen, siapkan file memori secara sengaja alih-alih menulisnya secara ad hoc seiring berjalannya pekerjaan. Pola berikut mengubah memori menjadi mekanisme pemulihan: setiap sesi baru melanjutkan dari keadaan yang dicatat oleh sesi terakhir.



Cara kerja pola ini

1. Sesi inisialisasi: Sesi pertama menyiapkan file memori sebelum pekerjaan substantif dimulai. Ini mencakup log kemajuan (melacak apa yang telah dilakukan dan apa yang berikutnya), daftar periksa fitur (mendefinisikan cakupan pekerjaan), dan referensi ke skrip startup atau inisialisasi apa pun yang dibutuhkan proyek.

2. Sesi berikutnya: Setiap sesi baru dibuka dengan membaca file memori tersebut. Ini memulihkan keadaan proyek tanpa menjelajahi ulang basis kode atau menelusuri kembali keputusan sebelumnya.

3. Pembaruan akhir sesi: Sebelum sesi berakhir, sesi memperbarui log kemajuan dengan apa yang telah diselesaikan dan apa yang tersisa. Ini memastikan sesi berikutnya memiliki titik awal yang akurat.



Prinsip utama

Kerjakan satu fitur pada satu waktu. Tandai fitur sebagai selesai hanya setelah verifikasi end-to-end mengonfirmasi bahwa fitur tersebut berfungsi, bukan ketika kodenya selesai ditulis. Ini menjaga log kemajuan tetap akurat dari sesi ke sesi.



Langkah selanjutnya