lossless-context-mcp

lossless-context-mcp

エージェントのコンテキストを記録するフライトレコーダーです。 コーディングエージェントに提示されたすべてのファイルバージョンを、フック経由で継続的に記録する台帳です。これにより、コンパクションで作業セットが失われることも、サブエージェント群が同じファイルに何度もコストを費やすこともなくなり、あとからモデルが実際に見た内容を正確に証明できます。

                      ┌──────────────────────┐
  ledger reads ──────▶│                      │──▶ RESTORE   working set survives /compact
  (read_file, MCP)    │   flight recorder    │──▶ PACKS     one cache-cached prefix for a fan-out fleet
  transcript sweeps ─▶│  (content-addressed  │──▶ RECEIPTS  signed, git-bound "what did it see"
  (native Read/Edit)  │   archive on disk)   │──▶ METERING  where the read tokens went, in dollars
                      └──────────────────────┘

実際の動作

コンパクションでエージェントの作業セットが失われることは、もうありません。 — PreCompact でスイープし、その後マニフェストを注入。根拠のない編集はブロックされ、作業セットを復元してから編集を許可します。

2つのエージェント、1つのファイル — 航空管制です。 2つ目のエージェントは、上書きの途中で止められ、原因となったエージェントも特定されます。

これらの録画のすべての行は、リリース済みコードから出力された実際の内容です。デモは docs/demo/make-demo.mjs が生成します。このスクリプトは実際のフックとサーバーを動かし、実際の出力をレンダリングします。ぜひご自身でも再実行してください。

1. 復元：コンパクションで作業セットが失われることはもうありません

Claude Code がコンパクションを行うと、一般的なコンテキストの約3分の2を占めるツール出力（主にファイルの内容）が永久に破棄されます。その後、モデルは手探りで作業します。うろ覚えのファイルを読み直したり、さらに悪い場合は、もう手元にない内容を推測したりします（#27242 は80 👍 の要望です）。

フライトレコーダーが、この問題を自動的に解決します。

1. PreCompact — スイープフックがセッションのトランスクリプトを解析し、セッションで触れたすべてのファイルをアーカイブします（MCP 経由の読み取りだけでなく、ネイティブの Read／Edit／Write も対象です）。その後、優先順位付きの作業セットマニフェストを書き込みます。コンパクション処理に組み込めるほど高速です。実際の14 MBのトランスクリプトを361 msでスイープしました。ご自身の環境でも計測できます。 node bench/sweep-bench.mjs <transcript.jsonl>.
2. SessionStart(compact) — 注入フックが、簡潔なマニフェストを新しいコンテキストに戻します。「作業セットはこの12ファイルでした（編集したファイルを先頭に表示）。推測せずに、必要なファイルを復元してください。」
3. restore_context — 現在のディスク上の状態から作業セットを再出力します。予算上限を設け、モデルが最後に見た後で変更されたファイルには注記を付けます。

claude-mem などのセッションをまたぐメモリツールは、次のセッション向けに何が起きたかを要約します。これはそれを補完するセッション中のレイヤーで、直前に作業していた内容を、ファイルバージョン単位で正確に復元します。

2. 根拠のない編集を防止：アクティブなセーフティネットとしてのレコーダー

レコーダーは、モデルがこのコンテキストエポックで実際に確認したファイルバージョンを正確に把握しています。PreToolUse フックはこれを利用して、最も深刻な2種類の編集失敗を、書き込みが反映される前に防ぎます。

• コンパクション後の推測による編集 — モデルがコンテキストをコンパクション／リセットした後に読んでいないファイルを、内容についての要約の記憶に頼って編集するケースです。ハーネス自体の「編集前に読み取り済みか」の追跡情報は、コンパクション後も維持されるとは明記されておらず、新しいモデルでは未読ファイルの編集自体が許可されています。この編集を拒否し、モデルに理由を1行で示します。ファイルを読んで（または restore_context を使って）から、再試行してください。 自動で復旧でき、追加コストは読み取り1回だけです。
• 古いベースに基づく編集 — モデルがファイルを読んだ後、別のエージェント、ユーザー、またはフォーマッターによってディスク上のファイルが変更されたケースです。mtime から推測するのではなく、コンテンツハッシュで比較します。同じ再読み取りの指示を付けて拒否します。

設計上、フェイルオープンです。疑わしい点があれば（解析できないトランスクリプト、部分的な読み取り、モデル自身が直前に編集したファイル、大きすぎるファイルなど）、編集には手を加えず続行します。LOSSLESS_GUARD=off でいつでも無効にできます。

