🪟 コンテキスト窓を守る MCP プラグイン context-mode の構造とデータ

AI コーディングエージェントを長く動かすと、ログ・ブラウザのスナップショット・Issue 一覧といった大きなツール出力がコンテキスト窓を埋めます。context-mode は、この生出力を会話へ流し込まずにサンドボックス実行と SQLite 全文検索へ迂回させる MCP プラグインです。

この記事では、npm context-mode@1.0.169（GitHub release tag v1.0.169、公開 2026-06-29）を対象に、内部構造・永続データ・導入・運用までを整理します。数値と挙動は、公開されている README・ベンチマーク・ソースコードに基づきます。

この記事の全体像。以下、順に解説します。

context-mode とは

context-mode は、ホストのエージェントが受け取るツール出力の行き先を変える層です。MCP サーバーとして 11 個の ctx_* ツールを公開し、あわせてホスト側のフックでルーティングを強制します。モデルが大きな出力を直接読む経路を減らし、代わりに次の 2 つを通します。

• サンドボックスでのコード実行。処理結果を中心とした短いレスポンスだけが文脈へ入ります。
• SQLite FTS5 の知識ベース。検索でヒットした断片だけが文脈へ入ります。

作者は Mert Koseoğlu です。配布物は npm パッケージ context-mode と GitHub リポジトリ mksglu/context-mode で、ライセンスは Elastic License 2.0 です。

公式サイトは、OSS プラグインと有償 Platform を同じエンジンの二面として位置づけます。

プラグインはローカルの SQLite だけで動きます。Platform はオプトインのイベント転送で、公式は転送対象をツール名・ファイルパス・エラー件数などの構造メタデータに限定し、ソースコードとプロンプト本文は対象外としています。

解こうとしている 4 つの問題

README はコンテキストの問題を 4 つの辺で定義します。

削減量のベンチマーク

公式の BENCHMARK.md は、実ツール出力のフィクスチャを使った削減量を公称値として載せています。概要は 21 シナリオと書きますが、内訳表は 14 行 + 6 行の 20 行で、掲載されている Raw Size を足しても概要の総量と一致しません。次の値は公称値として読み、丸め済みの表から自分で削減率を再計算しないほうが安全です。

README が掲げる「98% reduction」は ctx_execute_file 小計に相当します。全体の 96% とは別の集計です。この読み替えは後段の「注意点」でまとめます。

近い技術との違い

context-mode は MCP サーバーを置き換える製品ではなく、MCP の結果経路とホストのフック経路を束ねる層です。

用途から選ぶなら、次の対応になります。

Claude Code の MCP Tool Search はツール定義の遅延ロードで、context-mode はツール結果の迂回です。同じ「コンテキスト節約」でも層が異なります。

特徴

• サンドボックス実行: ctx_execute / ctx_execute_file / ctx_batch_execute が子プロセスでコードを走らせ、処理結果を中心に返します（実行したコードの抜粋やパス、失敗時の標準エラーも付きます）。対応言語は JavaScript、TypeScript、Python、Shell、Ruby、Go、Rust、PHP、Perl、R、Elixir、C# の 12 です。
• Think in Code: 集計・フィルタ・解析はスクリプト側で行い、モデルは結果だけを読みます。
• FTS5 知識ベース: ctx_index が見出し単位でチャンク化し、Porter stemming と trigram の結果を Reciprocal Rank Fusion で合成します。
• URL 取得と TTL キャッシュ: ctx_fetch_and_index が HTML を Markdown 化して索引します。既定 TTL は 24 時間です。
• 意図フィルタ: 出力が約 5 KB を超え intent の指定がある場合、全文を索引したうえで意図に合う箇所だけ返します。
• セッション継続: ファイル編集・git・タスク・エラー・利用者の判断を SQLite へ残し、PreCompact でスナップショットを作り、SessionStart で必要な断片を検索可能にします。
• フックによるルーティング: 大きな出力を出すホストツールと他 MCP をサンドボックス側へ誘導します。標準出力へ流す curl / wget やインライン HTTP は PreToolUse でコマンドを書き換え、WebFetch は拒否します。
• 文体への不介入: ルーティングはデータの行き先に限定し、最終回答の短文化は強制しません。
• 11 個の MCP ツール: サンドボックス 6（ctx_batch_execute、ctx_execute、ctx_execute_file、ctx_index、ctx_search、ctx_fetch_and_index）とメタ 5（ctx_stats、ctx_doctor、ctx_upgrade、ctx_purge、ctx_insight）。
• マルチホスト: フックの実装形（HookParadigm）は json-stdio / ts-plugin / mcp-only の 3 つ、プラットフォーム識別子（PlatformId）は 18 値 + unknown です。
• 検索の段階制御: 同一エージェント文脈での検索回数に応じて結果件数を絞り、過多な検索を ctx_batch_execute へ誘導します。
• ローカル実行: プラグインは端末上で完結します。Elastic License 2.0 は、実質的な機能一式をホスト型サービスとして第三者へ提供することを制限します。

