Pemadatan

BangunManajemen konteks

Compaction

Compaction konteks sisi server untuk mengelola percakapan panjang yang mendekati batas jendela konteks.

This feature is eligible for Zero Data Retention (ZDR). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.

Compaction sisi server adalah strategi yang direkomendasikan untuk mengelola konteks dalam percakapan jangka panjang dan alur kerja agentic. Ini menangani manajemen konteks secara otomatis dengan usaha integrasi minimal.

Compaction memperpanjang panjang konteks efektif untuk percakapan dan tugas jangka panjang dengan secara otomatis merangkum konteks yang lebih lama ketika mendekati batas jendela konteks. Ini bukan hanya tentang tetap berada di bawah batas token. Seiring percakapan menjadi lebih panjang, model kesulitan mempertahankan fokus di seluruh riwayat. Compaction menjaga konteks aktif tetap fokus dan berkinerja dengan mengganti konten basi dengan ringkasan ringkas.

Untuk pandangan yang lebih mendalam tentang mengapa konteks panjang menurun dan bagaimana compaction membantu, lihat Effective context engineering.

Ini ideal untuk:

Percakapan berbasis chat, multi-turn di mana Anda ingin pengguna menggunakan satu chat untuk jangka waktu yang lama
Prompt berorientasi tugas yang memerlukan banyak pekerjaan lanjutan (sering kali penggunaan alat) yang mungkin melebihi jendela konteks

Compaction sedang dalam beta. Sertakan beta header compact-2026-01-12 dalam permintaan API Anda untuk menggunakan fitur ini.

Model yang didukung

Compaction didukung pada model berikut:

Claude Mythos Preview (claude-mythos-preview)
Claude Opus 4.7 (claude-opus-4-7)
Claude Opus 4.6 (claude-opus-4-6)
Claude Sonnet 4.6 (claude-sonnet-4-6)

Cara kerja compaction

Ketika compaction diaktifkan, Claude secara otomatis merangkum percakapan Anda ketika mendekati ambang token yang dikonfigurasi. API:

Mendeteksi ketika token input melebihi ambang pemicu yang Anda tentukan.
Menghasilkan ringkasan percakapan saat ini.
Membuat blok compaction yang berisi ringkasan.
Melanjutkan respons dengan konteks yang dipadatkan.

Pada permintaan berikutnya, tambahkan respons ke pesan Anda. API secara otomatis menghapus semua blok pesan sebelum blok compaction, melanjutkan percakapan dari ringkasan.

Diagram alur yang menunjukkan proses compaction: ketika token input melebihi ambang pemicu, Claude menghasilkan ringkasan dalam blok compaction dan melanjutkan respons dengan konteks yang dipadatkan

Penggunaan dasar

Aktifkan compaction dengan menambahkan strategi compact_20260112 ke context_management.edits dalam permintaan Messages API Anda.

client = anthropic.Anthropic()

messages = [{"role": "user", "content": "Help me build a website"}]

response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)

# Append the response (including any compaction block) to continue the conversation
messages.append({"role": "assistant", "content": response.content})

Parameter

Parameter	Tipe	Default	Deskripsi
`type`	string	Diperlukan	Harus `"compact_20260112"`
`trigger`	object	150.000 token	Kapan memicu compaction. Harus minimal 50.000 token.
`pause_after_compaction`	boolean	`false`	Apakah akan berhenti setelah menghasilkan ringkasan compaction
`instructions`	string	`null`	Prompt perangkuman khusus. Sepenuhnya menggantikan prompt default ketika disediakan.

Konfigurasi pemicu

Konfigurasikan kapan compaction dipicu menggunakan parameter trigger:

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [
            {
                "type": "compact_20260112",
                "trigger": {"type": "input_tokens", "value": 150000},
            }
        ]
    },
)

Instruksi perangkuman khusus

Secara default, compaction menggunakan prompt perangkuman berikut:

You have written a partial transcript for the initial task above. Please write a summary of the transcript. The purpose of this summary is to provide continuity so you can continue to make progress towards solving the task in a future context, where the raw history above may not be accessible and will be replaced with this summary. Write down anything that would be helpful, including the state, next steps, learnings etc. You must wrap your summary in a <summary></summary> block.