3. 調整：並行エージェントの航空管制

1 つのリポジトリで 2 つのエージェントセッションを実行すると、互いに気付かないまま相手の変更を上書きしてしまいます。B が 10 分前に A が読んだファイルを編集し、A は古いコピーを元に編集するため、マージ結果はひどいものになり、どちらも気付きません。これをローカルで調整する既製の手段はありません。しかし、レコーダーはすでに、各セッションで各エージェントが何を保持し、編集しているかを把握しています。v2 では、その情報をアクティブに活用します。

• 編集中の検出 — あるエージェントプロセスに編集が許可されると、ローカルのプレゼンスプレーン（~/.lossless-context/presence/、プロセスごとに 1 ファイル、デーモンなし、ロックなし）にインテントを公開します。数秒後に別のエージェントが同じファイルを編集しようとすると、原因となったエージェントを明示して拒否されます。「エージェントセッション 3f2a91b0 が 12 秒前にこのファイルの編集を開始しており、まだ反映されていない可能性があります。」 同じセッションの兄弟サブエージェントも対象です。
• セッション間の古いベース検出 — 別のセッションによる編集が、現在のセッションが保持している内容より新しく、最後の接触時に検証可能なハッシュが残っていない場合、編集は再読み込みの指示とともに拒否されます。通常の差分チェックが実行される際、理由にはファイルを変更したエージェントが明示されるようになりました。
• レーダー — coordination_status は、確認可能なすべてのエージェントセッション、各セッションが編集している内容、セッション間または編集中のアクティビティがあるファイルを表示します。

制約についても正直に述べます。これは助言的な仕組みであり、ロックではありません。フックのないセッションは見えず、同じ秒に発生する競合はすり抜ける可能性があり、プレゼンスファイルは認証されていないローカル JSON です。つまり、任意のローカルプロセスがファイルを偽造し、誤った 拒否 を引き起こせます（構造上、誤って許可することはありません。プレゼンスによって追加されるのは拒否の種類だけです）。インテントの後、権限確認プロンプトで編集が拒否された場合、そのインテントは期限切れになるまで LOSSLESS_COORD_INTENT_SECS（90 秒）残ります。この仕組みで並行した上書きが起こる時間帯は大幅に狭まりますが、完全になくすことはできません。また、実際にどの程度検出できるかはまだ測定されていません。LOSSLESS_COORD=off を設定すると、ガードとは独立して調整機能が無効になります。（ガードの圧縮追跡はセッション単位です。マシン全体で共有されるエポックファイルを使用するのは重複排除エンジンだけで、セッション間の更新が発生しても、保守的な全件再送が 1 回必要になるだけです。）

4. パック：すべてのサブエージェントで同じファイルにトークンを使うのをやめる

トークンの無駄が実際に発生するのは、処理を複数のエージェントに振り分ける場面です。実際のマルチエージェント実行 195 件を測定したところ、サブエージェントの Read トークン全体の 19.6% は、兄弟エージェントが同一コンテンツを重複して読み取ったものでした（2,640 万トークン中 518 万トークン）。すべての兄弟エージェントが初期状態から開始し、同じ CLAUDE.md、同じ仕様書、同じコアモジュールを読み取ります。

export_pack は、アーカイブに保存されたセッション間の読み取り履歴から安定した頻出ファイルをランク付けし、カスタムのエージェントタイプのシステムプロンプトに含めるための、決定的な形式のブロックとして出力します。このブロックは安定したプレフィックスなので、エージェント群全体でプロバイダーのプロンプトキャッシュが利用されます。実際のレビューの振り分けでは、ベースラインより46.55% 安価でした。一方、同じパックをタスクごとに注入すると 19.6% 高コストになりました（兄弟エージェントごとにキャッシュへの書き込みが発生するためです）。このため、ツールはパックの配置場所を案内します。どちらの数値も、1 つの実データを外部で測定したものであり、このリポジトリ内のハーネスで測定したものではありません。正確な数値、手法、注意事項については BENCHMARK.md を参照してください。実行ごとにパックを 1 回生成し、そのまま埋め込んでください。ランキングは最新の読み取り履歴に従うため、export_pack を繰り返し実行すると結果が異なる場合があります。

5. 責任の追跡：その変更を行ったとき、エージェントには何が見えていたのか？

