token-saver-context-compression

トークン節約コンテキスト圧縮

根拠のある証拠を保持しながら、トークン使用量を削減するためにこのスキルを使用します。以下を統合します。

• pnpm search:code（ハイブリッド検索）
• token-saver Python 圧縮スクリプト
• MemoryRecord のフレームワークメモリへの永続化
• spawn プロンプトへの証拠の注入（[mem:*] / [rag:*]）

起動方法

token-saver スキルは、次の 2 つの方法で起動できます。

手動での起動（常に利用可能）

Skill({ skill: 'token-saver-context-compression' });

コンテキストの逼迫が激しい場合、pnpm search:tokens でファイル／ディレクトリが 32K トークンを超えている場合、またはクエリに合わせた圧縮が必要な場合に使用します。

compression-reminder.txt による自動適用（AUTO_COMPRESSION_PHASE_3=1 が必要）

.env に AUTO_COMPRESSION_PHASE_3=1 を設定して、compression-reminder.txt トリガーを有効にします。

# In .env
AUTO_COMPRESSION_PHASE_3=1

有効にすると、圧縮イベントが発生するたびに compression-trigger.cjs が .claude/context/runtime/compression-reminder.txt を書き込みます。ルーターはこのファイルを読み取り、context-compressor を自動的に起動します。

この環境変数が設定されていない場合：圧縮イベントは .claude/context/compression-stats.jsonl に記録されますが、compression-reminder.txt は書き込まれないため、ルーターは圧縮を自動起動しません。スキルを手動で起動する必要があります。

ルーターが適用するトークンしきい値（CLAUDE.md のセクション 8 より）：

• 80K トークン — 先行して context-compressor を起動します
• 120K トークン — 新たな起動の前に圧縮が必須です
• 150K トークン — 圧縮が完了するまで、新たなエージェントを起動しません

注：これらのしきい値は、CLAUDE.md のセクション 8 で確認するルーターの動作ガイドラインです。compression-trigger.cjs のトリガーは、別個のヒューリスティック（予算の 90% 超過、読み取りが 10KB 超、取得が 5KB 超、10 操作ごとの定期実行）です。80K／120K／150K のしきい値を適用する自動フックはありません。これらは、ルーターが compression-reminder.txt を読み取ることを前提としています。

使用するタイミング

• pnpm search:tokens でファイル／ディレクトリが 32K トークンを超えている場合
• コンテキストが大きい、またはコストが高く、圧縮した要約が必要な場合
• 統合前にクエリに合わせた圧縮が必要な場合
• メモリを永続化する前に、証拠が十分かどうかを厳密に判定する必要がある場合
• プロンプトを作成していて、search:code の検索結果だけではコンテキストが不十分な場合

鉄則

サブプロセスから圧縮した内容をメモリファイルに直接永続化してはいけません。 MemoryRecord ペイロードを出力し、同期／インデックス作成はフレームワークのフックに任せてください。

ワークフロー

1. 候補となるコンテキストを取得します（pnpm search:code "<query>"）。

ステップ 0.5：実際のトークン使用量とコストを確認する（ccusage-adapter）

圧縮する前に、ccusage-adapter を使って今日の実際の API トークン使用量とコストを取得します。 これにより、データに基づいて圧縮の判断を行い、正確なコスト削減額を報告できます。

// Attempt to read actual token usage (graceful degradation — never blocks compression)
let usageData = null;
let costs = null;
try {
  const ccusage = require('.claude/lib/utils/ccusage-adapter.cjs');
  usageData = ccusage.getTodayTotals();
  if (usageData) {
    costs = ccusage.calculateCost(usageData, process.env.CCUSAGE_MODEL || 'opus');
  }
} catch (_err) {
  // ccusage not installed or unavailable — fall back to heuristic estimation
}

if (usageData && costs) {
  console.log('[token-saver] Usage today:', {
    total: usageData.inputTokens + usageData.outputTokens,
    cost: `$${costs.actualCost.toFixed(4)}`,
    cacheSaved: `$${costs.cacheSavings.toFixed(4)}`,
  });

  // Use actual counts to decide compression aggressiveness
  const totalTokens = usageData.inputTokens + usageData.outputTokens;
  if (totalTokens > 120_000) {
    console.log('[token-saver] HIGH pressure (>120K tokens) — aggressive compression mode');
  } else if (totalTokens > 80_000) {
    console.log('[token-saver] MODERATE pressure (>80K tokens) — standard compression mode');
  } else {
    console.log('[token-saver] LOW pressure (<80K tokens) — light compression');
  }
} else {
  // ccusage unavailable — fall through to heuristic estimation from compression-trigger.cjs
  console.log('[token-saver] ccusage unavailable — using heuristic token estimation');
}