Anda dapat memberikan instruksi khusus melalui parameter instructions untuk menggantikan prompt ini sepenuhnya. Instruksi khusus tidak melengkapi default; mereka sepenuhnya menggantinya:

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [
            {
                "type": "compact_20260112",
                "instructions": "Focus on preserving code snippets, variable names, and technical decisions.",
            }
        ]
    },
)

Menjeda setelah pemadatan

Gunakan pause_after_compaction untuk menjeda API setelah menghasilkan ringkasan pemadatan. Ini memungkinkan Anda menambahkan blok konten tambahan (seperti mempertahankan pesan terbaru atau pesan yang berorientasi pada instruksi tertentu) sebelum API melanjutkan dengan respons.

Ketika diaktifkan, API mengembalikan pesan dengan alasan penghentian compaction setelah menghasilkan blok pemadatan:

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [{"type": "compact_20260112", "pause_after_compaction": True}]
    },
)

# Check if compaction triggered a pause
if response.stop_reason == "compaction":
    # Response contains only the compaction block
    messages.append({"role": "assistant", "content": response.content})

    # Continue the request
    response = client.beta.messages.create(
        betas=["compact-2026-01-12"],
        model="claude-opus-4-7",
        max_tokens=4096,
        messages=messages,
        context_management={"edits": [{"type": "compact_20260112"}]},
    )

Memberlakukan anggaran token total

Ketika model bekerja pada tugas panjang dengan banyak iterasi penggunaan alat, konsumsi token total dapat tumbuh secara signifikan. Anda dapat menggabungkan pause_after_compaction dengan penghitung pemadatan untuk memperkirakan penggunaan kumulatif dan menyelesaikan tugas dengan baik setelah anggaran tercapai:

Python

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
TRIGGER_THRESHOLD = 100_000
TOTAL_TOKEN_BUDGET = 3_000_000
n_compactions = 0

response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [
            {
                "type": "compact_20260112",
                "trigger": {"type": "input_tokens", "value": TRIGGER_THRESHOLD},
                "pause_after_compaction": True,
            }
        ]
    },
)

if response.stop_reason == "compaction":
    n_compactions += 1
    messages.append({"role": "assistant", "content": response.content})

    # Estimate total tokens consumed; prompt wrap-up if over budget
    if n_compactions * TRIGGER_THRESHOLD >= TOTAL_TOKEN_BUDGET:
        messages.append(
            {
                "role": "user",
                "content": "Please wrap up your current work and summarize the final state.",
            }
        )

Bekerja dengan blok pemadatan

Ketika pemadatan dipicu, API mengembalikan blok compaction di awal respons asisten.

Percakapan yang berjalan lama dapat menghasilkan beberapa pemadatan. Blok pemadatan terakhir mencerminkan keadaan akhir dari prompt, menggantikan konten sebelumnya dengan ringkasan yang dihasilkan.

Output

{
  "content": [
    {
      "type": "compaction",
      "content": "Summary of the conversation: The user requested help building a web scraper..."
    },
    {
      "type": "text",
      "text": "Based on our conversation so far..."
    }
  ]
}

Meneruskan blok pemadatan kembali

Anda harus meneruskan blok compaction kembali ke API pada permintaan berikutnya untuk melanjutkan percakapan dengan prompt yang diperpendek. Pendekatan paling sederhana adalah menambahkan seluruh konten respons ke pesan Anda:

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)
# After receiving a response with a compaction block
messages.append({"role": "assistant", "content": response.content})

# Continue the conversation
messages.append({"role": "user", "content": "Now add error handling"})

response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)

Ketika API menerima blok compaction, semua blok konten sebelumnya diabaikan. Anda dapat:

Menyimpan pesan asli dalam daftar Anda dan membiarkan API menangani penghapusan konten yang dipadatkan
Secara manual menghapus pesan yang dipadatkan dan hanya menyertakan blok pemadatan ke depan

Streaming

Ketika streaming respons dengan pemadatan diaktifkan, Anda akan menerima acara content_block_start ketika pemadatan dimulai. Blok pemadatan streaming berbeda dari blok teks. Anda akan menerima acara content_block_start, diikuti oleh satu content_block_delta dengan konten ringkasan lengkap (tanpa streaming perantara), dan kemudian acara content_block_stop.

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]