context_blame（CLI コマンドもあります：lossless-context-mcp blame <path>）は、エージェントのインシデント報告で誰もが知りたいデバッグ上の疑問に答えます。指定したファイルについて、モデルに表示されたすべてのコンテンツバージョン（SHA-256 と git blob SHA-1、初回／最終確認時刻、取得元、セッション）と、選択した時点でほかにどの情報がコンテキストに含まれていたかを示します。エージェントが誤った変更を行ったときは、エージェントの自己申告を問い詰める代わりに、記録を検索できます。

6. レシート：モデルが見た内容を Git にひも付けて証明する

可観測性ベンダーは、エージェントが読み取った内容を変更可能なトレースストアに記録します。誰も署名せず、リポジトリの識別情報にもひも付けません。また、エージェント自身による報告は証拠になりません（実際には読んでいないものを「検証した」と主張するエージェントに遭遇した人なら誰でも分かるでしょう）。

context_receipt は、HMAC-SHA256 署名付きの証明書を発行します。表示されたファイル／ビューすべて、各コンテンツバージョンの SHA-256、各バージョンの Git blob SHA-1（クローンを持つ検証者なら誰でも git cat-file -e <sha1> で確認できます。その内容は実際にコミットされたことがあるか）、発行時点のリポジトリ HEAD、配信種別、トークン合計、そして証明対象とするキャプチャ経路（mcp と、include_sweep を指定した場合の transcript-sweep）を明示する coverage ステートメントを含みます。デフォルトでは trust-mcp のレシートと同じキーファイルで署名するため、1 つのキーで証拠の連鎖全体を検証できます。つまり、エージェントが見た内容と、エージェントが行ったことです。

対象範囲を正直に示します：レシートが証明するのは、台帳とスイープを通過した内容です。仲介されていない経路まで網羅しているとは主張せず、そのことを独自の coverage.note に記載します。

7. 使用量の計測（とトークン節約の現実確認）

context_stats では、セッションのファイル読み取りトークンがどこで使われたかを、リポジトリ別、ファイル別に、金額とともに、実際のトークナイザーで計測して確認できます。

現実確認。以前のバージョンから残しているのは、これが事実だからです：セッション内のトークン節約としては、実際の Claude Code トランスクリプトで**約 0%**です（never-lose エンジン使用時は +0.4%。ネイティブのファイル状態キャッシュがすでに節約の余地を取り込んでいます。BENCHMARK.md に全データがあります）。実際に存在する節約効果は、エージェントをまたいだ場合のものです（上記のパックを参照）。読み取り経路の重複排除を維持しているのは、損失がなく、効果がマイナスになることもないと証明されているからです。単体で大きな節約になるからではありません。

インストール（2 つのコマンド）

npm i -g lossless-context-mcp
lossless-context-mcp init        # wires all hooks into ~/.claude/settings.json
claude mcp add lossless-context --scope user -- lossless-context-mcp

init は冪等です（アップグレード後に再実行すると、重複させずにパスを更新します）。最初に設定ファイルをバックアップし、解析できない設定ファイルには変更を加えず、自身が追加したもの以外のフックは削除しません。--dry-run で事前に確認できます。次の設定を行います。

• sweep-transcript.mjs（PreCompact + SessionEnd）— ワーキングセットと正確なバージョンをキャプチャします。PreCompact 時に重複排除のエポックを進め、圧縮を妨げません。
• inject-manifest.mjs（SessionStart、matcher compact）— 圧縮後に復元されたワーキングセットのマニフェストを注入します。
• reset-epoch.mjs（SessionStart）— 新しいセッションをまたいでも読み取りの重複排除で情報が失われないようにします。
• guard-edit.mjs（PreToolUse、Edit|Write|MultiEdit）— ブラインド編集ガードです（LOSSLESS_GUARD=off で、設定を解除せずに無効化できます）。

init の後、Claude Code を再起動してください。フックがなくてもすべての機能は動作しますが、自動のネイティブツールキャプチャ、圧縮後の注入、ガードは利用できません。その場合、台帳には MCP の読み取りのみが記録されます。

ツール

