Token Compression: 数ヶ月分の Agent 記憶を1つのプロンプトに収める¶

AI agent のメモリには常にジレンマがあります: agent にはすべてを記憶してほしいけれど、AI モデルには一度に処理できるテキスト量に厳密な制限があります。履歴が増えれば増えるほど、収まる量は減っていきます。

Token compression がこの問題を解決します。 重要なものを残し、残りを圧縮し、制御可能な予算内に履歴を収めます。

1枚の図でわかる課題¶

Agent の完全な履歴: 50,000 トークン
    ↓
AI モデルのコンテキストウィンドウ: 4,000 トークン
    ↓
圧縮なしの場合: 最後の 4,000 トークンだけが生き残る
    （それより古いものはすべて消える — 重要な決定やエラーも含めて）

以前のアプローチは tail window — 最新のイベントだけを残し、それ以外はすべて破棄する。予測可能ですが無駄が多い: 昨日の重要なエラーを捨てて、5分前の冗長なログを残すかもしれません。

圧縮の仕組み¶

新しいアプローチはもっと賢い:

残す重要なもの: エラー、決定、ファイルパス、最近の状態
圧縮する ノイズ: 繰り返しのログ、スタックトレース、冗長な出力
削る低優先度のコンテンツは、圧縮だけでは足りない場合のみ

npm run contextdb -- context:pack \
  --session <id> \
  --limit 80 \
  --token-budget 1200 \
  --token-strategy balanced

結果¶

以前:

❌ 旧アプローチ: 最後の20イベントを残す → イベント #5 の重要なバグを見逃す

今:

✅ 新アプローチ: 全80イベントを残し、ノイズを圧縮 → バグはまだそこにある

3つのストラテジー¶

ストラテジー	使うタイミング	何をするか
`balanced`	デフォルト	ノイズを圧縮し、シグナルを残す。日常利用に最適。
`aggressive`	非常に小さい予算	厳しい制約向けの最大圧縮。
`legacy`	互換性	旧来の tail-window 動作。必要な場合のみ使用。

balanced から始めてください。 90% のケースで正しい選択です。

保護されるもの¶

次のものは 絶対に削られません:

エラーメッセージと失敗シグナル
ファイルパスとコマンド出力
最近の状態と決定
次のアクションシグナル

次のものが 最初に圧縮されます（短縮されますが、必ずしも削除されるとは限りません）:

繰り返しのログ行
スタックトレース
冗長なツール出力

パケットにはテレメトリが含まれているため、何が起きたか正確に確認できます: 何トークンがそのまま残り、何が圧縮され、何イベントが削られたか。

最も必要なシーン¶

Token compression は次のようなシナリオで力を発揮します:

数ヶ月の履歴がある 長期プロジェクト
同じ ContextDB を共有する 複数の agent
大量のログを生成する 夜間 harness 実行
コンパクトなコンテキストが必要な agent 間の切り替え

遅延読み込みの起動とも相性が良い — agent は小さなサマリーで即座に起動し、必要なときだけ圧縮された完全な履歴を読み込みます。

試してみる¶

npm run contextdb -- context:pack \
  --session <your-session-id> \
  --token-budget 1200 \
  --token-strategy balanced \
  --out memory/context-db/exports/compressed.md

出力を確認すると、何トークン節約できたかのサマリーが表示されます。

Token compression は ContextDB に組み込まれており、Harness CLI の一部です。追加ツールは不要です。