densely

densely

LLM 向けのロスレスコンテキスト圧縮。 任意のテキストを、バイト単位で完全に復元できることを保証しながら、トークン数を 2～8 分の 1 に圧縮します。展開のたびに sha256 で検証します。

MIT ライセンスで、永久に無料です。（チーム向けのホステッドプランを近日提供予定です — ウェイトリスト。）

1 つの o200k トークンには最大約 17.6 ビットの情報を格納できますが、一般的なコードで各トークンが使うのはわずか約 5～6 ビットです。densely はその差を活用します。

text -> lzma -> 16-bit chunks -> 65,536 single-token English words

キャリアとなる単語（" the"、" of"、…）のコストは正確に 1 トークンです。o200k の事前トークナイザーは単語の境界をまたいで結合しないため、ペイロード内のすべてのトークンに、圧縮データ 2 バイト（理論上利用可能な約 17.6 ビットのうち 16 ビット、チャネル容量の 91％）を格納できます。

ベンチマーク

python3 bench.py で再現できます（固定シード、stdlib のコードサンプル）。

シナリオ	バックエンド	トークン数（o200k）	比率	削減率
コード（argparse.py + densely）	lzma	21,659 → 10,726	2.02x	50.5%
コード（同じサンプル）	neural	21,659 → 2,538	8.53x	88.3%
モデルが見たことのないコード	neural	3,433 → 472	7.27x	86.3%
JSON（コード検索、100 件）	lzma	15,465 → 1,995	7.75x	87.1%
ログ（SRE インシデント、約 1600 行）	lzma	117,766 → 16,962	6.94x	85.6%

ニューラルバックエンド（--backend neural、python3 bench.py --neural）は、Qwen2.5-Coder-0.5B の次トークン確率を用いた整数算術コーダーを動作させます。NNCP 方式で、セグメントをまとめて処理します。88.3％という数値は、モデルが学習時に Python の stdlib を見ていたことによるものです。86.3％の行はこのリポジトリ独自のソースコード、つまり 2026-08-08 より前には存在しなかったコードであり、新規コードに対する正直な数値です（約 0.56 ビット／バイト）。

実世界のデータで測定

こちらで選別していないデータを同じパイプラインに通しました。このリポジトリ独自のソースコード、インストール済みの pip モジュール、実際の macOS /var/log/install.log の一部、実際の package-lock.json、および express に対する npm レジストリのライブ応答です。 o200k のトークン数は tiktoken でローカルに計測し、Claude のトークン数は Anthropic 独自の count_tokens エンドポイントで計測しました（Sonnet 5、リクエストのオーバーヘッドは調整で除外）。claude1 アルファベットを使用しています。すべての行で、バイト単位の完全な往復復元を確認しました。

データ	サイズ	o200k 元データ → ペイロード	削減率	Claude 元データ → ペイロード	削減率
このリポジトリ独自のコード	25 KB	7,008 → 4,254	39.3%	10,724 → 6,811	36.5%
インストール済み pip モジュール（factory.py）	32 KB	6,332 → 3,956	37.5%	10,625 → 6,334	40.4%
実際のシステムログ（install.log）	195 KB	65,684 → 4,204	93.6%	104,328 → 6,732	93.5%
実際の package-lock.json	27 KB	11,421 → 3,690	67.7%	15,743 → 5,910	62.5%
npm レジストリのライブ JSON（express）	195 KB	76,167 → 12,293	83.9%	113,444 → 19,672	82.7%

比較として、Headroom は、コーディングエージェントで 15～20％、JSON で 60～95％の削減を報告しています。これはコンテキストからコンテンツを 削除 し、元のデータを TTL 付きのローカルキャッシュに保持することで実現しています。densely はすべてのデータをコンテキスト内に保持し、外部ストレージも有効期限も使わず、バイト単位で完全に復元できます。

データのエントロピーを下回るロスレス圧縮は、数学的に不可能です（シャノン。詳しくは Fundamental Limits of Prompt Compression も参照してください）。この限界の範囲内で、densely は決定論的かつ CPU のみを使う方式として、実用上の上限に近い性能を発揮します。

使い方

pip install "densely[mcp]"
# extras: [neural] for the neural backend (torch + transformers)

densely compress  big_context.txt -o payload.dense
densely compress  src.py -o payload.dense --backend neural
densely decompress payload.dense   -o restored.txt   # byte-identical
densely stats     file1.py file2.json                # token savings

ライブラリ：

from densely import compress, decompress

payload = compress(text)        # ~2x-8x fewer tokens
assert decompress(payload) == text  # always true, sha256-checked

CLI の compress は、出力を書き込む前に往復処理を自己検証します。decompress は、破損やハッシュの不一致があると ValueError を送出します。

Claude Code / Cursor（MCP）で使う

# Claude Code
claude mcp add --scope user densely -- "$(which densely-mcp)"

