CTXでClaude Codeに動くメモリを足す

Claude Codeは毎セッションきれいに忘れる。
昨日決めた設計、採用しなかった案、触るべきファイル、前に説明した好みは、次のターミナルには残らない。

DEV Communityに出ていた CTXの記事は、この忘れ方にかなり直接刺している。
Claude Codeの UserPromptSubmit フックに入り、ユーザーのプロンプトがモデルへ届く前に、関連しそうな過去の判断、コード、ドキュメント、チャット履歴をローカルで引いて差し込む。

CLAUDE.mdのトークン管理では、進捗や判断をファイルやgitへ逃がす運用を書いた。
CTXはその次の面倒を狙う。
残した情報を「読んで」と明示するのではなく、プロンプト前に勝手に取りに行く。

UserPromptSubmitで先に差し込む

CTXの入り口はClaude Codeのhookだ。
READMEでは ctx-install が ~/.claude/settings.json に UserPromptSubmit と PostToolUse のhookを追加する。
DEV記事では pip install ctx-retriever && ctx-install、またはClaude Code側の /plugin install ctx@jaytoone が紹介されていた。

差し込む情報は大きく3系統ある。

系統	取りに行くもの	使いどころ
G1	git log由来の判断履歴	なぜその構成にしたか、なぜ別案を捨てたか
G2	コードとMarkdownドキュメント	関数名、関連ファイル、説明文書
CM	SQLite上の過去チャット	前に説明した方針やユーザー固有の文脈

G2は単なる全文検索だけではない。
READMEでは4種類のトリガーに分け、明示的なシンボル名、概念検索、依存関係、時間的な履歴で経路を変える。
依存関係の問い合わせではimport graphをBFSでたどり、テキスト検索だけでは拾いにくい「何がこれを使っているか」を拾う。

ここは Compresr Context Gateway と方向が違う。
CompresrはエージェントとLLM APIの間でコンテキストを圧縮するプロキシだ。
CTXはClaude Codeの入力直前で、必要そうな文脈を足す。
コンテキストを絞るのではなく、読むべきものを先回りして用意するアプローチに近い。

メモリを全部ベクトルDBに寄せない

CTXのよさは、メモリという言葉の中身を一つに潰していないところだ。
git logの判断履歴、コード検索、チャット履歴は、似ているようで取り出し方が違う。

設計判断はgit logに残っているなら、ベクトル検索よりコミット単位のほうが根拠を追いやすい。
コードはシンボル名やimport関係が強い。
過去チャットはBM25とオプションのベクトル検索で、ユーザーが前に言った断片を拾う。

YourMemory はMCPサーバとして recall_memory、store_memory、update_memory を公開し、BM25、ベクトル検索、グラフ、忘却曲線を混ぜる。
WUPHF はMarkdownとGitを正本にして、エージェントが残した知識をwikiへ昇格する。
どちらも「記憶の正本をどこに置くか」が大きなテーマだった。

CTXはもっとClaude Codeの操作面に寄っている。
正本を新しく作るというより、すでに手元にあるgit、コード、Markdown、Claude Codeのセッションログを、プロンプト直前に小さく束ねる。
この軽さは個人開発には合う。

数字は強いが測り方を見る

DEV記事ではメモリ再現のベンチマークとして、baselineが0.00、CTX v3が0.88のRecallを出したと書かれている。
10,000ターン超の実測では、注入した項目をClaudeが実際に引用した割合が全体39.6%、チャットメモリは52.6%だったという。

GitHub README側には別の評価もある。
合成ベンチマークではCTXがRecall@5 0.874、トークン使用5.2%、TES 0.776。
Flask、FastAPI、Requestsの外部コードベースではBM25より平均Recall@5が0.163高い。
一方でCodeSearchNet Pythonのような自然言語からコードを探す評価では、CTX Adaptive TriggerのRecall@5は0.740で、BM25の0.980に負けている。

この負け方はむしろ読みやすい。
CTXは万能検索ではなく、既知のコードベースでシンボルや依存関係が効くと強い。
自然文で「こんな処理をするコードを探して」と投げるなら、Dense EmbeddingやHybrid Dense+CTXのほうが向く。

