echocache

echocache — キャッシュされた LLM 応答のための MCP サーバー

キャッシュされた LLM 応答のための MCP サーバーです。高コストなサーバー応答を HTTP キャッシュに保存する方法であり、ブラウザーが静的アセットをキャッシュする方法とは異なります。一度回答した質問をもう一度尋ねると、答えを再導出する代わりに、保存された答えが返されます。

2 種類のキャッシュ方式に着想を得た、2 つの検索方法を用意しています。

• 完全一致、HTTP 方式 — cache_get / cache_set は (model, prompt, params) をキーとして使用し、ttl_seconds と stale_while_revalidate_seconds は Cache-Control のように、新鮮、古い、期限切れの状態を扱います。
• ナレッジグラフによる再呼び出し — 保存された各エントリは、小規模な類似性グラフのノードになります。cache_query は完全一致のキーだけでなく、意味に基づいて関連エントリを検索します。cache_related はグラフのエッジ（自動リンクされた「類似」エントリ、または明示的な「派生元」親エントリ）をたどり、エージェントが作業を一からやり直す前に、すでに判明しているすべての情報を提示します。cache_invalidate は、元となる情報が変更された際に、「派生元」エッジをたどって無効化を連鎖させることができます。

標準的な stdio MCP サーバーとして動作するため、Claude Code、Claude Desktop、Cursor、VS Code + Copilot、その他あらゆる MCP 対応ホストで利用できます。詳しくは、以下のインストールと、接続されたエージェントが従うべきツール使用プロトコルを説明するAGENTS.mdをご覧ください。

何のためのものか、そして何のためのものではないか

エージェントが読んだ内容ではなく、導き出した結論をキャッシュします。これが設計のすべてです。直感的な使い方は誤りなので、率直に述べておく価値があります。キャッシュしたファイルの読み取り結果を返しても、読み手が消費するトークン数はファイルを読んだときとまったく同じです。内容をコンテキストに取り込む必要があるためです。つまり、ヒット率がどれだけ高くても、ファイルの読み取りをキャッシュしても何も節約できません。エージェントがファイルを再出力して保存するなら、見返りのない出力料金分のトークンまで支払うことになります。キャッシュが役に立つのは、ヒットによって何かを再生成する必要がなくなる場合だけです。

効果がある場合と、測定の結果、効果がないとわかった場合：

• 最も効果がある：コストのかかる調査や判断。 このプロジェクト自身の履歴にある実際の22回のツール呼び出しからなる調査チェーンでは、255トークンの結論を得るまでに出力トークンを37,119消費していました。出力料金を考慮すると、結論を返す場合との差は728倍です。その結論を一度再利用するだけで、書き込みコストの約145倍を回収できます。同じ方法で、ウェブ検索から新たに導いた設計上の判断もライブ環境で検証しました。異なる言い回しでも正しく想起され、表面的な語彙が似ている無関係なエントリーよりも適切に上位に表示されました。このプロジェクト自身の履歴では、まだ再発することは確認されていません。しかし、1回のヒットで十分大きな効果があるため、ファイルの読み取りとは異なり、頻度が低くても不採用の理由にはなりません。
• 条件付きで効果がある：セッションをまたいだ再把握。 エージェントがコードベースを読んで理解し、セッションが終わった後、別のセッションで同じ理解が再び必要になる場合です。express/lib（6ファイル、62KB）では、ソースを読み直すと15,504トークンかかるのに対し、キャッシュした概要を返すと549トークンで済み、約28分の1です。後のセッションで幅広い理解が本当に必要な場合には、この効果が得られます。特定の答えを1つだけ必要としているなら、grepして必要な箇所だけを読み、約900トークンで済むため、キャッシュは太刀打ちできません。
• 効果がない：並列ディスパッチで読み取りを置き換えること。 コードレビューの1回のディスパッチで、30のサブエージェントが、別のエージェントがすでに読んだ内容を約374,000トークン分取得しました。しかし、166回の読み取りのうち127回ではoffset／limitを使っており、すでにファイル全体ではなく一部だけを取得していました。こうした部分読み取りを共有の導出結果で置き換えると、実際の方法より27％悪いという測定結果になりました。grepはすでに低コストで正確な手がかりを示すため、キャッシュしたマップは同じ土俵で競い、負けてしまいます。