構造

内部アーキテクチャを C4 モデルの 3 段階で図解します。システムコンテキスト図とコンテナ図は役割名で、コンポーネント図はファイル名とアダプタ名で示します。

システムコンテキスト図

開発者がホストエージェントへ作業を依頼し、ホストエージェントが context-mode を呼び出します。context-mode はツール出力をサンドボックスと検索ストアへ導き、セッション状態を永続化します。

コンテナ図

起動単位とデータストアに分解します。ホストエージェントは、JSON 標準入出力の MCP 子プロセス、プロセス内プラグイン、フック起動の 3 経路で接続します。

内部のコンテナです。

外部の要素です。

コンポーネント図

コンテナ内部をファイル単位に分解します。MCP のツール実装とフックのルーティングは、別プロセスでも同じコアを共有します。図は入口側、MCP サーバ側、フックと永続化側の 3 枚に分けます。

まず、ホストからの 4 つの入口とアダプタ層です。

次に、MCP サーバ内部とツールの依存です。

最後に、フックディスパッチャ、Executor、2 つのストアです。

CLI と MCP Server の内訳です。

プラグイン・フック・アダプタの内訳です。

アダプタは 3 つのパラダイムに分かれます。

実行と永続化の内訳です。

データ

永続データの単位は、プロジェクト単位の SessionDatabase と、検索用の ContentDatabase です。列名は src/session/db.ts と src/store.ts の DDL に従います。

概念モデル

所有関係を入れ子、利用関係を矢印で示します。

情報モデル

型名は DDL の論理型を汎用名へ写したものです。日時は TEXT のため string です。図はセッション側とコンテンツ側に分けます。

まず、ストレージ根とセッション側です。

次に、検索用のコンテンツ側です。Chunk と ChunkTrigram は、セッションのイベントとメタへ任意で結び付きます。

実装上の細部です。

イベントの優先度定数 EventPriority は LOW=1 / NORMAL=2 / HIGH=3 / CRITICAL=4 です。追い出しの SQL は ORDER BY priority ASC, id ASC なので、数値が小さいものから先に消えます。

配置パスは次のとおりです。

サイドカーは <path>-wal と <path>-shm です。journal は WAL、synchronous は NORMAL です。

構築方法

前提条件

• Node.js >= 22.5.0（package.json の engines.node）。
• 代替ランタイムとして Bun を使えます。
• SQLite バックエンドは実行時に自動選択されます（src/db-base.ts の loadDatabase()）。
  • Bun: bun:sqlite
  • Node.js >= 22.5 かつ FTS5 あり: node:sqlite（OS は問いません）
  • それ以外、または node:sqlite に FTS5 が無いとき: native addon の better-sqlite3（依存 ^12.6.2）
• Claude Code のプラグイン経路では、/plugin と /plugin marketplace が使える版が必要です。README は v1.0.33+ と書きますが、これらのコマンドを含むプラグインシステムは Claude Code 2.0.12 で公開されたため、実際にはそれ以降の版を用意します。/plugin が認識されなければ先に Claude Code を更新します。
• Claude Code 以外のフック経路では、グローバルバイナリ context-mode を PATH に置きます。

導入前後の確認です。

node --version
claude --version
npm view context-mode version

context-mode doctor

Claude Code では slash command でも診断できます。

/context-mode:ctx-doctor

Claude Code プラグイン

README の主経路です。

/plugin marketplace add mksglu/context-mode
/plugin install context-mode@context-mode

インストール後に Claude Code を再起動するか /reload-plugins を実行し、/context-mode:ctx-doctor で確認します。プラグインは次を登録します。