# Cursor (~/.cursor/mcp.json) and other MCP clients
{"mcpServers": {"densely": {"command": "/absolute/path/to/densely-mcp"}}}

3 つのツール：

• compress_file(path) — 大きなログ／JSON／ダンプを読む代わりにエージェントが呼び出します。プレビューと、トークン数を 2～8 分の 1 に抑えた高密度ペイロードを取得します。
• compress_text(text) — すでに手元にある大きなツール出力に対して同じ処理を行います。
• expand(payload | payload_file, start_line, end_line) — sha256 検証済みの正確な元データを復元します。行範囲を指定することで、エージェントは必要な部分だけを取得できます。

圧縮のたびに、元のファイルの隣に .dense サイドカーファイルも書き込みます。これはコミット、配布、アーカイブが可能なプレーンテキストファイルで、キャッシュも TTL もなく、期限切れになることもありません。小さなペイロードはインラインでも返されます。これはコンテキストの圧縮において重要です。圧縮後の要約は古い会話内容に置き換わるため、インラインのペイロードだけでは要約で省かれる可能性がありますが、ディスク上のサイドカー（および要約にも引き継がれるそのパス）は失われません。Anthropic の圧縮 API ベータ版を直接使う場合は、ペイロードの参照がそのまま残るように、instructions に次の内容を追加してください。

高密度ペイロードの参照（.dense で終わるパス、または DENSE1/DENSE2 で始まる行）は、要約内にそのまま保持してください。この要約を作成する間は、ツールを呼び出さないでください。

自動モード（フック）

手間をかけずに節約できます。PostToolUse フックが、すべての大きなツール出力（Bash の出力、コード以外のファイルの Read、5,000 トークン以上）をその場で圧縮します。エージェントにはプレビューと統計情報が表示され、正確な内容は検索／展開で引き続き利用できます。また、置き換えた内容はすべて節約量台帳に記録されます（stats ツール、または各置き換え時に表示される累計値）。

~/.claude/settings.json に追加してください（フックはシェルの PATH の外で実行されるため、絶対パスを指定します）。

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Read|Bash",
      "hooks": [{
        "type": "command",
        "command": "/absolute/path/to/densely-hook",
        "timeout": 30
      }]
    }]
  }
}

（インストール後に which densely-hook を実行すると絶対パスが表示されます。フックはシェルの PATH の外で実行されるため、絶対パスのみを使用してください。）

DENSELY_HOOK_MIN_TOKENS で調整できます（デフォルトは 5000）。エージェントが編集しているコードファイルには、一切手を加えません。

トークンを節約できる場合と、できない場合

エージェントセッションでは、API にリクエストを送るたびに履歴全体を再送信するため、コンテキスト内にあるものには、毎回コストがかかります。densely がコンテンツの種類ごとに行う処理は次のとおりです。

コンテキスト内のコンテンツ	節約量	理由
エージェントが現在編集中のコード	なし — 圧縮しないでください	エージェントが読む必要があります。ペイロードは判読できません
参照用コード（1 回読んで、「念のため」保持しているもの）	20～40%	正確なコピーを低コストで保持できます。必要に応じて expand で行範囲を展開します
ツール出力：ログ、JSON、ダンプ	78～87%	エージェントが 1,500 行すべてを必要とすることはありません。プレビューと必要な部分の展開で十分です
圧縮後も保持する必要があるもの	間接的	ペイロードは圧縮をそのまま通過しますが、要約には残りません

プロンプトキャッシュに関する注意：キャッシュされた履歴は低コストになりますが、コンテキストウィンドウのサイズは変わりません。densely が主に確保するのは余裕であり、その次にコストを節約します。

他のツールとの比較

主要なツールはそれぞれ異なるトレードオフを採用しています（数値は各プロジェクトが公開しているベンチマークによるものです）。

	densely	Headroom	claw-compactor
アプローチ	エントロピー符号化 -> 単一トークンのキャリア	非可逆の選別、モデルが読み取れる出力	読み取り可能な 14 段階の変換（うち 2 段階は非可逆）
正確な復元	常に可能：sha256 検証済み、会話内で復元	TTL キャッシュ、必要に応じて取得	LRU「RewindStore」、検証についての記載なし
ログ	85.6%	約 92%（非可逆）	24.1%
JSON	87.1%（可逆）	60～95%（非可逆）	81.9%（非可逆サンプリングによる）
コード（使用中）	なし — 仕様によるもの	15～20%（AST スケルトン）	25%
モデルが出力を読む	いいえ（検索／展開ツール）	はい	はい
エージェントとの統合	MCP + フック + スキル（Claude Code、Cursor）	プロキシ + ラッパー + MCP	CLI のみ