フォールバック動作：getTodayTotals() が null を返した場合（ccusage が未インストール、タイムアウト、または CCUSAGE_DISABLED=1）、既存の compression-trigger.cjs のヒューリスティックしきい値を使用してワークフローを続行します。このステップが圧縮を妨げることはありません。

ステータスファイル：ccusage-statusline フックは、各プロンプトでライブステータスを .claude/context/runtime/ccusage-status.txt に書き込みます。アダプターを直接呼び出さずに、人が読みやすい概要をすばやく確認するには、このファイルを読み取ってください。

料金表

正式な参照元 — これらの料金は ccusage-adapter.cjs → calculateCost() で使用されます。 skill-updater がこのスキルを更新する際は、Exa 検索でこれらの値を確認し、この表と .claude/lib/utils/ccusage-adapter.cjs の PRICING の両方を更新する必要があります。

最終確認日：2026年3月（情報源：Silicon Data、IntuitionLabs、DevTk.AI）

モデル	入力	出力	キャッシュ書き込み（入力の1.25倍）	キャッシュ読み取り（入力の0.10倍）
opus → Claude Opus 4.6	$5.00/M	$25.00/M	$6.25/M	$0.50/M
sonnet → Claude Sonnet 4.6	$3.00/M	$15.00/M	$3.75/M	$0.30/M
haiku → Claude Haiku 4.5	$1.00/M	$5.00/M	$1.25/M	$0.10/M

キャッシュ料金のルール（Anthropic 標準）：

• キャッシュ書き込み = 基本入力料金の1.25倍（プレフィックスの保存に25％の割増料金）
• キャッシュ読み取り = 基本入力料金の0.10倍（コンテキストの再利用時に90％割引）

使用中のモデルに合わせるには、CCUSAGE_MODEL=sonnet または CCUSAGE_MODEL=haiku を設定します。 デフォルトは opus です（保守的な設定 — 最も高い料金を使用し、削減額を最大限に表示します）。

コスト追跡コンポーネント

コスト追跡パイプラインは、次の3つのファイルで構成されています。

ファイル	役割
.claude/lib/utils/ccusage-adapter.cjs	JSONL セッションログを解析し、トークン数を合計して、PRICING 表を使ってコストを計算します
.claude/hooks/monitoring/ccusage-statusline.cjs	UserPromptSubmit フック — プロンプトごとにアダプターを実行し、ステータスをランタイムファイルに書き込みます
.claude/context/runtime/ccusage-status.txt	ライブステータスファイル — ルーターがパイプラインの概要を表示するために読み取ります

ステータス出力形式（3段階の削減）：

[tokens]      <N> today (in: <N> / out: <N>) | Cost: $<X>
[cache]       $<X> saved | <N> reads, <N> writes
[compression] <N> events | <X>KB freed (~<N> tokens) | ~$<X> saved

• [tokens] — 実際の API 支出
• [cache] — サーバー側の削減（Anthropic のプロンプトキャッシュ。キャッシュ読み取り時に90％割引）
• [compression] — クライアント側の削減（このスキルが送信を完全に回避したトークン数）

メンテナンス手順（skill-updater 向け）

skill-updater がこのスキルを更新する際は、標準の調査プロトコルの後に、次の手順を追加で実行します。

料金確認手順

1. 現在の Claude API 料金を確認するため、Exa 検索を実行します。

   mcp__Exa__web_search_exa({
     query: 'Anthropic Claude API pricing per million tokens Opus Sonnet Haiku current',
     numResults: 4,
   });
   

2. 少なくとも2つの情報源（例：Anthropic のドキュメント、Silicon Data、IntuitionLabs、DevTk.AI）を照合します。

3. 見つかった料金を、上記の料金表と比較します。

4. いずれかの料金が変更されている場合：

   • この SKILL.md の表を更新します
   • .claude/lib/utils/ccusage-adapter.cjs の PRICING 定数を更新します
   • 最終確認日 を更新します
   • 変更を .claude/context/memory/decisions.md に記録します

5. 料金に変更がない場合は、最終確認日 のみを更新します。

重要な理由：古い料金を使うと、削減額が実際より大きく表示されます（古い Opus 4.0 の料金では、$86 の削減額が $258 と表示されます）。正確な料金は、このスキルのコストレポート機能の中核です。

