Context Guardian

Context Guardian

ローカルモデルのセッションがコンテキスト上限に達して終了してしまいます。これで防げます。

mcp-name: io.github.LuminariSoftwares/context-guardian

クイックスタート · 対応環境 · クライアントの設定 · 使用例 · 両方をインストール · 開発の理由 · 2 つの実行方法 · プロキシをインストール · DSH にインストール · 動作を確認 · 互換性 · 変更履歴

ローカルモデル向けの圧縮を確実に実行し、会話を決して終了させません。入口は 2 つですが、考え方は 1 つです。Ollama、LiteLLM、Headroom、vLLM、LM Studio などの OpenAI 互換バックエンドの前段に置き、あらゆる CLI やエージェントから使えるプロキシと、DeepSeek Harness 用のネイティブエンジンです。どちらも元の全文をディスクに保持し、どちらもオープン状態で失敗します。

**実測値：**コードネームをセッション途中で変更した条件で、qwen3-coder:30b（Ollama、64K ウィンドウ）を使った 48 プロンプトの DeepSeek Harness セッションでは、0.1.0-alpha.9 はすべての実行（n = 3）で 12/12 の事実を最新の状態に保ち、古い回答は 0 件で、初期の詳細 3/3 を再提示しました。一方、ピンだけでは 0/3 件の詳細しか再提示できませんでした（n = 2）。詳細：実測：重要な情報を保持できるか（2026-10-01）。

動作するツール

	接続方法	状態	例
Ollama	プロキシ：GUARDIAN_UPSTREAM_URL=http://localhost:11434/v1	テスト済み（毎日使用、Windows 11）	examples/ollama-proxy
LM Studio	プロキシ：GUARDIAN_UPSTREAM_URL=http://localhost:1234/v1	動作する見込みですが、LM Studio 自体では未テスト	examples/lmstudio-proxy
vLLM	プロキシ：GUARDIAN_UPSTREAM_URL=http://localhost:8000/v1	動作する見込みですが、未テスト	Ollama の例をコピーして、URL を変更してください
LiteLLM	プロキシ：GUARDIAN_UPSTREAM_URL=<your LiteLLM proxy>/v1	動作する見込みですが、未テスト	Ollama の例をコピーして、URL を変更してください
DeepSeek Harness	ネイティブエンジン：エージェントプリセットに1行追加	DSH 0.1.2-alpha.2 でテスト済み	examples/dsh-preset

プロキシに必要なのは、OpenAI 互換の /v1/chat/completions だけです。CLI の OPENAI_BASE_URL をプロキシに設定してください。「動作する見込み」は、まだテストされていないことを意味します。確認した内容を添えて、issue を作成してください。完全な対応状況は互換性をご覧ください。

クイックスタート

pip install context-guardian && context-guardian   # proxy on :8786 in front of Ollama on :11434; set OPENAI_BASE_URL=http://localhost:8786/v1
context-guardian-doctor                            # second terminal: checks the install and the running proxy, prints a fix: line for anything wrong

別のバックエンドやウィンドウを使う場合は、examples/ または設定をご覧ください。クライアントの設定については、クライアントをプロキシに接続するをご覧ください。DeepSeek Harness のユーザーは、以下の手順でネイティブエンジンをインストールしてください。

コンテキストの圧縮後、context-guardian-recall "<term>" でアーカイブされた原文を検索できます（モデルが受け取る要約には、正確なコマンドが記載されます）。

クライアントをプロキシに接続する

プロキシは、OpenAI 形式の POST /v1/chat/completions リクエストを圧縮します。以下の各クライアントは、それぞれのドキュメントに記載された設定を使って構成します。これら4つのクライアントはいずれも、まだプロキシでの動作をテストしていないため、確認できた内容を issue でお知らせください。

クライアント	設定場所	設定内容
Claude Code	環境変数	Claude Code は Anthropic Messages API（/v1/messages）を使用します。GUARDIAN_UPSTREAM_URL がその API を提供している場合、プロキシも対応しています（要約のリクエストは、同じアップストリームの /messages に、指定したキーを使って送信され、system に入ります）：ANTHROPIC_BASE_URL=http://localhost:8786。または、OpenClaude などの OpenAI 互換ビルドを使用します：CLAUDE_CODE_USE_OPENAI=1 OPENAI_BASE_URL=http://localhost:8786/v1 OPENAI_API_KEY=local OPENAI_MODEL=<model>
Cline	Settings → API Provider: OpenAI Compatible	Base URL http://localhost:8786/v1 · API Key 任意の空でない文字列 · Model ID <model>
Continue	~/.continue/config.yaml	models: の下に追加：- {name: Context Guardian, provider: openai, model: <model>, apiBase: "http://localhost:8786/v1", apiKey: local}
OpenCode	opencode.json	"provider": {"guardian": {"npm": "@ai-sdk/openai-compatible", "name": "Context Guardian", "options": {"baseURL": "http://localhost:8786/v1"}, "models": {"<model>": {}}}}

<model> はバックエンドが提供するモデル名です（Ollama の場合は、ollama list に表示される名前です）。プロキシは API キーを変更せずに転送します。ローカルバックエンドでは、このキーは無視されます。次に、GUARDIAN_NUM_CTX をそのモデルの実際のコンテキストウィンドウに設定します（設定）。

