claude-remind-mcp

claude-remind-mcp

ローカルの Claude Code の会話履歴を検索する Model Context Protocol (MCP) サーバーです。~/.claude/projects/ にある過去のすべてのセッションを BM25 でインデックス化し、シークレットを秘匿化します。実行中の Claude エージェントは、問題を最初から説明し直すことなく、すでに解決した内容を思い出して作業を再開できます。

Docker、デプロイ、認証のバグをひと月に二度も解決していることに気づいたことがあるなら、このツールが役に立ちます。このパッケージはローカルでのみ動作し（ネットワーク呼び出しなし）、純粋な JavaScript で実装されており（ネイティブモジュールなし）、npx でインストールできる単一のバイナリとして提供されます。

ステータス：実験的（v0.1.x）。ツールのインターフェースは安定していますが、内部実装は変更される可能性があります。

---

インストール

シェルから：

claude mcp add claude-remind -- npx -y claude-remind-mcp

任意の手動設定可能な mcp.json から（Cursor、Windsurf など）：

{
  "mcpServers": {
    "claude-remind": {
      "command": "npx",
      "args": ["-y", "claude-remind-mcp"]
    }
  }
}

モデルのダウンロードも、デーモンも、データベースも不要です。最初のクエリで ~/.claude/projects/ からインデックスを作成し（一般的な履歴なら数秒）、~/.claude-remind/ に保存します。以降のクエリではインデックスを再利用し、mtime が変更されたファイルだけを再解析します。

npx が誤ったパッケージを解決する場合は、解決先を指定してください。

npm install -g claude-remind-mcp

---

ユースケース

過去の Claude Code の会話履歴を検索すると役立つケースをいくつか紹介します。

• 繰り返し発生するインフラエラー。 「先月のステージング環境へのデプロイで ExpiredTokenException が発生しました。修正方法は何でしたか？」 remind_search を 1 回実行すれば、該当セッション、解決時のスニペット、再開コマンドが返されます。
• プロジェクト間のナレッジ共有。 「別の Coolify プロジェクトで BuildKit キャッシュをどう設定しましたか？」 インデックスは ~/.claude/projects/ 以下のすべてのプロジェクトを対象とするため、プロジェクト B で作業中でもプロジェクト A の解決策が見つかります。
• 過去に行った作業の確認。 数週間ぶりにリポジトリに戻ってきましたか？「Cognito」、「RunPod」、「tailwind config」などで検索し、コードを grep し続ける代わりに、最新のセッション概要を確認できます。
• 不要な詳細調査の回避。 Claude が問題を一から診断するために 10k トークンを消費する前に、まず remind_search を呼び出して、すでに解決済みかどうか確認できます。デフォルトの応答サイズは約 1.5 KB です。
• 中断したところからの再開。 各検索結果には、すぐに貼り付けて使える claude --resume <id> コマンドに加えて、元の cwd と gitBranch が含まれるため、途中まで進めたスレッドにワンペーストで戻れます。

ツール

検索 → 読み取り → 再開という流れで連携するよう設計された 4 つのツールです。

remind_search

過去のメッセージを BM25 で検索します。順位付けされた結果として、スニペット、solvedHint、messageUuid、すぐに貼り付けて使える claude --resume コマンドを返します。

{
  query: string;
  project?: string;       // substring of cwd, e.g. "my-app"
  limit?: number;         // 1–50, default 5
  sinceDays?: number;     // age filter
  format?: "compact" | "detailed" | "full";  // 400 / 1000 / 2000-char snippet
}

[
  {
    "sessionId": "abc12345-...",
    "messageUuid": "msg-9f8e-...",
    "score": 432.8,
    "ts": "2026-04-10T11:30:26Z",
    "role": "assistant",
    "project": "/Users/you/Code/my-app",
    "gitBranch": "deploy",
    "hasError": false,
    "solvedHint": "likely",
    "aiTitle": "RunPod serverless deploy walkthrough",
    "snippet": "Step-by-step: 1) Push the image to NGC 2) Configure the Network Volume…",
    "resumeCommand": "claude --resume abc12345-..."
  }
]

クエリのヒント：具体的な語句を優先してください。正確なエラー文字列、ツールやライブラリの名前、ファイルパスなどが有効です。auth や docker のような一般的な単語だけでは、関連性が薄まります。

remind_message

1 つのメッセージの全文と、任意で前後のやり取りを取得します。remind_search が返した messageUuid のメッセージを全文で読みたい場合に使用します。

