Estoy construyendo una app que monitoriza mi consumo de tokens en Claude Code. Hace unos días, mirando los números en crudo, me encontré con esto:
cacheReadInputTokens: 4.241.579.174
inputTokens: 1.293.019
Cuatro mil doscientos millones de tokens leídos de caché. Un millón trescientos mil tokens «frescos». Eso es un 99,97% de cache hit.
Mi primera reacción fue pensar que algo estaba roto. Nadie tiene un 99% de caché. Ni Redis. Ni Cloudflare. Ni tu madre cuando te dice que ya sabe lo que le vas a pedir de comer.
Pero resulta que no está roto. Es exactamente así como funciona. Y el motivo es tan elegante como contraintuitivo.
Lo que se cachea no es texto
Aquí es donde la mayoría de explicaciones se quedan cortas. Cuando lees «prompt caching» piensas en algo tipo Redis: guardas la pregunta, guardas la respuesta, si alguien hace la misma pregunta le devuelves la misma respuesta.
De eso nada, monada.
Lo que se cachea son tensores KV — las matrices Key y Value que el transformer calcula durante la fase de prefill. Dicho en cristiano: cuando un LLM recibe tu prompt, lo primero que hace es convertir todo ese texto en representaciones numéricas internas (los embeddings) y multiplicarlos por matrices de pesos para obtener las «claves» (K) y «valores» (V) que el mecanismo de atención necesita para generar la respuesta.
Ese cálculo es carísimo. En un prompt de 200.000 tokens (algo normal en Claude Code, donde el historial de conversación se acumula), estamos hablando de miles de millones de operaciones de multiplicación de matrices. Es la parte que más GPU consume, la que más tarda, la que más cuesta.
Y aquí está la gracia: entre un mensaje tuyo y el siguiente, el 99% de ese prompt no cambia. El system prompt es idéntico. El historial de conversación previo es idéntico. Los ficheros que leyó son los mismos. Lo único nuevo es tu último mensaje.
¿Para qué recalcular lo que ya calculaste hace 30 segundos?
Cómo funciona el matching
No basta con cachear. Hay que saber cuándo la caché sirve. Y aquí Anthropic usa un truco elegante: hashing acumulativo por prefijo.
Cada bloque del prompt (system, tools, mensajes) genera un hash. Pero no un hash individual: un hash acumulativo. El hash del bloque 3 incluye el contenido de los bloques 1, 2 y 3. Si cualquier cosa cambia en un bloque anterior, el hash de todos los bloques siguientes cambia también.
Cuando llega una petición nueva, el sistema busca hacia atrás desde el punto marcado con cache_control, comparando hashes bloque a bloque, hasta encontrar el prefijo más largo que coincide. Todo lo que coincide → se lee de caché. Solo lo nuevo → se calcula.
Es como una película que ya has visto 40 veces. No necesitas verla entera para saber qué pasa. Solo necesitas ver desde el punto donde difiere de lo que recuerdas.
Ojo al dato: el sistema solo revisa hasta 20 bloques hacia atrás. Más allá de eso, deja de buscar. Esto es una decisión práctica para no gastar más tiempo buscando en la caché que calculando los tensores directamente.
Por qué Claude Code tiene un 99% de cache hit
Ahora que sabes cómo funciona el matching, el 99% deja de ser misterioso. Mira lo que pasa en una sesión típica de Claude Code:
Mensaje 1 (el primero de la sesión):
System prompt (8K tokens) + Tools (2K tokens) + Tu mensaje (500 tokens)
= 10.500 tokens → TODO se calcula, TODO se escribe en caché
Mensaje 2:
System prompt (8K) + Tools (2K) + Mensaje 1 (500) + Respuesta 1 (3K) + Tu mensaje 2 (500)
= 14.000 tokens
→ Los primeros 10.500 → CACHE HIT (ya los calculamos antes)
→ Los 3.500 nuevos → se calculan y se añaden a la caché
Cache hit: 75%
Mensaje 10:
System prompt + Tools + 9 mensajes + 9 respuestas + Tu mensaje 10
= ~150.000 tokens
→ Los primeros ~149.500 → CACHE HIT
→ Los ~500 nuevos → se calculan
Cache hit: 99,7%
¿Lo ves? El historial de conversación solo crece. Cada mensaje nuevo es una fracción diminuta del total acumulado. El ratio de caché converge al 99% con la certeza de un logaritmo neperiano.
No es magia. Es geometría: el numerador (tokens nuevos) crece linealmente; el denominador (tokens acumulados) también, pero lleva una ventaja enorme.
Dónde viven esos tensores
Aquí es donde la cosa se pone bonita. Porque cachear tensores KV no es como cachear strings en Redis. Estamos hablando de gigas de datos numéricos que tienen que estar disponibles con latencia de microsegundos.
Anthropic usa un sistema de dos niveles:
Nivel 1: VRAM (5 minutos de TTL)
Los tensores viven directamente en la memoria de la GPU que va a servir la siguiente petición. Zero copia, zero latencia de red. El cache hit es casi instantáneo porque los datos ya están donde se necesitan.
TTL: 5 minutos. Si nadie hace una petición en 5 minutos, se eviccionan. Este es el cache que usas con la API estándar. Precio del cache write: 1,25x el precio de input normal.
Nivel 2: SSD del nodo GPU (1 hora de TTL)
Si pagas el cache write extendido (2x el precio de input), los tensores no se eviccionan a los 5 minutos. En su lugar, cuando salen de VRAM por presión de memoria, se descargan al SSD local del nodo GPU.
Cuando llega un cache hit, se recargan del SSD a VRAM. Más lento que el nivel 1, pero infinitamente más rápido que recalcular los tensores desde cero.
Lo interesante de esto: no hay red de por medio. No es un Redis remoto. No es un S3. Es un SSD pegado físicamente al servidor que tiene la GPU. La arquitectura está diseñada para minimizar movimiento de datos.
Petición → ¿En VRAM? → Sí → Cache hit instantáneo
→ No → ¿En SSD local? → Sí → Cargar a VRAM → Cache hit (~ms)
→ No → Calcular tensores KV → Cache miss
Desde febrero de 2026, el aislamiento es por workspace (antes era por organización). Esto significa que los tensores de tu equipo de desarrollo no se mezclan con los del equipo de marketing, incluso si están en la misma organización de Anthropic.
Los números
Si estás evaluando si esto importa para tu caso de uso, aquí van los datos duros:
| Concepto | Valor |
|---|---|
| Cache read | 0,1x del precio de input (90% descuento) |
| Cache write 5 min | 1,25x del precio de input |
| Cache write 1 hora | 2x del precio de input |
| Reducción de latencia | ~85% en prompts largos |
| Mínimo cacheable | 1.024 tokens por checkpoint |
Con Sonnet, el input cuesta $3,00/M tokens. Un cache read cuesta $0,30/M. En una sesión de Claude Code con 200K tokens de historial, la diferencia entre recalcular y leer de caché es la diferencia entre $0,60 y $0,06 por mensaje.
Multiplica eso por los cientos de mensajes que puedes cruzar en una sesión larga y se entiende por qué Anthropic invirtió en construir esto: sin prompt caching, las conversaciones largas con contexto enorme serían económicamente inviables.
Mis datos reales
Vuelvo a mis números del principio. En mi uso de Claude Code a lo largo de un mes:
cacheReadInputTokens: 4.241.579.174 (4,2 mil millones — leídos de caché)
cacheCreationInputTokens: 196.596.243 (197 millones — escritos en caché)
inputTokens: 1.293.019 (1,3 millones — calculados sin caché)
outputTokens: 2.517.666 (2,5 millones — generados por el modelo)
Cache hit rate global: 95,5%. Y dentro de sesiones individuales largas, supera el 99% fácilmente.
Fíjate en la asimetría: he leído 4,2 mil millones de tokens de caché, pero el modelo solo ha generado 2,5 millones de tokens de output. El ratio de lectura-de-caché a trabajo-real es de 1.685:1. Por cada token que el modelo produce, reutiliza 1.685 tokens de contexto previo.
Eso también significa que cacheReadInputTokens no es una buena métrica de productividad. No mide cuánto has «usado» el modelo. Mide cuánto historial ha relído el modelo. Es como medir tu productividad por cuántas veces has abierto el mismo fichero en tu editor.
Lo que Anthropic no cuenta
Hay cosas que no son públicas:
- Afinidad usuario→GPU: ¿cómo garantizan que tu siguiente petición aterrice en el mismo nodo que tiene tu caché? Probablemente sticky routing por sesión, pero no lo confirman.
- Tipo de SSD: ¿NVMe? ¿CXL-attached? Los tensores KV de un prompt de 200K tokens ocupan varios GB. La velocidad del SSD importa mucho.
- PagedAttention: vLLM (el serving engine open source más popular) usa una técnica llamada PagedAttention que gestiona los tensores KV como páginas de memoria virtual. ¿Usa Anthropic algo similar, o tienen algo propietario? No se sabe.
- Topología del clúster: cuántas GPUs, cómo están interconectadas, si usan InfiniBand o Ethernet. Nada público.
La analogía que lo resume todo
Piensa en el prompt caching como la memoria de trabajo de un cirujano durante una operación.
El cirujano (el modelo) tiene que procesar toda la información del paciente (el prompt) para decidir cada movimiento (el output). Sin caché, tendría que releer el historial médico completo antes de cada corte. Con caché, recuerda todo lo que ya leyó y solo necesita procesar la información nueva — la última analítica, la respuesta del tejido al corte anterior.
Lo que se guarda no son los documentos del paciente (el texto). Son las conclusiones intermedias que el cirujano ya extrajo de esos documentos (los tensores KV). No necesita volver a leer la analítica. Ya sabe lo que dice. Solo necesita integrar lo nuevo con lo que ya sabe.
El 99% de cache hit simplemente refleja que, en una conversación con un LLM, la cantidad de «lo que ya sabemos» crece mucho más rápido que la cantidad de «lo nuevo que hay que procesar».
Y eso, dicho en cristiano, es lo que hace posible que tengas conversaciones de 200K tokens de contexto sin que cada mensaje te cueste un riñón y parte del otro.
Relacionado: Si te interesa qué pasa cuando la app que monitoriza esos tokens se basa en datos inventados por la propia IA, lee Silent failure: cuando tu IA inventa y los tests dicen que todo va bien. Y si quieres ver cómo gestiono los secretos de la API sin que 1Password me pida Touch ID cada 30 segundos, fatiga de autorización y un cache de 40 líneas.
Read this article in English.