with client.beta.messages.stream(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
) as stream:
    for event in stream:
        if event.type == "content_block_start":
            if event.content_block.type == "compaction":
                print("Compaction started...")
            elif event.content_block.type == "text":
                print("Text response started...")

        elif event.type == "content_block_delta":
            if event.delta.type == "compaction_delta":
                print(f"Compaction complete: {len(event.delta.content)} chars")
            elif event.delta.type == "text_delta":
                print(event.delta.text, end="", flush=True)

    # Get the final accumulated message
    message = stream.get_final_message()
    messages.append({"role": "assistant", "content": message.content})

Prompt caching

Compaction bekerja dengan baik dengan prompt caching. Anda dapat menambahkan breakpoint cache_control pada blok compaction untuk menyimpan konten yang diringkas dalam cache. Konten compaction asli diabaikan.

{
  "role": "assistant",
  "content": [
    {
      "type": "compaction",
      "content": "[summary text]",
      "cache_control": { "type": "ephemeral" }
    },
    {
      "type": "text",
      "text": "Based on our conversation..."
    }
  ]
}

Memaksimalkan cache hits dengan system prompts

Ketika compaction terjadi, ringkasan menjadi konten baru yang perlu ditulis ke cache. Tanpa breakpoint cache tambahan, ini juga akan membatalkan system prompt yang di-cache, memerlukan untuk di-cache ulang bersama dengan ringkasan compaction.

Untuk memaksimalkan tingkat cache hit, tambahkan breakpoint cache_control di akhir system prompt Anda. Ini menjaga system prompt tetap di-cache secara terpisah dari percakapan, sehingga ketika compaction terjadi:

Cache system prompt tetap valid dan dibaca dari cache
Hanya ringkasan compaction yang perlu ditulis sebagai entri cache baru

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-7",
    max_tokens=4096,
    system=[
        {
            "type": "text",
            "text": "You are a helpful coding assistant...",
            "cache_control": {
                "type": "ephemeral"
            },  # Cache the system prompt separately
        }
    ],
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)

Pendekatan ini sangat bermanfaat untuk system prompt yang panjang, karena tetap di-cache bahkan di seluruh beberapa peristiwa compaction dalam percakapan.

Memahami penggunaan

Compaction memerlukan langkah sampling tambahan, yang berkontribusi pada batas laju dan penagihan. API mengembalikan informasi penggunaan terperinci dalam respons:

Output

{
  "usage": {
    "input_tokens": 23000,
    "output_tokens": 1000,
    "iterations": [
      {
        "type": "compaction",
        "input_tokens": 180000,
        "output_tokens": 3500
      },
      {
        "type": "message",
        "input_tokens": 23000,
        "output_tokens": 1000
      }
    ]
  }
}

Array iterations menunjukkan penggunaan untuk setiap iterasi sampling. Ketika compaction terjadi, Anda akan melihat iterasi compaction diikuti oleh iterasi message utama. input_tokens dan output_tokens tingkat atas cocok dengan iterasi message persis dalam contoh ini karena hanya ada satu iterasi non-compaction. Hitungan token iterasi terakhir mencerminkan ukuran konteks efektif setelah compaction.

input_tokens dan output_tokens tingkat atas tidak termasuk penggunaan iterasi compaction. Mereka mencerminkan jumlah semua iterasi non-compaction. Untuk menghitung total token yang dikonsumsi dan ditagih untuk permintaan, jumlahkan semua entri dalam array usage.iterations.

Jika Anda sebelumnya mengandalkan usage.input_tokens dan usage.output_tokens untuk pelacakan biaya atau audit, Anda perlu memperbarui logika pelacakan Anda untuk menggabungkan di seluruh usage.iterations ketika compaction diaktifkan. Array iterations hanya diisi ketika compaction baru dipicu selama permintaan. Menerapkan kembali blok compaction sebelumnya tidak menimbulkan biaya compaction tambahan, dan bidang penggunaan tingkat atas tetap akurat dalam kasus itu.

Menggabungkan dengan fitur lain

Server tools