{
  sessionId: string;       // full or 8-char prefix
  messageUuid?: string;    // omit to read whole session (capped at 50 messages)
  contextBefore?: number;  // 0–20, default 1
  contextAfter?: number;   // 0–20, default 1
}

返されるウィンドウでは、一致したメッセージに isFocus: true のフラグが付きます。

remind_session

セッションの構造化された概要を表示します。タイトル、メッセージ数、使用したツール名、変更したファイル、エラー数、時間範囲、解決のヒント、最後のユーザーメッセージが含まれます。

{
  sessionId: string; // full or 8-char prefix
}

remind_resume

セッション ID（全体または 8 文字のプレフィックス）を、すぐに実行できる claude --resume <id> コマンドに解決し、セッションの cwd と git ブランチも返します。remind_search はすべての検索結果にこの情報を含めているため、そちらを優先してください。このツールは ID しか手元にない場合に使用します。

---

仕組み

1. ~/.claude/projects/ 以下のすべての JSONL ファイルを1行ずつ読み込みます。インデクサーの処理範囲を制限するため、1行あたりの上限を1 MB、ファイルあたりのメッセージ数の上限を50 000件にしています。
2. Claude Code のサイドカーエントリ（permission-mode、file-history-snapshot、attachment、system-reminder など）をスキップし、実際の user と assistant のターンだけをインデックス化します。
3. コンテンツをインデックスに追加する前に、よく知られたシークレットのパターン（API キー、JWT、秘密鍵ブロック、環境変数形式の代入）をマスキングします。
4. メッセージテキスト、ツール名、プロジェクトパスを対象に minisearch の BM25 インデックスを構築し、~/.claude-remind/ にアトミックに保存します。
5. 起動時には、mtime が変更されたファイルだけを再解析します。
6. 各セッションについて、hasError、endedCleanly、最後のユーザーメッセージ、保守的な solvedHint を導出します（明確な肯定的感情がある場合、またはエラーなしで正常に終了した場合のみ likely、明確な否定的感情がある場合のみ unlikely、それ以外は unknown）。

ディスク上のインデックスは単一の JSON ファイルです。削除しても問題ありません。次のクエリで再構築されます。

---

設定

環境変数	デフォルト	用途
CLAUDE_CONFIG_DIR	~/.claude	Claude Code がログを保存する場所です。
CLAUDE_REMIND_DIR	~/.claude-remind	インデックスの保存先です。

どちらも、設定する場合は絶対パスである必要があります。そうでない場合はデフォルト値が使用されます。

---

プライバシー

~/.claude-remind/index.json のインデックスファイルはモード 0600 で書き込まれ、会話からインデックス化されたテキストを含みます。組み込みの正規表現処理により、よく知られたシークレット形式（OpenAI／Anthropic／GitHub／AWS／Stripe／Google／Slack のキー、JWT、秘密鍵ブロック、一般的な KEY=value 形式の環境変数代入）を、コンテンツがインデックスに追加される前にマスキングします。これは可能な範囲での対策です。過去の会話に独自形式の認証情報を貼り付けていた場合、検出できないことがあります。インデックスを消去するには、~/.claude-remind/ を削除してください。

サーバーは stdio 経由で完全にローカルで動作します。ネットワーク接続は行いません。

---

開発

git clone https://github.com/emretheus/claude-remind-mcp && cd claude-remind-mcp
npm install
npm run build
npm test

スクリプト：

npm run build         # TypeScript build with executable permissions on dist/index.js
npm run dev           # tsc --watch
npm run start         # Run the MCP server (stdio)
npm run lint          # ESLint
npm run lint:fix      # ESLint --fix
npm run format        # Prettier write
npm run format:check  # Prettier check
npm run typecheck     # tsc --noEmit
npm test              # Vitest run

Claude Code のインスタンスをローカルのチェックアウトに向けるには：

claude mcp add claude-remind -- node /absolute/path/to/dist/index.js

シェルから MCP ハンドシェイクをスモークテストするには：

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}' \
  | node dist/index.js

プリコミットでは Husky 経由で lint-staged（ステージ済みファイルに対する ESLint + Prettier）を実行します。

---

要件

• Node.js ≥ 20
• ~/.claude/projects/ に書き込む Claude Code のインストール

このパッケージには、実行時依存関係として @modelcontextprotocol/sdk と minisearch の2つがあります。ネイティブモジュールはありません。

---

ライセンス

MIT