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 文件。