この3つが示すルールは、grepでは再構成できないものをキャッシュすることです。結論、判断、何かがそのようになっている理由、単一の検索では明らかにならない複数ファイルにまたがる統合的な情報、調査結果、何かが存在しないという事実です。場所の情報はキャッシュしません。grepなら、キャッシュを参照するより低コストで見つけられます。ファイルもキャッシュしません。

キャッシュしたエントリーにファイルパスや行番号が含まれる場合は、読み手を正確な詳細へ案内するためのものであり、その内容の読み取りを置き換えるためではありません。また、一致する情報を探すときはcache_getではなくcache_queryを使ってください。後のセッションや別のエージェントは、書き手と同じ言い回しで質問するとは限らないためです。

これは、ファイルを読まずに済ませる方法でも、信頼できる唯一の情報源でも、同じ会話内で使うprompt cachingの代替でもありません。会話内でのprompt cachingのほうが安価で、サーバーも必要ありません。echocacheは、それを生み出したコンテキストが終了した後も保持する必要のある結果のためのものです。

Claude Code で無料ですでにできること

ホストが Claude Code だけであれば、Claude Code 自体の永続メモリですでにこの仕組みの中核を実現できます。結論を、元になったファイルではなくメモリファイルに書き込み、後のセッションで作業をやり直す前に読み戻します。これは、このプロジェクトがたどり着いたのと同じルールで、無料で利用でき、登録するサーバーも不要です。このプロジェクトの構築で得られた知見と測定結果も、echocache 自体ではなくそこに保存されています。つまり、このツールを生み出した調査そのもののキャッシュには使われていないという点にも注目してください。

実際に異なる点を、重要度の高い順に示します。

• プロジェクト間の共有。 Claude Code のメモリは、1 つのプロジェクトディレクトリに限定されます。echocache は、マシン上のどのプロジェクトからでも登録できる 1 つの SQLite ファイルなので、あるリポジトリで得た結論を別のリポジトリから照会できます。これは実際に可能ですが、実証はされていません。このプロジェクトの履歴を見ると、結論がセッションをまたいで実際に再利用された例はゼロであり、プロジェクト間での再利用は、それよりもさらに高いハードルです。
• セマンティック検索。 cache_query は、表現の仕方や保存先のファイルに関係なく、意味に基づいて一致する内容を見つけます。メモリは、常時読み込まれるインデックスと、何を開くかについてのエージェント自身の判断によって取得されます。ベクトル検索はありません。
• ホストに依存しないこと。 Cursor、VS Code、Claude Desktop、その他の MCP クライアントから利用できます。メモリは Claude Code 専用の機能です。
• 明示的な鮮度管理。 TTL／stale-while-revalidate による鮮度管理と、ハッシュベースの derived_from 無効化により、ソースが古くなると自動的に検出されます。メモリにはそのどちらもなく、エージェントがたまたま気づいた場合にのみ古さが検出されます。

1 人のユーザーが 1 つのホスト上で 1 つのプロジェクトだけを扱うなら、メモリによって、この仕組みの価値の大部分をすでに無料で得られます。echocache の実際の価値として残るものは、「LLM の応答をキャッシュする」という説明よりも範囲が狭く、メモリストアを共有していないプロジェクト間やホスト間で、導出結果を共有することにあります。そして、この文書にある他のすべての内容と同じ方法で測定されるまでは、この限定的な用途は未検証なだけではなく、実証されていません。

インストール

クローンやビルドは不要です。npm から直接登録できます。

Claude Code

claude mcp add echocache -- npx -y echocache

Claude Desktop / Cursor / VS Code — ホストの MCP 設定に stdio エントリを追加します （claude_desktop_config.json、.cursor/mcp.json、.vscode/mcp.json）。

{
  "mcpServers": {
    "echocache": {
      "command": "npx",
      "args": ["-y", "echocache"]
    }
  }
}