Saat menggunakan server tools (seperti pencarian web), pemicu compaction diperiksa di awal setiap iterasi sampling. Compaction dapat terjadi beberapa kali dalam satu permintaan tergantung pada ambang pemicu Anda dan jumlah output yang dihasilkan.

Token counting

Endpoint token counting (/v1/messages/count_tokens) menerapkan blok compaction yang ada dalam prompt Anda tetapi tidak memicu compaction baru. Gunakan untuk memeriksa hitungan token efektif Anda setelah compaction sebelumnya:

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
count_response = client.beta.messages.count_tokens(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-7",
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)

print(f"Current tokens: {count_response.input_tokens}")
print(f"Original tokens: {count_response.context_management.original_input_tokens}")

Contoh

Berikut adalah contoh lengkap percakapan jangka panjang dengan kompresi:

client = anthropic.Anthropic()

messages: list[dict] = []


def chat(user_message: str) -> str:
    messages.append({"role": "user", "content": user_message})

    response = client.beta.messages.create(
        betas=["compact-2026-01-12"],
        model="claude-opus-4-7",
        max_tokens=4096,
        messages=messages,
        context_management={
            "edits": [
                {
                    "type": "compact_20260112",
                    "trigger": {"type": "input_tokens", "value": 100000},
                }
            ]
        },
    )

    # Append response (compaction blocks are automatically included)
    messages.append({"role": "assistant", "content": response.content})

    # Return the text content
    return next(block.text for block in response.content if block.type == "text")


# Run a long conversation
print(chat("Help me build a Python web scraper"))
print(chat("Add support for JavaScript-rendered pages"))
print(chat("Now add rate limiting and error handling"))
# ... continue as long as needed

Berikut adalah contoh yang menggunakan pause_after_compaction untuk mempertahankan pertukaran sebelumnya dan pesan pengguna saat ini (tiga pesan total) secara verbatim alih-alih merangkumnya:

from typing import Any

client = anthropic.Anthropic()

messages: list[dict[str, Any]] = []


def chat(user_message: str) -> str:
    messages.append({"role": "user", "content": user_message})

    response = client.beta.messages.create(
        betas=["compact-2026-01-12"],
        model="claude-opus-4-7",
        max_tokens=4096,
        messages=messages,
        context_management={
            "edits": [
                {
                    "type": "compact_20260112",
                    "trigger": {"type": "input_tokens", "value": 100000},
                    "pause_after_compaction": True,
                }
            ]
        },
    )

    # Check if compaction occurred and paused
    if response.stop_reason == "compaction":
        # Get the compaction block from the response
        compaction_block = response.content[0]

        # Preserve the prior exchange + current user message (3 messages)
        # by including them after the compaction block
        preserved_messages = messages[-3:] if len(messages) >= 3 else messages

        # Build new message list: compaction + preserved messages
        new_assistant_content = [compaction_block]
        messages_after_compaction = [
            {"role": "assistant", "content": new_assistant_content}
        ] + preserved_messages

        # Continue the request with the compacted context + preserved messages
        response = client.beta.messages.create(
            betas=["compact-2026-01-12"],
            model="claude-opus-4-7",
            max_tokens=4096,
            messages=messages_after_compaction,
            context_management={"edits": [{"type": "compact_20260112"}]},
        )

        # Update our message list to reflect the compaction
        messages.clear()
        messages.extend(messages_after_compaction)

    # Append the final response
    messages.append({"role": "assistant", "content": response.content})

    # Return the text content
    return next(block.text for block in response.content if block.type == "text")


# Run a long conversation
print(chat("Help me build a Python web scraper"))
print(chat("Add support for JavaScript-rendered pages"))
print(chat("Now add rate limiting and error handling"))
# ... continue as long as needed

Keterbatasan saat ini

Model yang sama untuk perangkuman: Model yang ditentukan dalam permintaan Anda digunakan untuk perangkuman. Tidak ada opsi untuk menggunakan model yang berbeda (misalnya, lebih murah) untuk ringkasan.

Langkah berikutnya

Buku masak kompresi memori sesi

Jelajahi implementasi praktis yang mengelola percakapan jangka panjang dengan kompresi memori sesi instan menggunakan threading latar belakang dan caching prompt.

Jendela konteks

