cowork-history

Cowork 历史 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 文件。