• hooks: PreToolUse / PostToolUse / UserPromptSubmit / PreCompact / SessionStart / Stop
• 11 個の MCP ツール
• skills（slash command）

フックと slash command を省いて試すだけなら、MCP のみでも登録できます。

claude mcp add context-mode -- npx -y context-mode

ステータスラインはプラグイン manifest の外側で、~/.claude/settings.json に一度書きます。

{
  "statusLine": {
    "type": "command",
    "command": "context-mode statusline"
  }
}

保存後に Claude Code を再起動すると、$ saved this session · $ saved across sessions · % efficient が表示されます。

npm グローバル導入とフック

Claude Code プラグイン以外は、まずグローバル導入します。

npm install -g context-mode

package.json の bin は "context-mode": "./cli.bundle.mjs" で、このバイナリが MCP サーバ起動と context-mode hook <platform> <event> の両方を担います。

Gemini CLI では ~/.gemini/settings.json に MCP とフックをまとめます。

{
  "mcpServers": {
    "context-mode": {
      "command": "context-mode"
    }
  },
  "hooks": {
    "BeforeTool": [
      {
        "matcher": "run_shell_command|read_file|read_many_files|grep_search|search_file_content|web_fetch|activate_skill|mcp__plugin_context-mode|mcp__context-mode|mcp__(?!.*context-mode)",
        "hooks": [{ "type": "command", "command": "context-mode hook gemini-cli beforetool" }]
      }
    ],
    "AfterTool": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "context-mode hook gemini-cli aftertool" }]
      }
    ],
    "PreCompress": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "context-mode hook gemini-cli precompress" }]
      }
    ],
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "context-mode hook gemini-cli sessionstart" }]
      }
    ]
  }
}

ルーティング用の指示ファイルは任意です。グローバル導入後のコピー元は npm root -g 配下です。

cp "$(npm root -g)/context-mode/configs/gemini-cli/GEMINI.md" ./GEMINI.md

OpenCode プラグイン

OpenCode は TypeScript プラグイン経路で、ctx_* は OpenCode プロセス内のツールとして登録されます。

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["context-mode"]
}

plugin: ["context-mode"] と旧来の mcp.context-mode を同時に書くと、MCP 子プロセス側の tools/list が意図的に空になります。ツールの重複登録を避けるための挙動で、プラグイン側の 11 ツールはそのまま使えます。MCP クライアントから子プロセスを覗くと「ツールが無い」ように見えるため、旧ブロックは context-mode upgrade で外します。KiloCode は同じ経路で、設定ファイル名が kilo.json です。

Codex プラグイン

まず marketplace を追加し、Codex のプラグイン UI からプラグインをインストールします。

codex plugin marketplace add mksglu/context-mode

フックは feature flag で有効化します。

[features]
plugin_hooks = true
hooks = true

現行の Codex は [features].hooks を公開しますが、バンドルされた plugin hooks は既定で有効になるまで plugin_hooks も必要です。ストレージを移すときは絶対パスを渡します。

CONTEXT_MODE_DIR="$HOME/.codex-context-mode" codex

インストール後に Codex を再起動し、ctx stats で MCP の到達を確認します。フックは、Codex がプラグインのフックコマンドを信頼したうえで有効になるため、承認を求められたら確認します。

Codex の PreToolUse は deny に対応します。updatedInput は runtime が拒否するため（openai/codex#18491）、additionalContext は PreToolUse では落ち、PostToolUse と SessionStart で注入されます。

plugin_hooks が無いビルドでは手動で配線します。~/.codex/config.toml に MCP を書き、

[features]
hooks = true

[mcp_servers.context-mode]
command = "context-mode"

[mcp_servers.context-mode.env]
CONTEXT_MODE_PLATFORM = "codex"

続けて $CODEX_HOME/hooks.json（未設定なら ~/.codex/hooks.json）へフックを登録します。この JSON を書かないと、MCP ツールは使えてもルーティングは効きません。matcher の文字列はツール名と完全一致で照合されるため、shell_command や裸の ctx_* 名を削らずに、公式の値をそのまま使います。

