basforge

Search titles, text and the “If it doesn’t work” cases.

    RU

    The constant part of a prompt goes first, under the cache

    The prompt cache keeps the start of a request for 5 minutes (or an hour): a repeat request with the same start reads it at 10–40 times less than regular input and answers faster. It only works on a byte-for-byte match, so the constant parts — tools, system prompt, documents — go first, and the date, user name and question go last.

    How it works

    [tools][system][document 80K][history …][new question]
     └──────── matches the previous request ──────┘
               read from cache:  0.1× input price on Sonnet 5.5, 0.05× on Opus 5.5, 0.025× on Fable 5.1
                                                    └ after the marker — the regular price
    Price relative to regular input
    a 5-minute cache write 1.25×
    a 1-hour write ("ttl": "1h") 2×
    a cache read 0.1× (Opus 5.5 — 0.05×, Fable 5.1 — 0.025×)

    Every read extends the entry’s life. The 5-minute cache pays off from the second request: 1.25 + 0.1 = 1.35 versus 2 without the cache. The 1-hour one, from the third.

    How to turn it on

    {
      "model": "claude-sonnet-5-5",
      "max_tokens": 4096,
      "cache_control": { "type": "ephemeral" },
      "system": "…a long constant prompt…",
      "messages": [ … ]
    }

    cache_control at the top level places the marker on the last suitable block itself. For precise control, put a marker on the block you want, up to four markers per request. A prefix shorter than the minimum is silently not cached: 512 tokens on 5.5 models, 4096 on Haiku 4.5 and Opus 4.6.

    What silently breaks the cache

    • The date and time in the system prompt. “It’s 14:32:07 now” makes every request start differently. Put the date in the last message.
    • Key order. Tool JSON built from an unsorted dictionary can change order.
    • The tool set. Add or remove a tool and everything after it is recomputed.
    • Switching models. Each model has its own cache.

    How to check

    Send the same request twice within a minute. In the second response usage.cache_read_input_tokens covers nearly all the input, and input_tokens only the tail after the marker. Zero in cache_read_input_tokens both times means something from the list above changes the start.

    In chat apps and agents the apps themselves turn the cache on; your part is not to change the start of the conversation or CLAUDE.md mid-session without need.