これは DSH エンジン（0.1.0-alpha.9）の動作を示す図であり、DSH の画面ではありません。DSH 内では、DSH 独自の「Context compacted」行とコンテキストメーター、負荷と直近の圧縮を表示する /context と /guardian、会話内の [context-guardian recall] メッセージとして確認できます。動作の流れは次のとおりです。ウィンドウの 85 % に達すると圧縮が行われ、保持するよう指定した事実がすべてのチェックポイントの先頭に置かれます。古いターンはディスクに残り、その後の質問で圧縮により失われた詳細が必要になると、回答の前に古くなった情報の再呼び出しによって元の行が戻されます。結果の行は、測定結果に記載されたベンチマークです。プロキシには専用のモニターがあります：動作を確認するをご覧ください。

	Context Guardian なし	使用時
ローカルモデル上の Claude Code 形式 CLI	自動圧縮が一度も実行されず、バックエンドがリクエストを拒否してセッションが終了します	ウィンドウが埋まる前にプロキシが圧縮するため、セッションを続行できます
32K のローカルモデル上の DSH（測定値：圧縮試行 314 回）	48 回成功。残りは空の要約が返されたか、要約中にウィンドウを超過して失敗しました	失敗した要約や実行できない要約はすべて、決定論的なチェックポイントにフォールバックします：~14,012 → ~584 トークン、23 ms、モデル呼び出しなし
圧縮によって失われた部分	消失	ディスクにアーカイブされます。DSH では、各チェックポイントの行に recall が読み戻す seq ポインターが付与されます

両方をインストールする（DeepSeek Harness、約5分）

Context Guardian と Tool Guardian は、1つの問題を解決する2つの部分です。Tool Guardian はツールスキーマとツールの結果でコンテキストウィンドウが埋まるのを防ぎ、Context Guardian はウィンドウが埋まる前に会話を圧縮し、重要な情報を保持します。両者はファイルを共有せず、それぞれ個別にインストールします。DSH 0.1.2-alpha.2 以降、Node.js ^22.19 または >=24、および Tool Guardian のルーター用に PATH 上の Python 3.9 以降が必要です。

# 1. Add both bundles to the DSH profile you use (`web` is the one `dsh web` uses)
dsh plugin --profile web add dsh-tool-guardian
dsh plugin --profile web add dsh-context-guardian

# 2. Tool Guardian: copy in the MCP servers you already use (Claude Desktop / Cursor / Windsurf / .mcp.json), then check them
cd ~/.dsh/profiles/web/node_modules/dsh-tool-guardian          # Windows: cd %USERPROFILE%\.dsh\profiles\web\node_modules\dsh-tool-guardian
npm run setup                  # asks before it writes ~/.tool-guardian/mcp.json, then prints a doctor report

# 3. Context Guardian: add its compaction row to your agent preset (a dry run until --apply)
cd ~/.dsh/profiles/web/node_modules/dsh-context-guardian       # Windows: cd %USERPROFILE%\.dsh\profiles\web\node_modules\dsh-context-guardian
npm run setup
npm run setup -- --apply

# 4. Start DSH and open a NEW session with the preset setup named
dsh web

そのセッションで /guardian と入力します。Context Guardian のエンジンリビジョンとモデルのコンテキストウィンドウが表示されます。次に /toolguardian と入力します。Tool Guardian が起動した各 MCP サーバー、ルーターがリクエストごとに節約するトークン数、更新の有無が表示されます。

DSH を使っていない場合も利用できます。Context Guardian のプロキシ（python context_guardian.py。README を参照）は、OpenAI 互換の CLI であればどれでも動作します。Tool Guardian は、Claude Code、Cursor、その他の MCP クライアントで通常の MCP サーバーとして動作します（README を参照）。

2つの実行方法

	プロキシ（context_guardian.py）	DSH エンジン（engine.js）
対応環境	OpenClaude、Cline、Continue、OpenCode（クライアントをプロキシに接続する）など、OpenAI 互換の /v1/chat/completions と通信するもの。標準の Claude Code は圧縮せずにそのまま通過します	DeepSeek Harness 0.1.2+
組み込み方法	OPENAI_BASE_URL をプロキシに設定します	エージェントプリセットの compaction グループに1行追加します
要約の生成元	同じバックエンドモデルに、プロキシが要約を依頼します	まず DSH 独自の要約器を使い、失敗した場合、何も返さなかった場合、または収まらない場合は決定論的コンパイラーを使います
元の内容の読み戻し	ディスク上のスパンアーカイブ（プレーンな JSON、圧縮ごとに1ファイル）	モデル用の recall / search ツール、ユーザー用の /recall と /context
ライブビュー	圧縮モニターを備えた /guardian/health ダッシュボード、/guardian/events	DSH 独自の「Context compacted」行とコンテキストメーターに加え、判断ごとに guardian_dsh.jsonl に出力される1行の JSON
アイドル中の圧縮	—	0.1.0-alpha.8 以降はデフォルトで無効です。idleCompactRatio（例：0.45）を設定すると有効になります
アーカイブ形式	logs/guardian_spans/<run>/NNNN.json	同じ形式なので、同じツールで両方を読み込めます
セットアップガイド	この README	docs/dsh-integration.md

