Pengeditan konteks

Ikhtisar

"Context editing" (pengeditan konteks) memungkinkan Anda membersihkan konten tertentu secara selektif dari riwayat percakapan seiring pertumbuhannya. Selain mengoptimalkan biaya dan tetap berada dalam batas, ini adalah tentang mengkurasi secara aktif apa yang dilihat Claude: konteks adalah sumber daya terbatas dengan hasil yang semakin berkurang, dan konten yang tidak relevan menurunkan fokus model. Pengeditan konteks memberi Anda kontrol runtime yang terperinci atas kurasi tersebut. Untuk prinsip yang lebih luas di balik manajemen konteks, lihat Rekayasa konteks yang efektif. Halaman ini mencakup:

• Pembersihan hasil alat - Paling cocok untuk alur kerja agentik dengan penggunaan alat yang intensif di mana hasil alat lama tidak lagi diperlukan
• Pembersihan blok thinking - Untuk mengelola blok thinking saat menggunakan "extended thinking" (pemikiran diperpanjang), dengan opsi untuk mempertahankan thinking terbaru demi kesinambungan konteks
• Kompaksi SDK sisi klien - Alternatif berbasis SDK untuk manajemen konteks berbasis ringkasan (kompaksi sisi server umumnya lebih disarankan)

Strategi sisi server

Pembersihan hasil alat

Strategi clear_tool_uses_20250919 membersihkan hasil alat ketika konteks percakapan tumbuh melampaui ambang batas yang Anda konfigurasi. Ini sangat berguna untuk alur kerja agentik dengan "tool use" (penggunaan alat) yang intensif. Hasil alat yang lebih lama (seperti isi file atau hasil pencarian) tidak lagi diperlukan setelah Claude memprosesnya.

Saat diaktifkan, API secara otomatis membersihkan hasil alat terlama dalam urutan kronologis. API mengganti setiap hasil yang dibersihkan dengan teks placeholder yang menunjukkan kepada Claude bahwa hasil tersebut telah dihapus. Secara default, hanya hasil alat yang dibersihkan. Anda dapat secara opsional membersihkan hasil alat dan panggilan alat (parameter penggunaan alat) dengan mengatur clear_tool_inputs ke true.

Pembersihan blok thinking

Strategi clear_thinking_20251015 mengelola blok thinking dalam percakapan ketika pemikiran diperpanjang diaktifkan. Strategi ini memberi Anda kontrol atas pelestarian thinking: Anda dapat memilih untuk menyimpan lebih banyak blok thinking guna mempertahankan kesinambungan penalaran, atau membersihkannya secara lebih agresif untuk menghemat ruang konteks.

Satu giliran percakapan asisten dapat mencakup beberapa blok konten (misalnya, saat menggunakan alat) dan beberapa blok thinking (misalnya, dengan interleaved thinking).

Pengeditan konteks terjadi di sisi server

Pengeditan konteks diterapkan di sisi server sebelum prompt mencapai Claude. Aplikasi klien Anda mempertahankan riwayat percakapan lengkap yang tidak dimodifikasi. Anda tidak perlu menyinkronkan status klien Anda dengan versi yang telah diedit. Lanjutkan mengelola riwayat percakapan lengkap Anda secara lokal seperti biasa.

Pada Claude Fable 5.1, manajemen konteks sisi server tidak pernah membatalkan validitas blok thinking. Pengeditan sisi klien pada giliran sebelumnya dapat membatalkan validitas blok thinking di setiap giliran asisten berikutnya. Untuk akun baru yang dibuat pada atau setelah 31 Agustus 2026, permintaan yang memutar ulang blok yang tidak valid akan ditolak kecuali Anda memilih untuk membuangnya. Lihat Thinking yang dipertahankan.

Pengeditan konteks dan caching prompt

Interaksi pengeditan konteks dengan "prompt caching" (caching prompt) bervariasi menurut strategi:

