Por que 99% do que você envia para o Claude já está em cache

Estou construindo um app que monitora meu consumo de tokens no Claude Code. Alguns dias atrás, olhando os números brutos, me deparei com isso:

cacheReadInputTokens:     4.241.579.174
inputTokens:                  1.293.019

Quatro bilhões e duzentos milhões de tokens lidos do cache. Um milhão e trezentos mil tokens “frescos”. Isso é um 99,97% de cache hit.

Minha primeira reação foi pensar que algo estava quebrado. Ninguém tem 99% de cache. Nem Redis. Nem Cloudflare. Nem sua mãe quando ela diz que já sabe o que você vai pedir para comer.

Mas acontece que não está quebrado. É exatamente assim que funciona. E o motivo é tão elegante quanto contraintuitivo.

O que é cacheado não é texto

É aqui que a maioria das explicações fica pela metade. Quando você lê “prompt caching” pensa em algo tipo Redis: guarda a pergunta, guarda a resposta, se alguém faz a mesma pergunta você devolve a mesma resposta.

Nada disso.

O que é cacheado são tensores KV — as matrizes Key e Value que o transformer calcula durante a fase de prefill. Em termos simples: quando um LLM recebe seu prompt, a primeira coisa que faz é converter todo esse texto em representações numéricas internas (os embeddings) e multiplicá-los por matrizes de pesos para obter as “chaves” (K) e “valores” (V) que o mecanismo de atenção precisa para gerar a resposta.

Esse cálculo é caríssimo. Em um prompt de 200.000 tokens (algo normal no Claude Code, onde o histórico de conversa se acumula), estamos falando de bilhões de operações de multiplicação de matrizes. É a parte que mais consome GPU, a que mais demora, a que mais custa.

E aqui está o pulo do gato: entre uma mensagem sua e a próxima, 99% desse prompt não muda. O system prompt é idêntico. O histórico de conversa anterior é idêntico. Os arquivos que ele leu são os mesmos. A única coisa nova é sua última mensagem.

Para que recalcular o que já calculou 30 segundos atrás?

Como funciona o matching

Não basta cachear. Tem que saber quando o cache serve. E aqui a Anthropic usa um truque elegante: hashing acumulativo por prefixo.

Cada bloco do prompt (system, tools, mensagens) gera um hash. Mas não um hash individual: um hash acumulativo. O hash do bloco 3 inclui o conteúdo dos blocos 1, 2 e 3. Se qualquer coisa muda em um bloco anterior, o hash de todos os blocos seguintes muda também.

Quando chega uma requisição nova, o sistema busca para trás a partir do ponto marcado com cache_control, comparando hashes bloco a bloco, até encontrar o prefixo mais longo que coincide. Tudo que coincide → é lido do cache. Só o novo → é calculado.

É como um filme que você já viu 40 vezes. Não precisa ver inteiro para saber o que acontece. Só precisa ver a partir do ponto onde difere do que você lembra.

Fique atento: o sistema só revisa até 20 blocos para trás. Mais além disso, para de procurar. Essa é uma decisão prática para não gastar mais tempo procurando no cache do que calculando os tensores diretamente.

Por que Claude Code tem 99% de cache hit

Agora que você sabe como funciona o matching, os 99% deixam de ser misteriosos. Veja o que acontece em uma sessão típica do Claude Code:

Mensagem 1 (a primeira da sessão):

System prompt (8K tokens) + Tools (2K tokens) + Sua mensagem (500 tokens)
= 10.500 tokens → TUDO é calculado, TUDO é escrito no cache

Mensagem 2:

System prompt (8K) + Tools (2K) + Mensagem 1 (500) + Resposta 1 (3K) + Sua mensagem 2 (500)
= 14.000 tokens
→ Os primeiros 10.500 → CACHE HIT (já calculamos antes)
→ Os 3.500 novos → são calculados e adicionados ao cache
Cache hit: 75%

Mensagem 10:

System prompt + Tools + 9 mensagens + 9 respostas + Sua mensagem 10
= ~150.000 tokens
→ Os primeiros ~149.500 → CACHE HIT
→ Os ~500 novos → são calculados
Cache hit: 99,7%

Viu? O histórico de conversa só cresce. Cada mensagem nova é uma fração diminuta do total acumulado. A taxa de cache converge para 99% com a certeza de um logaritmo neperiano.

Não é mágica. É geometria: o numerador (tokens novos) cresce linearmente; o denominador (tokens acumulados) também, mas leva uma vantagem enorme.

Onde vivem esses tensores

É aqui que a coisa fica interessante. Porque cachear tensores KV não é como cachear strings no Redis. Estamos falando de gigabytes de dados numéricos que têm que estar disponíveis com latência de microssegundos.

A Anthropic usa um sistema de dois níveis:

Nível 1: VRAM (5 minutos de TTL)

Os tensores vivem diretamente na memória da GPU que vai servir a próxima requisição. Zero cópia, zero latência de rede. O cache hit é quase instantâneo porque os dados já estão onde são necessários.

