Claude Historian

claude-historian-mcp

Claude Code の会話履歴を検索するための Model Context Protocol（MCP） サーバーです。過去の解決策を見つけ、ファイルの変更を追跡し、これまでの作業から学べます。

---

インストール

必要条件：

シェルから：

claude mcp add claude-historian-mcp -- npx claude-historian-mcp

Claude 内から（再起動が必要です）：

Add this to our global mcp config: npx claude-historian-mcp

Install this mcp: https://github.com/Vvkmnn/claude-historian-mcp

手動で設定できる mcp.json から：（Cursor、Windsurf など）

{
  "mcpServers": {
    "claude-historian-mcp": {
      "command": "npx",
      "args": ["claude-historian-mcp"],
      "env": {}
    }
  }
}

npm install は不要です。外部依存関係やローカルデータベースはなく、検索アルゴリズムのみを使用します。

ただし、npx が誤ったパッケージを解決する場合は、次のようにして解決先を指定できます。

npm install -g claude-historian-mcp

名称変更： このプロジェクトは claude-historian から claude-historian-mcp に名称変更されました。既存のユーザーは、インストールコマンドと MCP 設定の引数を claude-historian-mcp に更新してください。

スキル

必要に応じて、Claude が historian を積極的に利用するタイミングを学習できるよう、スキルをインストールしてください。

npx skills add Vvkmnn/claude-historian-mcp --skill claude-historian --global
# Optional: add --yes to skip interactive prompt and install to all agents

これにより、Claude はウェブ検索の前、エラーが発生したとき、またはセッション開始時に、履歴を自動的に確認するようになります。MCP はスキルなしでも動作しますが、スキルを使うと見つけやすくなります。

プラグイン

フックとコマンドを使って履歴を自動検索するには、claude-emporium マーケットプレイスからインストールしてください。

/plugin marketplace add Vvkmnn/claude-emporium
/plugin install claude-historian@claude-emporium

claude-historian プラグインには、以下が用意されています。

フック（対象を絞り込み、成功時のオーバーヘッドはゼロ）：

• WebSearch/WebFetch の前 → search scope="similar" を確認
• EnterPlanMode の前 → search scope="plans" を確認
• Task エージェントの前 → search scope="tools" を確認
• Bash エラーの後 → search scope="errors" を確認

コマンド： /historian-search <query>

先に MCP サーバーをインストールする必要があります。その他の Claude Code プラグインと MCP については、emporium をご覧ください。

機能

Claude が会話履歴にアクセスできるようにするMCP サーバーです。2 つのツール、11 のスコープ、依存関係はありません。

ローカルで動作します（クールなサングラス付き [⌐■_■] 📜）。

search

会話、ファイル、エラー、プラン、設定、タスク、セッション、ツール、類似クエリ、メモリーを横断して検索します。

search query="docker auth error"                          # default scope: all
search query="fix build" scope="conversations"            # past solutions
search query="ENOENT" scope="errors"                      # error patterns + fixes
search query="auth" scope="plans"                         # implementation plans
search query="hooks" scope="config"                       # rules, skills, CLAUDE.md
search query="git push" scope="similar"                   # related questions asked before
search query="Edit" scope="tools"                         # tool usage workflows
search filepath="package.json" scope="files"              # file change history
search scope="sessions"                                   # recent sessions
search scope="memories"                                   # project memory files
search query="deploy" scope="all" detail_level="detailed" # full context
search query="auth" timeframe="7d" project="my-app"       # filtered

📜 ── search "docker auth" ── 5 results · 405 tokens

{
  "results": [{
    "type": "assistant",
    "ts": "2h ago",
    "content": "Fixed Docker auth by updating registry credentials...",
    "project": "my-app",
    "score": 100,
    "ctx": { "filesReferenced": ["docker-compose.yml"], "toolsUsed": ["Edit", "Bash"] }
  }]
}

📜 ── files "package.json" ── 92 operations · 1594 tokens

{
  "filepath": "package.json",
  "operations": [{
    "type": "edit",
    "ts": "1d ago",
    "changes": ["Changed: \"version\": \"1.0.3\" → \"version\": \"1.0.4\""],
    "content": "Updated version for release"
  }]
}

📜 ── tools "Bash" ── 5 patterns · 427 tokens

{
  "tool": "Bash",
  "patterns": [{
    "name": "Bash",
    "uses": 10,
    "workflow": "$ npm run build 2>&1",
    "practice": "Used with: ts, js, json, md files"
  }]
}

inspect

セッション ID（完全な UUID または短いプレフィックス）を指定して、セッションのインテリジェントな要約を取得します。

inspect session_id="latest"                      # most recent session
inspect session_id="d537af65"                    # short prefix works
inspect session_id="d537af65" focus="files"      # only file changes
inspect session_id="d537af65" focus="tools"      # only tool usage
inspect session_id="d537af65" focus="solutions"  # only solutions

📜 ── inspect my-app (68d5323b)