引き継ぎファイル（DSH エンジン）。 圧縮のたびに、エンジンは memory.json と同じ場所に handoff_<session>.json、.md、および handoff_latest.json を書き込みます。新しいセッションや別のエージェントがこれらだけを参照して作業を引き継げるよう、セッションの目標、現在のピン留め情報、決定事項が記録されます。 GUARDIAN_HANDOFF=0（またはエンジン行で handoff: false）を設定すると無効になります。docs/dsh-integration.md を参照してください。

flowchart LR
    subgraph P["Proxy: any OpenAI-compatible harness"]
      A1["CLI / agent"] --> G1["Context Guardian<br/>proxy :8786"] --> B1["Ollama / LiteLLM / vLLM"]
      G1 -. "over budget" .-> S1["summarise older turns<br/>keep recent verbatim"]
    end
    subgraph D["Engine: inside DeepSeek Harness"]
      A2["DSH agent"] --> C2["compaction-basic"] --> E2{"LLM summary<br/>fits and works?"}
      E2 -->|yes| K2["LLM checkpoint"]
      E2 -->|no| X2["deterministic checkpoint<br/>with seq pointers"]
    end
    S1 --> Z[("span archive on disk")]
    X2 --> Z
    K2 --> Z

このページの残りはプロキシについて説明します。DSH エンジンの5分ガイドは、docs/dsh-integration.md を参照してください。

互換性

	テスト環境	動作が期待される環境	備考
DeepSeek Harness（エンジン）	Windows 11 上の 0.1.2-alpha.2	0.1.2-alpha.2 およびそれ以降の 0.1.x	compaction-basic が必要です（standard プリセットには含まれています）。npm run setup には、ユーザーエージェントのプリセットか、DSH に同梱されている standard が必要です
Node.js（エンジン、セットアップ）	Windows 11 上の 22.23、Linux（テストコンテナ）上の 22.x	^22.19.0 または >=24	package.json の engines フィールド
Python（プロキシ、ブリッジ、cg_doctor.py）	3.11	3.10 以降	DSH エンジン自体に Python は不要です
オペレーティングシステム	Windows 11（常用）；Ubuntu、Windows、macOS（CI：プッシュごとに pytest と node のスモークテストを実行）	—	CI でのテストスイート実行時のみ macOS を使用しています。Mac はまだ常用していません
バックエンド（プロキシ）	Ollama /v1	OpenAI 互換の /v1/chat/completions を提供するもの：LiteLLM、vLLM、LM Studio、llama.cpp サーバー	プロキシがトークン数を独自に推定するため、バックエンドの使用量データは不要です
バックエンド（DSH エンジン）	DSH で動作させる Ollama モデル	DSH で動作させる任意のモデル	コンテキストウィンドウは、DSH がそのモデルについて報告する値です。より小さい値を強制する場合にのみ numCtx を設定してください
クライアント（プロキシ）	OpenClaude	Claude Code およびその他の OpenAI 互換 CLI	Cursor は未テストです
コンパニオン	同じ DSH プロファイルに並行してインストールした dsh-tool-guardian 0.3.0-alpha.x	0.3.0 以降	2 つはファイルを共有せず、別々にインストールします

「テスト環境」とは、このリポジトリのテストスイートに加え、開発に使用したマシンでの常用を意味します。「動作が期待される環境」は未テストです。動作しない場合は、イシューを作成してください。

実測：重要な情報は保持されるか？（2026-10-01）

DeepSeek Harness での qwen3-coder:30b（Ollama、64K ウィンドウ）を使った 48 プロンプトのセッションです。最初の 6 プロンプトで 12 個のプロジェクトコードネームを提示し、40 件のダミー読解タスクで 3～7 回の圧縮を発生させた後、モデルに 12 個すべてを尋ねます（null は許容、推測は誤答としてカウント）。実行ごとに新しいランダムなコードネームを使用します。

事実の伝え方	guardian 無効	0.1.0-alpha.7	0.1.0-alpha.8
「重要です。後で使うので、これを保持してください：...」	3 回中 2 回は 12/12（1 回は 12 個すべてを捏造）	3 回中 0 回正解（1 回は 12 個すべてを捏造、2 回は最後まで完了せず）	3 回中 3 回が 12/12、捏造 0 件
「後で使うので、これを覚えておいてください：...」	--	--	12/12、捏造 0 件
「参考情報：...」（保持するよう求めていない）	2 回中 0/12（1 回は null と回答、1 回は 12 個すべてを捏造）	--	2 回中 2 回が 12/12、捏造 0 件

変更点：ユーザーが保持するよう求めた事実は、原文のままピン留めされます。要約の呼び出し時にも ## Must Keep セクションを作成するよう求め、その箇条書きはセッション中ピン留めされます。すべてのチェックポイントでピン留め内容を確認し、アイドルトリガーはデフォルトで無効になっています。

0.1.0-alpha.9（2026-10-04）：以前の詳細も思い出せるようになりました。 同じセッションですが、セッションの途中でコードネームが変わり、最後に、誰もフラグを付けていなかった最初の文書の詳細を尋ねます。デフォルトで有効な古い情報の呼び出し機能は、メッセージで、圧縮されたターンにしか残っていない情報を指定すると、一致する元の行を最大 3 行含む [context-guardian recall] メッセージを追加します。