{
  "hooks": {
    "PreToolUse": [{ "matcher": "local_shell|shell|shell_command|exec_command|Bash|Shell|apply_patch|Edit|Write|grep_files|ctx_execute|ctx_execute_file|ctx_batch_execute|ctx_fetch_and_index|ctx_search|ctx_index|mcp__", "hooks": [{ "type": "command", "command": "context-mode hook codex pretooluse" }] }],
    "PostToolUse": [{ "hooks": [{ "type": "command", "command": "context-mode hook codex posttooluse" }] }],
    "SessionStart": [{ "hooks": [{ "type": "command", "command": "context-mode hook codex sessionstart" }] }],
    "PreCompact": [{ "hooks": [{ "type": "command", "command": "context-mode hook codex precompact" }] }],
    "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "context-mode hook codex userpromptsubmit" }] }],
    "Stop": [{ "hooks": [{ "type": "command", "command": "context-mode hook codex stop" }] }]
  }
}

再起動後は、ctx stats で MCP を、ルーティング規則に当たるコマンドの実行でフックを、それぞれ分けて確認します。

その他のプラットフォーム

共通の前段は npm install -g context-mode です。

Cursor Marketplace は README が審査待ちと書いており、掲載までは local-folder 経路になります。フックの呼び出し形はどのホストでも共通です。

context-mode hook <platform> <event>

native ビルド

glibc 2.31 以上（Ubuntu 20.04+、Debian 11+、Fedora 34+、macOS、Windows）では prebuilt を使います。Node.js 22.5 以上で FTS5 があるときは、OS を問わず組み込みの node:sqlite に切り替わります。古い glibc では、ソースビルドに C++20 コンパイラ・Make・Python setuptools が必要です。Windows で native addon が欠けるときは、プラグインディレクトリで npm install better-sqlite3 --no-optional を実行します。

context-mode は Node を同梱しないため、ホストのプロセスから node が見えることも前提になります。

利用方法

ツールの引数

引数の正本は src/server.ts の server.registerTool で、ctx_search のみ src/search/ctx-search-schema.ts です。

language の enum は javascript / typescript / python / shell / ruby / go / rust / php / perl / r / elixir / csharp です。

サンドボックス実行

分析はコードで行い、ファイルの中身ではなく処理結果が文脈に入ります。

ctx_execute({
  language: "javascript",
  code: `
    const fs = require('fs');
    const files = fs.readdirSync('src').filter(f => f.endsWith('.ts'));
    files.forEach(f => {
      const lines = fs.readFileSync('src/'+f,'utf8').split('\\n').length;
      console.log(f + ': ' + lines + ' lines');
    });
  `
})

単一ファイルの処理では、内容が FILE_CONTENT 変数に入ります。

ctx_execute_file({
  path: "huge.log",
  language: "javascript",
  code: "const errs = FILE_CONTENT.split('\\n').filter(l => /ERROR|FATAL/.test(l)); console.log(errs.length + ' error lines');"
})

複数コマンドの実行と、その結果に対する検索をまとめて行えます。

ctx_batch_execute({
  commands: [
    { label: "README", command: "head -n 80 README.md" },
    { label: "Package", command: "cat package.json" }
  ],
  queries: ["authentication middleware", "entry point"],
  concurrency: 1
})

• timeout: 省略時は MCP ホストの RPC timeout が上限になります。
• background（ctx_execute のみ）: timeout 後もプロセスを残します。
• intent: 出力が約 5 KB を超えると FTS5 へ自動で索引し、該当箇所だけ返します。
• concurrency: 1〜8。I/O 向けで、CPU バウンドな処理は 1 のまま使います。

レスポンスは標準出力そのものではありません。buildExecuteEcho が実行したコードを最大 2,000 文字まで先頭に付け、ctx_execute_file ではパスも添えます。失敗時は標準エラーが返り、ctx_batch_execute は標準出力と標準エラーを結合します。読み込んだファイル全体が入らないという意味での節約であり、応答が結果 1 行だけになるとは限りません。

フックのルーティング判定

PreToolUse の判定は hooks/core/routing.mjs が持ちます。

インデックス作成

ctx_index({
  path: ".",
  source: "project:my-app",
  maxDepth: 5,
  maxFiles: 200
})

ctx_fetch_and_index({
  url: "https://example.com/docs",
  source: "Example docs"
})

複数 URL をまとめて取得できます。

ctx_fetch_and_index({
  requests: [
    { url: "https://example.com/a", source: "doc-a" },
    { url: "https://example.com/b", source: "doc-b" }
  ],
  concurrency: 4
})

