Cómo Claude Code utiliza el almacenamiento en caché de prompts

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

El almacenamiento en caché de prompts hace que Claude Code sea más rápido y eficiente en costos. Sin almacenamiento en caché, la API reprocesaría su historial completo en cada turno. Con almacenamiento en caché, reutiliza lo que ya procesó y solo realiza trabajo nuevo para lo que cambió. Claude Code gestiona el almacenamiento en caché de prompts automáticamente, a menos que lo desactive. Aún es útil saber cómo funciona el almacenamiento en caché de prompts, porque algunas acciones invalidan el caché y hacen que la siguiente respuesta sea más lenta y costosa mientras se reconstruye. Esta página cubre qué acciones son esas, por qué algunos ajustes esperan un reinicio para aplicarse, y cómo verificar el rendimiento del caché cuando el uso parece alto.

​

Cómo se organiza el caché

Cada vez que envía un mensaje en Claude Code, realiza una nueva solicitud de API. El modelo no recuerda nada entre solicitudes, por lo que Claude Code reenvía el contexto completo: el prompt del sistema, el contexto de su proyecto, cada mensaje anterior y resultado de herramienta, y su nuevo mensaje. El contenido nuevo se añade al final, lo que significa que la mayoría de cada solicitud es idéntica a la anterior. El almacenamiento en caché de prompts es cómo la API evita reprocesar la parte que no cambió. La API almacena en caché haciendo coincidir el inicio de cada solicitud, llamado el prefijo, con el contenido que procesó recientemente. En un turno normal, el prefijo es la solicitud anterior completa y solo el intercambio más reciente es nuevo. La coincidencia es exacta, por lo que un cambio en cualquier lugar del prefijo recalcula todo después de él. No hay almacenamiento en caché por archivo o por segmento. Vea cómo funciona el almacenamiento en caché de prompts en la referencia de API para el mecanismo subyacente. Para aprovechar al máximo la coincidencia de prefijos, Claude Code ordena cada solicitud para que el contenido que rara vez cambia entre turnos venga primero: Un cambio en la capa de conversación deja el prompt del sistema y el contexto del proyecto en caché. Un cambio en el prompt del sistema invalida todo, porque todo el contenido posterior ahora se encuentra detrás de un prefijo diferente. La tercera columna proporciona desencadenantes comunes en lugar de una lista exhaustiva, y las secciones a continuación cubren el conjunto completo, incluido contenido como el estilo de salida que se fija al inicio de la sesión. La regla de coincidencia de prefijos explica la mayoría de los comportamientos en esta página. Plan mode y skill loading, por ejemplo, añaden sus instrucciones como mensajes de conversación, por lo que el prefijo en caché permanece intacto. Dos ajustes no son parte del texto del prompt en absoluto, por lo que no aparecen en la tabla de capas. Se comportan de manera diferente para el almacenamiento en caché:

• Model: el caché se indexa por modelo, por lo que cada modelo tiene su propio caché. Cambiar de modelo recalcula toda la solicitud incluso cuando el contenido es idéntico. Vea Cambiar de modelo a continuación.
• Effort level: no es parte de la clave de caché ni del prompt, por lo que cambiarla a mitad de sesión no tiene efecto en el caché.

​

Dónde vive el caché

El almacenamiento en caché ocurre del lado del servidor, en cualquier infraestructura que sirva su modelo. Dónde es eso depende de cómo se autentique:

• Clave de API, suscripción de Claude, o Claude Platform on AWS: el caché vive en la infraestructura de Anthropic, accedido a través de la Claude API
• Bedrock o Vertex AI: el caché vive en la infraestructura de servicio de su proveedor de nube
• Foundry: las solicitudes se enrutan a la infraestructura de Anthropic
• ANTHROPIC_BASE_URL personalizado o LLM gateway: el caché vive donde se reenvíen sus solicitudes, y si el almacenamiento en caché funciona depende de la puerta de enlace

Para lo que cada proveedor almacena y procesa, vea data usage. Dondequiera que viva el caché, las entradas expiran después de un período de inactividad, y Cache lifetime a continuación cubre el TTL y cómo extenderlo.

​

Acciones que invalidan el caché

Estas acciones hacen que la siguiente solicitud pierda parte o todo el caché. Verá un turno más lento y costoso de una sola vez, después del cual el nuevo prefijo se almacena en caché. La mayoría de ellas se pueden evitar a mitad de tarea una vez que sabe que tienen un costo. Un cambio de modelo o una reconexión de MCP pueden parecer gratuitos hasta que note el turno más lento que sigue.