Pelajari tentang ukuran jendela konteks dan strategi manajemen.

Pengeditan konteks

Jelajahi strategi lain untuk mengelola konteks percakapan seperti pembersihan hasil alat dan pembersihan blok pemikiran.

Was this page helpful?

BangunManajemen konteks

Compaction

Compaction konteks sisi server untuk mengelola percakapan panjang yang mendekati batas jendela konteks.

This feature is eligible for Zero Data Retention (ZDR). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.

Untuk pandangan yang lebih mendalam tentang mengapa konteks panjang menurun dan bagaimana compaction membantu, lihat Effective context engineering.

Ini ideal untuk:

Percakapan berbasis chat, multi-turn di mana Anda ingin pengguna menggunakan satu chat untuk jangka waktu yang lama
Prompt berorientasi tugas yang memerlukan banyak pekerjaan lanjutan (sering kali penggunaan alat) yang mungkin melebihi jendela konteks

Compaction sedang dalam beta. Sertakan beta header compact-2026-01-12 dalam permintaan API Anda untuk menggunakan fitur ini.

Model yang didukung

Compaction didukung pada model berikut:

Claude Mythos Preview (claude-mythos-preview)
Claude Opus 4.7 (claude-opus-4-7)
Claude Opus 4.6 (claude-opus-4-6)
Claude Sonnet 4.6 (claude-sonnet-4-6)

Cara kerja compaction

Ketika compaction diaktifkan, Claude secara otomatis merangkum percakapan Anda ketika mendekati ambang token yang dikonfigurasi. API:

Mendeteksi ketika token input melebihi ambang pemicu yang Anda tentukan.
Menghasilkan ringkasan percakapan saat ini.
Membuat blok compaction yang berisi ringkasan.
Melanjutkan respons dengan konteks yang dipadatkan.

Pada permintaan berikutnya, tambahkan respons ke pesan Anda. API secara otomatis menghapus semua blok pesan sebelum blok compaction, melanjutkan percakapan dari ringkasan.

Penggunaan dasar

Aktifkan compaction dengan menambahkan strategi compact_20260112 ke context_management.edits dalam permintaan Messages API Anda.

client = anthropic.Anthropic()

messages = [{"role": "user", "content": "Help me build a website"}]

response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)

# Append the response (including any compaction block) to continue the conversation
messages.append({"role": "assistant", "content": response.content})

Parameter

Parameter	Tipe	Default	Deskripsi
`type`	string	Diperlukan	Harus `"compact_20260112"`
`trigger`	object	150.000 token	Kapan memicu compaction. Harus minimal 50.000 token.
`pause_after_compaction`	boolean	`false`	Apakah akan berhenti setelah menghasilkan ringkasan compaction
`instructions`	string	`null`	Prompt perangkuman khusus. Sepenuhnya menggantikan prompt default ketika disediakan.

Konfigurasi pemicu

Konfigurasikan kapan compaction dipicu menggunakan parameter trigger:

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [
            {
                "type": "compact_20260112",
                "trigger": {"type": "input_tokens", "value": 150000},
            }
        ]
    },
)

Instruksi perangkuman khusus

Secara default, compaction menggunakan prompt perangkuman berikut:

You have written a partial transcript for the initial task above. Please write a summary of the transcript. The purpose of this summary is to provide continuity so you can continue to make progress towards solving the task in a future context, where the raw history above may not be accessible and will be replaced with this summary. Write down anything that would be helpful, including the state, next steps, learnings etc. You must wrap your summary in a <summary></summary> block.

Anda dapat memberikan instruksi khusus melalui parameter instructions untuk menggantikan prompt ini sepenuhnya. Instruksi khusus tidak melengkapi default; mereka sepenuhnya menggantinya:

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [
            {
                "type": "compact_20260112",
                "instructions": "Focus on preserving code snippets, variable names, and technical decisions.",
            }
        ]
    },
)

Menjeda setelah pemadatan

Ketika diaktifkan, API mengembalikan pesan dengan alasan penghentian compaction setelah menghasilkan blok pemadatan:

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [{"type": "compact_20260112", "pause_after_compaction": True}]
    },
)