• 既定 TTL は 24 時間です。
• ttl はミリ秒で、ttl: 0 はキャッシュをバイパスします。
• force: true でも再取得します。
• maxDepth の既定は 5、maxFiles は 200、respectGitignore は true です。

検索

ctx_search({
  source: "project:my-app",
  queries: ["authentication middleware", "token refresh"],
  limit: 2,
  sort: "relevance"
})

• sort: "relevance": プロジェクトの永続 ContentStore を BM25 の関連度順で検索します。
• sort: "timeline": 時系列で、ContentStore に加えて SessionDB と auto-memory も対象にします。
• contentType: "code" または "prose" を指定します。
• 引数名は queries に統一されています。単数形の query はスキーマに無く、MCP 経由では検証で落ちます。
• 返るのはチャンク全体ではありません。各ヒットは一致箇所の周辺 1,500 文字程度へ抜粋されるため、長いコードブロックは途中で切れます。
• limit のスキーマ既定は 3 ですが、ハンドラが通常時も Math.min(limit, 2) を適用します。連打を検知したあとは 1 クエリ 1 件です。limit: 5 と書いても 1 クエリあたり最大 2 件になります。

更新と削除

ctx_upgrade({})

context-mode upgrade --platform codex

--platform は MCP の clientInfo に基づく自動検出を上書きします。

ctx_purge({ confirm: true, scope: "project" })
ctx_purge({ confirm: true, sessionId: "7c8a-1234-5678-9abc-def012345678" })

• confirm: true で実行します。confirm: false は中止を返します。
• sessionId と scope: "project" の同時指定はエラーです。
• 引数が {confirm: true} だけの場合は scope: "project" として扱われ、標準エラーへ非推奨の警告が出ます。

CLI リファレンス

引数なしの起動は MCP サーバ（stdio）です。

context-mode                         Start MCP server stdio
context-mode index <path>            Index a file or directory
context-mode search <query...>       Search the FTS5 knowledge base
context-mode doctor                  Diagnose runtimes, hooks, FTS5, version
context-mode upgrade                 Fix hooks, permissions, and settings
context-mode hook <platform> <event> Dispatch a hook script
context-mode statusline              Print Claude Code status line
context-mode insight                 Open Insight dashboard

context-mode index . --source project:my-app
context-mode search "authentication middleware" --source project:my-app --limit 5
CONTEXT_MODE_DIR=/absolute/path context-mode

Claude Code の slash command は MCP ツールに 1 対 1 で対応します。

運用

稼働後の操作は次のとおりです。

• ホストが MCP 子プロセスとして context-mode を stdio で起動します。
• 診断は context-mode doctor または ctx_doctor です。
• 更新は context-mode upgrade または ctx_upgrade です。
• 削除は ctx_purge(confirm: true) だけです。
• セッション継続は --continue / --resume 付きの起動です。

起動

引数なしの CLI が MCP サーバ起動です。

context-mode

ストレージ根を差し替えるときは、起動環境に絶対パスを置きます。

CONTEXT_MODE_DIR="$HOME/.codex-context-mode" codex

空文字や空白のみの CONTEXT_MODE_DIR は未設定として扱われます。非空の値は絶対パスが必須で、相対パスは StorageDirectoryError になります。~ は展開されません。

停止

通常の停止はホストのセッション終了に追随します。開発時の残骸掃除は CONTRIBUTING の手順です。

pkill -f "context-mode.*start.mjs"

/ctx-upgrade は新しいファイルを入れる前に、同じプロジェクトの MCP プロセスを SIGTERM から SIGKILL の順で止めます。複数ウィンドウから同一プロジェクトの DB へ書くことは正規の使い方です（ADR 0001、busy_timeout 30000ms）。

状態確認

/context-mode:ctx-stats
/context-mode:ctx-doctor

context-mode doctor
context-mode index . --source project:my-app
context-mode search "authentication middleware" --source project:my-app

ctx_stats は読み取り専用です。統計が返ることは MCP 到達の証明であり、フックが信頼され発火していることの証明は別に確認します。

ログ確認

フックは標準エラーを /dev/null（Windows は \\.\NUL）へ閉じます。バグ報告用の一次診断は debug スクリプトです。

bash scripts/ctx-debug.sh

収集対象は、OS、ランタイム、better-sqlite3、アダプタ検出、設定（秘匿値はマスク）、フック検証、FTS5、executor、プロセス、セッション DB、環境変数です。