バリアント	実行回数	現在の事実	古い情報への回答	初期の事実
ピン留めのみ（alpha.8）	2	12/12、9/12	0、3	0/3、0/3
ピン留め + 古い情報の呼び出し（alpha.9）	3	毎回 12/12	毎回 0	毎回 3/3

これが存在する理由

Claude Code スタイルのコーディング CLI（Claude Code 自体や、OpenAI 互換バックエンドに対応した OpenClaude などのツール）には、自動コンパクト機能が組み込まれています。この機能は、CLI が期待する形式で、正確なトークン使用量がリアルタイムに API から返されることを前提としています。こうしたツールを、Ollama の /v1 エンドポイント、LiteLLM プロキシ、Headroom プロキシなどの OpenAI 互換ブリッジ経由でローカルモデルに接続すると、使用量の情報が欠落していたり、不正確だったり、異なる形式で返されたりすることが多く、その結果、自動コンパクトが気づかれないまま一度も実行されません。

目に見える症状としては、バックエンドがリクエストを拒否するまでセッションが続き（「トークン制限に達しました」）、セッションを閉じて開き直す必要が生じます。その間に部分的にコンパクト化することはなく、会話の続きから再開できません。

Context Guardian は、この特定の問題に対処するための、小規模で意図的にシンプルなフォールバックです。実行中のトークン数を独自に推定し、会話が設定可能なしきい値を超えると、同じバックエンドに会話の古い部分を 1 つの要約メッセージにまとめるよう依頼してから、リクエストを転送します。直近のメッセージは常にそのまま保持されます。要約の呼び出し自体が失敗した場合、Guardian はオープンに失敗し、履歴を気づかれないまま削除するリスクを避けて、コンパクト化していない元のリクエストを転送します。

スタック内での配置

これは既存のチェーンに加わる新しいリンクであり、すでに利用しているものを置き換えるものではありません。

Your CLI / agent (Claude Code, OpenClaude, etc.)
    -> Context Guardian        (this project)
    -> your existing OpenAI-compatible backend
       (Ollama directly, a LiteLLM proxy, Headroom, vLLM, ...)

CLI の OPENAI_BASE_URL をバックエンドの URL ではなく Context Guardian に設定し、GUARDIAN_UPSTREAM_URL にはバックエンドの実際の URL を設定します。Guardian は POST /v1/chat/completions 以外では純粋なパススルーとして動作し、このエンドポイントでのみコンパクト化のチェックを行います。ストリーミングレスポンスを含むその他すべてのルートは、バイト単位でそのまま転送されます。

MCP サーバーやエージェント型 CLI を使用している場合は、こちらをお読みください

Guardian は、tools 配列をコンテキストの予算に含めるようになりました。0.2.0 より前はそうなっておらず、実際の不具合でした。変更履歴をご覧ください。

ツール定義は、メッセージ履歴とは異なり、通常は見えません。自分で入力することも、スクロールして流れていくこともなく、CLI のコンテキスト表示にも個別に表示されないことがよくあります。しかし、すべてのリクエストに含まれています。この開発時に使用した環境では、最初のユーザーメッセージを送る前に、7 つの MCP サーバーだけで 28,689 トークン — 32,768 トークンのウィンドウの 87.6% を占めていました。

Guardian はこれらを圧縮できません。 会話履歴は要約できますが、ツール定義はその下に固定で存在するためです。つまり、問題は 2 種類あり、Guardian が解決できるのはそのうち 1 つだけです。

問題	解決方法
会話履歴が増え続け、ウィンドウがいっぱいになる	Guardian
入力を始める前にウィンドウの 3 分の 2 が使われている	読み込むツールを減らすか、Tool Guardian

Guardian は、どちらの問題が起きているかを知らせるようになりました。特定のツールペイロードを初めて認識したときに tool_budget イベントを記録し、ツール定義だけでウィンドウ全体と同じか、それを超える場合は明確に警告します。

[ContextGuardian] TOOL DEFINITIONS ALONE (2671) EXCEED THE ENTIRE CONTEXT
WINDOW (1000). Nothing this proxy does can fix that -- send fewer tools.

これが表示された場合、プロキシの設定では解決できません。MCP に対応する CLI のほとんどでは、セッションごとに読み込むサーバーを指定できます。Claude Code と OpenClaude はどちらも --mcp-config <file> と --strict-mcp-config を併用でき、この場合、そのファイルだけがセッションで使用する MCP サーバーの読み込み元になります。

関連プロジェクト — Tool Guardian （npm では dsh-tool-guardian、通常の MCP サーバーとしては tool-guardian。詳しくは README をご覧ください）は、この問題のもう半分を解決します。MCP サーバーの前段に 3 つの汎用ツールを置き、残りのツールは必要になったときに公開するため、ツール定義が各リクエストで再送信されなくなります。Context Guardian はこの固定されたツール分を圧縮できませんが、Tool Guardian は取り除きます。併用してください。一方は会話を、もう一方はツールを削減します。

覚えておくべき点が 1 つあります。アップグレード後は、Guardian がより早く、より頻繁に圧縮するようになります。 リクエスト全体を測定するようになり、これまではその一部しか測定していなかったためです。圧縮が過剰に感じられる場合は、ウィンドウはもともとこれほどいっぱいで、それが見えていなかったというのが実情です。