Cloudflare Agent Memory のようなマネージド記憶層は、Facts、Events、Instructions、Tasksを分類し、HyDEやRRFまで含めて取り出しを設計していた。
CTXはそこまで大きな記憶基盤ではない。
代わりに、Claude Codeの1プロジェクトで「今このプロンプトに足すもの」を速く選ぶ。

入れる前に見る穴

CTXはローカル専用で、LLM呼び出しなし、必須テレメトリなしと書かれている。
PyPIの ctx-retriever は2026-05-02時点で0.3.11、MITライセンス、Python 3.9以上。
GitHubリポジトリも2026-05-02に更新されていた。

hookの衝突がある。
ctx-install は既存hookを上書きせず、コマンド文字列で重複排除すると書かれているが、Claude Codeをすでにhook運用している環境では ~/.claude/settings.json の差分を見たほうがいい。

注入の癖もある。
プロンプト前に関連ファイルを勝手に足す仕組みは便利だが、古い判断や誤った実装も一緒に持ってくる。
READMEには [fix] タグで既存実装への引きずられを抑える仕組みがある。
修正タスクで過去文脈が強すぎると、壊れた設計を再利用する方向に寄るからだ。

規模の制約もある。
READMEのHook Performanceでは、2,000ファイル超のコードベースは自動スキップされる。
小中規模のプロジェクトで、過去判断や関連ファイルを毎回説明している人には合う。
巨大モノレポや未知のコードベース探索を任せたいなら、ASTベースのindexerや専用RAGを別に見るほうがよさそうだ。

どのメモリが何を残すか

CTXだけ見ても「メモリ」の全体像はわからない。
ここ半年で出てきたツールを並べると、そもそも解いている問題が違う。

ツール	差し込み方	保存先	セッション跨ぎ
CLAUDE.md	セッション開始時に自動読込	プロジェクト内ファイル	○（手動更新）
Claude Code auto-memory	セッション開始時に自動読込	`~/.claude/projects/` 配下	○（会話から自動蓄積）
CTX	毎プロンプト前にhookで注入	git log / ソースコード / SQLite	△（チャット履歴のみSQLiteに残る）
YourMemory	MCPでstore/recall	SQLite + ベクトルDB	○（忘却曲線で減衰）
WUPHF	MCPでwiki読み書き	Markdown + Git	○（複数エージェント共有）
Cloudflare Agent Memory	API経由	Durable Objects + Vectorize	○（マネージド、4分類で構造化）

大きく2つに分かれる。
セッション内で関連文脈を引いてきて注入する検索系と、セッションを越えて情報を残す永続系だ。

CTXは検索系に振り切っている。
gitとコードとチャット履歴から関連する断片をプロンプト前に拾うだけで、新しい記憶を書き出す仕組みは持っていない。
Compresrも永続化はしないが、あちらはコンテキスト圧縮なので記憶とは方向が逆だ。

永続系はさらに「何を」「どう」残すかでばらける。

Claude Codeの組み込みauto-memoryは会話からユーザーの役割やフィードバックを拾い、次のセッション冒頭で自動読込する。
プロジェクト単位で分離されるから、リポジトリごとに別の記憶が溜まる。
CLAUDE.mdも毎セッション読まれるが、あちらはルールとテンプレの静的な置き場で、会話から勝手に育つものではない。

YourMemoryは明示的にstore/recallしないと動かない代わりに、忘却曲線で古い記憶のスコアを下げる。
長く使うほどゴミが溜まる問題を「忘れる」側から対処している。

WUPHFは個人用ではなくチームwikiだ。
複数エージェントの作業ログや判断根拠をMarkdownに書き出し、Git履歴で誰がいつ書いたか追跡する。

Cloudflare Agent MemoryはFacts、Events、Instructions、Tasksの4分類で記憶を構造化するマネージドサービスで、HyDEやRRFまで含めた検索を提供する。
個人プロジェクトの記憶というよりプロダクション向けインフラだ。