# Check if compaction triggered a pause
if response.stop_reason == "compaction":
    # Response contains only the compaction block
    messages.append({"role": "assistant", "content": response.content})

    # Continue the request
    response = client.beta.messages.create(
        betas=["compact-2026-01-12"],
        model="claude-opus-4-7",
        max_tokens=4096,
        messages=messages,
        context_management={"edits": [{"type": "compact_20260112"}]},
    )

Memberlakukan anggaran token total

Python

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
TRIGGER_THRESHOLD = 100_000
TOTAL_TOKEN_BUDGET = 3_000_000
n_compactions = 0

response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [
            {
                "type": "compact_20260112",
                "trigger": {"type": "input_tokens", "value": TRIGGER_THRESHOLD},
                "pause_after_compaction": True,
            }
        ]
    },
)

if response.stop_reason == "compaction":
    n_compactions += 1
    messages.append({"role": "assistant", "content": response.content})

    # Estimate total tokens consumed; prompt wrap-up if over budget
    if n_compactions * TRIGGER_THRESHOLD >= TOTAL_TOKEN_BUDGET:
        messages.append(
            {
                "role": "user",
                "content": "Please wrap up your current work and summarize the final state.",
            }
        )

Bekerja dengan blok pemadatan

Ketika pemadatan dipicu, API mengembalikan blok compaction di awal respons asisten.

Percakapan yang berjalan lama dapat menghasilkan beberapa pemadatan. Blok pemadatan terakhir mencerminkan keadaan akhir dari prompt, menggantikan konten sebelumnya dengan ringkasan yang dihasilkan.

Output

{
  "content": [
    {
      "type": "compaction",
      "content": "Summary of the conversation: The user requested help building a web scraper..."
    },
    {
      "type": "text",
      "text": "Based on our conversation so far..."
    }
  ]
}

Meneruskan blok pemadatan kembali

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)
# After receiving a response with a compaction block
messages.append({"role": "assistant", "content": response.content})

# Continue the conversation
messages.append({"role": "user", "content": "Now add error handling"})

response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)

Ketika API menerima blok compaction, semua blok konten sebelumnya diabaikan. Anda dapat:

Menyimpan pesan asli dalam daftar Anda dan membiarkan API menangani penghapusan konten yang dipadatkan
Secara manual menghapus pesan yang dipadatkan dan hanya menyertakan blok pemadatan ke depan

Streaming

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]

with client.beta.messages.stream(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
) as stream:
    for event in stream:
        if event.type == "content_block_start":
            if event.content_block.type == "compaction":
                print("Compaction started...")
            elif event.content_block.type == "text":
                print("Text response started...")

        elif event.type == "content_block_delta":
            if event.delta.type == "compaction_delta":
                print(f"Compaction complete: {len(event.delta.content)} chars")
            elif event.delta.type == "text_delta":
                print(event.delta.text, end="", flush=True)

    # Get the final accumulated message
    message = stream.get_final_message()
    messages.append({"role": "assistant", "content": message.content})

Prompt caching

{
  "role": "assistant",
  "content": [
    {
      "type": "compaction",
      "content": "[summary text]",
      "cache_control": { "type": "ephemeral" }
    },
    {
      "type": "text",
      "text": "Based on our conversation..."
    }
  ]
}

Memaksimalkan cache hits dengan system prompts

Cache system prompt tetap valid dan dibaca dari cache
Hanya ringkasan compaction yang perlu ditulis sebagai entri cache baru

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-7",
    max_tokens=4096,
    system=[
        {
            "type": "text",
            "text": "You are a helpful coding assistant...",
            "cache_control": {
                "type": "ephemeral"
            },  # Cache the system prompt separately
        }
    ],
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)

Pendekatan ini sangat bermanfaat untuk system prompt yang panjang, karena tetap di-cache bahkan di seluruh beberapa peristiwa compaction dalam percakapan.

Memahami penggunaan

Compaction memerlukan langkah sampling tambahan, yang berkontribusi pada batas laju dan penagihan. API mengembalikan informasi penggunaan terperinci dalam respons:

Output

{
  "usage": {
    "input_tokens": 23000,
    "output_tokens": 1000,
    "iterations": [
      {
        "type": "compaction",
        "input_tokens": 180000,
        "output_tokens": 3500
      },
      {
        "type": "message",
        "input_tokens": 23000,
        "output_tokens": 1000
      }
    ]
  }
}

