Cowork History

🚀 Cowork History MCP

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

🚀 クイックスタート

インストールが完了すると、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"

✨ 主な機能

• ハイブリッド検索 - 複数の検索方法を組み合わせて、最適な結果を得ることができます。
  • 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"
      }
    }
  }
}

💻 使用例

基本的な使用法

"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

高度な使用法

# 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"

📚 ドキュメント

利用可能なツール

検索と閲覧

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

検索モード

cowork_history_searchツールは、複数の検索モードをサポートしています。

ベクトル検索の有効化

ベクトル検索は、意味的な類似性の一致（正確なキーワードがなくても関連する概念を見つける）を提供します。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で強制的に再構築することもできます。

環境変数

トラブルシューティング

会話が見つからない場合

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インスペクターでのテスト

npx @modelcontextprotocol/inspector uvx cowork-history

📄 ライセンス

MITライセンス - 詳細については、LICENSEファイルを参照してください。