# Содержимое KV-Cache

## Что такое Prompt Caching?

Когда вы общаетесь с Claude, каждый API-запрос отправляет полный контекст диалога (системный промпт + определения инструментов + история сообщений). Механизм prompt caching от Anthropic кэширует уже вычисленное содержимое префикса на стороне сервера, и если префикс последующих запросов совпадает, результат кэша используется повторно, минуя повторные вычисления, что значительно снижает задержку и стоимость.

В cc-viewer этот механизм называется "KV-Cache", и он соответствует prompt caching на уровне Anthropic API, а не key-value cache в слоях внимания transformer внутри LLM.

## Как работает кэширование

Prompt caching от Anthropic объединяет ключи кэша в фиксированном порядке:

```
Tools → System Prompt → Messages (до точки разрыва кэша)
```

Если этот префикс полностью совпадает с любым запросом в окне TTL, API попадает в кэш (возвращая `cache_read_input_tokens`), а не выполняет повторное вычисление (`cache_creation_input_tokens`).

> **Claude Code не зависит жёстко от атрибута `cache_control`, серверная сторона удаляет часть этих атрибутов, но по-прежнему успешно создаёт кэш, поэтому отсутствие атрибута `cache_control` не означает, что кэширование не работает**
>
> Для специальных клиентов, таких как Claude Code, серверная сторона Anthropic не полностью полагается на атрибут `cache_control` в запросе для определения поведения кэширования. Сервер автоматически выполняет стратегию кэширования для определённых полей (таких как системный промпт, определения инструментов), даже если в запросе явно не указана метка `cache_control`. Поэтому, когда вы не видите этот атрибут в теле запроса, не стоит удивляться — сервер уже выполнил операцию кэширования за кулисами, просто не раскрывая эту информацию клиенту. Это негласное соглашение между Claude Code и Anthropic API.

## Что такое "Текущее содержимое KV-Cache"?

"Текущее содержимое KV-Cache", отображаемое в cc-viewer, извлекается из последнего запроса MainAgent и представляет содержимое, расположенное перед границей кэша (cache breakpoint). Конкретно включает:

- **System Prompt**: Системные инструкции Claude Code, включая основные инструкции агента, правила использования инструментов, инструкции проекта CLAUDE.md, информацию об окружении и т.д.
- **Tools**: Список определений доступных инструментов (таких как Read, Write, Bash, Agent, MCP-инструменты и т.д.)
- **Messages**: Часть истории диалога, которая находится в кэше (обычно более ранние сообщения, до последней метки `cache_control`)

## Зачем просматривать содержимое кэша?

1. **Понимание контекста**: Узнайте, какое содержимое Claude "помнит" в данный момент, помогая вам определить, соответствует ли его поведение ожиданиям
2. **Оптимизация затрат**: При попадании в кэш стоимость намного ниже, чем при пересчёте. Просмотр содержимого кэша помогает понять, почему определённые запросы вызвали перестроение кэша (cache rebuild)
3. **Отладка диалога**: Когда ответ Claude не соответствует ожиданиям, проверка содержимого кэша подтверждает, правильны ли системный промпт и история сообщений
4. **Мониторинг качества контекста**: В процессе отладки, изменения конфигурации или настройки промптов KV-Cache-Text предоставляет централизованное представление, помогая вам быстро подтвердить, не произошла ли деградация основного контекста или загрязнение неожиданным содержимым — без необходимости просматривать исходные сообщения по одному

## Многоуровневая стратегия кэширования

KV-Cache, соответствующий Claude Code, не является единственным. Серверная сторона генерирует отдельные кэши для Tools и System Prompt, независимые от кэша Messages. Преимущество такого дизайна в том, что когда стек messages нарушается (обрезка контекста, изменение сообщений и т.д.) и требуется перестроение, кэши Tools и System Prompt не инвалидируются вместе с ним, что позволяет избежать полного пересчёта.

Это оптимизационная стратегия серверной стороны на текущем этапе — поскольку определения Tools и System Prompt при нормальном использовании относительно стабильны и редко меняются, раздельное кэширование позволяет максимально сократить ненужные затраты на перестроение. Поэтому при наблюдении за Cache вы обнаружите, что помимо перестроения Tools, которое требует полного обновления всех кэшей, нарушение System Prompt и Messages по-прежнему оставляет доступные унаследованные кэши.

## Жизненный цикл кэша

- **Создание**: При первом запросе или после инвалидации кэша API создаёт новый кэш (`cache_creation_input_tokens`)
- **Попадание**: При последующих запросах с идентичным префиксом кэш повторно используется (`cache_read_input_tokens`)
- **Истечение**: Кэш имеет TTL (время жизни) 5 минут и автоматически истекает по окончании этого периода
- **Перестроение**: Когда системный промпт, список инструментов, модель или содержимое сообщений изменяются, ключ кэша не совпадает, вызывая перестроение соответствующего уровня кэша