このツールが行わないこと

• バックエンドがすでに行っている圧縮（Headroom、プロンプトキャッシュなど）を置き換えたり、重複して実行したりするものではありません。 先に圧縮するかどうかを判断した後は、そのままバックエンドに転送します。両者は補完関係にあり、競合しません。
• CLI 独自のコンテキスト使用量表示を修正するものではありません。 CLI はこのプロキシの存在を認識しないため、圧縮が行われると、CLI 独自のトークンカウンターと実際の値にずれが生じます。大切なのは、処理が完全に停止するのではなく、セッションが継続することです。その後に表示される数値に多少の誤差が生じるのは、プロキシ層で見えない形で処理することの許容されたトレードオフです。通常、CLI 自体は変更できないためです。
• トークナイザーに正確に基づいたカウンターではありません。 トークン数は実際のトークナイザーではなく、文字数（デフォルトでは約 3.5 文字あたり 1 トークン）から推定するため、遅れてではなく少し早めに作動します。正確な測定ではなく、安全マージンを見込んだトリガーとしてご利用ください。

インストール

git clone https://github.com/LuminariSoftwares/context-guardian.git
cd context-guardian
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt

Guardian を初めて起動する前に、python configure.py を実行してください（下記の設定をご覧ください）。

設定

設定ファイルを手動で編集する代わりに、対話式セットアップスクリプトを実行してください。お使いのハードウェアやバックエンドについていくつか質問します（特に、モデルの実際のコンテキストウィンドウについて確認します）。回答は .env に書き込まれます。

python configure.py

各質問には [角括弧] 内に適切なデフォルト値が表示されます。Enter キーを押すと、その値が使われます。回答を変更するには、いつでも configure.py を再実行できます。または、その後 .env を直接編集することもできます。 ユーザーごとに実際に重要なのは GUARDIAN_NUM_CTX だけです。 このプロジェクトはもともと、32K のコンテキストウィンドウに設定したモデルを、16GB のカード（RTX 4070 Ti Super）で動かしてテストしていました。この数値はそのハードウェア固有のものであり、誰にでも当てはまるデフォルトではありません。適切な値は、使用する GPU／VRAM の予算とモデルによって完全に異なるため、configure.py は全員の環境が同じだと暗黙に仮定せず、この値を明示的に尋ねます。実際の値がわからない場合は、次を確認してください。

• Ollama： モデルを読み込んだ状態で ollama ps を実行します。CONTEXT 列に、実際に使用中の値が表示されます（モデルの理論上の最大値とは限りません）。
• LM Studio／vLLM／その他のサーバー： モデルの読み込み時に設定したコンテキスト長の設定を確認します。Guardian にはこれを自動検出する方法がないため、実際に設定した値と一致させる必要があります。
• 値がわからない場合、または明示的に設定していない場合： まずは控えめな値から始めます（configure.py のデフォルトである 32768 は、一般向けの単体 GPU で広く安全に使える開始値です）。バックエンドが VRAM 不足にならずに実際にこの値を維持できると確認できたら、後から引き上げてください。

値を高く設定しすぎると、Guardian が早めにコンパクションを行えず、Guardian が介入する前にバックエンドで致命的なエラーが発生する可能性があります。値を低く設定しすぎた場合は、必要以上に頻繁にコンパクションが行われるだけです。安全ではありますが、最適ではありません。

ウィザードを使わない場合は、.env.example を .env にコピーして、手動で編集してください。

cp .env.example .env

