Claude Codeでメモリ永続化を実現するClaude-memの使い方

開発期間中の数週間にわたるあらゆるアーキテクチャ上の決定、バグ修正、リファクタリングセッションをAIアシスタントが記憶していたらどうでしょうか？Claude-memは、ツール使用の観測を自動的にキャプチャし、それらを意味的要約に圧縮し、関連する履歴をすべての新しいClaude Codeセッションに注入することで、失われたコンテキストによる摩擦を解消します。

問題：AIアシスト開発におけるコンテキストの記憶喪失

すべてのClaude Codeセッションは白紙の状態から始まります。ターミナルを閉じたり、セッションから切断したりすると、Claudeはすべてを忘れてしまいます。プロジェクト構造、最近のリファクタリングの決定、デバッグの発見、アーキテクチャパターンなどです。これにより、コードベースを繰り返し説明する必要が生じ、冗長なコンテキストにトークンを消費し、ワークフローの継続性を妨げます。

開発者は現在、CLAUDE.mdファイルを手動で管理したり、別のドキュメントにメモを取ったり、セッションの開始時にプロジェクトのコンテキストを再説明したりすることで、この問題を回避しています。これらのアプローチは脆弱で時間がかかり、開発履歴の豊かな情報を完全にキャプチャすることはありません。Claude-memは、すべてのツール呼び出しを自動的に監視し、その出力を検索可能な意味記憶に圧縮し、必要なときにインテリジェントに関連コンテキストを取得することで、この問題を解決します。

💡

美しいAPIドキュメントを生成する優れたAPIテストツールをお探しですか？

開発チームが最大の生産性で共同作業できる、統合されたオールインワンプラットフォームをお探しですか？

Apidogはすべての要求に応え、Postmanをはるかに手頃な価格で置き換えます！

button

Claude-memのアーキテクチャを理解する

Claude-memは、Claude Codeのライフサイクルに組み込まれる永続的なメモリ圧縮システムとして動作します。ツール出力（通常1,000〜10,000トークン）をキャプチャし、ClaudeのAgent SDKを使用して約500トークンの意味的な観測結果に圧縮します。これらの観測結果はタイプ（決定、バグ修正、機能、リファクタリング、発見、変更）で分類され、関連する概念やファイル参照でタグ付けされた後、全文検索機能を備えたローカルのSQLiteデータベースに保存されます。

このシステムは、コンテキストをキャプチャするために5つのライフサイクルフックを使用します。

SessionStart: セッション開始時に以前のセッションからのコンテキストを注入
UserPromptSubmit: パターン認識のためにユーザーのクエリをキャプチャ
PostToolUse: すべてのツール実行とその出力を監視
Stop: Claudeが応答を終了したときにセッションの要約を生成
SessionEnd: セッションストレージの最終処理とクリーンアップ

このアーキテクチャは、プログレッシブ開示（Progressive Disclosure）を可能にします。これは、カバレッジとトークン効率のバランスをとる階層化されたメモリ取得システムです。履歴全体をコンテキストにダンプする代わりに、Claude-memは観測結果を層状に取得し、手動でのコンテキスト管理と比較して、セッションあたり約2,250トークンを節約します。

インストールとシステム要件

Claude-memには、Node.js 18.0.0以降、プラグインサポート付きの最新のClaude Code、およびJavaScriptランタイムとプロセスマネージャーとしてBunが必要です（不足している場合は自動インストールされます）。SQLite 3は永続ストレージのためにバンドルされています。このプラグインは、Windows、macOS、Linuxでクロスプラットフォームに動作します。

クイックスタートインストール

Claude-memは、プラグインマーケットプレイスから2つのコマンドで直接インストールできます。

/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem

インストール後、Claude Codeを再起動してください。プラグインは、プリビルドされたバイナリを自動的にダウンロードし、BunとSQLiteを含む依存関係をインストールし、セッションライフサイクル管理用のフックを設定し、最初のセッションでワーカーサービスを自動起動します。

claude-mem from the claude code plugin marketplace

ソースからの高度なインストール

開発またはテストのために、GitHub上のソースからクローンしてビルドしてください。

git clone https://github.com/thedotmack/claude-mem.git
cd claude-mem
npm install
npm run build
npm run worker:start