• Pembersihan hasil alat: Membatalkan validitas prefiks prompt yang di-cache ketika konten dibersihkan. Untuk mengantisipasi hal ini, bersihkan token yang cukup agar pembatalan cache sepadan. Gunakan parameter clear_at_least untuk memastikan jumlah minimum token dibersihkan setiap kali. Anda akan dikenai biaya penulisan cache setiap kali konten dibersihkan, tetapi permintaan berikutnya dapat menggunakan kembali prefiks yang baru di-cache.

• Pembersihan blok thinking: Ketika blok thinking disimpan dalam konteks (tidak dibersihkan), cache prompt dipertahankan, memungkinkan cache hit dan mengurangi biaya token input. Ketika blok thinking dibersihkan, cache dibatalkan validitasnya pada titik di mana pembersihan terjadi. Konfigurasikan parameter keep berdasarkan apakah Anda ingin memprioritaskan kinerja cache atau ketersediaan "context window" (jendela konteks).

Model yang didukung

Pengeditan konteks tersedia di semua model Claude yang didukung.

Penggunaan pembersihan hasil alat

Cara paling sederhana untuk mengaktifkan pembersihan hasil alat adalah dengan hanya menentukan tipe strategi. Semua opsi konfigurasi lainnya menggunakan nilai defaultnya:

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[{"role": "user", "content": "Search for recent developments in AI"}],
    tools=[{"type": "web_search_20250305", "name": "web_search"}],
    betas=["context-management-2025-06-27"],
    context_management={"edits": [{"type": "clear_tool_uses_20250919"}]},
)

Konfigurasi lanjutan

Anda dapat menyesuaikan perilaku pembersihan hasil alat dengan parameter tambahan:

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Create a simple command line calculator app using Python",
        }
    ],
    tools=[
        {
            "type": "text_editor_20250728",
            "name": "str_replace_based_edit_tool",
            "max_characters": 10000,
        },
        {"type": "web_search_20250305", "name": "web_search", "max_uses": 3},
    ],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_tool_uses_20250919",
                # Picu pembersihan saat ambang batas terlampaui
                "trigger": {"type": "input_tokens", "value": 30000},
                # Jumlah penggunaan alat yang dipertahankan setelah pembersihan
                "keep": {"type": "tool_uses", "value": 3},
                # Opsional: Bersihkan setidaknya sejumlah token ini
                "clear_at_least": {"type": "input_tokens", "value": 5000},
                # Kecualikan alat-alat ini dari pembersihan
                "exclude_tools": ["web_search"],
            }
        ]
    },
)

Penggunaan pembersihan blok thinking

Aktifkan pembersihan blok thinking untuk mengelola konteks dan caching prompt secara efektif ketika pemikiran diperpanjang diaktifkan:

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": {"type": "thinking_turns", "value": 2},
            }
        ]
    },
)

Opsi konfigurasi untuk pembersihan blok thinking

Strategi clear_thinking_20251015 mendukung konfigurasi berikut:

Contoh konfigurasi:

Simpan blok thinking dari 3 giliran asisten terakhir:

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": {"type": "thinking_turns", "value": 3},
            }
        ]
    },
)

Simpan semua blok thinking (memaksimalkan cache hit):

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": "all",
            }
        ]
    },
)

Menggabungkan strategi

Anda dapat menggunakan pembersihan blok thinking dan pembersihan hasil alat secara bersamaan:

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    messages=[
        {
            "role": "user",
            "content": "Search for the latest developments in quantum error correction and summarize the key breakthroughs.",
        }
    ],
    tools=[
        {
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 5,
        }
    ],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": {"type": "thinking_turns", "value": 2},
            },
            {
                "type": "clear_tool_uses_20250919",
                "trigger": {"type": "input_tokens", "value": 50000},
                "keep": {"type": "tool_uses", "value": 5},
            },
        ]
    },
)

print(response)

Opsi konfigurasi untuk pembersihan hasil alat

Respons pengeditan konteks

Anda dapat melihat pengeditan konteks mana yang diterapkan pada permintaan Anda menggunakan field respons context_management, beserta statistik yang berguna tentang konten dan token input yang dibersihkan.

