Claude Historian

claude-historian-mcp

一个用于搜索 Claude Code 对话历史的 Model Context Protocol (MCP) 服务。查找过往解决方案、追踪文件变更，并从以往工作中汲取经验。

---

安装

要求：

通过 shell 安装：

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

在 Claude 中安装（需要重启）：

Add this to our global mcp config: npx claude-historian-mcp

Install this mcp: https://github.com/Vvkmnn/claude-historian-mcp

通过任何可手动配置的 mcp.json 安装：（Cursor、Windsurf 等）

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

无需执行 npm install——没有外部依赖或本地数据库，只有搜索算法。

不过，如果 npx 解析到了错误的包，可以通过以下方式强制指定：

npm install -g claude-historian-mcp

**已重命名：**本项目已从 claude-historian 更名为 claude-historian-mcp。现有用户应将安装命令和 MCP 配置参数更新为 claude-historian-mcp。

技能

你也可以选择安装此技能，让 Claude 知道何时主动使用 historian：

npx skills add Vvkmnn/claude-historian-mcp --skill claude-historian --global
# Optional: add --yes to skip interactive prompt and install to all agents

这样，Claude 就会在进行网页搜索、遇到错误或会话开始时自动检查历史记录。MCP 服务无需此技能也能正常工作，但该技能有助于 Claude 发现并使用它。

插件

如需通过钩子和命令自动搜索历史记录，请从 claude-emporium 市场安装：

/plugin marketplace add Vvkmnn/claude-emporium
/plugin install claude-historian@claude-emporium

claude-historian 插件提供：

钩子（针对性触发，成功时零开销）：

• WebSearch/WebFetch 执行前 → 检查 search scope="similar"
• EnterPlanMode 执行前 → 检查 search scope="plans"
• Task Agent 执行前 → 检查 search scope="tools"
• Bash 出错后 → 检查 search scope="errors"

命令： /historian-search <query>

需要先安装 MCP 服务。请参阅 emporium，了解其他 Claude Code 插件和 MCP。

功能

MCP 服务，让 Claude 能够访问你的对话历史记录。两个工具、11 个范围、零依赖。

在本地运行（戴着酷炫的墨镜 [⌐■_■] 📜）：

search

搜索对话、文件、错误、计划、配置、任务、会话、工具、相似查询和记忆。

search query="docker auth error"                          # default scope: all
search query="fix build" scope="conversations"            # past solutions
search query="ENOENT" scope="errors"                      # error patterns + fixes
search query="auth" scope="plans"                         # implementation plans
search query="hooks" scope="config"                       # rules, skills, CLAUDE.md
search query="git push" scope="similar"                   # related questions asked before
search query="Edit" scope="tools"                         # tool usage workflows
search filepath="package.json" scope="files"              # file change history
search scope="sessions"                                   # recent sessions
search scope="memories"                                   # project memory files
search query="deploy" scope="all" detail_level="detailed" # full context
search query="auth" timeframe="7d" project="my-app"       # filtered

📜 ── search "docker auth" ── 5 results · 405 tokens

{
  "results": [{
    "type": "assistant",
    "ts": "2h ago",
    "content": "Fixed Docker auth by updating registry credentials...",
    "project": "my-app",
    "score": 100,
    "ctx": { "filesReferenced": ["docker-compose.yml"], "toolsUsed": ["Edit", "Bash"] }
  }]
}

📜 ── files "package.json" ── 92 operations · 1594 tokens

{
  "filepath": "package.json",
  "operations": [{
    "type": "edit",
    "ts": "1d ago",
    "changes": ["Changed: \"version\": \"1.0.3\" → \"version\": \"1.0.4\""],
    "content": "Updated version for release"
  }]
}

📜 ── tools "Bash" ── 5 patterns · 427 tokens

{
  "tool": "Bash",
  "patterns": [{
    "name": "Bash",
    "uses": 10,
    "workflow": "$ npm run build 2>&1",
    "practice": "Used with: ts, js, json, md files"
  }]
}

inspect

通过 ID（完整 UUID 或短前缀）获取任意会话的智能摘要。

inspect session_id="latest"                      # most recent session
inspect session_id="d537af65"                    # short prefix works
inspect session_id="d537af65" focus="files"      # only file changes
inspect session_id="d537af65" focus="tools"      # only tool usage
inspect session_id="d537af65" focus="solutions"  # only solutions