arXivのOCR-Memoryはまた違う方向で、エージェントの作業履歴をテキストではなく画像に変換して検索する。
テキスト要約で細部が消える問題に対する研究段階の解答だ。

個人プロジェクトには何を足すか

Claude Codeで個人プロジェクトを回している場合、ほとんどの面倒はCLAUDE.mdとauto-memoryで潰せる。
プロジェクトの規約やテンプレはCLAUDE.mdに書き、好みや指摘の蓄積はauto-memoryが勝手にやる。
追加インストールは不要。

困るのはセッションを跨いだコード文脈だ。
昨日読んだファイル、先週の設計判断、試してダメだった方針。
auto-memoryの守備範囲はユーザーの好みや役割であって、コードの文脈ではない。
CLAUDE.mdに全部書くと肥大化して、本当に読んでほしいルールが埋もれる。

CTXはここに入る。
プロンプトのたびにgit logやソースやチャット履歴から関連する断片を引いてくるから、「あのファイル見て」「あの方針にした理由は」を毎回言わなくて済む。
ただしCTXは記憶を新しく書き出す仕組みではなく、既存の情報を検索して注入するだけだ。
gitとコードとチャット履歴が手元にある限り動くが、それ以上の永続化はしない。

YourMemoryは、コードに残りにくい知見を蓄積したい場面で出番がある。
「このAPIは将来廃止予定」「このライブラリは相性が悪かった」のような判断を明示的にstoreして、忘却曲線で古い記憶を沈める。
MCPサーバを立てる手間はかかる。

WUPHFは一人で使うには重い。
複数人・複数エージェントで判断根拠を共有するwikiで、個人の記憶層とは射程が違う。
Cloudflare Agent Memoryはプロダクトに記憶基盤を組み込むインフラなので、比較対象自体がズレている。

個人でClaude Codeを使うなら、CLAUDE.md + auto-memoryで始めて、セッション跨ぎのコード文脈で困ったらCTXを足す、が最小構成になる。

1Mコンテキストでも足りない

これだけメモリツールが出てくると、そもそもなぜ作るのかが気になる。
Claude（1Mトークン）、Gemini（1Mトークン）、OpenAIのCodex（1Mトークン）と、主要なコーディングエージェントのコンテキストウィンドウはどれも1M前後に揃った。
全部突っ込めばいいのでは、と思うのが自然だ。

足りない。
中規模プロジェクト（ファイル2,500個程度）でソースコードだけで500K〜750Kトークンになる。
会話履歴、ツール出力、diff、エラーログを足すと、1Mウィンドウでもセッション後半には埋まる。
Next.jsモノレポ（27,000ファイル超）のコードレビューでは1回のスキャンで739Kトークンを消費したという報告がある。
中規模でぎりぎり、大規模は無理だ。

テキストと画像で1つのプールを食い合う

公称1Mトークンはテキストだけの上限ではない。
画像、動画、音声があれば、それらも同じ1つのコンテキストウィンドウからトークンを消費する。
テキストと画像で別枠があるわけではなく、同じプールを食い合う構造だ。

各モデルのトークン化ルールは微妙に違う。

Claudeは画像を512×512のタイルに分割し、85ベース + タイル数×170トークンで計算する。
簡易的には width × height ÷ 750 で概算できる。
1080pのスクリーンショット1枚で約1,600トークン。
Opus 4.7では長辺の上限が2576pxに拡がって、高解像度画像は1枚4,800トークン近くまでいく。

Geminiは768×768のタイルで258トークン。
テキストと比べると画像単体のトークン効率はClaudeより良いが、動画と音声がある。
動画は1fps抽出で1フレーム258トークン。
音声は1秒あたり32トークン。
1分の動画を渡すと映像だけで15,480トークン、音声込みで17,400トークン超になる。
コードレビュー中にデモ動画を渡すとテキストの枠が一気に削れる。

OpenAIはClaudeとほぼ同じタイル方式で、85ベース + 512×512タイル×170トークン。
1024×1024の画像で765トークン。
ただし低解像度モードなら1枚85トークン固定で、UIの概要確認程度ならこちらが使える。