{
  "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message",
  "role": "assistant",
  "content": [
    // ...
  ],
  "usage": {
    // ...
  },
  "context_management": {
    "applied_edits": [
      // When using `clear_thinking_20251015`
      {
        "type": "clear_thinking_20251015",
        "cleared_thinking_turns": 3,
        "cleared_input_tokens": 15000
      },
      // When using `clear_tool_uses_20250919`
      {
        "type": "clear_tool_uses_20250919",
        "cleared_tool_uses": 8,
        "cleared_input_tokens": 50000
      }
    ]
  }
}

Untuk respons streaming, pengeditan konteks disertakan dalam event message_delta terakhir:

{
  "type": "message_delta",
  "delta": {
    "stop_reason": "end_turn",
    "stop_sequence": null
  },
  "usage": {
    "output_tokens": 1024
  },
  "context_management": {
    "applied_edits": [
      // ...
    ]
  }
}

Penghitungan token

Endpoint penghitungan token mendukung manajemen konteks, memungkinkan Anda melihat pratinjau berapa banyak token yang akan digunakan prompt Anda setelah pengeditan konteks diterapkan.

response = client.beta.messages.count_tokens(
    model="claude-opus-5",
    messages=[{"role": "user", "content": "Continue our conversation..."}],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_tool_uses_20250919",
                "trigger": {"type": "input_tokens", "value": 30000},
                "keep": {"type": "tool_uses", "value": 5},
            }
        ]
    },
)

print(f"Original tokens: {response.context_management.original_input_tokens}")
print(f"After clearing: {response.input_tokens}")
print(
    f"Savings: {response.context_management.original_input_tokens - response.input_tokens} tokens"
)

{
  "input_tokens": 25000,
  "context_management": {
    "original_input_tokens": 70000
  }
}

Respons menunjukkan jumlah token akhir setelah manajemen konteks diterapkan (input_tokens) dan jumlah token asli sebelum pembersihan apa pun terjadi (original_input_tokens).

Penggunaan dengan alat memori

Pengeditan konteks dapat digabungkan dengan alat memori. Ketika konteks percakapan Anda mendekati ambang batas pembersihan yang dikonfigurasi, Claude menerima peringatan otomatis untuk mempertahankan informasi penting. Ini memungkinkan Claude menyimpan hasil alat atau konteks ke file memorinya sebelum dibersihkan dari riwayat percakapan.

Kombinasi ini memungkinkan Anda untuk:

• Mempertahankan konteks penting: Claude dapat menulis informasi penting dari hasil alat ke file memori sebelum hasil tersebut dibersihkan
• Mempertahankan alur kerja yang berjalan lama: Memungkinkan alur kerja agentik yang seharusnya melampaui batas konteks dengan memindahkan informasi ke penyimpanan persisten
• Mengakses informasi sesuai kebutuhan: Claude dapat mencari informasi yang sebelumnya dibersihkan dari file memori saat diperlukan, daripada menyimpan semuanya di jendela konteks aktif

Misalnya, dalam alur kerja pengeditan file di mana Claude melakukan banyak operasi, Claude dapat merangkum perubahan yang telah selesai ke file memori seiring pertumbuhan konteks. Ketika hasil alat dibersihkan, Claude tetap memiliki akses ke informasi tersebut melalui sistem memorinya dan dapat terus bekerja secara efektif.

Untuk menggunakan kedua fitur secara bersamaan, aktifkan keduanya dalam permintaan API Anda:

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[{"role": "user", "content": "Hello"}],
    tools=[{"type": "memory_20250818", "name": "memory"}],
    betas=["context-management-2025-06-27"],
    context_management={"edits": [{"type": "clear_tool_uses_20250919"}]},
)

Untuk referensi lengkap alat memori termasuk perintah dan contoh, lihat Alat memori.

Kompaksi sisi klien (SDK)