診断

CLI の context-mode doctor は次を確認します。

MCP ツールの ctx_doctor はサーバ内で [OK] / [FAIL] / [WARN] を返します。対象は runtimes、storage、server test、FTS5、hooks、version で、plugin registration は CLI 側の担当です。完全な診断は CLI の context-mode doctor になります。

更新

MCP の ctx_upgrade はアップグレード用のシェルコマンドを返します。実行後にセッションの再起動が必要です。

npm install -g context-mode@latest
context-mode upgrade

CLI の context-mode upgrade は、marketplace の同期、clone、同プロジェクトの MCP 停止、リビルド、キャッシュ修復、フック再配線、doctor 再実行を行います。OpenCode / KiloCode で plugin と mcp.context-mode が併存し、旧 MCP 接続の tools/list が空になったときも、このコマンドが古い mcp.context-mode だけを外します。

パージ

取り消せない破壊的操作です。confirm: true が必須です。

/clear と /compact は context-mode のデータを消しません。削除経路は ctx_purge だけです。

Insight

ctx_insight / context-mode insight は、ホストされたダッシュボードをブラウザで開きます。URL は https://context-mode.com/insight です。ローカルの Insight サーバは廃止されています。

セッション継続

--continue / --resume / /resume 付きの起動は source: "resume" として扱われ、前回セッションのイベントまたは未消費スナップショットを注入します。--continue なしの起動は source: "startup" の新規セッションで、ホストの会話は白紙から始まります。

PreCompact
  → SessionDB の events を読む
  → 優先度付き XML snapshot
  → session_resume に保存
SessionStart source compact
  → snapshot を取り出す
  → 構造化 events ファイルを FTS5 へ自動インデックス
  → Session Guide を注入

生のセッションイベントはコンテキストへ入りません。入るのは要約と ctx_search 用のクエリだけです。SessionStart は孤児の probe ID（pid-* 形）を消し、UUID のセッションは 7 日を超えたものを掃除します。content DB と sources は 14 日を超えると起動時に削除されます。

スケールと隔離

プロセスは「ホストの 1 セッションあたり MCP 1 つ」が正規です。リンクされた git worktree はセッション DB 名に __<8hex> を付けます。明示的に上書きするなら CONTEXT_MODE_SESSION_SUFFIX を使います（空文字は隔離無効）。

export CONTEXT_MODE_SESSION_SUFFIX=ci-job-123

ctx_search の連打防止はセッション ID 単位で効きます。

ベストプラクティス

CI/CD

• ジョブごとに CONTEXT_MODE_SESSION_SUFFIX を一意にします。
• 共有ランナーでは CONTEXT_MODE_DIR をジョブ専用の絶対書き込みパスにします。
• 内部ネットワークへの取得範囲を絞るときは CTX_FETCH_STRICT=1 を使います。
• チームで共有するフックは、ポータブルな context-mode hook <platform> <event> 形にします。マシン固有の絶対パスは doctor が FAIL します。
• オフライン CI では npm install -g context-mode@<version> とバージョンを固定すると再現性が上がります。

マルチ環境

• 既定のストレージはアダプタの configDir 配下です。
• CONTEXT_MODE_DIR=/abs は <root>/sessions と <root>/content に分かれます。
• プラットフォーム検出が曖昧なときは CONTEXT_MODE_PLATFORM で固定します。
• OMP は ~/.omp/context-mode/、Pi は ~/.pi/context-mode/ を使い、共有しません。
• OpenCode は plugin: ["context-mode"] だけを書きます。
• Cursor はプロジェクトの .cursor/hooks.json がユーザーの ~/.cursor/hooks.json より優先されます。

リソース制限

• 個別の ctx_search を連打するより ctx_batch_execute(commands, queries) にまとめます。
• ディレクトリの索引は maxFiles / maxDepth / --ext / --exclude で上限を置きます。
• 取得の TTL 既定は 24 時間です。再取得は ttl: 0 または force: true です。
• 14 日のクリーンアップを前提に、長期的に残したい知識はプロジェクト外の正本へ置きます。

セキュリティ

サンドボックスはプロセス境界であり、OS レベルの隔離（seatbelt / bwrap / landlock）は実装されていません。子プロセスはホストのファイルシステムとネットワークを継承します。

