cowork-history

Cowork History MCP

~/.claude/ に保存されている Claude の会話履歴を検索、閲覧するための MCP（Model Context Protocol）サーバーです。Claude Code と Cowork の両方の会話に対応しています。

特長

• ハイブリッド検索 - 複数の検索方式を組み合わせ、最適な結果を提供します。
  • SQLite FTS5 - BM25 ランキングによる高速な全文検索
  • macOS Spotlight - mdfind を使ってシステムのコンテンツインデックスを活用
  • ベクトル埋め込み - セマンティック類似検索（オプション。Ollama が必要です）
• スマートなパスの再構築 - 推測ではなく、プローブによって実際のファイルシステムパスを復元します
• 永続インデックス - 増分更新に対応した SQLite データベースにより、高速なクエリを実現します
• Ollama セットアップツール - 埋め込みの自動インストールと設定

インストール

オプション 1：Claude Desktop（ワンクリックインストール）

最新リリースから cowork-history.mcpb をダウンロードし、ダブルクリックしてインストールします。

オプション 2：uvx 経由（CLI におすすめ）

uvx cowork-history

オプション 3：pip 経由

pip install cowork-history

オプション 4：手動設定

Claude Desktop の設定（~/Library/Application Support/Claude/claude_desktop_config.json）に追加します。

{
  "mcpServers": {
    "cowork-history": {
      "command": "uvx",
      "args": ["cowork-history"],
      "env": {
        "OLLAMA_URL": "http://localhost:11434",
        "EMBEDDING_MODEL": "nomic-embed-text"
      }
    }
  }
}

クイックスタート

インストールすると、Claude で会話履歴を検索できるようになります。

"What did we discuss about authentication last week?"
"Find the conversation where we debugged the payment webhook"
"Show me my conversations in the my-project folder"

利用可能なツール

検索と閲覧

ツール	説明
cowork_history_search	ハイブリッド検索（FTS + Spotlight + ベクトル）で会話を検索します
cowork_history_list	最近の会話を一覧表示します。プロジェクトで絞り込むこともできます
cowork_history_get	セッション ID を指定して、特定の会話の全文を取得します
cowork_history_projects	会話履歴のあるプロジェクトをすべて一覧表示します
cowork_history_stats	統計情報と検索機能のステータスを取得します
cowork_history_reindex	インデックスを再構築し、オプションで埋め込みを生成します

Ollama のセットアップ（ベクトル検索用）

ツール	説明
history_system_check	Ollama のシステム要件を確認します
history_setup_ollama	Homebrew 経由で Ollama をインストールします（macOS）
history_setup_ollama_direct	直接ダウンロードで Ollama をインストールします（Homebrew 不要）
history_ollama_status	Ollama のステータスと埋め込みモデルの利用可否を確認します

検索モード

cowork_history_search ツールは複数の検索モードに対応しています。

モード	説明
auto（デフォルト）	利用可能なすべての方式を使用し、最適な結果を提供します
fts	全文検索のみ（最速）
spotlight	macOS Spotlight のみ
vector	セマンティック類似検索のみ（Ollama が必要です）
hybrid	ランキングを使った明示的な組み合わせ

検索例

"authentication bug"           → finds conversations with both words
"how to deploy"                → semantic search finds related discussions
"\"exact phrase\""             → exact phrase matching
project:"my-app" "database"    → filter by project

ベクトル検索を有効にする

ベクトル検索では、セマンティック類似マッチングを利用できます（キーワードが完全一致しなくても、関連する概念を見つけられます）。使用するには、埋め込みモデルを備えた Ollama が必要です。

クイックセットアップ

Claude にセットアップを依頼できます。

"Set up Ollama for vector search"

または、手動で設定します。

# Install Ollama (macOS)
brew install ollama

# Start Ollama service
brew services start ollama

# Pull the embedding model
ollama pull nomic-embed-text

次に、埋め込みを生成します。

"Rebuild the history index with embeddings"

仕組み

インデックス作成

サーバーは ~/.claude/.history-index/conversations.db に SQLite データベースを保持します。データベースには以下が含まれます。

• 高速な全文検索を実現する FTS5 仮想テーブル
• 会話のメタデータ（セッション ID、プロジェクト、タイムスタンプ、トピック）
• 包括的な検索に使う全文
• 再構築したパスのキャッシュ
• ベクトル検索用の埋め込みテーブル（オプション）

検索時にインデックスは自動更新されます（作成から 5 分以上経過している場合）。または、cowork_history_reindex で強制的に再構築できます。

環境変数

変数	デフォルト	説明
OLLAMA_URL	http://localhost:11434	Ollama サーバーの URL
EMBEDDING_MODEL	nomic-embed-text	Ollama の埋め込みモデル

トラブルシューティング

会話が見つからない

1. ~/.claude/ ディレクトリが存在することを確認します
2. 会話履歴があることを確認します（先に Claude Code または Cowork を使用してください）
3. MCP サーバーが正しく設定されていることを確認します

ベクトル検索を利用できない場合

1. Ollama がインストールされていることを確認します：ollama --version
2. Ollama が実行中であることを確認します：curl http://localhost:11434/api/tags
3. モデルが利用可能であることを確認します：ollama list
4. 埋め込みモデルをプルします：ollama pull nomic-embed-text

検索しても期待する結果が見つからない場合

• 自然言語のクエリを試します（セマンティック検索のほうが柔軟です）
• 完全一致検索には mode: "fts" を使用します
• cowork_history_stats を確認して、どの検索バックエンドが有効かを調べます

開発

ローカルでの実行

# Clone the repository
git clone https://github.com/egoughnour/cowork-history
cd cowork-history

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest tests/

# Run the server directly
python -m src.cowork_history_server

MCP Inspector でのテスト

npx @modelcontextprotocol/inspector uvx cowork-history

ライセンス

MIT License — 詳細については LICENSE ファイルを参照してください。