# Вміст кешу KV-Cache

## Що таке Prompt Caching?

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

У cc-viewer цей механізм називається "KV-Cache" і відповідає prompt caching на рівні Anthropic API, а не key-value кешу в шарах уваги трансформера всередині LLM.

## Як працює кеш

Prompt caching від Anthropic об'єднує ключі кешу у фіксованому порядку:

```
Tools → System Prompt → Messages (до cache breakpoint)
```

Поки цей префікс повністю ідентичний будь-якому запиту у вікні TTL, API влучає в кеш (повертає `cache_read_input_tokens`), а не перераховує (`cache_creation_input_tokens`).

> **Claude Code не є сильно залежним від атрибута `cache_control` — сервер видаляє деякі з цих атрибутів, але все одно добре створює кеш, тому відсутність атрибута `cache_control` не означає, що вміст не кешується**
>
> Для спеціальних клієнтів на кшталт Claude Code сервер Anthropic не повністю залежить від атрибута `cache_control` у запиті для визначення поведінки кешу. Сервер автоматично застосовує стратегії кешування для певних полів (таких як system prompt і визначення інструментів), навіть коли запит явно не містить маркерів `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 не відповідає очікуванням, перевірка вмісту кешу дозволяє підтвердити, чи system prompt та історія повідомлень правильні
4. **Моніторинг якості контексту**: Під час налагодження, зміни конфігурації або коригування промптів, KV-Cache-Text забезпечує централізовану перспективу, яка допомагає швидко підтвердити, чи основний контекст не погіршився або не був забруднений неочікуваним вмістом — без необхідності переглядати оригінальні повідомлення одне за одним

## Багаторівнева стратегія кешування

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

Це стратегія оптимізації на стороні сервера — оскільки визначення Tools та System Prompt відносно стабільні під час звичайного використання і рідко змінюються, окреме кешування їх максимізує зменшення непотрібних витрат на перебудову. Тому, спостерігаючи за кешем, ви помітите, що окрім перебудови Tools, яка потребує повного оновлення всіх кешів, руйнування System Prompt та Messages все ще дозволяє успадковувати доступні кеші.

## Життєвий цикл кешу

- **Створення**: При першому запиті або після закінчення терміну дії кешу, API створює новий кеш (`cache_creation_input_tokens`)
- **Влучення**: Наступні запити з ідентичним префіксом повторно використовують кеш (`cache_read_input_tokens`)
- **Закінчення**: Кеш має TTL (час життя) 5 хвилин і автоматично закінчується після цього часу
- **Перебудова**: Коли system prompt, список інструментів, модель або вміст повідомлень змінюються, ключ кешу не збігається, що спричиняє перебудову відповідного рівня