OpenCode — opencode.jsonc にエントリを追加します（グローバル設定は ~/.config/opencode/opencode.jsonc、またはリポジトリのルートにあるプロジェクトレベルの設定）。

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "echocache": {
      "type": "local",
      "command": ["npx", "-y", "echocache"],
      "enabled": true
    }
  }
}

その他の MCP 対応ホストでも同じ起動コマンドを使います。異なるのは設定ファイルだけです。次に、キャッシュを「いつ」使うべきかエージェントが把握できるよう、AGENTS.md を参照させてください。キャッシュ対象を誤るとトークンの節約ではなく消費につながるため、接続設定よりもプロトコルのほうが重要です。

使用プロトコルはスキル（echocache-cache、echocache-gain）としても提供され、Claude Code 用の codebase-orienter サブエージェントも含まれています。このリポジトリをクローンした環境では、.claude/skills/ と .opencode/skills/ から自動的に検出されます。npm パッケージにも含まれていますが、ホストは自身のスキルディレクトリにあるスキルしか検出しないため、npm install -g echocache の後に一度インストールしてください。

# Claude Code
mkdir -p ~/.claude/skills ~/.claude/agents
cp -r "$(npm root -g)"/echocache/.claude/skills/echocache-* ~/.claude/skills/
cp "$(npm root -g)"/echocache/.claude/agents/codebase-orienter.md ~/.claude/agents/

# OpenCode
mkdir -p ~/.config/opencode/skills
cp -r "$(npm root -g)"/echocache/.opencode/skills/echocache-* ~/.config/opencode/skills/

設定

すべての設定は環境変数で指定します。いずれも任意です。

変数	デフォルト	意味
ECHOCACHE_DB_PATH	~/.echocache/cache.db	SQLite ファイルの場所
ECHOCACHE_MAX_ENTRIES	10000	保持するエントリー数の LRU 上限
ECHOCACHE_MAX_BYTES	268435456 (256MB)	保持するレスポンスバイト数の LRU 上限
ECHOCACHE_DEFAULT_TTL_SECONDS	未設定（期限なし）	呼び出し元が指定しなかった場合の有効期間。エントリーには引き続き LRU 上限が適用されます
ECHOCACHE_SIMILARITY_THRESHOLD	0.25	エントリーを自動リンクする類似度の下限
ECHOCACHE_LINK_CANDIDATE_POOL	500	新しい書き込みとの比較対象となる最近のエントリー数
ECHOCACHE_ENCRYPTION_KEY	未設定	64 桁の 16 進数（32 バイト）。保存時の AES-256-GCM 暗号化を有効にします

データベースのディレクトリは 0700、ファイルは 0600 で作成されます。エントリーの内容も保存時に暗号化するには、暗号化キーを設定します。

export ECHOCACHE_ENCRYPTION_KEY=$(node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")

暗号化の有効化または無効化には、新しいデータベースが必要です。インプレース移行には対応していません。また、キーとデータベースが一致しない場合は、後の読み取り時に失敗するのではなく、起動時に拒否されます。

ツール

ツール	用途
cache_get	完全一致検索。鮮度は新鮮／古い／期限切れで判定します
cache_set	結果を保存し、類似性グラフに自動リンクします
cache_query	キャッシュ内のすべてのエントリーを対象にセマンティック検索します
cache_related	1 つのエントリーから、リンクされたエントリーへグラフをたどります
cache_invalidate	エントリーを削除します。依存するエントリーを連鎖的に削除することもできます
cache_stats	完全一致のヒット率、queryHits／queryMisses、提供したトークン数を表示します

すべてのツールは 1 つの SQLite ファイルを使用します。このサーバーを登録したすべてのプロジェクトで共有されるため、あるリポジトリで得られた結論を別のリポジトリから検索できます。別々のプロセスからの同時読み取りと書き込みは例外的なケースではなく、想定されている動作です。

開発

git clone https://github.com/kskurtveit/echocache && cd echocache
npm install
npm run check        # typecheck + tests
npm start            # or: npm run dev

アーキテクチャとモジュールのリファレンスについては、CLAUDE.md を参照してください。

ライセンス

MIT