📜 ── inspect my-app (68d5323b)

{
  "session": {
    "id": "68d5323b",
    "ts": "2h ago",
    "duration": 45,
    "messages": 128,
    "project": "my-app",
    "tools": ["Edit", "Bash", "Read"],
    "files": ["src/auth.ts", "package.json"],
    "accomplishments": ["fixed auth bug", "added unit tests"],
    "decisions": ["chose JWT over sessions"]
  }
}

方法

claude-historian-mcp 的工作原理：

"docker auth" query
      |
      ├─> Parallel Processing (search.ts:174): 15 projects × 10 files concurrently
      |   • Promise.allSettled for 6x speed improvement
      |   • Early termination when sufficient results found
      |   • Enhanced file coverage with comprehensive patterns
      |
      ├─> Enhanced Classification (search.ts:642): implementation → boost tool workflows
      |   • Workflow detection for tool sequences (Edit → Read → Bash)
      |   • Semantic boundary preservation (never truncate mid-function)
      |   • Claude-optimized formatting with rich metadata
      |
      ├─> Smart Ranking (utils.ts:267):
      |   ├─> Core Terms (scoring-constants.ts): "docker" +10, "auth" +10
      |   ├─> Supporting Terms: context words +3 each
      |   ├─> Tool Usage: Edit/Bash references +5
      |   ├─> File References: paths/extensions +3
      |   └─> Project Match: current project +5
      |
      ├─> Results sorted by composite score:
      |   • "Edit workflow (7x successful)" (2h ago) ***** [score: 45]
      |   • "Docker auth with context paths" (yesterday) **** [score: 38]
      |   • "Container debugging patterns" (last week) *** [score: 22]
      |
      └─> Return Claude Code optimized results

核心优化：

• 并行处理：使用 Promise.allSettled，跨项目和文件实现 6 倍速度提升
• 工作流检测：捕获“Edit → Read → Bash”等工具调用序列模式
• 增强的文件匹配：全面覆盖各种路径形式，并支持不区分大小写匹配
• 智能去重：基于内容去重，同时保留得分最高的结果
• 智能截断：绝不会在函数或错误内容中途截断
• 针对 Claude 优化的格式：提供丰富的元数据，并优先呈现技术内容

搜索策略：

• JSON 流式解析器 (parseJsonlFile)：按需读取 Claude Code 对话文件，无需完整反序列化
• LRU 缓存 (messageCache)：内存缓存，可智能淘汰频繁访问的对话
• 受 TF-IDF 启发的评分 (calculateRelevanceScore)：结合文档频率权重计算词频得分，以评估相关性
• 查询分类 (classifyQueryType)：采用朴素贝叶斯风格分类（错误／实现／分析／通用），并动态调整限制
• 编辑距离 (calculateQuerySimilarity)：对技术术语进行模糊匹配，并容忍拼写错误
• 指数时间衰减 (getTimeRangeFilter)：提高近期消息的权重，并支持配置半衰期
• 并行文件处理 (getErrorSolutions)：并发扫描项目，并提前终止，实现 0.8s 响应时间
• 工作流模式识别 (getToolPatterns)：检测工具使用序列和相关工作流，以便学习
• 增强的文件上下文 (findFileContext)：通过全面的路径匹配搜索多个项目
• 内容感知截断 (smartTruncation)：依据智能内容边界截断，而非任意字符数限制
• 技术内容优先保留 (BeautifulFormatter)：完整保留代码块、错误信息和文件路径
• 查询相似度聚类 (findSimilarQueries)：扩展语义并对模式分组，以关联相关问题

设计原则：

• 通用引擎 —— 为所有 Claude Code 对话提供单一搜索后端
• 并行处理 —— 并发扫描会话目录中的文件
• 语义扩展 —— 使用查询同义词和相关词提升召回率
• 零依赖 —— 仅依赖 @modelcontextprotocol/sdk，无需数据库
• 离线运行 —— 数据不会离开你的计算机，仅扫描本地 JSONL 文件

文件访问：

• 读取路径：~/.claude/conversations/
• 不进行持久化存储或索引
• 数据不会离开你的计算机

性能： 基准测试、优化历史和质量评分请参阅 PERFORMANCE.md。

替代方案

每款对话历史工具要么始终加载上下文（未使用时也会消耗 token），要么需要外部运行时和数据库。Historian 可按需搜索，且零依赖。