• Cambiar de modelo
• Conectar o desconectar un servidor MCP
• Denegar una herramienta completa
• Compactar la conversación
• Actualizar Claude Code

​

Cambiar de modelo

Cada modelo tiene su propio caché. Cambiar con /model significa que la siguiente solicitud lee todo el historial de conversación sin aciertos de caché, aunque el contenido sea idéntico. La configuración de modelo opusplan se resuelve a Opus durante el modo de plan y Sonnet durante la ejecución, por lo que cada alternancia de modo de plan es un cambio de modelo e inicia un caché nuevo.

​

Conectar o desconectar un servidor MCP

Las definiciones de herramientas se encuentran en la capa del prompt del sistema, por lo que el caché se invalida cuando el conjunto de herramientas MCP disponibles para Claude cambia entre turnos. La causa más común es un servidor MCP que se conecta o desconecta a mitad de sesión, lo que puede suceder sin ninguna acción de su parte: el proceso de un servidor stdio sale, una sesión HTTP expira, o un servidor se reconecta automáticamente después de una falla transitoria. Un servidor conectado también puede enviar una actualización de herramienta dinámica que cambia su lista de herramientas. Editar su configuración de MCP no cambia el caché por sí solo. La nueva configuración entra en vigor solo después de un reinicio, que es cuando el servidor se conecta o desconecta. MCP tool search reduce cuánto contribuye cada herramienta al prefijo al diferir definiciones de herramientas completas, pero el conjunto de nombres de herramientas aún tiene que mantenerse estable para que el caché siga siendo válido.

​

Denegar una herramienta completa

Agregar un nombre de herramienta simple como Bash o WebFetch como una regla de denegación elimina esa herramienta del contexto de Claude por completo. Las definiciones de herramientas se encuentran en la capa del prompt del sistema, por lo que agregar o eliminar una de estas reglas a mitad de sesión invalida el caché de la misma manera que un servidor MCP que se conecta o desconecta. El cambio entra en vigor en el siguiente turno, ya sea que lo agregue a través de /permissions o editando un archivo de configuración directamente. Solo un nombre de herramienta simple, o la forma equivalente Bash(*), tiene este efecto. Las reglas de denegación con alcance como Bash(rm *), y todas las reglas de permitir y preguntar, no cambian qué herramientas ve Claude. Claude Code las verifica cuando Claude intenta una llamada, dejando el prefijo intacto.

​

Compactar la conversación

Compaction reemplaza su historial de mensajes con un resumen. Por diseño, esto invalida la capa de conversación, ya que la siguiente solicitud tiene un historial nuevo y más corto que no comparte un prefijo con el anterior. Claude Code reutiliza la capa del prompt del sistema y recarga el contexto del proyecto desde el disco, que solo tiene aciertos de caché si CLAUDE.md y la memoria no han cambiado desde que comenzó la sesión. Para producir el resumen, Claude Code envía una solicitud única con el mismo prompt del sistema, herramientas e historial que su conversación, más una instrucción de resumen añadida como un mensaje de usuario final. Porque comparte su prefijo, esa solicitud lee el caché existente en lugar de reprocesar el historial completo. La mayoría del tiempo de compactación se dedica a generar el resumen, no a una pérdida de caché. El turno que sigue reconstruye el caché de conversación solo para el resumen mucho más corto, por lo que el turno posterior a la compactación no es la parte lenta.

​

Actualizar Claude Code

Una nueva versión de Claude Code típicamente actualiza el prompt del sistema o las definiciones de herramientas, por lo que la primera solicitud después de una actualización reconstruye el caché desde el principio. Auto-update descarga nuevas versiones en segundo plano pero las aplica en el siguiente lanzamiento, nunca a mitad de sesión, por lo que ve esto como un primer turno sin caché después de reiniciar en lugar de una sorpresa durante una sesión. Establezca DISABLE_AUTOUPDATER=1 para controlar cuándo se aplican las actualizaciones.

​

Acciones que mantienen el caché

Estas acciones ya sea se añaden al final de la conversación o no tocan la solicitud en absoluto. Algunas de ellas, como editar CLAUDE.md o cambiar el estilo de salida, también son por qué un cambio de ajuste espera un reinicio para aplicarse.

• Editar archivos en su repositorio
• Editar CLAUDE.md a mitad de sesión
• Cambiar el estilo de salida
• Cambiar el modo de permiso
• Invocar skills y comandos
• Ejecutar /recap
• Rewind de la conversación
• Generar un subagente