"Compaction" (kompaksi) adalah fitur SDK yang secara otomatis mengelola konteks percakapan dengan menghasilkan ringkasan ketika penggunaan token tumbuh terlalu besar. Berbeda dengan strategi pengeditan konteks sisi server yang membersihkan konten, kompaksi menginstruksikan Claude untuk merangkum riwayat percakapan, lalu mengganti seluruh riwayat dengan ringkasan tersebut. Ini memungkinkan Claude untuk terus mengerjakan tugas yang berjalan lama yang seharusnya melampaui jendela konteks.

Cara kerja kompaksi

Ketika kompaksi diaktifkan, SDK memantau penggunaan token setelah setiap respons model:

1. Pemeriksaan ambang batas: SDK menghitung total token sebagai input_tokens + cache_creation_input_tokens + cache_read_input_tokens + output_tokens (lihat Caching prompt untuk field token cache).
2. Pembuatan ringkasan: Ketika ambang batas terlampaui, prompt ringkasan disisipkan sebagai giliran pengguna, dan Claude menghasilkan ringkasan terstruktur yang dibungkus dalam tag <summary></summary>.
3. Penggantian konteks: SDK mengekstrak ringkasan dan mengganti seluruh riwayat pesan dengannya.
4. Kelanjutan: Percakapan dilanjutkan dari ringkasan, dengan Claude melanjutkan dari titik terakhir.

Menggunakan kompaksi

Tambahkan compaction_control ke panggilan tool_runner Anda untuk mengaktifkan peringkasan otomatis ketika penggunaan token melampaui ambang batas.

Apa yang terjadi selama kompaksi

Seiring pertumbuhan percakapan, riwayat pesan terakumulasi:

Sebelum kompaksi (mendekati 100k token):

[
  { "role": "user", "content": "Analyze all files and write a report..." },
  { "role": "assistant", "content": "I'll help. Let me start by reading..." },
  {
    "role": "user",
    "content": [{ "type": "tool_result", "tool_use_id": "...", "content": "..." }]
  },
  { "role": "assistant", "content": "Based on file1.txt, I see..." },
  {
    "role": "user",
    "content": [{ "type": "tool_result", "tool_use_id": "...", "content": "..." }]
  },
  { "role": "assistant", "content": "After analyzing file2.txt..." }
  // ... 50 more exchanges like this ...
]

Ketika token melampaui ambang batas, SDK menyisipkan permintaan ringkasan dan Claude menghasilkan ringkasan. Seluruh riwayat kemudian diganti:

Setelah kompaksi (kembali ke ~2–3k token):

[
  {
    "role": "assistant",
    "content": "# Task Overview\nThe user requested analysis of directory files to produce a summary report...\n\n# Current State\nAnalyzed 52 files across 3 subdirectories. Key findings documented in report.md...\n\n# Important Discoveries\n- Configuration files use YAML format\n- Found 3 deprecated dependencies\n- Test coverage at 67%\n\n# Next Steps\n1. Analyze remaining files in /src/legacy\n2. Complete final report sections...\n\n# Context to Preserve\nUser prefers markdown format with executive summary first..."
  }
]

Claude melanjutkan pekerjaan dari ringkasan ini seolah-olah itu adalah riwayat percakapan asli.

Opsi konfigurasi

Memilih ambang batas token

Ambang batas menentukan kapan kompaksi terjadi. Ambang batas yang lebih rendah berarti kompaksi lebih sering dengan jendela konteks yang lebih kecil. Ambang batas yang lebih tinggi memungkinkan lebih banyak konteks tetapi berisiko mencapai batas.

Menggunakan model yang berbeda untuk ringkasan

Anda dapat menggunakan model yang lebih cepat atau lebih murah untuk menghasilkan ringkasan:

Prompt ringkasan kustom

Anda dapat menyediakan prompt kustom untuk kebutuhan spesifik domain. Prompt Anda harus menginstruksikan Claude untuk membungkus ringkasannya dalam tag <summary></summary>.

Prompt ringkasan default

Prompt ringkasan bawaan menginstruksikan Claude untuk membuat ringkasan kelanjutan terstruktur yang mencakup:

