Cowork History

🚀 Cowork History MCP

Cowork History MCP 是一個 MCP（模型上下文協議）服務器，用於搜索和瀏覽存儲在 ~/.claude/ 中的 Claude 對話歷史記錄。它適用於 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（推薦用於命令行界面）

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

💻 使用示例

可用工具

搜索與瀏覽

Ollama 設置（用於向量搜索）

搜索模式

cowork_history_search 工具支持多種搜索模式：

搜索示例

"authentication bug"           → 查找包含這兩個詞的對話
"how to deploy"                → 語義搜索查找相關討論
"\"exact phrase\""             → 精確短語匹配
project:"my-app" "database"    → 按項目過濾

啟用向量搜索

向量搜索提供語義相似性匹配（即使沒有確切關鍵詞也能找到相關概念）。它需要 Ollama 和一個嵌入模型。

快速設置

讓 Claude 為你設置：

"Set up Ollama for vector search"

或者手動設置：

# 安裝 Ollama（macOS）
brew install ollama

# 啟動 Ollama 服務
brew services start ollama

# 拉取嵌入模型
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 以查看哪些搜索後端處於活動狀態。

開發

本地運行

# 克隆倉庫
git clone https://github.com/egoughnour/cowork-history
cd cowork-history

# 以開發模式安裝
pip install -e ".[dev]"

# 運行測試
pytest tests/

# 直接運行服務器
python -m src.cowork_history_server

使用 MCP Inspector 進行測試

npx @modelcontextprotocol/inspector uvx cowork-history

📄 許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE 文件。