TTL: 5 minutos. Se ninguém faz uma requisição em 5 minutos, são removidos. Este é o cache que você usa com a API padrão. Preço do cache write: 1,25x o preço de input normal.

Nível 2: SSD do nó GPU (1 hora de TTL)

Se você paga o cache write estendido (2x o preço de input), os tensores não são removidos aos 5 minutos. Em vez disso, quando saem da VRAM por pressão de memória, são descarregados para o SSD local do nó GPU.

Quando chega um cache hit, são recarregados do SSD para a VRAM. Mais lento que o nível 1, mas infinitamente mais rápido que recalcular os tensores do zero.

O interessante disso: não há rede no meio. Não é um Redis remoto. Não é um S3. É um SSD conectado fisicamente ao servidor que tem a GPU. A arquitetura foi projetada para minimizar movimento de dados.

Requisição → Está na VRAM? → Sim → Cache hit instantâneo
                           → Não → Está no SSD local? → Sim → Carregar na VRAM → Cache hit (~ms)
                                                       → Não → Calcular tensores KV → Cache miss

Desde fevereiro de 2026, o isolamento é por workspace (antes era por organização). Isso significa que os tensores da sua equipe de desenvolvimento não se misturam com os da equipe de marketing, mesmo se estiverem na mesma organização da Anthropic.

Os números

Se você está avaliando se isso importa para seu caso de uso, aqui vão os dados duros:

Com Sonnet, o input custa $3,00/M tokens. Um cache read custa $0,30/M. Em uma sessão do Claude Code com 200K tokens de histórico, a diferença entre recalcular e ler do cache é a diferença entre $0,60 e $0,06 por mensagem.

Multiplique isso pelas centenas de mensagens que você pode trocar em uma sessão longa e dá para entender por que a Anthropic investiu em construir isso: sem prompt caching, conversas longas com contexto enorme seriam economicamente inviáveis.

Meus dados reais

Voltando aos meus números do início. No meu uso do Claude Code ao longo de um mês:

cacheReadInputTokens:       4.241.579.174  (4,2 bilhões — lidos do cache)
cacheCreationInputTokens:     196.596.243  (197 milhões — escritos no cache)
inputTokens:                    1.293.019  (1,3 milhões — calculados sem cache)
outputTokens:                   2.517.666  (2,5 milhões — gerados pelo modelo)

Cache hit rate global: 95,5%. E dentro de sessões individuais longas, supera os 99% facilmente.

Observe a assimetria: li 4,2 bilhões de tokens do cache, mas o modelo só gerou 2,5 milhões de tokens de output. A taxa de leitura-de-cache para trabalho-real é de 1.685:1. Para cada token que o modelo produz, reutiliza 1.685 tokens de contexto anterior.

Isso também significa que cacheReadInputTokens não é uma boa métrica de produtividade. Não mede quanto você “usou” o modelo. Mede quanto histórico o modelo releu. É como medir sua produtividade por quantas vezes você abriu o mesmo arquivo no seu editor.

O que a Anthropic não conta

Há coisas que não são públicas:

• Afinidade usuário→GPU: como garantem que sua próxima requisição chegue no mesmo nó que tem seu cache? Provavelmente sticky routing por sessão, mas não confirmam.
• Tipo de SSD: NVMe? CXL-attached? Os tensores KV de um prompt de 200K tokens ocupam vários GB. A velocidade do SSD importa muito.
• PagedAttention: vLLM (o serving engine open source mais popular) usa uma técnica chamada PagedAttention que gerencia os tensores KV como páginas de memória virtual. A Anthropic usa algo similar, ou tem algo proprietário? Não se sabe.
• Topologia do cluster: quantas GPUs, como estão interconectadas, se usam InfiniBand ou Ethernet. Nada público.

A analogia que resume tudo

Pense no prompt caching como a memória de trabalho de um cirurgião durante uma operação.

O cirurgião (o modelo) tem que processar toda a informação do paciente (o prompt) para decidir cada movimento (o output). Sem cache, teria que reler o histórico médico completo antes de cada corte. Com cache, lembra tudo o que já leu e só precisa processar a informação nova — o último exame, a resposta do tecido ao corte anterior.

O que é guardado não são os documentos do paciente (o texto). São as conclusões intermediárias que o cirurgião já extraiu desses documentos (os tensores KV). Não precisa voltar a ler o exame. Já sabe o que diz. Só precisa integrar o novo com o que já sabe.

Os 99% de cache hit simplesmente refletem que, em uma conversa com um LLM, a quantidade de “o que já sabemos” cresce muito mais rápido que a quantidade de “o novo que há para processar”.

E isso, em termos simples, é o que torna possível ter conversas de 200K tokens de contexto sem que cada mensagem te custe os tubos.

Relacionado: Se você tem interesse no que acontece quando o app que monitora esses tokens se baseia em dados inventados pela própria IA, leia Silent failure: quando sua IA inventa e os testes dizem que tudo está bem. E se quer ver como gerencio os segredos da API sem que o 1Password me peça Touch ID a cada 30 segundos, fadiga de autorização e um cache de 40 linhas.