1. Ikhtisar Tugas: Permintaan inti pengguna, kriteria keberhasilan, dan batasan.
2. Status Saat Ini: Apa yang telah diselesaikan, file yang dimodifikasi, dan artefak yang dihasilkan.
3. Temuan Penting: Batasan teknis, keputusan yang dibuat, kesalahan yang diselesaikan, dan pendekatan yang gagal.
4. Langkah Selanjutnya: Tindakan spesifik yang diperlukan, penghambat, dan urutan prioritas.
5. Konteks yang Perlu Dipertahankan: Preferensi pengguna, detail spesifik domain, dan komitmen yang dibuat.

Struktur ini memungkinkan Claude melanjutkan pekerjaan secara efisien tanpa kehilangan konteks penting atau mengulangi kesalahan.

You have been working on the task described above but have not yet completed it. Write a continuation summary that will allow you (or another instance of yourself) to resume work efficiently in a future context window where the conversation history will be replaced with this summary. Your summary should be structured, concise, and actionable. Include:

1. Task Overview
The user's core request and success criteria
Any clarifications or constraints they specified

2. Current State
What has been completed so far
Files created, modified, or analyzed (with paths if relevant)
Key outputs or artifacts produced

3. Important Discoveries
Technical constraints or requirements uncovered
Decisions made and their rationale
Errors encountered and how they were resolved
What approaches were tried that didn't work (and why)

4. Next Steps
Specific actions needed to complete the task
Any blockers or open questions to resolve
Priority order if multiple steps remain

5. Context to Preserve
User preferences or style requirements
Domain-specific details that aren't obvious
Any promises made to the user

Be concise but complete—err on the side of including information that would prevent duplicate work or repeated mistakes. Write in a way that enables immediate resumption of the task.

Wrap your summary in <summary></summary> tags.

Keterbatasan

Alat sisi server

Saat menggunakan alat sisi server, SDK mungkin salah menghitung penggunaan token, menyebabkan kompaksi dipicu pada waktu yang salah.

Misalnya, setelah operasi pencarian web, respons API mungkin menunjukkan:

{
  "usage": {
    "input_tokens": 63000,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 270000,
    "output_tokens": 1400
  }
}

SDK menghitung total penggunaan sebagai 63.000 + 0 + 270.000 + 1.400 = 334.400 token. Namun, nilai cache_read_input_tokens mencakup akumulasi pembacaan dari beberapa panggilan API internal yang dilakukan oleh alat sisi server, bukan konteks percakapan Anda yang sebenarnya. Panjang konteks Anda yang sebenarnya mungkin hanya 63.000 input_tokens, tetapi SDK melihat 334k dan memicu kompaksi terlalu dini.

Solusi sementara:

• Gunakan endpoint penghitungan token untuk mendapatkan panjang konteks yang akurat
• Hindari kompaksi saat menggunakan alat sisi server secara ekstensif

Kasus tepi penggunaan alat

Ketika SDK memicu kompaksi saat respons penggunaan alat masih tertunda, SDK menghapus blok penggunaan alat dari riwayat pesan sebelum menghasilkan ringkasan. Claude akan mengeluarkan kembali panggilan alat setelah melanjutkan dari ringkasan jika masih diperlukan.

Memantau kompaksi

Memahami kapan kompaksi dipicu membantu Anda menyetel ambang batas dan memverifikasi perilaku yang diharapkan.

Kapan menggunakan kompaksi

Kasus penggunaan yang baik:

• Tugas agen yang berjalan lama yang memproses banyak file atau sumber data
• Alur kerja riset yang mengakumulasi informasi dalam jumlah besar
• Tugas multilangkah dengan kemajuan yang jelas dan terukur
• Tugas yang menghasilkan artefak (file, laporan) yang bertahan di luar percakapan

Kasus penggunaan yang kurang ideal:

• Tugas yang memerlukan ingatan presisi atas detail percakapan awal
• Alur kerja yang menggunakan alat sisi server secara ekstensif
• Tugas yang perlu mempertahankan status yang tepat di banyak variabel

Langkah selanjutnya