トークンキャッシュとは、多くのモデルプロバイダが提供している仕組みで、キャッシュされた入力トークン——短い期間内にすでに処理された共通のトークンプレフィックス——に対して割安な料金を課すものである。基盤となるインフラが、それらを生み出した高コストな計算の多くをキャッシュして再利用できることがその理由である。最初の出典の説明に従えば、これはモデルに何ができるかの問題ではなく、変化していないプレフィックスにどのような料金が課されるかの問題である。
用法
これがコーディングエージェントにとって重要なのは、チャットテンプレート形式のプロンプト の仕組みから来ている。モデルはステートレスなので、その周囲のソフトウェアはターンごとに会話全体を再送し、セッションが長くなるにつれて入力は増えていく。トークンキャッシュはその増加分の一部を相殺する——ただし、変化していないプレフィックスに限られる。設計上の帰結は最初の出典に明言されている。コーディングエージェントはこの最適化を念頭に置いて作られており、キャッシュをできるだけ効率よく使えるよう、会話の前の部分の内容を変更することを避けている。
この制約が注目に値するのは、出典が設計上の圧力としてはっきり述べながら、それがどう解決されるかについては何も語っていないからである。キャッシュの効率的な利用と、会話の前の部分の書き換えとは互いに相反しており、出典が説明するエージェントは書き換えないことによってそれを解決している。
Claude Code のトークン節約ガイド：1M コンテキストは慎重に使え、新しいセッションを開かないのも常に開くのも正しくない は、あるエージェントについてこの仕組みが実際にどれだけのコストをもたらすかを詳しく検討している。同記事はキャッシュに二つの条件があると説明する。一つ目は、マッチングがプレフィックスのみ、かつ完全一致であることである。一致は入力の先頭から続いていなければならないため、前の方で何かを変えるとそれ以降がすべて無効になる一方、末尾への追記であればそれまでのプレフィックス全体が有効なまま残る。同記事が、入力は変化しない素材を先に置く順序——システム指示とツール定義、次に会話履歴、そして新しいメッセージ——で並べられると述べるのはそのためである。二つ目は、キャッシュされたエントリが失効することである。同記事はその期間をメインエージェントで 1 時間、サブエージェントで 5 分としており、ヒットのたびにタイマーがリセットされるため、一定のリズムを保った対話であればキャッシュを無期限に維持できる。また、キャッシュの読み出しコストは再計算のおよそ 10 分の 1 であること、そしてキャッシュはモデルごとに分離されているため、セッションの途中でモデルを切り替えると新しいキャッシュが一から始まることも報告している。
適用される場面
二つ目の出典が導く実践上の帰結は、キャッシュミスのコストがコンテキストの長さに比例して大きくなるということであり、これはコスト節約に関するいくつかの直感を覆す。セッションをクリアして新しく始めるほうが安く感じられるが、それはキャッシュされたプレフィックス——同記事によれば Claude Code の場合、システムプロンプト、ツール定義、プロジェクト設定でおよそ 50,000 トークン——を捨て、それを再構築するために正規の料金を払うことになる。同じ理屈で、非常に大きなコンテキストウィンドウは、トークンあたりの価格が小さいものと同じであっても無料ではない。1M トークンのキャッシュを取り逃すことは、200K のキャッシュを取り逃すよりはるかに大きな請求になる。同記事の推奨はここから直接導かれる。キャッシュが温まっている間はアクティブなセッションを続け、新しいセッションを始めるのは、タスクが変わったとき、キャッシュが失効したとき、あるいはコンテキストが目下の作業と無関係な素材で埋まったときに限った条件付きの手段として扱う、というものである。
これがどの程度確立しているかは、二つの半分で異なる。変化していないプレフィックスがより安く課金されることは、両方の出典が前提として扱う、文書化されたプロバイダの挙動である。一方、具体的な数値——10 倍の比率、1 時間と 5 分の期間、50,000 トークンという下限——は、一人の実務者の記事がベンダーの発言やコミュニティの報告を伝えたものであって、同記事自身が行った測定に基づくものではない。また同記事自体も、ユーザーが報告していた消費の挙動についてベンダーがまだ調査中であったことに触れている。
三つ目の出典は、同じ仕組みが逆方向から破綻する様子を示しており、そこではキャッシュミスはコスト上の判断ではなく症状として現れる。最近の Claude Code の品質に関する報告についての最新情報 は、すでに起きた退避を利用するつもりだった Claude Code のある最適化について説明している。1 時間以上アイドル状態だったセッションはいずれにせよキャッシュミスになるので、そこから古い思考を一度だけ消去すれば、再開時に送られるキャッシュされないトークンを減らせる、というものだった。ところがバグにより、その後のセッションではターンごとに履歴が消去されるようになり、各リクエストが直前のリクエストに含まれていた思考ブロックを落とすため、プレフィックスが変わり続け、リクエストはミスし続けた。Anthropic は、利用上限が想定より早く減っていくという別個のユーザー報告について、これが最も有力な説明だとしている。
これが上の説明に付け加えるのは、プレフィックスの安定性が、ハーネスが追求することを選ぶ課金上の最適化にとどまらず、他の変更によって気づかれないうちに壊されうる性質でもあるという点である。上で述べたプレフィックスのみの完全一致というマッチングこそが、前の部分の内容をターンごとに変更することを、ターンごとの正規料金での再構築に変えてしまう。そしてそのコストは、レイテンシの退行とは違って目に見えない。エージェントは動き続け、ユーザーが最初に気づいたのは消費量だった。
関連用語
チャットテンプレート形式のプロンプト, コンパクション, コンテキストロット, コンテキストリセット, サブエージェントアーキテクチャ