このアプローチは、プラグインを変更したり、Endless Modeなどのベータ機能を実行したりする必要がある場合に便利です。

インストール後の検証

インストール後、すべてが機能していることを確認してください。

プラグインのインストールを確認:

cat plugin/hooks/hooks.json

ワーカーサービスが実行中であることを確認:

curl http://localhost:37777/api/health

最近のワーカーログを表示:

npm run worker:logs

新しいClaude Codeセッションを開始してコンテキスト取得をテストします。初期プロンプトで以前のセッションからのコンテキストが自動的に読み込まれるはずです。

データストレージと設定

Claude-memは、すべてのデータを~/.claude-mem/にローカルに保存します。

データベース: ~/.claude-mem/claude-mem.db (FTS5検索付きSQLite)
PIDファイル: ~/.claude-mem/.worker.pid
ポートファイル: ~/.claude-mem/.worker.port
ログ: ~/.claude-mem/logs/worker-YYYY-MM-DD.log
設定: ~/.claude-mem/settings.json

デフォルトのデータディレクトリは環境変数で上書きできます。

export CLAUDE_MEM_DATA_DIR=/custom/path

設定オプション

設定は~/.claude-mem/settings.jsonで管理されます（初回実行時に自動作成）。主要な設定には以下が含まれます。

CLAUDE_MEM_CONTEXT_OBSERVATIONS: セッション開始時に注入される観測結果の数（デフォルト: 50）
CLAUDE_MEM_FOLDER_INDEX_ENABLED: フォルダー内のCLAUDE.mdファイルの自動生成を有効/無効にする
AIによる圧縮のためのモデル選択
ワーカーのポートとホストの設定
ログレベルの設定

Claude-memがコンテキストをキャプチャし処理する方法

claude-memを有効にしてClaude Codeを使用すると、システムはすべてのツール呼び出しを自動的にキャプチャします。Claudeがファイルを読み込んだり、bashコマンドを実行したり、globパターンで検索したり、コードを編集したりするたびに、claude-memはその入力と出力を監視します。

ワーカーサービスはこれらの観測結果を処理し、以下の情報を抽出します。

タイトル: 何が起こったかの簡単な説明
サブタイトル: 追加のコンテキスト
ナラティブ: アクティビティの詳細な説明
事実: 要点としての主要な学習
コンセプト: 検索に関連するタグとカテゴリ
タイプ: 分類（決定、バグ修正、機能、リファクタリング、発見、変更）
ファイル: 読み込まれたまたは変更されたファイル

この圧縮は手動介入なしに自動的に行われます。生のツール出力は5,000トークンになることがありますが、データベースに保存される意味的な観測結果は約500トークンであり、ノイズを排除しながら意味を保持します。

セッションの要約

Claudeが応答を終えたとき（Stopフックがトリガーされたとき）、claude-memはセッションの要約を自動的に生成します。これには以下の情報が含まれます。

要求: 何を求めたか
調査済み: Claudeが回答するために何を調査したか
学習したこと: 主要な発見と洞察
達成したこと: 何が完了したか
次のステップ: 推奨されるフォローアップアクション

これらの要約は、個々の観測結果とともに将来のセッションに注入され、詳細な情報と高レベルのナラティブコンテキストの両方を提供します。

MCP検索ツールを使用して記憶を照会する

Claude-memは、トークン効率の高い3層ワークフローパターンに従う4つのMCPツールを公開しています。この設計は、トークン使用量を最小限に抑えながら関連性を最大化し、コンテキストを段階的に取得します。

3層ワークフロー

search: IDを含むコンパクトなインデックスを取得（結果あたり約50-100トークン）
timeline: 興味深い結果の周辺の時系列コンテキストを取得
get_observations: フィルタリングされたIDのみの完全な詳細を取得（結果あたり約500-1,000トークン）

このアプローチは、完全な詳細を取得する前にフィルタリングすることで、約10倍のトークン節約を実現します。

利用可能なMCPツール

search: 全文検索クエリでメモリインデックスを検索します。タイプ、日付、またはプロジェクトでフィルタリングできます。
timeline: 特定の観測またはクエリに関する時系列コンテキストを取得します。特定の決定やバグ修正に至った経緯を理解するのに役立ちます。
get_observations: IDで完全な観測詳細を取得します。オーバーヘッドを最小限に抑えるために、常に複数のIDを単一の呼び出しでバッチ処理してください。
__IMPORTANT: Claudeがメモリシステムを効果的に使用する方法を説明する、常に表示されるワークフロー文書。