{
  "session": {
    "id": "68d5323b",
    "ts": "2h ago",
    "duration": 45,
    "messages": 128,
    "project": "my-app",
    "tools": ["Edit", "Bash", "Read"],
    "files": ["src/auth.ts", "package.json"],
    "accomplishments": ["fixed auth bug", "added unit tests"],
    "decisions": ["chose JWT over sessions"]
  }
}

手法

claude-historian-mcp の仕組み：

"docker auth" query
      |
      ├─> Parallel Processing (search.ts:174): 15 projects × 10 files concurrently
      |   • Promise.allSettled for 6x speed improvement
      |   • Early termination when sufficient results found
      |   • Enhanced file coverage with comprehensive patterns
      |
      ├─> Enhanced Classification (search.ts:642): implementation → boost tool workflows
      |   • Workflow detection for tool sequences (Edit → Read → Bash)
      |   • Semantic boundary preservation (never truncate mid-function)
      |   • Claude-optimized formatting with rich metadata
      |
      ├─> Smart Ranking (utils.ts:267):
      |   ├─> Core Terms (scoring-constants.ts): "docker" +10, "auth" +10
      |   ├─> Supporting Terms: context words +3 each
      |   ├─> Tool Usage: Edit/Bash references +5
      |   ├─> File References: paths/extensions +3
      |   └─> Project Match: current project +5
      |
      ├─> Results sorted by composite score:
      |   • "Edit workflow (7x successful)" (2h ago) ***** [score: 45]
      |   • "Docker auth with context paths" (yesterday) **** [score: 38]
      |   • "Container debugging patterns" (last week) *** [score: 22]
      |
      └─> Return Claude Code optimized results

主な最適化：

• 並列処理：Promise.allSettled によって、プロジェクトとファイル全体で 6 倍の速度向上を実現
• ワークフローの検出：「Edit → Read → Bash」のようなツールの連続した使用を記録
• ファイルマッチングの強化：大文字と小文字を区別しないマッチングによる、網羅的なパスのバリエーション
• インテリジェントな重複排除：コンテンツに基づいて重複を排除し、スコアの最も高い結果を保持
• インテリジェントな切り詰め：関数やエラーの途中で切り詰められることはありません
• Claude に最適化されたフォーマット：技術的なコンテンツを優先した、豊富なメタデータ

検索戦略：

• JSON ストリーミングパーサー (parseJsonlFile)：完全にデシリアライズせず、必要に応じて Claude Code の会話ファイルを読み込みます
• LRU キャッシュ (messageCache)：頻繁にアクセスされる会話を対象に、インテリジェントな破棄を行うメモリ内キャッシュです
• TF-IDF に着想を得たスコアリング (calculateRelevanceScore)：関連度を判定するため、文書頻度で重み付けした用語頻度スコアリングです
• クエリ分類 (classifyQueryType)：適応型の上限を備えたナイーブベイズ方式の分類（エラー／実装／分析／一般）です
• 編集距離 (calculateQuerySimilarity)：技術用語のあいまい検索と誤入力への対応です
• 指数関数的な時間減衰 (getTimeRangeFilter)：設定可能な半減期に基づき、最近のメッセージに高い重みを付けます
• ファイルの並列処理 (getErrorSolutions)：プロジェクトを並行してスキャンし、早期終了することで、0.8 秒の応答時間を実現します
• ワークフローパターン認識 (getToolPatterns)：学習に役立てるため、ツールの使用順序と関連するワークフローを検出します
• 拡張されたファイルコンテキスト (findFileContext)：包括的なパス照合による、複数プロジェクトの検索です
• コンテンツを考慮した切り詰め (smartTruncation)：任意の文字数制限ではなく、コンテンツに適した境界で切り詰めます
• 技術コンテンツの優先処理 (BeautifulFormatter)：コードブロック、エラー、ファイルパスを完全な形で保持します
• クエリ類似度のクラスタリング (findSimilarQueries)：関連する質問を対象に、意味的な拡張とパターンのグループ化を行います

設計原則：

• 汎用エンジン -- すべての Claude Code の会話に対応する単一の検索バックエンドです
• 並列処理 -- セッションディレクトリ全体でファイルを並行してスキャンします
• 意味的な拡張 -- 検索の再現率を高めるため、クエリの同義語や関連語を使用します
• 依存関係ゼロ -- @modelcontextprotocol/sdk のみを使用し、データベースは不要です
• オフライン -- ローカルの JSONL ファイルのみをスキャンし、データがマシンの外に出ることはありません

ファイルアクセス：

• 読み込み元：~/.claude/conversations/
• 永続ストレージやインデックスは使用しません
• データがマシンの外に出ることはありません

パフォーマンス： ベンチマーク、最適化の履歴、品質スコアについては、PERFORMANCE.md を参照してください。

代替ツール

会話履歴ツールはどれも、使わないときもトークンを消費しながら常にコンテキストを読み込むか、外部ランタイムやデータベースを必要とします。Historian は依存関係なしで、必要なときに検索します。

