Claude Codeはセッション中は非常に強力ですが、セッション間では記憶を失ってしまいます。新しい会話を始めるたびにゼロからスタートし、複雑なプロジェクトでは実際の作業に入る前に、アーキテクチャや決定事項、コーディング規約を再度説明する必要があります。この問題を解決するため、開発者がオープンソースのMCPサーバー「memory-mcp」を構築しました。本記事では、その革新的なアーキテクチャについて詳しく解説します。
この記事のポイント
- Claude Codeの既存機能（CLAUDE.mdとフック）を活用した永続メモリの実現
- 2層構造のメモリアーキテクチャでコンテキストウィンドウを効率的に活用
- 外部データベースや特別なプロトコル不要のシンプルな設計
設計を決定づけた制約条件
Claude Codeには、セッション開始時に必ず「CLAUDE.md」というファイルを読み込む機能が組み込まれています。このファイルに書かれた内容は、Claudeの初期コンテキストの一部となります。これはClaude Codeの基本動作として実装されており、開発者が活用できる重要な特性です。
さらに、Claude Codeにはフックシステムが備わっています。フックを使うと、以下のタイミングでシェルコマンドを実行できます：
- Stop: 各レスポンス後に実行
- PreCompact: コンテキスト圧縮前に実行
- SessionEnd: セッション終了時に実行
この2つの機能を組み合わせることで、永続メモリに必要なすべてが揃います。フックが知識を捕捉し、CLAUDE.mdがそれを配信します。カスタムプロトコルも外部データベースもClaude Codeの動作変更も一切不要という、非常にエレガントな解決策です。
2層構造のメモリアーキテクチャ
すべてのメモリが同じ重要度を持つわけではありません。毎セッションで必要なコンテキストもあれば、時々しか必要としないものもあります。すべてをCLAUDE.mdに入れるとコンテキストウィンドウを浪費してしまいます。一方、すべてをデータベースに入れると、Claudeが基本的な情報を得るために能動的に検索しなければなりません。
この問題を解決するのが2層構造のアーキテクチャです。
Tier 1: CLAUDE.md（自動読み込み層）
約150行程度のコンパクトなブリーフィングドキュメントです。自動生成・自動更新され、信頼度とアクセス頻度でランク付けされた最も重要なプロジェクト知識を含みます。Claudeは起動時にこれを自動的に読み込むため、プロンプトは一切不要です。
この層には以下のような情報が適しています：
– プロジェクトの基本アーキテクチャ
– 主要な技術的決定事項
– コーディング規約やスタイルガイド
– 頻繁に参照される設定情報
Tier 2: .memory/state.json（オンデマンド層）
完全なメモリストアで、容量制限はありません。これまでに捕捉されたすべての事実、決定、観察が保存されています。会話中にMCPツールを通じてアクセス可能で、以下の方法で検索できます：
- キーワード検索
- タグベースのクエリ
- 自然言語での質問
- 関連情報の取得
この2層構造により、重要な情報は常に利用可能でありながら、詳細な履歴情報も必要に応じて取得できるバランスの取れた設計となっています。
知っておくと便利なTips
- CLAUDE.mdは150行程度を目安に、最も重要な情報に絞り込む
- フックシステムを活用して、セッション終了時に自動的に知識を保存する仕組みを構築できる
- 2層構造を意識し、頻繁にアクセスする情報とアーカイブ的な情報を分離する
- memory-mcpはオープンソースなので、自分のワークフローに合わせてカスタマイズ可能
まとめ
Claude Codeのセッション間での記憶喪失は、多くの開発者が経験する課題です。memory-mcpは、Claude Codeの既存機能であるCLAUDE.mdファイルとフックシステムを巧みに活用し、外部データベースや複雑なプロトコルなしで永続メモリを実現しています。2層構造のアーキテクチャにより、コンテキストウィンドウを効率的に使いながら、必要な情報にいつでもアクセスできます。この設計思想は、既存のシステムの制約を創造的に活用するという点で、他のツール開発にも応用できる優れたアプローチと言えるでしょう。
📎 元記事: https://dev.to/suede/the-architecture-of-persistent-memory-for-claude-code-17d
コメント