1. token-saver を JSON モードで使って圧縮します（run_skill_workflow.py --output-format json）。
2. 証拠が不十分で、失敗時に処理を停止する設定が有効な場合は、停止します。
3. 抽出した知見を MemoryRecord 対応のペイロードにマッピングします。
4. MemoryRecord を通じて永続化し、.claude/hooks/memory/sync-memory-index.cjs を実行します。

マッピング規則（決定論的）

• gotchas.json：
  • テキストに gotcha|pitfall|anti-pattern|risk|warning|failure が含まれる
• issues.md：
  • テキストに issue|bug|error|incident|defect|gap が含まれる
• decisions.md：
  • テキストに decision|tradeoff|choose|selected|rationale が含まれる
• patterns.json：
  • それ以外の、抽出されたすべての証拠のデフォルトの保存先

ツールコマンド

推奨のラッパーエントリーポイント：

node .claude/skills/token-saver-context-compression/scripts/main.cjs --query "<question>" --mode evidence_aware --limit 20 --fail-on-insufficient-evidence

Python エンジンを直接実行する場合（上級者向け）：

python .claude/skills/token-saver-context-compression/scripts/run_skill_workflow.py --file <path> --mode evidence_aware --query "<question>" --output-format json --fail-on-insufficient-evidence

出力契約

• ラッパーは次の内容を含む JSON を出力します。
  • search の要約
  • compression の要約
  • ターゲット（patterns、gotchas、issues、decisions）ごとにグループ化された memoryRecords
  • エビデンスの十分性ステータス

ワークフローの参照先

• スキルのワークフロー：.claude/workflows/token-saver-context-compression-skill-workflow.md
• 関連ツール：.claude/tools/token-saver-context-compression/token-saver-context-compression.cjs
• コマンドのインターフェース：.claude/commands/token-saver-context-compression.md
• 引用形式は変更されていません。
  • メモリー項目は [mem:xxxxxxxx] になります
  • RAG 項目は引き続き [rag:xxxxxxxx] になります

search:tokens との連携

このスキルを呼び出すタイミングを判断するには、pnpm search:tokens を使用してください。

# Check if you need compression
pnpm search:tokens .claude/lib/memory
# Output: 60 files, 500KB, ~128K tokens ⚠ OVER CONTEXT

# Then compress with a targeted query
node .claude/skills/token-saver-context-compression/scripts/main.cjs \
  --query "how does memory persistence work" --mode evidence_aware --limit 10

このツールは、検索結果からファイルパスだけでなく実際のファイル内容を読み取り、Python エンジンで圧縮し、タイプ（patterns、gotchas、issues、decisions）ごとに分類されたメモリーレコードを抽出します。

適応型圧縮

適応型圧縮（コーパスのサイズに応じた圧縮率の調整）は自動で行われ、環境変数の設定は不要です。入力コーパスが小さい場合は圧縮が控えめになり、大きい場合はより強く圧縮されます。これは、トークン数に基づいて Python エンジンが内部的に制御します。

要件

• Node.js 18+
• Python 3.10+

厳守事項

1. 必ず圧縮前にハイブリッド検索（pnpm search:code）を実行し、要約出力の根拠となるエビデンスを取得すること
2. 未解決の不確実性が残っているコンテキストは、絶対に圧縮しないこと。圧縮前に曖昧さを解消すること
3. 圧縮後は必ず、要約した知見を MemoryRecord で直ちに保存すること
4. 圧縮中に、現在の作業仮説に反するエビデンスを絶対に破棄しないこと
5. 下流のスポーンプロンプトの根拠を示すため、圧縮出力には [mem:*] と [rag:*] の引用を必ず含めること

アンチパターン

アンチパターン	失敗する理由	正しい方法
事前にハイブリッド検索をせずに圧縮する	出力に根拠となるエビデンスがなく、ハルシネーションのリスクが高まる	最初に pnpm search:code を実行し、引用を埋め込む
矛盾するエビデンスを破棄する	要約出力に対する誤った確信につながる	相反するすべての情報を要約に残す
圧縮後に MemoryRecord を作成しない	次回のコンテキストリセット時に知見が失われる	重要な知見を MemoryRecord で直ちに保存する
圧縮が遅すぎる（80K トークン超過後）	圧縮前に精度が大幅に低下する	上限に達してからではなく、80K トークンで圧縮を開始する
[mem:*]／[rag:*] の引用を省略する	下流のエージェントが主張を検証できない	出力内でエビデンスの出所を必ず明記する

メモリープロトコル（必須）

作業前：

cat .claude/context/memory/learnings.md

作業後：

• 連携に関する知見を .claude/context/memory/learnings.md に追加する
• 連携に関するリスクを .claude/context/memory/issues.md に追加する