実際の影響はどの程度か。
Claude Codeでエラー画面のスクショ5枚、UI確認3枚を渡すセッションを考えると、画像だけで約13,000トークン。
1Mに対して1.3%だから些細に見えるが、これにソースコード500K + 会話履歴100K + ツール出力200Kが乗る。
残り200Kのうち13Kが画像で消えるのは、セッション後半では無視できないサイズになる。

Geminiでデモ動画3本（合計5分）を渡すケースはもっと激しくて、映像と音声で87,000トークン超が飛ぶ。
テキストしか流さない前提で設計されたワークフローにマルチモーダルを混ぜると、実効容量が見た目以上に縮む。

長くても精度が落ちる

仮に詰め込めたとしても精度が落ちる。
Liu et al.の研究で、回答に必要なドキュメントをコンテキストの先頭から中間に移動しただけでQA精度が30%以上下がった。
先頭と末尾には注意が向き、中間に埋もれた情報を拾えない。
lost in the middleと呼ばれる現象で、RoPE（Rotary Position Embedding）の位置バイアスが原因とされている。
Du et al.はさらに厳しくて、無関係なトークンをホワイトスペースに置き換えてノイズを完全に消しても、入力長が増えるだけで精度が13.9〜85%落ちた。
長い入力それ自体がペナルティになる。

コスト

Claude Sonnet（入力$3/Mトークン）で200Kトークンを毎回投げると1回$0.60。
知識グラフで関連コードだけ抽出したケースでは739Kトークンが15Kトークンまで減り、49倍のコスト削減になった。
別の報告では412Kトークンが3.4Kトークンに圧縮されて99.2%削減。
プロンプトキャッシュがあればキャッシュヒット分は10%課金になるが、新規の差分は毎回フル課金だ。

結局「選別」の問題

メモリツールが解いている問題の実態は「記憶」より「選別」に近い。
2,500ファイルのプロジェクトで1つのタスクが触るのはせいぜい5〜15ファイル。
全部入れると精度が落ち、コストが跳ね、レイテンシも伸びる。
CTXがhookで関連コードを差し込むのも、YourMemoryがMCPでrecallするのも、必要な断片だけ選んで入力に足す仕組みだ。
セッションを跨ぐかどうかは、選別の対象が過去チャットやgit logにまで広がるかの違いでしかない。

同じ1Mでも中身が違う

公称1Mトークンで横並びに見えるが、そのウィンドウをどう使うかはエージェントごとにまるで違う。

Claude Codeはセッション内でコンパクションを回す。
古いツール出力や会話のやりとりを要約・圧縮して、新しい入力の枠を空ける。
1Mは静的なバッファではなく、常に中身が入れ替わるローリングウィンドウだ。
50メッセージ前のコード解析結果は原文で残っていない。
CLAUDE.mdとシステムプロンプトが常駐枠を占め、直近のやりとりと圧縮された要約で埋まる。
「容量」が1Mあっても、アクセスできるのは直近の一部と、圧縮で情報が落ちた過去だけだ。

OpenAIのCodexはまた違う。
タスクごとにクラウド上のサンドボックスが立ち上がり、完了したら消える。
1Mのウィンドウは1タスクの中でしか生きない。
前のタスクで読んだファイルや出したdiffは次のタスクに引き継がれない。
セッションという概念がそもそも薄く、記憶の蓄積がアーキテクチャレベルで起きない。

Geminiは1Mを一括で埋められる。
コードベースを丸ごと流し込んで「このバグを直して」ができる。
ただしlost in the middleはGeminiにもあり、先頭と末尾に注意が偏る。
大量に入れられることと、入れた情報を均等に使えることは別の話だ。

コンパクションで回すか、タスクごとに使い捨てるか、一括で埋めるかで、同じ1Mでも「過去の文脈をどこまで保てるか」がまったく違う。
CTXのようなメモリツールが要るのは、容量不足だけでなく、エージェントのアーキテクチャ自体が文脈を捨てる前提で動いているからだ。