克劳德历史MCP
一个MCP服务器，使您的Claude Code对话历史可搜索且主动有用。使用混合BM25+TF-IDF搜索对所有过去的会话进行索引，提取知识（决策、解决方案、错误修复），并在会话开始时自动注入项目上下文。
它做什么
Claude Code将完整的对话记录作为JSONL文件存储在 ~/.claude/projects/此MCP服务器对它们进行索引，并提供6个工具：
| 工具 | 目的 |
|---|---|
search_history | 使用筛选器语法在所有对话中进行全文搜索 |
find_solutions | 了解您之前是如何修复错误/问题的 |
get_session_summary | 任何会议的结构化摘要 |
list_projects | 列出所有包含会话计数和日期的项目 |
find_patterns | 发现重复出现的主题、工作流程和问题 |
get_project_context | 完整的项目背景（最近的会议、决定、知识） |
cloud_sync_push | 将知识和会话推送到云服务器 |
cloud_sync_pull | 从云服务器提取知识和会话 |
cloud_sync_status | 检查云同步配置和连接 |
主要特点
- 混合搜索：BM25（关键字精度）+TF-IDF（语义召回）与互易秩融合
- 筛选器语法:
project:name,before:7d,after:2024-01-15,tool:Bash - 知识抽取：自动提取决策、解决方案和错误→从对话中修正模式
- 主动式情境：会话开始挂钩将相关项目历史记录注入新会话
- 增量索引：文件监视器检测新的/更改的会话并自动重新索引
- 快：索引构建约9秒，170个会话，搜索\<200毫秒
运作原理
┌──────────────────────────────────────────────────────┐
│ ClaudeHistoryMCP │
├──────────────┬───────────────┬───────────────────────┤
│ MCP Server │ /claude-history │ SessionStart Hook │
│ (6 tools) │ Skill │ (auto-context) │
├──────────────┴───────────────┴───────────────────────┤
│ Hybrid Search Engine │
│ BM25 (keywords) + TF-IDF (semantic) │
├──────────────────────────────────────────────────────┤
│ Indexing Pipeline │ Knowledge Layer │ Summaries │
├──────────────────────────────────────────────────────┤
│ JSONL Parsers │ File Watcher │ Document Store │
└──────────────────────────────────────────────────────┘
↕ ↕
~/.claude/history.jsonl ~/.claude/projects/*/*.jsonl搜索引擎
- 分词器：小写→ 条形标记→ 分裂→ 删除停用词→ 波特茎→ 二元组
- BM25：关键字精度的倒排指数（Okapi BM25，k1=1.2，b=0.75）
- TF-IDF：稀疏向量+余弦相似度用于语义召回
- 融合：结合两种排名的互惠排名融合（RRF）
- 提升：最近度（7天=1.2倍，30天=1.1倍）+项目匹配（如果cwd匹配，则为1.3倍）
知识抽取
当会话结束时（文件停止更改5分钟以上），系统会自动提取：
- 决策：“决定”、“配合”、“选择”模式
- 解决方案：“已修复”、“已解决”、“问题是”模式
- 错误修复：错误→ 分辨率序列
数据存储
运行时数据存储在 ~/.claude-history-mcp/:
~/.claude-history-mcp/
index.msgpack # Serialized search index
knowledge.json # Extracted knowledge entries
summaries/{sessionId}.json # Cached session summaries
meta.json # Last-indexed timestamps安装
git clone https://github.com/jhammant/ClaudeHistoryMCP.git
cd ClaudeHistoryMCP
npm install
npm run build1.构建搜索索引
npm run build-index这将解析您的所有Claude Code对话历史并构建搜索索引。大约170个会话需要大约10秒。
2.注册MCP服务器
claude mcp add claude-history -- node "/path/to/ClaudeHistoryMCP/dist/index.js"3.安装会话开始挂钩和技能（可选）
npm run install-hook这注册了一个 SessionStart 钩住 ~/.claude/settings.json 自动注入项目上下文，并安装 /claude-history 技能。
4.添加到您的CLAUDE.md（推荐）
将以下内容添加到您的全局 ~/.claude/CLAUDE.md 确保Claude主动使用历史工具：
## Claude History MCP
When the `claude-history` MCP is available, use it proactively:
- **Session start**: Use `get_project_context` to check for prior decisions, patterns, and recent session summaries for the current project
- **Debugging**: Use `find_solutions` to search history for past fixes before starting from scratch
- **Context questions**: When the user asks "have we done X before", "what did we decide", or similar — use `search_history` to find relevant past conversations
- **Patterns**: Use `find_patterns` to identify recurring workflows or issues when relevant没有这一点，克劳德可以使用这些工具，但可能并不总是想去使用它们。
5.配置云同步（可选）
要跨设备同步知识或与团队共享，请设置 克劳德历史云:
export CLAUDE_HISTORY_API_URL=https://your-server.com
export CLAUDE_HISTORY_API_KEY=your-api-key
export CLAUDE_HISTORY_TEAM_ID=optional-team-uuid # for team sync然后使用 cloud_sync_push 和 cloud_sync_pull 工具同步。
用法
通过MCP工具（自动）
注册后，Claude Code可以直接使用这些工具：
User: "Have I dealt with this ECONNREFUSED error before?"
Claude: [calls find_solutions with "ECONNREFUSED"]
→ Shows past solutions from your history通过/claude历史技能
/claude-history docker network error # General search
/claude-history --solutions ECONNREFUSED # Find past error fixes
/claude-history --summary # Summarize last session
/claude-history --patterns # Discover recurring patterns
/claude-history --context # Get full project context
/claude-history --projects # List all projects筛选器语法
查询支持内联过滤器：
search_history("docker error project:ghostty after:7d")
search_history("authentication tool:Bash before:2024-06-01")
search_history("deployment project:myapp after:30d")project:name--筛选到项目（部分匹配）before:date/after:date--日期过滤器（ISO或相对：7d,1w,1m,1y)tool:name--使用特定工具筛选会话
会话启动挂钩
当你启动一个新的Claude Code会话时，钩子会自动输出：
[ClaudeHistory] Previous context for myproject:
- Last session (2 days ago): Fixed Docker networking — switched to host networking
- Key decision: Use systemd timer instead of cron for scheduling
- Solution found: CORS issue resolved by adding proxy config项目结构
src/
index.ts # MCP server entry (stdio transport)
server.ts # Tool registration via McpServer + zod
config.ts # Paths, constants, defaults
parsers/
history-parser.ts # Parse ~/.claude/history.jsonl
session-parser.ts # Stream-parse session JSONL files
content-extractor.ts # Extract text from message content arrays
indexing/
index-manager.ts # Orchestrate indexing, persistence, incremental updates
bm25.ts # BM25 inverted index (Okapi BM25)
tfidf.ts # TF-IDF vectors + cosine similarity
tokenizer.ts # Tokenize, stem, stop words, bigrams
document-store.ts # Store indexed document chunks + metadata
search/
search-engine.ts # Hybrid search: BM25 + TF-IDF + RRF fusion
query-processor.ts # Parse query syntax (project:, before:, after:)
result-ranker.ts # Score fusion, recency/project boost, dedup
knowledge/
knowledge-store.ts # Persist extracted knowledge entries
session-summarizer.ts # Generate session summaries (heuristic, no LLM)
knowledge-extractor.ts # Extract decisions, solutions, error fixes
sync/
cloud-client.ts # HTTP client for ClaudeHistory Cloud API
sync-state.ts # Track last sync timestamps
watcher/
file-watcher.ts # Debounced fs.watch on conversation files
incremental-indexer.ts # Diff mtimes, re-index only changed files
tools/ # One file per MCP tool handler
hooks/
session-start-hook.ts # Auto-inject project context on session start
utils/
stemmer.ts # Inline Porter stemmer (no deps)
path-encoder.ts # Encode/decode Claude's project path format
cache.ts # LRU cache
cli/
build-index.ts # Build the full search index
install.ts # Install hook + skill
commands/
claude-history.md # /claude-history skill definition
tests/ # Unit + integration tests (82 tests)依赖项
最小--只有2个运行时依赖关系：
@modelcontextprotocol/sdk--MCP协议msgpackr--高效的索引序列化zod--模式验证（MCP SDK的对等端）
Porter词干分析器和停用词是内联实现的。
发展
npm run dev # Run with tsx (no build needed)
npm run build # Compile TypeScript
npm test # Run tests
npm run test:watch # Watch mode
npm run build-index # Rebuild the search index许可证
麻省理工学院