Claude Academy
Loading

Rules of prompt caching

Lesson 4710 min

Prompt caching in Claude works by storing the computational work done on messages so it can be reused in follow-up requests. This makes subsequent requests both cheaper and faster to execute, but only when you're repeatedly sending the same content.

Claude writes the work done on the prompt "Please summarize this" to the cache, then reads it on the follow-up request.

The process follows a two-phase pattern: the initial request writes to the cache, and follow-up requests can read from it. The cache only lives for 5 minutes, so this feature is most useful when you're sending the same content repeatedly within a short timeframe.

Cache Points

Prompt caching isn't enabled automatically - you need to manually add cache point message parts to control what gets cached. Cache points tell Claude to cache all the work done for everything before that point in your message.

A user message like the code below, with an arrow labeling the highlighted cachePoint part after the "Long prompt" text.

Here's how you add a cache point to a user message:

python
user_message = {
  "role": "user",
  "content": [
    {"text": ""},
    {"cachePoint": {"type": "default"}}
  ]
}

The key rule is that work done for everything before the cache point will be cached, but anything after the cache point won't be stored in the cache.

How Cache Points Work

Initial request: Claude's work on "Summarize this long text" before the cache point is cached but not its work on "Focus on".

When you make an initial request with a cache point, Claude processes all the content and stores the work done up to that cache point. On follow-up requests, if the content before the cache point is identical, Claude reads the previously processed work from cache instead of reprocessing it.

Claude reads cached work for "Summarize this long text" and processes only the three parts after the cache point.

The cache will only be used if the content before the cache point is completely identical. Even small changes like adding "Please" to the beginning of your prompt will prevent cache usage, forcing Claude to process everything from scratch.

The prompt now begins with "Please", so it no longer matches the cached work for "Summarize this".

Caching Across Messages

Cache points can span multiple messages and even include assistant messages. This means you can cache entire conversation histories up to a certain point.

A summarize request, an assistant summary, then a user message ending in a cache point, so work for all three is cached.

For example, you might have a conversation with a user message, assistant response, and another user message, with a cache point at the end. All the processing work for that entire conversation thread gets cached and can be reused.

Minimum Content Length

Content must be at least 1024 tokens long to be cached. This is the sum of all messages and parts you're trying to cache before the cache point.

Two conversations with a cache point: a single "Hi there!" is not cached, but "Hi there!" duplicated 503 times is cached.

A simple "Hi there!" message won't meet the 1024 token minimum, so nothing gets cached. But if you repeat "Hi there!" 500 times, that would exceed 1024 tokens and qualify for caching.

Cache Point Locations

Cache points aren't restricted to user messages. You can add them to system prompts and tool definitions, which are actually the most common caching opportunities.

"Tool definitions will be cached" and "System prompt will be cached" label the tools and system code, each shown below.

For tool definitions:

python
tools = [
  {"toolSpec": add_duration_to_datetime_schema},
  {"toolSpec": get_current_datetime_schema},
  {"cachePoint": {"type": "default"}}
]

For system prompts:

python
system = [
  {"text": "You are a senior software..."},
  {"cachePoint": {"type": "default"}}
]

These are the most valuable caching opportunities because system prompts and tool lists rarely change between requests, making them perfect candidates for caching.