変数	デフォルト	機能
GUARDIAN_PORT	8786	Guardian 自身がリッスンするポート
GUARDIAN_UPSTREAM_URL	http://localhost:11434/v1	Guardian がリクエストを転送する OpenAI 互換バックエンド
GUARDIAN_NUM_CTX	32768	モデルの実際のコンテキストウィンドウ（トークン単位）です。実際のバックエンド／モデル設定と一致させてください。Ollama では、代わりにプロキシがモデルごとに読み取れます。GUARDIAN_OLLAMA_CONTEXT を参照してください
GUARDIAN_OLLAMA_CONTEXT	auto	アップストリームが Ollama の場合（auto：アップストリーム URL のポートが 11434、1：常に有効、0：常に無効）、モデルごとに一度 /api/show を呼び出し、報告された num_ctx に基づいて予算を設定します。モデルが学習時の context_length しか報告しない場合、Ollama ではそれより小さい値で実行されることがあるため、GUARDIAN_NUM_CTX の値を引き下げることはあっても、引き上げることはありません。エラーが発生した場合、そのモデルについては実行終了まで GUARDIAN_NUM_CTX にフォールバックします
GUARDIAN_COMPACT_THRESHOLD	0.85	圧縮が実行される GUARDIAN_NUM_CTX に対する割合
GUARDIAN_KEEP_RECENT_MESSAGES	未設定	未設定（デフォルト）の場合、使用可能なウィンドウ（GUARDIAN_NUM_CTX − GUARDIAN_RESERVE_OUTPUT）の GUARDIAN_KEEP_RECENT_FRACTION の範囲内に収まる最新のメッセージを保持します。最低でも 4 件を保持します。40 KB のツール結果は、1 件のメッセージとしてではなく、実際のサイズとして数えられます。数値を設定すると、その件数のメッセージを正確に保持します（以前の固定件数の動作です。0 の場合は何も保持しません）
GUARDIAN_KEEP_RECENT_FRACTION	0.20	GUARDIAN_KEEP_RECENT_MESSAGES が未設定の場合に、そのまま保持する使用可能なウィンドウの割合
GUARDIAN_CHARS_PER_TOKEN	3.5	推定に使用するトークンあたりの文字数
GUARDIAN_COUNT_TOOLS	1	予算に tools 配列を含めます。0 に設定すると、0.2.0 より前のメッセージのみを対象とする動作になります
GUARDIAN_CALIBRATE	1	バックエンドから返される使用量の数値を基に、モデルごとの実際の文字あたりトークン数を学習し、推定値を補正します。リクエストごとに読み取られます。0 に設定すると、生の推定値を使用します
GUARDIAN_UPSTREAM_TIMEOUT	600	アップストリームのバックエンドから応答があるまで待機する秒数
GUARDIAN_UPSTREAM_CONNECT_TIMEOUT	10	アップストリームへの接続自体を待機する秒数
GUARDIAN_LOG_PATH	<repo>/logs/context_guardian_log.json	圧縮イベントを記録する場所（JSON Lines 形式）
GUARDIAN_HOST	127.0.0.1	Guardian がバインドするインターフェースです。何をしているのか分かっている場合を除き、変更しないでください。Guardian は認証なしでバックエンドの前段に配置されます
GUARDIAN_RESERVE_OUTPUT	8192	モデルの 出力 用に確保するトークン数です。ウィンドウには応答と（推論モデルの場合は）思考内容の両方を収める必要があるため、圧縮は残りの領域を基準に実行されます。これが GUARDIAN_NUM_CTX 以上の場合は、ウィンドウの半分に制限され、その旨がログに記録されます。設定を修正してください
GUARDIAN_SPAN_DIR	<repo>/logs/guardian_spans	追い出されたメッセージを折りたたむ前にアーカイブする場所です。これにより、ディスク上での圧縮時に情報が失われません
GUARDIAN_KEEP_SPANS	500	保持するスパンファイルの数です。0 の場合は保持しません
GUARDIAN_KEEP_SUMMARIES	1	Guardian が作成した過去の要約をウィンドウ内に保持する数です。古い要約は破棄せず、次のスパンに折り込みます
GUARDIAN_MIN_SUMMARY_CHARS	40	要約がこの文字数に満たない場合、要約に失敗したものとして扱い、何も追い出しません。これが存在する理由については、変更履歴の 0.4.0 を参照してください
GUARDIAN_MIN_TRANSCRIPT_CHARS	80	追い出されるメッセージをレンダリングした結果がこの文字数に満たない場合、Guardian は何もないものを要約するのではなく、要約を拒否します
GUARDIAN_TOOL_ARG_CHARS	300	ツール呼び出しの引数のうち、要約器に渡す文字数です。全文はスパンに保存されます
GUARDIAN_SUMMARY_REASONING_EFFORT	未設定	要約呼び出しに限り、reasoning_effort として渡されます。標準仕様ではないため、デフォルトでは無効です。gpt-oss では low にすると、要約のレイテンシが約半分になりました
GUARDIAN_VERBOSE	1	圧縮のたびに、圧縮内容、圧縮前後のトークン数、削減したトークン数を複数行のバナーで表示します。0 に設定すると、以前の単一行のログ出力になります
GUARDIAN_COST_PER_1M_INPUT_USD	0	ローカル実行によって 利用を避けている ホステッド API の 100 万入力トークンあたりの価格です。設定すると、圧縮によって再送せずに済んだトークンの累計金額を Guardian が報告します。0（デフォルト）の場合、料金行は省略されます。ローカルモデルを使用しているため、実際の請求は発生しません
GUARDIAN_VERSION_CHECK	1	起動時に PyPI に一度問い合わせ（タイムアウト 2 秒、24 時間キャッシュ、完全なフェイルオープン動作）、新しい context-guardian がある場合は 1 行表示します。無効にするには 0 に設定します。エアギャップ環境やプライバシー重視の環境では、ネットワークに接続しません
GUARDIAN_VERSION_CACHE	<repo>/logs/.version_check_cache.json	頻繁な再起動時にネットワークへの再アクセスを避けるため、更新チェックで取得した PyPI の応答をキャッシュする場所（TTL は 24 時間）
GUARDIAN_DRY_RUN	0	1：すべての圧縮を計算します（要約器も呼び出されます）。実際の圧縮イベントと同じフィールドを持つ dry_run イベントとして記録しますが、クライアントのリクエストはバイト単位で変更せずに転送します。ヘルスダッシュボードに計上されます。プロキシの動作を確認してから実際に有効にする場合に使います
GUARDIAN_INJECT_STREAM_OPTIONS	0	1：stream_options を含まないストリーミングチャットリクエストに stream_options: {"include_usage": true} を追加し、使用量フレームがキャリブレーターに届くようにします。クライアントが想定していない場合のある、choices が空の追加の最終フレームをクライアントが受け取るため、デフォルトでは無効です
タイムアウトに関する注意： ローカルの「思考」／推論モデルは、最初の出力トークンを返すまで長時間応答しないことがあります。長い待ち時間の後、実際の（単純ではない）リクエストでのみ 500 エラーが発生する場合は、何かが壊れていると判断する前に GUARDIAN_UPSTREAM_TIMEOUT を大きくしてください。ほとんどの HTTP クライアントに標準で設定されているデフォルトの 5 秒のタイムアウトは、通常の REST API 向けであり、ローカル LLM 推論向けではありません。これは、開発中にこのプロジェクト自体のコミット履歴で確認された、まさにその不具合です。