実行ツールの承認は、任意コード実行の承認として扱うのが安全です。ctx_execute_file のパス検査が守るのは path 引数だけで、同じ呼び出しの code が開くファイルは対象外です。ctx_execute / ctx_batch_execute も同様に、コードからホストの FS とネットワークへ届きます。ホストの deny パターンだけでは隔離できないため、3 つの実行ツールを個別承認にするか、隔離した環境でホストごと動かす判断が要ります。

次の設定は、ホストのツール（Bash や Read）に対する許可・拒否の例です。意図的にプロジェクト外を読ませたい場合は permissions.allow に Read(...) を足します。

{
  "permissions": {
    "deny": [
      "Bash(sudo *)",
      "Read(.env)",
      "Read(**/.env*)"
    ],
    "allow": [
      "Bash(git:*)",
      "Read(/var/log/**)"
    ]
  }
}

• 評価順は deny > ask > allow です。
• ctx_fetch_and_index は http: / https: のみを許可し、クラウドのメタデータアドレス 169.254.0.0/16 は遮断します。
• MCP の tool_input は、秘密情報を示すキー名に一致した値だけを再帰的に [REDACTED] へ置き換えます。値の中身は検査しないため、URL のクエリ文字列やコード中に埋め込まれた秘密情報はマスクされません。

Elastic License 2.0 の Limitations は、実質的な機能一式をホスト型・マネージド型サービスとして第三者へ提供することを禁じています。

You may not provide the software to third parties as a hosted or managed
service, where the service provides users with access to any substantial set
of the features or functionality of the software.

設定管理

• グローバルバイナリ context-mode を PATH に置き、フックは context-mode hook <platform> <event> 形へ統一します。
• Claude Code は marketplace プラグインを正とし、MCP のみの登録は試用向けです。
• Node は >= 22.5.0 にそろえます。
• Windows の better-sqlite3 は npm rebuild ではなく npm install が正です。
• Cursor の Windows ローカルプラグインは robocopy /MIR で実体コピーします（symlink は辿られません）。

注意点

ドキュメントと実装、あるいは資料どうしで記載が食い違う箇所があります。導入判断に効くものを挙げます。

Stars 22,499 / forks 1,618 は 2026-09-13 時点の GitHub API の値で、時間とともに変わります。

トラブルシューティング

導入と診断でよくある症状です。

実行時の症状です。

Windows の Cursor へローカルプラグインを置く例です。

git clone https://github.com/mksglu/context-mode.git
cd context-mode
robocopy . "$env:USERPROFILE\.cursor\plugins\local\context-mode" /MIR

better-sqlite3 の復旧例です。

cd "$(npm root -g)/context-mode"
npm install better-sqlite3 --no-optional
context-mode doctor

まとめ

• context-mode は、ツール出力をサンドボックス実行と SQLite FTS5 へ迂回させ、処理結果と検索ヒットだけをコンテキストへ入れる MCP プラグインです。
• 内部は CLI・MCP サーバ・プロセス内プラグイン・フックディスパッチャ・アダプタ・Executor・SessionDB・ContentStore に分かれ、経路が違っても同じコアを共有します。
• 永続データはプロジェクト単位の SessionDatabase と ContentDatabase で、イベントは 1000 件上限、content は 14 日で掃除されます。
• 削減率はワークロードで大きく変わります。ログやスナップショットの迂回は 98%、文書・コード検索は 82% です。
• サンドボックスはプロセス境界までで OS 隔離はありません。実行ツールの承認は任意コード実行の承認として扱い、必要なら隔離環境で動かします。

この記事が少しでも参考になった、あるいは改善点などがあれば、ぜひリアクションやコメント、SNSでのシェアをいただけると励みになります！

参考リンク

• mksglu/context-mode
• README.md
• BENCHMARK.md
• LICENSE
• package.json
• 公式サイト
• docs/platform-support.md
• CONTRIBUTING.md
• src/adapters/types.ts
• src/server.ts
• src/session/db.ts
• src/store.ts
• src/db-base.ts
• hooks/core/routing.mjs
• ADR 0001 SessionDB multi-writer
• Issue #852 project boundary
• Issue #857 sandbox residual
• openai/codex#18491 updatedInput
• Anthropic Code execution with MCP
• Cloudflare Code Mode
• Claude Code Hooks