claude-historian

一个用于搜索您的Claude Code（及Claude Desktop）对话历史的Model Context Protocol (MCP)服务器。查找过去的解决方案，跟踪文件更改，并从以前的工作中学习。

安装

需求：

• Claude Code

npm install -g claude-historian

从 shell：

claude mcp add claude-historian -- npx claude-historian

从 Claude 内部（需要重启）：

在全局 mcp 配置中添加：npx claude-historian

安装此 mcp：https://github.com/Vvkmnn/claude-historian

从任何手动配置的 mcp.json：（Cursor, Windsurf 等）

{
  "mcpServers": {
    "claude-historian": {
      "command": "npx",
      "args": ["claude-historian"],
      "env": {}
    }
  }
}

就这样；不需要执行 npm install，因为没有外部依赖或本地数据库，只有搜索算法。

然而，在极少数情况下，如果您拉取了错误的包 / npx 注册表已过期，您可以在某些环境中强制解决这些问题：

npm install -g claude-historian

功能

MCP 服务器使 Claude 能够访问您的对话历史。快速搜索并智能优先级排序。

本地运行（带有酷炫的墨镜 [⌐■_■]）：

[⌐■_■] search_conversations query=<查询>
  > "我们是如何解决那个 Redis 连接池噩梦的？"
  > "Docker 容器在 Kubernetes 部署时崩溃"
  > "React 无限重新渲染循环 - useEffect 依赖地狱"

[⌐□_□] find_file_context filepath=<文件路径>
  > "上个月破坏一切的 package.json 更改"
  > "当我们不小心将 .env 提交到主分支时"
  > "身份验证服务重构 - 前后比较"

[⌐×_×] get_error_solutions error_pattern=<错误>
  > "MODULE_NOT_FOUND - 经典的 npm/yarn 版本不匹配"
  > "CORS 预检失败 - 但只在生产周五？"
  > "黑色星期五流量高峰期间的数据库死锁"

[⌐◆_◆] find_similar_queries query=<查询>
  > "数据库查询比我的早晨咖啡冲泡还要慢"
  > "如何实现错误边界而不失去理智"
  > "状态管理：Redux vs Zustand vs 只使用 useState"

[⌐○_○] list_recent_sessions
  > "周二调试马拉松：晚上9点到凌晨3点的不稳定测试狩猎"
  > "性能优化冲刺 - 减少捆绑包 40%"
  > "2024 年伟大的 TypeScript 迁移"

[⌐⎚_⎚] find_tool_patterns tool_name=<工具>
  > "读取 → 编辑 → Bash 组合以快速原型设计"
  > "我何时使用 Grep 和 Task 进行不同搜索"
  > "功能分支管理期间的 Git 操作"

方法论

claude-historian 的工作原理：

"docker auth" 查询
      |
      ├─> 并行处理（search.ts:949）：15个项目 × 10个文件并发
      |   • 使用 Promise.allSettled 提高速度 6 倍
      |   • 当找到足够结果时提前终止
      |   • 使用全面模式增强文件覆盖
      |
      ├─> 增强分类（search.ts:294）：实现 → 提升工具工作流程
      |   • 工具序列检测（编辑 → 读取 → Bash）
      |   • 语义边界保存（永不截断函数中间部分）
      |   • Claude 优化格式化，带有丰富的元数据
      |
      ├─> 智能排名（search.ts:213）：
      |   • "编辑工作流（7次成功）"（2小时前）*****
      |   • "带上下文路径的 Docker 认证"（昨天）****
      |   • "容器调试模式"（上周）***
      |
      └─> 返回 Claude Code 优化的结果

核心优化：

• 并行处理：使用 Promise.allSettled 在项目和文件之间提高速度 6 倍
• 工作流检测：捕获如“编辑 → 读取 → Bash”模式的工具序列
• 增强文件匹配：全面的路径变化，带有大小写不敏感匹配
• 智能去重：基于内容的去重，保留最高得分的结果
• 智能截断：永不截断函数或错误中间部分
• Claude 优化格式化：带有技术内容优先级的丰富元数据

搜索策略：

• JSON 流式解析器 (parseJsonlFile)：按需读取 Claude Code 对话文件，无需完全反序列化
• LRU 缓存 (messageCache)：带有智能驱逐的内存缓存，用于频繁访问的对话
• TF-IDF 启发评分 (calculateRelevanceScore)：基于词频和文档频率加权的相关性评分
• 查询分类 (classifyQueryType)：朴素贝叶斯风格分类（错误/实现/分析/通用），带有自适应限制
• 编辑距离 (calculateQuerySimilarity)：技术术语的模糊匹配和拼写容错
• 指数时间衰减 (getTimeRangeFilter)：最近的消息权重更高，具有可配置的半衰期
• 并行文件处理 (getErrorSolutions)：并发项目扫描，带有提前终止，响应时间为 0.8 秒
• 工作流模式识别 (getToolPatterns)：检测工具使用序列及相关工作流以供学习
• 增强文件上下文 (findFileContext)：多项目搜索，带有全面的路径匹配
• 内容感知截断 (smartTruncation)：智能内容边界超过任意字符限制
• 技术内容优先级 (formatSearchResults)：代码块、错误和文件路径得到完整保留
• 查询相似性聚类 (findSimilarQueries)：语义扩展和相关问题的模式分组

文件访问：

• 从 ~/.claude/conversations/ 读取
• 零持久存储或索引
• 从未离开您的机器

开发

git clone https://github.com/vvkmnn/claude-historian && cd claude-historian
npm install && npm run build
npm test

包需求：

• Node.js: >=20.0.0（ES 模块支持）
• npm: >=10.0.0（package-lock v3）
• 运行时: 唯一依赖是 @modelcontextprotocol/sdk
• 零外部依赖用于生产部署
• 优化: 并行处理减少 50% 的令牌

开发工作流：

npm run build          # TypeScript 编译，带有可执行权限
npm run dev            # 监视模式，使用 tsc --watch
npm run lint           # ESLint 代码质量检查
npm run format         # Prettier 格式化
npm run type-check     # TypeScript 验证，不生成
npm run prepublishOnly # 发布前验证（构建 + 检查 + 格式化）

贡献：

• 请分叉仓库并创建功能分支
• 在提交 PR 之前使用大型对话历史进行测试
• 遵循 TypeScript 严格模式和 MCP 协议标准

从示例中学习：

• 官方 MCP 服务器作为参考实现
• TypeScript SDK的最佳实践
• 创建 Node.js 模块 - NPM 包开发指南

桌面

Claude Desktop 支持目前被 LevelDB 锁定 和 Electron 沙箱阻止。您仍然可以从 Claude Code 搜索 Claude Desktop，但仅当 Claude 应用程序关闭时。

有一个 DXT 包和构建可用于未来兼容性；正在进行进一步调查。您可以自由地进行测试。

许可

MIT

---

Claude Fauchet (1744-1793)，法国历史学家