実行

python context_guardian.py

次に、CLI の OPENAI_BASE_URL を http://localhost:8786/v1（または設定したポート）に向けます。

セットアップを確認する：cg_doctor.py

1 つのコマンドで、設定されている内容、問題点、および各問題の修正方法を確認できます。

python cg_doctor.py                          # from the repo, or the installed npm package folder
context-guardian-doctor                      # after `pip install context-guardian` (0.7.0+)
python cg_doctor.py --preset path/to/agent.cordis.yml   # also check the DSH preset that mounts engine.js
python cg_doctor.py --json                   # the same findings as JSON

チェックごとに OK／WARN／FAIL の行が 1 つ表示され、問題がある場合はその下に fix: の行が表示され、件数の行（doctor: 5 ok, 1 warnings, 0 errors）も表示されます。FAIL が 1 つでもある場合は、終了コード 1 で終了します。次の項目をチェックします。

• パッケージのバージョン（package.json）とプロキシ自体のバージョン（context_guardian.py）。
• .env — ファイルが見つかったかどうか、および数値の GUARDIAN_* 値がすべて実際に解析できるかどうか（32k や、GUARDIAN_NUM_CTX を下回っていない GUARDIAN_RESERVE_OUTPUT は、修正方法とともに FAIL として表示されます）。
• 使用中のコンテキストウィンドウ — GUARDIAN_NUM_CTX を設定している場合はその値、設定していない場合は --preset で指定したプリセットに固定されている numCtx（WARN が表示されます。0.1.0-alpha.5 以降、エンジンは DSH からモデルの実際のウィンドウを読み取るため、コピーした numCtx: 32768 は通常、ウィンドウを小さくするだけです）、それもない場合は DSH がセッションについて報告するウィンドウ。
• プロキシが GUARDIAN_HOST:GUARDIAN_PORT で応答するかどうか（FAIL ではなく WARN です。DSH バンドルはプロキシなしでも動作します）、および実行中のプロキシが現在設定されているものとは異なるウィンドウで起動されたかどうか。
• Python ブリッジが動作するかどうか — プラグインが選択するものと同じインタープリター（GUARDIAN_PYTHON、次にパッケージと同じ場所にある .venv、次に PATH 上の python／python3）で modules/cg_bridge.py を起動し、Python 3.10 以降が必要です。

標準ライブラリのみを使用し、ファイルを変更することはありません。

実際のセッションで使う前にテストする

1. 実際のバックエンド（Ollama、LiteLLM、Headroom など、使用しているもの）を通常どおり起動します。
2. Guardian を起動します：python context_guardian.py
3. 圧縮のテストを行う前に、通常のパススルーが動作することを確認するため、実際の CLI ではなく、手動でリクエストを 1 つ送信します。

   curl http://localhost:8786/v1/chat/completions \
     -H "Content-Type: application/json" \
     -d '{"model":"<your-model>","messages":[{"role":"user","content":"say hi"}]}'
   

4. GET http://localhost:8786/guardian/stats で、実行中のトークン推定値と圧縮回数を確認します。または、ブラウザーで http://localhost:8786/guardian/health を開くと、ライブダッシュボード（ウィンドウ使用量、圧縮回数、削減されたトークン数／コスト、および更新通知）が表示されます。これは、同じ JSON を 3 秒ごとに更新して表示するだけです。
5. 圧縮テストを強制的に行います：一時的に GUARDIAN_NUM_CTX と GUARDIAN_COMPACT_THRESHOLD を低く設定し（例：NUM_CTX=2000、THRESHOLD=0.5）、長いメッセージをいくつか含む会話を送信します。GUARDIAN_LOG_PATH に圧縮ログのエントリーが表示され、バックエンドに実際に届くリクエストが送信したものより小さいことを確認します。
6. その後で初めて、CLI の OPENAI_BASE_URL を Guardian に向け、実際のセッションでテストします。

コンテキストウィンドウが異なる複数のモデルを実行する

Ollama では、Guardian は各モデルの num_ctx を /api/show に問い合わせます（GUARDIAN_OLLAMA_CONTEXT を参照）。そのため、Modelfile で num_ctx が設定されているモデルは、そのモデル独自のウィンドウを基準に予算が計算されます。それ以外の場合、GUARDIAN_NUM_CTX は実行中のインスタンスの稼働中は固定されます。コンテキストウィンドウが大きく異なるモデルを切り替えて使用する場合は、次のいずれかを行います。

• 独自の GUARDIAN_NUM_CTX を設定した 2 つ目の Guardian インスタンスを、別の GUARDIAN_PORT で実行する、または
• 1 つのインスタンスを使い続け、しきい値をウィンドウの小さい／制約の厳しい方のモデルに合わせる（もう一方より安全です。ウィンドウの大きいモデルでは、Guardian が必要最小限より少し早めに圧縮するだけだからです）。

