7月10日、Vigetが「Giving Claude Code A Persistent Memory」と題した記事を公開した。Claude Codeにセッションをまたいだ永続的なメモリ機能を自作実装する方法と、6週間の実運用データが詳しく紹介されている。
Claude Codeは強力なAIコーディングエージェントだが、セッションをまたいで文脈を記憶できないという構造的な制約がある。毎回「あのプロジェクトでは○○という方針でやっている」と説明し直す手間は、使い込むほど積み重なる。この記事では、その問題をシェルスクリプトと最小限のLLM呼び出しで解決するシステムの設計と実装が紹介されている。
なお、Claude Codeがメモリレス設計になっているのは意図的なトレードオフだ。公式ドキュメントによれば、各セッションを独立させることでコストの予測可能性を高め、意図しないコンテキスト汚染を防ぐ狙いがある。一方、MCP（Model Context Protocol）を使った外部メモリ統合も選択肢としては存在するが、サーバー構築や認証管理が必要になる。本記事のアプローチはシェルスクリプトとClaude Codeのフック機能だけで完結するため、インフラ依存を最小限に抑えられる点が特徴だ。
4ステップで構成される「知識のフィードバックループ」
このシステムは以下の4つのステップで動作する。
- Capture（収集） — セッション終了時にフックが発火し、会話内容をプライベートな「vault（金庫）」にダンプする。LLMを呼び出さない純粋なシェル処理なのでコストゼロ。
- Distill（蒸留） — 毎夜、ローカルジョブが未処理のセッションを読み込み、「知識ノート」に圧縮する。平均約27倍の圧縮率を実現。モデルは元記事記載の
claude-sonnet-4系に固定してコストを抑えている。 - Retrieve（取得） — プロジェクトでClaude Codeを開くと、フックが知識のインデックスをコンテキストとして注入する。Claudeは必要に応じて個々のノートをオンデマンドで参照する。
- Surface（提案） — 蒸留処理が複数セッションにまたがるパターンを検出すると、スキル提案を
inbox/proposals.mdに書き出す。自動適用はしない。人間がレビューして採否を決める。
フィードバックループが核心だ。ステップ2で書かれた知識がステップ3で読み返される。使えば使うほど、vaultは自動で賢くなっていく。
コスト最小化への徹底したこだわり
設計上の最も重要な判断は、LLM呼び出しを可能な限り減らすことだ。
Captureはコストゼロ。フックはセッション内容をダンプするだけで終わる。LLMへの問い合わせも要約も行わない。
Distillはトークンを絞る。Bashスクリプトがツール呼び出しや不要な情報をすべて除去してから、実際の会話部分だけをLLMに渡す。
Retrieveはインデックスのみ注入。フックが全ノートの内容をコンテキストに詰め込むのではなく、ノートへのリンク一覧（インデックス）だけを渡す。Claudeは必要なノートだけをオンデマンドで読む。vaultが数百件規模に育っても、セッションあたりのトークンコストが膨らまない設計だ。
Surfaceは自動化しない。繰り返しパターンが見つかっても、スキルの自動作成は行わない。スキルはトークン消費が大きくなり得るため、知らないうちに作成されることを防ぐ安全策でもある。
スコープの設計
知識はできる限り狭いスコープに保つ。あるプロジェクト内のパターンはそのプロジェクトのローカルにとどまる。2つ以上のプロジェクトをまたいで現れたパターンが、初めてグローバル知識の候補として提案される。グローバルな知識ベースが無用に肥大化しない仕組みだ。
6週間の実績
実際に6週間運用した結果が報告されている。
- 80件以上のセッションを6プロジェクトにわたって収集
- 70件以上の知識ノートに蒸留
- セッションデータを約27倍に圧縮
- 1夜あたりのコストは約0.85ドル（元記事では「月約20ドル」と記載されているが、0.85×30で計算すると約25ドル前後になる。Haiku使用でさらに削減可能とも述べられており、実際の運用ペースや処理量によって変動するものと思われる）
- 7件のスキル提案を生成
また、蒸留後に自動更新されるダッシュボードも用意されており、vaultの状態を常に把握できる。
まとめ
このアプローチの特徴は、外部サービスやMCPサーバーを一切使わず、Claude Code標準のフック機能とシェルスクリプトだけで完結する点にある。コードはすべてローカルで動き、会話内容が外部に送信されるのは蒸留時のLLM呼び出しのみだ。プライバシーを重視しつつ、毎回ゼロから説明し直す手間をなくし、かつトークンコストを現実的な水準に抑えたこの設計は、Claude Codeをヘビーに使うエンジニアにとって参考になる構成だ。
詳細はGiving Claude Code A Persistent Memoryを参照していただきたい。