​

Editar archivos en su repositorio

El contenido del archivo entra en contexto solo cuando Claude lo lee, y las lecturas se añaden a la conversación. Editar un archivo que Claude leyó anteriormente no cambia retroactivamente la lectura anterior en el historial. En su lugar, Claude Code añade un <system-reminder> notando que el archivo cambió, y Claude lo relee si es necesario.

​

Editar CLAUDE.md a mitad de sesión

Sus archivos CLAUDE.md de raíz de proyecto y nivel de usuario se leen una vez al inicio de la sesión y se mantienen en memoria. Editarlos a mitad de sesión no invalida el caché, pero la edición tampoco se aplica. Claude continúa trabajando con la versión que se cargó al inicio de la sesión. El nuevo contenido se carga en el siguiente /clear, /compact, o reinicio. Archivos CLAUDE.md anidados en subdirectorios y reglas con frontmatter paths: se cargan más tarde, cuando Claude lee por primera vez un archivo coincidente. Editar uno antes de que se cargue sí tiene efecto. Después de que se carga, el contenido es parte del historial de conversación, por lo que una edición a mitad de sesión no lo cambia retroactivamente.

​

Cambiar el estilo de salida

Output style es parte del prompt del sistema, que Claude Code lee una vez al inicio de la sesión. Cambiarlo a través de /config o la configuración outputStyle a mitad de sesión no invalida el caché, pero el cambio tampoco se aplica. Claude continúa usando el estilo que se cargó al inicio de la sesión. El nuevo estilo se carga en el siguiente /clear o reinicio.

​

Cambiar el modo de permiso

Cambiar entre permission modes, como de predeterminado a aceptar ediciones, no cambia el prompt del sistema o las definiciones de herramientas, por lo que los cambios de modo son seguros para el caché. La excepción es el modo de plan con la configuración de modelo opusplan, que cambia el modelo entre Opus y Sonnet cuando entra o sale del modo de plan. Eso hace que el cambio de modo sea un cambio de modelo.

​

Invocar skills y comandos

Skills y commands inyectan sus instrucciones como mensajes de usuario en el punto de invocación. Nada anterior en la conversación cambia.

​

Ejecutar /recap

/recap genera un resumen para mostrar en su terminal. A diferencia de /compact, añade el resumen como salida de comando en lugar de reemplazar su historial de mensajes, por lo que el prefijo en caché permanece intacto.

​

Rewind de la conversación

/rewind trunca su conversación de vuelta a un turno anterior. El historial restante es el mismo contenido del que se construyó el caché en ese punto, y las capas del prompt del sistema y contexto del proyecto no cambian, por lo que la siguiente solicitud acierta la entrada de caché anterior. Cada turno desde entonces ha leído a través de ese prefijo, que mantuvo la entrada activa incluso si el turno original fue hace más tiempo que el TTL. Restaurar puntos de control de archivo junto con la conversación no tiene efecto separado en el caché. El contenido del archivo entra en contexto solo cuando Claude lo lee, igual que editar archivos en su repositorio.

​

Duración del caché

Los prefijos en caché expiran después de un período de inactividad. Cada solicitud que acierta el caché reinicia el temporizador, por lo que el caché permanece activo mientras continúe trabajando. Después de una brecha lo suficientemente larga, la siguiente solicitud recalcula la entrada completa y restablece el caché, que es por qué el primer turno después de alejarse puede ser notablemente más lento. El tiempo de vida (TTL) controla cuánto tiempo la brecha el caché sobrevive. La API ofrece dos: un TTL de cinco minutos, y un TTL de una hora que mantiene el caché activo a través de descansos más largos pero factura escrituras de caché a una tasa más alta. Claude Code elige el TTL para usted según cómo se autentique, y puede anularlo con variables de entorno.

​

En una suscripción de Claude

En una suscripción de Claude, Claude Code solicita automáticamente el TTL de una hora. El uso se incluye en su plan en lugar de facturarse por token, por lo que el TTL más largo no le cuesta nada extra y solo afecta cuánto tiempo su caché permanece activo. Si ha superado el límite de uso de su plan y Claude Code está utilizando créditos de uso, se le factura por ese uso, por lo que Claude Code automáticamente reduce el TTL a cinco minutos.

​

En una clave de API o proveedor de terceros

