# KV-Cache キャッシュ内容

## Prompt Caching とは？

Claude と会話するとき、API リクエストごとに完全な会話コンテキスト（system prompt + ツール定義 + 過去のメッセージ）が送信されます。Anthropic の prompt caching メカニズムは、既に計算済みのプレフィックス内容をサーバー側にキャッシュし、後続のリクエストでプレフィックスが一致する場合、キャッシュ結果を直接再利用して重複計算をスキップし、レイテンシーとコストを大幅に削減します。

cc-viewer ではこのメカニズムを「KV-Cache」と呼んでいますが、これは Anthropic API レベルの prompt caching に対応するものであり、LLM 内部の transformer アテンション層の key-value cache ではありません。

## キャッシュの動作原理

Anthropic の prompt caching は固定順序でキャッシュキーを連結します：

```
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` 属性だけに完全に依存してキャッシュ動作を決定しているわけではありません。サーバー側は特定のフィールド（system prompt、tools 定義など）に対して自動的にキャッシュポリシーを実行しており、リクエストに `cache_control` マークが明示的に含まれていなくても同様です。そのため、リクエストボディにこの属性が見当たらなくても不思議に思う必要はありません——サーバー側は裏側でキャッシュ操作を完了していますが、この情報をクライアントに公開していないだけです。これは Claude Code と Anthropic API の間の暗黙の了解です。

## 「現在の KV-Cache キャッシュ内容」とは？

cc-viewer に表示される「現在の KV-Cache キャッシュ内容」は、最新の MainAgent リクエストから抽出された、キャッシュ境界（cache breakpoint）より前の内容です。具体的には以下を含みます：

- **System Prompt**：Claude Code のシステム指示。コア agent 指示、ツール使用規範、CLAUDE.md プロジェクト指示、環境情報などを含む
- **Tools**：現在利用可能なツール定義リスト（Read、Write、Bash、Agent、MCP ツールなど）
- **Messages**：会話履歴でキャッシュされた部分（通常は初期のメッセージで、最後の `cache_control` マークまで）

## キャッシュ内容を確認する理由

1. **コンテキストの理解**：Claude が現在「記憶している」内容を把握し、その動作が期待通りかどうかを判断するのに役立つ
2. **コスト最適化**：キャッシュヒット時のコストは再計算より大幅に低い。キャッシュ内容を確認することで、特定のリクエストがキャッシュ再構築（cache rebuild）をトリガーした理由を理解できる
3. **会話のデバッグ**：Claude の回答が期待と異なる場合、キャッシュ内容を確認して system prompt と過去のメッセージが正しいかを確認できる
4. **コンテキスト品質監視**：デバッグ、設定変更、prompt 調整の過程で、KV-Cache-Text は集約されたビューを提供し、コアコンテキストが劣化していないか、予期しない内容で汚染されていないかを素早く確認できる——元のメッセージを1つずつ確認する必要はない

## マルチレベルキャッシュ戦略

Claude Code に対応する KV-Cache は1つだけではありません。サーバー側は 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`）
- **期限切れ**：キャッシュは 5 分の TTL（存続時間）を持ち、タイムアウト後は自動的に無効化
- **再構築**：system prompt、ツールリスト、モデル、またはメッセージの内容が変更されると、キャッシュキーが一致せず、対応するレベルのキャッシュ再構築がトリガーされる