使用パターン例

特定のバグ修正を見つける:

// ステップ1: バグを検索
search(query="authentication bug", type="bugfix", limit=10)

// ステップ2: インデックスを確認し、関連するIDを特定（例: #123, #456）

// ステップ3: 関連する観測結果の完全な詳細を取得
get_observations(ids=[123, 456])

最近のアーキテクチャ上の決定を調査する:

search(query="database schema", type="decision", limit=5)

特定のファイルに関連するすべてを見つける:

search(query="worker-service.ts", limit=20)

自然言語クエリ

プロジェクトの履歴についてClaudeに自然に質問できます。

「エラー処理についてどのような決定をしましたか？」
「認証はどのように実装しましたか？」
「API層でどのようなバグを修正しましたか？」
「データベーススキーマへの変更を表示してください」

Claudeは適切なMCPツールを自動的に呼び出して関連するコンテキストを取得し、特定の観測結果を参照するclaude-mem:// URI引用付きで結果を提示します。

フォルダーコンテキストファイルとCLAUDE.mdの自動生成

Claude-memは、プロジェクトフォルダー内にCLAUDE.mdファイルを自動生成し、グローバルメモリデータベースを補完するアクティビティタイムラインを作成します。

フォルダーコンテキストの仕組み

フォルダー内のファイルを操作するとき、claude-memは以下の処理を行います。

触れられたファイルから一意のフォルダーパスを特定する
各フォルダーに関連する最近の観測結果を照会する
フォーマットされたアクティビティのタイムラインを生成する
そのフォルダーのCLAUDE.mdに（<claude-mem-context>タグ内に）書き込む

各フォルダーのCLAUDE.mdには、観測ID、タイムスタンプ、タイプインジケータ（バグ修正、機能、発見）、簡単なタイトル、および推定トークン数を示す「最近のアクティビティ」セクションが含まれています。

ユーザーコンテンツの保存

自動生成されたコンテンツは<claude-mem-context>タグで囲まれています。これらのタグの外に記述したコンテンツは、ファイルが再生成されても保持されます。これにより、以下のことが可能になります。

生成されたセクションの上または下に独自のドキュメントを追加する
Claudeのためにフォルダー固有の指示を記述する
アーキテクチャメモや規約を含める

CLAUDE.mdの例の構造:

# Authentication Module

This folder contains all authentication-related code.
Follow the established patterns for new auth providers.

<claude-mem-context>
# Recent Activity

| ID | Time | Type | Title | Tokens |
|----|------|------|-------|--------|
| #1234 | 4:30 PM | 🔵 | Implemented user authentication | ~250 |
| #1235 | 4:45 PM | 🔴 | Fixed login redirect bug | ~180 |
</claude-mem-context>

## Manual Notes

- OAuth providers go in /providers/
- Session handling uses Redis

プライバシー制御とセキュリティ

Claude-memは、機密データがメモリシステムに入り込むのを防ぐためのきめ細かなプライバシー制御を提供します。

プライベートコンテンツタグ

機密コンテンツを<private>タグで囲むことで、ストレージから除外できます。

<private>
API_KEY=sk-live-abc123xyz789
DATABASE_PASSWORD=supersecret456
</private>

エッジ処理により、プライベートコンテンツがデータベースに到達することはありません。これは、APIキー、資格情報、および独自のロジックにとって重要です。

デュアルタグプライバシーシステム

Claude-memはデュアルタグアプローチを使用しています。

<private>: 機密コンテンツのためのユーザー制御のプライバシー
<claude-mem-context>: 再帰的な観測結果の保存を防ぐためのシステムレベルのタグ

WebビューアUIとリアルタイム監視

Claude-memは、リアルタイムのメモリストリーム視覚化のためにhttp://localhost:37777でウェブビューアを実行します。このインターフェースは以下を表示します。

重要度を示す絵文字インジケータ付きのライブ観測ストリーム
時系列マーカー付きのセッションタイムライン
メモリを照会するための検索インターフェース
設定調整用の設定パネル
安定版とベータ版チャネル間のバージョン切り替え