MCP サーバー

（PyPI パッケージとともにインストールされる）context-guardian-mcp は stdio MCP サーバーです。そのため、MCP クライアントはターミナルを使わずにプロキシの動作を確認できます。ツールは 3 つあり、いずれも読み取り専用です。

ツール	機能
guardian_status	実行中のプロキシの /guardian/stats をループバック（GUARDIAN_HOST:GUARDIAN_PORT）経由で取得します
search_spans	コンパクションでアーカイブされたスパン内のテキストを検索します（context-guardian-recall と同じ検索です）
read_span	実行 ID とインデックスを指定して、アーカイブされたスパンを 1 件読み取ります。要約と元のメッセージを取得し、20,000 文字で切り詰めます

まずは何もインストールせず、uv を使って実行します。

uvx context-guardian mcp

Claude Desktop（claude_desktop_config.json）や、同じ形式を受け付けるクライアントの場合：

{
  "mcpServers": {
    "context-guardian": {
      "command": "uvx",
      "args": ["context-guardian", "mcp"]
    }
  }
}

pip でパッケージをインストールした場合も、{ "command": "context-guardian-mcp" } で同じように実行できます。

Claude Code：claude mcp add context-guardian -- uvx context-guardian mcp

引数：search_spans は term（必須）、run、max を受け取ります。read_span は run と index（どちらも必須）を受け取ります。guardian_status は引数を受け取りません。guardian_status の使用にはプロキシ（context-guardian）の実行が必要です。他の 2 つはディスク上のスパンアーカイブを読み取ります。

リポジトリのルートにある server.json には、公式 MCP Registry 用にパッケージ（PyPI の context-guardian、uvx context-guardian mcp で起動）が記載されています。この README の先頭にある mcp-name: 行は、所有権を示すマーカーです。

ベンチマーク

scripts/bench_proxy.py は、スクリプト化されたエージェントとの会話（ユーザーのターン、大きな結果を返すツール呼び出し、アシスタントの応答。クライアントはターンごとに履歴全体を再送信します）を、実際のプロキシアプリ経由でプロセス内のスタブアップストリームに送信し、1 行を出力します。同じ --turns と --seed を指定すると、トークン数は同じになります。レイテンシーはマシンによって異なります。ネットワークにもリポジトリにもアクセスしません。

python scripts/bench_proxy.py --turns 40 --seed 1

スタブアップストリーム（実際のモデルではありません。スタブは即座に要約するため、added_ms は要約時間ではなくプロキシ自体のオーバーヘッドです）を使用して測定。2026-10-14、Python 3.11、Linux コンテナー：

turns=40 tokens_before=1130722 tokens_after=160310 compactions=27 p50_added_ms=5.07 p95_added_ms=7.20

開発／テストの実行

pip install -r requirements-dev.txt
pytest
npm install --no-package-lock --legacy-peer-deps
npm run check && npm run test:node

CI では、Ubuntu、Windows、macOS 上で両方のテストスイートを実行します（tests、node）。

動作を確認する

プロキシの /guardian/health コンパクションモニター：コンパクションしきい値（GUARDIAN_COMPACT_THRESHOLD、ウィンドウの 85 %）を超えて届いたリクエストは、転送前にコンパクションされるため、バックエンドに長すぎるリクエストが届くことはありません。

• プロキシ： セッションの実行中に http://localhost:8786/guardian/health を開きます。コンパクションモニターでは、コンパクションのたびに処理前 → 処理後のバーを表示し、各コンパクションのドロップダウンと、固定の下限（ツール＋システムプロンプト）が本当の問題である場合にアドバイスボックスを表示します。GET /guardian/events は同じ記録を JSON で返します。
• DSH： セッションで /context と入力すると、負荷、キャッシュヒット数、今すぐコンパクションした場合の削減量を確認できます。元の内容を読むには /recall 3-7、/recall result 42、または /recall find <text> を実行します。判断の履歴は logs/guardian_dsh.jsonl で確認できます（idle-check → compaction/start → deterministic または llm → compaction/end）。

謝辞

Context Guardian は、ほかの人々のアイデアを基盤としており、そのことを明記しています。

• dsh-compaction-instant（TsFreddie、MIT）— vendor/compiler.js と vendor/region.js は、元のヘッダーと vendor/LICENSE.dsh-compaction-instant の MIT ライセンステキストを含め、0.1.4 から変更せずにベンダーとして取り込んでいます。recall / search の仕様は、同プロジェクトに従っています。
• VCC（lllyasviel）— 会話コンパイラーの原則です。コンパイラーは、ログを元のトークンだけで構成されたコンパクトなビューにコンパイルし、省略された各部分を参照できるようにします。
• dsh-openwolf（MIT）— 圧縮の直前にセッションの状態をスナップショットとして保存するアイデアです。エンジンの precompact-<seq>.json と FILES WRITTEN の一覧は、このアイデアを独自に実装したものであり、openwolf のコードは含まれていません。
• DeepSeek Harness — summarize() は、同プロジェクトの圧縮エンジンがこの目的のために用意しているフックです。

サードパーティに関する通知の全文：THIRD_PARTY_NOTICES.md。

ライセンス

MIT — LICENSE を参照してください。