使用说明

克劳德历史学家mcp

一模型上下文协议（MCP）用于搜索您的克劳德代码对话历史。查找过去的解决方案，跟踪文件更改，并从以前的工作中学习。

安装

要求：

来自shell：

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

从内部克劳德 （需要重新启动）：

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

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

从任何手动配置 mcp.json：（光标、风帆等）

{
  "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.

技能

可选地，安装技能来教克劳德何时主动使用历史记录：

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

这使得克劳德在网络搜索之前、遇到错误时或会话开始时自动检查您的历史记录。MCP在没有技能的情况下工作，但技能提高了可发现性。

插件

要使用钩子和命令进行自动历史搜索，请从安装克劳德商场市场：

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

这 克劳德历史学家 插件提供：

钩子（目标明确，成功后零开销）：

在WebSearch/WebFetch之前→ Check search scope="similar"
进入计划模式之前→ Check search scope="plans"
任务代理之前→ Check search scope="tools"
Bash错误后→ Check search scope="errors"

命令： /historian-search <query>

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

特征

MCP服务器这让克劳德可以访问你的对话历史记录。两个工具，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"]
  }
}

方法论

如何克劳德历史学家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倍的速度提升
工作流检测：捕获工具序列，如“编辑”→ Read → Bash”模式
增强的文件匹配：具有不区分大小写匹配的全面路径变化
智能重复数据删除：基于内容的重复数据删除保留了得分最高的结果
智能截断：从不截断中间函数或中间错误
Claude优化格式：具有技术内容优先级的丰富元数据

搜索策略：

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

设计原则：

通用发动机 --所有Claude Code对话的单一搜索后端
并行处理 --跨会话目录的并发文件扫描
语义扩展 --查询同义词和相关术语以更好地回忆
零依赖 --只有 @modelcontextprotocol/sdk，不需要数据库
离线 --永不离开您的计算机，仅扫描本地JSONL文件

文件访问：

阅读来源： ~/.claude/conversations/
零持久存储或索引
永远不要离开你的机器

演出看性能.md 用于基准测试、优化历史和质量分数。

替代方案

每个对话历史记录工具要么始终加载上下文（未使用时燃烧令牌），要么需要外部运行时和数据库。Historian按需搜索，零依赖。

|特点| 历史学家 |克劳德记忆|克劳德记忆|对话搜索| | ----------------------- | ----------------------- | ----------------------- | -------------------------------- | ------------------- | ---------------------------- | | 依赖项 | 零 |内置| Bun+Python+SQLite+Chroma | Python | Rust工具链| | 后台服务 | 不 |否|是（端口37777）|否|否| | 写入磁盘 | 从不 |是（自动内存文件）|是（SQLite+Chroma DB）|是| | 会话启动 | 0个令牌 |加载约200行|每次会话5-8k代币|加载技能提示|0代币| | 代币成本（闲置） | 0 |200行/课时|5-8k/课时|技能提示/课时|0| | 搜索算法 | 12 |无（文件读取）|矢量+关键字|加权信号|BM25全文| | 模糊匹配 | 是 |否|是（向量相似性）|否|否| | 工作流检测 | 是 |否|否|否| | 原始对话 | 是 |否（仅摘要）|否（压缩观察）|是|是（过滤）| | 维护 | 零 |零|工作进程、迁移|技能配置|索引重建|

克劳德记忆 --克劳德的内置存储器(CLAUDE.md +自动存储器）。在会话中保持项目规则和偏好。前瞻性（“始终使用ESM进口”）；不是对话搜索。 互补的：规则的记忆，过去解决方案的历史学家。

克劳德·梅 --该插件通过生命周期挂钩捕获观察结果，将其压缩到SQLite+Chroma中，并在每个会话中加载上下文。需要Bun、Python和端口37777上的后台工作者。真实世界测试（270多个会话）：95%的会话从不查询历史记录——不管怎样，始终在线的工具每次会话都要支付5-8k的令牌。Historian支付0个空闲令牌，每个查询500-2k，在100个会话中节省约475k令牌。已知问题：创建中断的存根会话文件 --continue，工作进程版本冲突，安全挂钩阻止有效编辑。

似曾相识 --Python技能，按情节和成就对会话进行索引。使用加权信号排名（待办事项>文件>文本）。需要Python和TodoWrite集成。

对话搜索 --Rust MCP服务器使用Tantivy BM25全文搜索。快速索引（约1000个对话/秒），但需要Rust工具链和持久磁盘索引。

桌面

注： Claude Desktop将对话存储在服务器端，而不是本地。本地LevelDB文件(~/Library/Application Support/Claude/)仅包含会话令牌、UI首选项和内部通信状态，不包含对话内容。Claude Desktop支持也被阻止 LevelDB锁和电子沙盒.

这意味着 当前无法搜索Claude Desktop的本地历史记录.本项目的重点是 克劳德代码，它在本地存储完整的对话历史记录 ~/.claude/projects/.

您可以从Claude Code获得一些Claude Desktop，但是 仅当Claude应用程序关闭时此外，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钩子（通过赫斯基）：

预承诺：自动格式化已暂存 .ts 使用Prettier和ESLint的文件
预推：在推送之前运行完整验证（格式、lint、类型检查、构建）

贡献：

分叉存储库并创建功能分支
在提交PR之前，使用大量对话历史记录进行测试
遵循TypeScript严格模式 MCP协议标准

从示例中学习：

官方MCP服务器供参考实现
TypeScript SDK 最佳实践
创建Node.js模块用于npm包开发

许可证

麻省理工学院

Appius Claudius Caecus在参议院 通过 凯撒马卡里 (1888).罗马政治家，拉丁散文之父。

使用说明

克劳德历史学家mcp

安装

技能

插件

特征

search

inspect

方法论

替代方案

桌面

发展

许可证

相关 MCP

Blender 3D建模MCP服务

iOS模拟器交互服务器

网页抓取与搜索MCP服务器

B站视频搜索服务

Minecraft MCP服务器

SSH远程命令执行MCP服务器

`search`

`inspect`