🚀 claude-historian
claude-historian 是一个用于搜索 Claude Code 对话历史的模型上下文协议（MCP）服务器。借助它，你可以查找过往解决方案、追踪文件变更，并从之前的工作中汲取经验。
🚀 快速开始
安装要求
安装方式
从 shell 安装
claude mcp add claude-historian -- npx claude-historian
从 Claude 内部安装（需要重启）
Add this to our global mcp config: npx claude-historian
Install this mcp: https://github.com/Vvkmnn/claude-historian
从手动配置的 mcp.json 安装（Cursor、Windsurf 等）
{
"mcpServers": {
"claude-historian": {
"command": "npx",
"args": ["claude-historian"],
"env": {}
}
}
}
安装完成。无需执行 npm install，因为它没有外部依赖或本地数据库，仅包含搜索算法。
✨ 主要特性
这是一个 MCP 服务器，可让 Claude 访问你的对话历史。它具备智能优先级排序功能，搜索速度快。
它可以在本地运行（带着酷炫的标志 [⌐■_■]）：
[⌐■_■] search_conversations query=
> "How did we fix that Redis connection pooling nightmare?"
> "Docker container keeps crashing on Kubernetes deployment"
> "React infinite re-render loop - useEffect dependency hell"
[⌐□_□] find_file_context filepath=
> "package.json changes that broke everything last month"
> "When we accidentally committed .env to main branch"
> "Authentication service refactor - before/after comparison"
[⌐×_×] get_error_solutions error_pattern=
> "MODULE_NOT_FOUND - the classic npm/yarn version mismatch"
> "CORS preflight failing - but only on production Fridays?"
> "Database deadlock during Black Friday traffic spike"
[⌐◆_◆] find_similar_queries query=
> "Database queries slower than my morning coffee brewing"
> "How to implement error boundaries without losing sanity"
> "State management: Redux vs Zustand vs just useState"
[⌐○_○] list_recent_sessions
> "Tuesday debugging marathon: 9pm-3am flaky test hunt"
> "Performance optimization sprint - reduced bundle 40%"
> "The great TypeScript migration of 2024"
[⌐⎚_⎚] find_tool_patterns tool_name=
> "Read → Edit → Bash combo for rapid prototyping"
> "When I use Grep vs Task for different searches"
> "Git operations during feature branch management"
🔧 技术细节
工作原理
claude-historian 的工作方式如下（源代码）：
"docker auth" query
|
├─> Classify: implementation query -> boost tool examples
|
├─> Stream & Filter:
| • Summary messages -> priority queue *****
| • Tool usage context -> high value ****
| • Error solutions -> targeted ***
|
├─> Smart Ranking:
| • "Fixed Docker auth with Read tool" (2h ago) *****
| • "OAuth implementation approach" (yesterday) ****
| • "Container auth debug" (last week) ***
|
└─> Return Claude Code optimized results
采用的技术
- JSON 流式解析器：按需读取 Claude Code 对话文件，无需完全反序列化。
- LRU 缓存：内存缓存，具备智能淘汰机制，用于频繁访问的对话。
- 受 TF-IDF 启发的评分：使用词频评分和文档频率加权来确定相关性。
- 查询分类：采用朴素贝叶斯风格的分类（错误/实现/分析/通用），并具有自适应限制。
- 编辑距离：对技术术语进行模糊匹配，并能容忍拼写错误。
- 指数时间衰减：近期消息权重更高，半衰期可配置。
文件访问
- 从
~/.claude/conversations/读取文件。 - 无需持久存储或索引。
- 数据不会离开你的设备。
📦 开发指南
克隆仓库并安装依赖
git clone https://github.com/vvkmnn/claude-historian && cd claude-historian
npm install && npm run build
npm test
贡献代码
- 请 Fork 仓库并创建功能分支。
- 在提交 PR 之前，使用大量对话历史进行测试。
- 遵循 TypeScript 严格模式和 MCP 协议 标准。
参考示例
- 官方 MCP 服务器 可作为参考实现。
- TypeScript SDK 可提供最佳实践。
📄 许可证
本项目采用 MIT 许可证。
Claude Fauchet (1744 - 1793)，法国历史学家