Menggabungkan dengan fitur lain

Server tools

Token counting

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
count_response = client.beta.messages.count_tokens(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-7",
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)

print(f"Current tokens: {count_response.input_tokens}")
print(f"Original tokens: {count_response.context_management.original_input_tokens}")

Contoh

Berikut adalah contoh lengkap percakapan jangka panjang dengan kompresi:

client = anthropic.Anthropic()

messages: list[dict] = []


def chat(user_message: str) -> str:
    messages.append({"role": "user", "content": user_message})

    response = client.beta.messages.create(
        betas=["compact-2026-01-12"],
        model="claude-opus-4-7",
        max_tokens=4096,
        messages=messages,
        context_management={
            "edits": [
                {
                    "type": "compact_20260112",
                    "trigger": {"type": "input_tokens", "value": 100000},
                }
            ]
        },
    )

    # Append response (compaction blocks are automatically included)
    messages.append({"role": "assistant", "content": response.content})

    # Return the text content
    return next(block.text for block in response.content if block.type == "text")


# Run a long conversation
print(chat("Help me build a Python web scraper"))
print(chat("Add support for JavaScript-rendered pages"))
print(chat("Now add rate limiting and error handling"))
# ... continue as long as needed

Berikut adalah contoh yang menggunakan pause_after_compaction untuk mempertahankan pertukaran sebelumnya dan pesan pengguna saat ini (tiga pesan total) secara verbatim alih-alih merangkumnya:

from typing import Any

client = anthropic.Anthropic()

messages: list[dict[str, Any]] = []


def chat(user_message: str) -> str:
    messages.append({"role": "user", "content": user_message})

    response = client.beta.messages.create(
        betas=["compact-2026-01-12"],
        model="claude-opus-4-7",
        max_tokens=4096,
        messages=messages,
        context_management={
            "edits": [
                {
                    "type": "compact_20260112",
                    "trigger": {"type": "input_tokens", "value": 100000},
                    "pause_after_compaction": True,
                }
            ]
        },
    )

    # Check if compaction occurred and paused
    if response.stop_reason == "compaction":
        # Get the compaction block from the response
        compaction_block = response.content[0]

        # Preserve the prior exchange + current user message (3 messages)
        # by including them after the compaction block
        preserved_messages = messages[-3:] if len(messages) >= 3 else messages

        # Build new message list: compaction + preserved messages
        new_assistant_content = [compaction_block]
        messages_after_compaction = [
            {"role": "assistant", "content": new_assistant_content}
        ] + preserved_messages

        # Continue the request with the compacted context + preserved messages
        response = client.beta.messages.create(
            betas=["compact-2026-01-12"],
            model="claude-opus-4-7",
            max_tokens=4096,
            messages=messages_after_compaction,
            context_management={"edits": [{"type": "compact_20260112"}]},
        )

        # Update our message list to reflect the compaction
        messages.clear()
        messages.extend(messages_after_compaction)

    # Append the final response
    messages.append({"role": "assistant", "content": response.content})

    # Return the text content
    return next(block.text for block in response.content if block.type == "text")


# Run a long conversation
print(chat("Help me build a Python web scraper"))
print(chat("Add support for JavaScript-rendered pages"))
print(chat("Now add rate limiting and error handling"))
# ... continue as long as needed

Keterbatasan saat ini

Model yang sama untuk perangkuman: Model yang ditentukan dalam permintaan Anda digunakan untuk perangkuman. Tidak ada opsi untuk menggunakan model yang berbeda (misalnya, lebih murah) untuk ringkasan.

Langkah berikutnya

Buku masak kompresi memori sesi

Jelajahi implementasi praktis yang mengelola percakapan jangka panjang dengan kompresi memori sesi instan menggunakan threading latar belakang dan caching prompt.

Jendela konteks

Pelajari tentang ukuran jendela konteks dan strategi manajemen.

Pengeditan konteks

Jelajahi strategi lain untuk mengelola konteks percakapan seperti pembersihan hasil alat dan pembersihan blok pemikiran.

Was this page helpful?