En una clave de API, Bedrock, Vertex, Foundry, o Claude Platform on AWS, paga las tasas por token, por lo que el TTL permanece en los cinco minutos más baratos por defecto. Para optar por el TTL de una hora, establezca ENABLE_PROMPT_CACHING_1H=1. En Bedrock, el soporte de almacenamiento en caché de prompts, la longitud mínima de prefijo almacenable en caché, y la disponibilidad de TTL de una hora varían según el modelo. Si los recuentos de tokens de caché permanecen en cero, verifique modelos soportados, regiones y límites en la documentación de Bedrock.

​

Anular el TTL

Establezca FORCE_PROMPT_CACHING_5M=1 para forzar el TTL de cinco minutos independientemente de la autenticación. Esto es útil cuando está depurando el comportamiento del caché, comparando los dos TTL, o anulando un ENABLE_PROMPT_CACHING_1H establecido en managed settings.

​

Alcance del caché

En Claude Code, el caché está efectivamente limitado a una máquina y directorio. El prompt del sistema incorpora el directorio de trabajo, plataforma, shell, versión del SO, y rutas de memoria automática, por lo que dos sesiones en directorios diferentes construyen prefijos diferentes y se pierden el caché del otro. Eso incluye worktrees del mismo repositorio, ya que cada worktree tiene su propio directorio de trabajo. Las sesiones que ejecuta en paralelo en el mismo directorio construyen prefijos coincidentes y leen el caché del otro. Las sesiones secuenciales comparten el prefijo solo cuando la instantánea de estado de git al inicio coincide, ya que el prompt del sistema también captura rama y commits recientes. El caché de API subyacente es más amplio. Los cachés están aislados entre organizaciones, y en algunos proveedores, entre espacios de trabajo dentro de una organización. Dentro de esos límites, cualquier dos solicitudes con el mismo modelo y prefijo leen el mismo caché. Para llamadores de Agent SDK que ejecutan flotas de procesos automatizados, vea mejorar el almacenamiento en caché de prompts entre usuarios y máquinas para suprimir las secciones por máquina del prompt del sistema y compartir el caché entre máquinas.

​

Verificar el rendimiento del caché

El rendimiento del caché se muestra como dos recuentos de tokens que la API reporta en cada respuesta. La forma más directa de verlos en vivo es un script de statusline que lee el objeto current_usage: Una alta relación de lectura a creación significa que el almacenamiento en caché está funcionando bien. Si la creación permanece alta turno tras turno, algo está cambiando en su prefijo. La sección acciones que invalidan el caché enumera las causas usuales. Para visibilidad en toda una organización, el exportador de OpenTelemetry reporta tokens de lectura y creación de caché por usuario y sesión. Vea Monitor usage para la referencia de métrica y atributo de evento.

​

Subagentes y el caché

Un subagent inicia su propia conversación con su propio prompt del sistema y conjunto de herramientas, separado del padre. Construye su propio caché, comenzando sin aciertos de caché en su primera llamada y calentándose a través de sus propios turnos. Los subagentes usan el TTL de cinco minutos incluso en una suscripción, ya que el TTL automático de una hora se aplica a la conversación principal. El caché del padre no se ve afectado. Desde el lado del padre, la llamada y resultado del subagente se añaden a la conversación, dejando el prefijo del padre intacto. Un fork, por el contrario, hereda el prompt del sistema del padre, herramientas e historial de conversación exactamente, por lo que su primera solicitud lee el caché del padre. La llamada de resumen de compactación descrita en Compactar la conversación usa el mismo enfoque de compartir prefijo.

​

Desactivar el almacenamiento en caché de prompts

Desactivar el almacenamiento en caché es ocasionalmente útil cuando se depura el comportamiento del almacenamiento en caché con un modelo o proveedor específico. Para desactivarlo, establezca una de estas variables de entorno a 1: Para establecer la política de almacenamiento en caché en toda una organización, coloque cualquiera de estas o las variables de TTL en el bloque env de managed settings. Para uso normal, deje el almacenamiento en caché habilitado.

​

Recursos relacionados

• Lecciones de construir Claude Code: El almacenamiento en caché de prompts lo es todo: la justificación del diseño para el modo de plan, carga de herramientas diferida, y compactación
• Explorar la ventana de contexto: qué se carga en contexto y cuándo
• Reducir el uso de tokens: estrategias más allá del almacenamiento en caché para gestionar el tamaño del contexto
• Rastrear y reducir costos: seguimiento de tokens de caché y configuración de TTL para llamadores de Agent SDK
• Almacenamiento en caché de prompts: el mecanismo de API subyacente, puntos de interrupción, y precios