ツール	機能
read_file(path, symbol?, lines?, force_full?)	損失のない読み取り：全体／変更なしマーカー／差分。省略可能な単一のsymbolまたはlines:"40-90"ビューを指定できます。バイナリファイルは拒否します。
read_files(paths[], force_full?)	1 回の呼び出しで作業セットを取得します。ファイルごとのエラーがバッチ全体の失敗につながることはありません。
working_set(limit?)	このセッション（および過去 24 時間）についてレコーダーが把握している内容を、重要度順に並べた表で表示します。ディスク上の状態との古さも示します。
restore_context(files?, budget_tokens?)	コンパクション後に作業セットを再出力します。デフォルトでは重要度上位 K 件のマニフェストを出力し、予算で制限でき、変更内容を注記します。
export_pack(repo?, top?, budget_tokens?, days?)	複数セッションの読み取り履歴から、エージェント型システムプロンプト向けの決定論的なファンアウト型コンテキストパックを作成します。
context_blame(path, at?, window_minutes?)	フォレンジック：モデルに提示されたファイルの全バージョンと、ある時点の関連コンテキストを表示します。シェルからlossless-context-mcp blame <path>を実行することもできます。
coordination_status()	レーダー：表示可能なエージェントセッション、各セッションの最近の編集、セッション間および処理中のファイルを表示します。
outline(path)	ファイルの簡易な構造マップを表示します（宣言のみ）。
context_stats()	このセッションでの読み取りに関するトークン数／費用の内訳を表示します。
context_receipt(artifact, include_sweep?)	カバレッジを明示した、署名付きの Git に紐づくコンテキストレシートです。
verify_context_receipt(receipt, signature)	タイミングセーフで正規化された検証を行います。

プライバシーとストレージ

アーカイブは~/.lossless-context/archiveに保存されます（変更するにはLOSSLESS_CONTEXT_DIRを指定）。コンテンツアドレス方式で管理され、上限は 512 MiB（LOSSLESS_ARCHIVE_BYTES）で、LRU 方式で削除されます。イベントログは 30 日後に期限切れになります（LOSSLESS_EVENTS_DAYS）。データがマシンの外に出ることはありません。 シークレットパターンに一致するファイル（.env*、鍵／証明書、.ssh／.awsのパス、認証情報、および独自に指定したLOSSLESS_ARCHIVE_EXCLUDEの glob）は、保存されません。チェックでは指定されたパスと解決後の実パスの両方を対象にするため、シークレットへのシンボリックリンクで回避することはできません。除外されたファイルについて記録されるのはパス、アクセス回数、タイムスタンプのみです（コンテンツのほか、低エントロピーのシークレットをオフラインで確認できる可能性があるハッシュやサイズなど、コンテンツ由来のメタデータも記録しません）。

読み取り経路が品質を損なわない理由

エンジンがコンテンツを省略したり差分だけを提示したりするのは、モデルがその内容をまだ保持していると証明できる場合に限られ、コンテキストのエポックによって制限されます（フックはコンパクション時にエポックを更新するため、コンパクション後の読み取りは常に全体を取得します）。400 件の操作をランダムに行う不変条件テストでは、各操作後にモデルが再構成できるビューがディスク上の実際の状態と一致することを検証します。証明の確度がそれより低いものは、すべて全体を送信します。

正直な制限事項

• 復元で提供するのは現在のディスク上の状態です（変更があれば注記します）。会話のタイムマシンではありません。正確な過去のバージョンは、レシート用にアーカイブに保存されます。
• トランスクリプト形式は Claude Code 内部のもので、変更される可能性があります。スイープ処理は意図的に 2 段階（安定したサーフェスの検出＋ベストエフォートの正確な取得）に分け、サイレントフェイルにしています。形式が変わると取得精度は低下しますが、セッションが中断されることはありません。
• レシートが証明するのは仲介されたパスのみで、その旨も明記します。レシートは HMAC（共有鍵）であり、第三者が検証できる署名ではありません。必要とする人がいれば、今後のバージョンで Ed25519 レシートを候補として検討します。
• パックの有効性は、プロバイダーのプロンプトキャッシュと安定したプレフィックスを前提としています。46.55%という数値は、あるワークロードで測定されたものであり、保証値ではありません。
• シンボルの抽出は、ヒューリスティックな波括弧／インデント解析であり、パーサーではありません（tree-sitterは評価しましたが、WASM／ABIの脆弱性を理由に採用を見送りました）。

ステータス

v2.0.0 — フルフライトレコーダー上に構築された調整プレーン。永続的なコンテンツアドレス型アーカイブ、トランスクリプトのスイープとマニフェスト注入フック、ワーキングセットの復元、ファンアウトパック、Git に紐づくレシート v2、ワンコマンドの init、ブラインド編集ガード、コンテキストの変更履歴追跡、エージェント間調整（進行中のインテント、反映済み編集との競合、coordination_status レーダー）を備えています。データ損失防止の不変条件を含む 121 件のテストがすべて成功。通信経由のスモークテストでは、スイープ → 注入 → 復元 → ガード → 調整 → レシートの一連の流れを検証。実際のトランスクリプトを使ったスイープとガードの実行も、実データで検証済みです。MIT ライセンス。