このUIは基本的な使用にはオプションですが、claude-memが何をキャプチャし、どのように開発履歴を整理しているかを理解するには非常に貴重です。

ベータ機能：エンドレスモード

ベータチャネルでは、拡張セッション向けの生物模倣型メモリアーキテクチャであるエンドレスモードが提供されます。50回のツール使用後にコンテキストの制限に達する代わりに、エンドレスモードは約1,000回の使用を約束します。これは20倍の増加です。これは、ツール出力をリアルタイムで圧縮することで、トークンを約95%削減し、スケーリングをO(N²)の二次関数からO(N)の線形関数に変更することで実現されます。

トレードオフ: 観測結果の生成には、ツール呼び出しあたり60〜90秒が追加されます。数日または数週間にわたる深く思慮深いコーディングセッションの場合、この遅延は許容されるかもしれません。しかし、高速なツール使用の場合、これは prohibitive（実行不可能）になる可能性があります。

ベータ機能は、ウェブビューアUI（http://localhost:37777 → 設定 → バージョンチャネル）から有効にできます。

よくある問題のトラブルシューティング

ワーカーサービスが起動しない

ワーカーがポート37777で起動しない場合:

ポートがすでに占有されているか確認してください。

lsof -i :37777

代替ポートを設定してください。

export CLAUDE_MEM_WORKER_PORT=8080

ワーカーを手動で起動してください。

bun plugin/scripts/worker-service.cjs

メモリが保存されない

Claudeが以前のセッションを記憶していない場合:

ワーカーが実行中であることを確認してください。

npm run worker:status

データベースファイルが存在することを確認してください。

ls -la ~/.claude-mem/claude-mem.db

ワーカーログでエラーを確認してください。

npm run worker:logs

コンテキスト注入の問題

セッション開始時にコンテキストが多すぎる、または少なすぎる場合:

観測制限を調整してください:

export CLAUDE_MEM_CONTEXT_OBSERVATIONS=10  # 減らす
export CLAUDE_MEM_CONTEXT_OBSERVATIONS=100 # 増やす

空のCLAUDE.mdファイル

claude-memがプロジェクト全体に空のCLAUDE.mdファイルを生成する場合、これはv9.0.5の既知の問題です。現在の回避策としては、手動で作成されたディレクトリを削除する、.gitignoreにパターンを追加する、または次期リリースでの修正を待つことが挙げられます。

Claude Desktopとの統合

Claude-memはMCPサーバー設定を通じてClaude Desktopと連携します。mcp-searchサーバーをClaude Desktopの設定に追加し、claude-memインストールのMCPサーバースクリプトを指し示し、Claude Desktopを再起動します。

設定が完了したら、過去の作業について自然に質問できます。

「前回のセッションで何をしましたか？」
「以前にこのバグを修正しましたか？」
「認証はどのように実装しましたか？」

メモリがキャプチャされていることを確認するには、localhost:37777のウェブビューアを使用し、接続に失敗した場合はClaude Desktopのログを確認してください。

手動ワーカー管理コマンド

claude-memディレクトリから、ワーカーサービスを管理できます。

npm run worker:start    # ワーカーサービスを開始
npm run worker:stop     # ワーカーサービスを停止
npm run worker:restart  # ワーカーサービスを再起動
npm run worker:logs     # ワーカーログを表示
npm run worker:status   # ワーカーの状態を確認

結論

Claude-memは、Claude Codeをステートレスなアシスタントから、時間とともにコードベースに関する知識を蓄積する永続的な開発パートナーへと変革します。ツール使用を自動的にキャプチャし、観測結果を検索可能な記憶に圧縮し、関連するコンテキストをインテリジェントに取得することで、AIアシスト開発を遅らせる反復的なコンテキスト構築作業を排除します。

このシステムのプログレッシブ開示アーキテクチャ（MCPツールによる階層型取得、フォルダーベースのCLAUDE.mdファイル、およびプライバシー制御）は、手動でのコンテキスト管理と比較して約10倍のトークン効率を提供し、データの完全な局所性とセキュリティを維持します。

Claude-memを強化したワークフローでAPIを構築したり外部サービスを操作したりする際は、Apidogでテストを効率化してください。Apidogは、視覚的なAPIテスト、自動ドキュメント生成、および永続的なメモリ設定を補完するコラボレーティブなデバッグ機能を提供します。

button