# lancemartin-anthropic-prompt-auto-caching-claude-2026-02

## Veille

Auto-caching Claude prompts: technical mechanism, cache_control API, 90% token savings, cache-friendly design

## Titre Article

Prompt auto-caching with Claude

## Date

2026-02

## URL

https://x.com/RLanceMartin/status/2024573404888911886

## Keywords

prompt caching, auto-caching, cache_control, ephemeral, cached tokens, hash prefix, cache hit, cache miss, LLM inference, prefill, decode, vLLM, SGLang, Claude messages API, stateless, agents, token cost, latency, breakpoint

## Authors

Lance Martin (@RLanceMartin, Anthropic)

## Ton

**Profile**: Perspective of a developer advocate at Anthropic, technical and pedagogical register, intermediate to advanced level

**Description**: Lance Martin adopts an explanatory, progressive tone, starting from the "why" (agents repay the entire context at every turn) to reach the "how" (cryptographic hash mechanism, prefill/decode). The style is that of a well-structured technical tutorial with interspersed JSON code examples. The author actively cites other contributors (@trq212 for Claude Code, @peakji of Manus, @sankalp, @kipply), creating an effect of a community of experts. The target audience consists of developers using the Claude API who want to optimize cost and latency.

## Pense-betes

- **Massive savings**: Cached tokens cost 10% of the price of non-cached tokens. Without caching, one pays for the entire context window at every agent turn.
- **Stateless API**: The Claude messages API does not remember past actions. The agent harness must repackage at every turn: new context + past actions + tool descriptions + general instructions. Most of the context is identical from one turn to the next.
- **Technical mechanism**: The `cache_control` breakpoint is a "write point" that creates a cryptographic hash of all blocks up to that point, scoped to the workspace. On the next request, Claude looks backward (max 20 blocks) to find a hash match. A single character of difference = cache miss.
- **Auto-caching (new)**: New single parameter `cache_control: {"type": "ephemeral"}` at the request level (not the block level). The breakpoint automatically moves to the last cacheable block. No more need to manually move the breakpoint.
- **Compatible with block-level caching**: Auto-caching works in addition to block-by-block caching (e.g. a fixed breakpoint on the system prompt).
- **Quote from @peakji (Manus)**: Cache hit rate is "the single most important metric" for an AI agent in production.
- **Two phases of LLM inference**: (1) Prefill = prompt processing, (2) Decode = output token generation. Caching avoids redoing the prefill for context already seen.
- **Risk of breaking the cache**: Modifying the conversation history risks breaking the cache. Points to @trq212's lessons for cache-friendly design.
- **Complementary to @trq212's post**: This post explains the technical "what/why/how" of caching, while @trq212 details the practical lessons from Claude Code (plan mode, compaction, tool search).

## RésuméDe400mots

Lance Martin, developer advocate at Anthropic, presents the prompt caching mechanism for the Claude API and announces the new auto-caching feature that considerably simplifies its use. Tokens using the cache cost only 10% of the normal price, representing a critical saving for agentic applications.

The fundamental problem is that the Claude messages API is **stateless**: it retains nothing between calls. An agent running actions in a loop must repackage, at every turn, the new context along with the history of actions, tool descriptions, and general instructions. Without caching, one pays the full price of the entire context window at every turn, even though most of the content is identical.

Prompt caching solves this problem by exploiting the two phases of LLM inference: **prefill** (prompt processing) and **decode** (generation). The prefill computation can be performed once, saved, then reused if part of the future prompt is identical. This is what frameworks such as vLLM and SGLang do.

Technically, caching uses a `cache_control` parameter that acts as a breakpoint. This breakpoint creates a **cryptographic hash** of all content blocks up to that point, scoped to the user's workspace. On subsequent requests, Claude looks backward (up to 20 blocks) to find a match. The match must be exact: a single character of difference produces a different hash and a cache miss.

The major new feature is **auto-caching**: a single `cache_control: {"type": "ephemeral"}` parameter placed at the request level (rather than at each block) causes the breakpoint to automatically move to the last cacheable block. As the conversation grows longer, the breakpoint follows automatically. This feature remains compatible with block-by-block caching for cases where one wants to set specific breakpoints (for example on the system prompt).

Martin cites @peakji of Manus, who considers the cache hit rate to be "the single most important metric for an AI agent in production," and points to the companion post by @trq212, which details the practical lessons drawn from Claude Code: how to structure the prompt to maximize hits, why one should never change tools or the model mid-session, and how to design features (plan mode, compaction) while respecting cache constraints. Together, the two articles form a complete guide to building cache-optimized agents on the Claude API.

## GrapheDeConnaissance

- Lance Martin —travaille_chez→ Anthropic (ORGANISATION, 0.98)
- Lance Martin —publie→ auto-caching (TECHNOLOGIE, 0.97)
- API Claude messages —est_instance_de→ API stateless (CONCEPT, 0.99)
- Tokens cachés —mesure→ 10% du prix des tokens non cachés (MESURE, 0.99)
- cache_control —permet→ hash cryptographique du préfixe (CONCEPT, 0.97)
- Auto-caching —améliore→ gestion des breakpoints cache (CONCEPT, 0.96)
- Auto-caching —converge_avec→ caching bloc par bloc (TECHNOLOGIE, 0.95)
- prefill et decode —fait_partie_de→ Inférence LLM (CONCEPT, 0.98)
- Prompt caching —réduit→ recalcul du prefill (CONCEPT, 0.97)
- @peakji —affirme_que→ le cache hit rate est la métrique la plus importante pour un agent en production (AFFIRMATION, 0.95)
- @peakji —travaille_chez→ Manus (ORGANISATION, 0.96)
- @trq212 —publie→ leçons pratiques cache Claude Code (DOCUMENT, 0.93)
- vLLM —utilise→ caching du prefill (CONCEPT, 0.9)
- SGLang —utilise→ caching du prefill (CONCEPT, 0.9)

---
Canonical: https://www.thekb.eu/en/fiches/lancemartin-anthropic-prompt-auto-caching-claude-2026-02/