功能	historian	Claude Memory	claude-mem	deja	conversation-search
依赖项	零	内置	Bun + Python + SQLite + Chroma	Python	Rust 工具链
后台服务	否	否	是（端口 37777）	否	否
写入磁盘	从不	是（自动记忆文件）	是（SQLite + Chroma DB）	是（线索记录）	是（约 10% 的索引开销）
会话启动	0 个 token	加载约 200 行	每个会话 5-8k 个 token	加载技能提示词	0 个 token
空闲时的 token 开销	0	每个会话 200 行	每个会话 5-8k 个 token	每个会话的技能提示词	0
搜索算法	12	无（读取文件）	向量 + 关键词	加权信号	BM25 全文搜索
模糊匹配	是	否	是（向量相似度）	否	否
工作流检测	是	否	否	否	否
原始对话	是	否（仅摘要）	否（压缩后的观察记录）	是	是（经过筛选）
维护	零	零	工作进程守护程序、迁移	技能配置	重建索引

Claude Memory——Claude 内置的记忆（CLAUDE.md + 自动记忆）。可在不同会话间保存项目规则和偏好。它面向未来（例如“始终使用 ESM 导入”），而非用于搜索对话。互为补充：memory 用于规则，historian 用于查找以往的解决方案。

claude-mem——一款通过生命周期钩子捕获观察记录、将其压缩到 SQLite + Chroma 中，并在每个会话加载上下文的插件。需要 Bun、Python，以及运行在端口 37777 上的后台工作进程。真实场景测试（270 多个会话）显示：95% 的会话从未查询历史记录——始终运行的工具无论是否使用，每个会话都会消耗 5-8k 个 token。Historian 空闲时不消耗 token，每次查询消耗 500-2k 个 token，在 100 个会话中可节省约 475k 个 token。已知问题：会创建导致 --continue 出错的会话占位文件、工作进程守护程序版本冲突、安全钩子会阻止有效编辑。

deja——一款按事件和成果为会话建立索引的 Python 技能。使用加权信号排序（待办事项 > 文件 > 文本）。需要 Python 和 TodoWrite 集成。

conversation-search——一款使用 Tantivy BM25 全文搜索的 Rust MCP 服务。索引速度快（约每秒 1000 个对话），但需要 Rust 工具链和持久化磁盘索引。

桌面应用

注意： Claude Desktop 将对话存储在服务端，而非本地。~/Library/Application Support/Claude/ 中的本地 LevelDB 文件仅包含会话令牌、界面偏好设置和 Intercom 状态，不包含对话内容。Claude Desktop 支持还受到 LevelDB 锁和 Electron 沙箱机制的阻碍。

这意味着，目前无法在本地搜索 Claude Desktop 的历史记录。本项目专注于 Claude Code，它会将完整的对话历史记录存储在本地的 ~/.claude/projects/ 中。

只有在 Claude 应用关闭时，你才能从 Claude Code 获取部分 Claude Desktop 数据。此外，现已提供 DXT 软件包和构建版本，以便未来兼容；相关调查仍在进行中。欢迎使用它进行测试。

开发

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

软件包要求：

• Node.js：>=20.0.0（ES 模块）
• 运行时：@modelcontextprotocol/sdk
• 无需外部数据库——可通过 npx 运行

开发工作流：

npm run build          # TypeScript compilation with executable permissions
npm run dev            # Watch mode with tsc --watch
npm run start          # Run the MCP server directly
npm run lint           # ESLint code quality checks
npm run lint:fix       # Auto-fix linting issues
npm run format         # Prettier formatting (src/)
npm run format:check   # Check formatting without changes
npm run typecheck      # TypeScript validation without emit
npm run test           # Lint + type check
npm run prepublishOnly # Pre-publish validation (build + lint + format:check)

Git 钩子（通过 Husky）：

• pre-commit：使用 Prettier 和 ESLint 自动格式化暂存的 .ts 文件
• pre-push：推送前运行完整验证（格式、lint、类型检查、构建）

贡献：

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

参考示例：

• 官方 MCP 服务，了解参考实现
• TypeScript SDK，了解最佳实践
• 创建 Node.js 模块，了解 npm 软件包开发

许可证

MIT

---

阿庇乌斯·克劳狄乌斯·卡埃库斯在元老院，作者为 切萨雷·马卡里（1888 年）。罗马政治家，拉丁散文之父。