方針の違いは、「精度を知らないうちに損なって最大限節約する」か、「正確さを保てなければ何もしない」かです。モデルが読み続ける必要があるコンテンツでは、読みやすく非可逆なツールが優れています。一方、データを決して誤らせず、圧縮、エクスポート、マシン間の移動を経ても保持する必要がある場合は、densely が適しています。両方を使ってください。

正直な注意点

• ペイロードは人間にもモデルにも読めません。ランダムな英単語の羅列のように見えます。読みやすい要約と併せて、チャット履歴、ツール出力、ソースファイルなどの正確なデータを高密度で格納する手段として使い、正確な内容が必要な場合はツール呼び出しで展開してください。
• 節約効果は冗長性によって異なります。非常に反復的なデータ（JSON、ログ）では7倍以上、密度の高い文章では約1.5～2倍、すでに圧縮済みのデータやランダムデータでは約0％です（ペイロードが生の入力より数個のヘッダートークン分を超えて大きくなることはありません。出荷前にstatsを確認してください）。
• 密度はトークナイザーごとに異なりますが、復元結果は常にバイト単位で完全に一致します。現在、2種類のアルファベットを提供しています。o200k（65,536語。OpenAI o200kではトークンあたり正確に16ビット）と、claude1（1,024語。Claude Sonnet 5 / Opus 5 / Fable 5ではトークンあたり正確に10ビット。Anthropicの語彙は公開されていないため、count_tokens APIを使って実測で収集しました）です。MCP サーバーとフックのデフォルトはclaude1、CLIのデフォルトはo200kです（変更するには--alphabet / DENSELY_ALPHABETを指定してください）。Sonnet 5でcount_tokensを使い、172KBのログで測定したところ、生データは93,117トークン、claude1ペイロードは25,904トークンでした（72.2％削減。o200kアルファベットでは47.8％の削減にとどまりました）。python3 tools/calibrate.pyで任意のアルファベットを任意の対象モデルで検証できます。tools/build_alphabet.pyで新しいアルファベットを収集できます。
• これが不要な場合（Redditユーザーの指摘はもっともです）：エージェントのハーネス全体を自分で管理しているなら、同じ仕組みを自分で構築できます。大きな出力をzstd/lzmaでファイルに圧縮し、エージェントに検索ツールを与え、ペイロードをモデルの入力から除外します。denselyはこのアーキテクチャをパッケージ化したものです（さらに、sha256検証、行単位の取得、プロンプト内に保持する必要がある一部のコンテンツ向けに、トークナイザーごとのキャリアアルファベットも備えています。これは、圧縮後も内容を一字一句変えずに保持する必要がある場合や、エクスポートしたセッションと一緒に持ち運ぶ場合に役立ちます）。クローズドなハーネス（Claude Code、Cursor）、一時的なサンドボックス、「信頼できるディスク＋grep」では対応できないあらゆる環境で真価を発揮します。
• ニューラルバックエンドの注意点：処理は遅く（約85 KBのコードの処理に、Apple Siliconではlzmaのミリ秒に対して数分かかります）、初回使用時にはtorchと約1 GBのモデルのダウンロードが必要です。復元結果がビット単位で完全に一致するのは、圧縮時と同じモデル／ソフトウェアスタックで展開した場合に限られます。そのため、compress(backend="neural")は返す前に往復処理全体を検証し、不一致があれば通知せずにlzmaへフォールバックします。100％の保証はニューラル経路には依存しません。

Densely Pro（近日公開）

ライブラリはMITライセンスで、今後も無料です。本番環境でエージェントを運用するチーム向けに、マネージドプランを開発しています。

• クラウドニューラル圧縮 — ローカルGPUなしでコードを86％圧縮
• マネージドプロキシ — コード変更なしでコストを削減
• チームダッシュボード — エージェントごと、日ごとのトークン削減量を金額で表示
• マシン間ペイロード — CIで圧縮し、どこでも展開

ウェイティングリストに登録 →（先行アクセス順＋初期ユーザー向け価格。突然の終了はありません — ライブラリはMITライセンスのままです）

ロードマップ

• ニューラルバックエンドのマシン間での決定性を実現します（整数／固定小数点推論、または不一致を許容する符号化方式）。これにより、あるマシンで圧縮したペイロードを別のマシンで展開できるようになります。
• llama.cppを使った、より高性能で高速なモデルにより、速度を高めながら圧縮率を向上させます。

テスト

python3 -m pytest tests/test_core.py tests/test_mcp.py   # fast suites
python3 -m pytest tests/test_neural.py                   # slow (~1 min): real LLM round trips

高速スイート：バイト単位で完全に一致する往復処理（Unicode、CJK、絵文字、ランダムバイト、ペイロードに似た入力）、改ざん検出、キャリアアルファベットの密度。 ニューラルスイート：単一セグメントと複数セグメントの往復処理、サイレントフォールバックがないことの確認、lzmaを上回ることの確認。