機能	historian	Claude Memory	claude-mem	deja	conversation-search
依存関係	なし	組み込み	Bun + Python + SQLite + Chroma	Python	Rust ツールチェーン
バックグラウンドサービス	なし	なし	あり（ポート 37777）	なし	なし
ディスクへの書き込み	一切なし	あり（自動メモリファイル）	あり（SQLite + Chroma DB）	あり（パンくず）	あり（インデックスのオーバーヘッド約 10%）
セッション開始時	0 トークン	約 200 行を読み込み	毎セッション 5～8k トークン	スキルプロンプトを読み込み	0 トークン
トークンコスト（アイドル時）	0	200 行／セッション	5～8k／セッション	スキルプロンプト／セッション	0
検索アルゴリズム	12	なし（ファイル読み込み）	ベクトル + キーワード	重み付けシグナル	BM25 全文検索
あいまい検索	あり	なし	あり（ベクトル類似度）	なし	なし
ワークフロー検出	あり	なし	なし	なし	なし
生の会話	あり	なし（要約のみ）	なし（圧縮された観察結果）	あり	あり（フィルター済み）
メンテナンス	不要	不要	ワーカーデーモン、マイグレーション	スキル設定	インデックスの再構築

Claude Memory -- Claude に組み込まれたメモリ（CLAUDE.md + 自動メモリ）です。セッションをまたいでプロジェクトのルールや設定を保持します。先を見越した内容（「常に ESM インポートを使う」など）を扱い、会話検索には対応しません。相互補完的です。ルールにはメモリ、過去の解決策には historian を使います。

claude-mem -- ライフサイクルフックで観察内容を記録し、SQLite + Chroma に圧縮して、毎セッションでコンテキストを読み込むプラグインです。Bun、Python、ポート 37777 で動作するバックグラウンドワーカーが必要です。実環境でのテスト（270 以上のセッション）では、履歴を検索しないセッションが 95% を占めています。常時有効なツールは、どのセッションでも 5～8k トークンを消費します。Historian はアイドル時にトークンを消費せず、検索 1 回あたり 500～2k トークンで、100 セッションで約 475k トークンを節約できます。既知の問題：--continue を動作不能にする空のセッションファイルの作成、ワーカーデーモンのバージョン競合、有効な編集をブロックするセキュリティフック。

deja -- エピソードと成果ごとにセッションをインデックス化する Python スキルです。重み付けしたシグナルによるランキング（ToDo > ファイル > テキスト）を使用します。Python と TodoWrite との統合が必要です。

conversation-search -- Tantivy の BM25 全文検索を使用する Rust 製 MCP サーバーです。インデックス化は高速（約 1000 会話／秒）ですが、Rust ツールチェーンと永続ディスクインデックスが必要です。

デスクトップ

注： Claude Desktop は会話をローカルではなくサーバー側に保存します。ローカルの LevelDB ファイル（~/Library/Application Support/Claude/）に含まれるのは、セッショントークン、UI の設定、Intercom の状態のみで、会話の内容は含まれません。また、Claude Desktop のサポートは LevelDB のロックと Electron のサンドボックス化によっても妨げられています。

つまり、現時点では Claude Desktop のローカル履歴を検索できません。このプロジェクトでは、会話履歴全体を ~/.claude/projects/ にローカル保存する Claude Code に重点を置いています。

Claude Code から Claude Desktop のデータを一部取得できる場合がありますが、Claude アプリが終了している場合に限ります。さらに、将来の互換性に備えて DXT パッケージとビルドを用意しており、現在も調査を続けています。ぜひお試しください。

開発

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

パッケージの要件：

• Node.js：>=20.0.0（ES モジュール）
• ランタイム：@modelcontextprotocol/sdk
• 外部データベース不要 -- npx で動作します

開発ワークフロー：

npm run build          # TypeScript compilation with executable permissions
npm run dev            # Watch mode with tsc --watch
npm run start          # Run the MCP server directly
npm run lint           # ESLint code quality checks
npm run lint:fix       # Auto-fix linting issues
npm run format         # Prettier formatting (src/)
npm run format:check   # Check formatting without changes
npm run typecheck      # TypeScript validation without emit
npm run test           # Lint + type check
npm run prepublishOnly # Pre-publish validation (build + lint + format:check)

Git フック（Husky 経由）：

• pre-commit：ステージされた .ts ファイルを Prettier と ESLint で自動フォーマットします
• pre-push：プッシュ前に完全な検証（フォーマット、リント、型チェック、ビルド）を実行します

貢献方法：

• リポジトリをフォークし、機能ブランチを作成します
• PR を提出する前に、大量の会話履歴でテストします
• TypeScript の strict モードと MCP プロトコルの標準に従います

例から学ぶ：

• 参考実装については、公式 MCP サーバーをご覧ください
• ベストプラクティスについては、TypeScript SDKをご覧ください
• npm パッケージの開発については、Node.js モジュールの作成をご覧ください

ライセンス

MIT

---

元老院のアッピウス・クラウディウス・カエクス、**チェーザレ・マッカリ**作（1888年）。ローマの政治家であり、ラテン散文の父。