Claude History MCP

克劳德历史MCP

一个MCP服务器，使您的Claude Code对话历史可搜索且主动有用。使用混合BM25+TF-IDF搜索对所有过去的会话进行索引，提取知识（决策、解决方案、错误修复），并在会话开始时自动注入项目上下文。

它做什么

Claude Code将完整的对话记录作为JSONL文件存储在 ~/.claude/projects/此MCP服务器对它们进行索引，并提供6个工具：

主要特点

• 混合搜索：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

搜索引擎

1. 分词器：小写→ 条形标记→ 分裂→ 删除停用词→ 波特茎→ 二元组
2. BM25：关键字精度的倒排指数（Okapi BM25，k1=1.2，b=0.75）
3. TF-IDF：稀疏向量+余弦相似度用于语义召回
4. 融合：结合两种排名的互惠排名融合（RRF）
5. 提升：最近度（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 build

1.构建搜索索引

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

许可证

麻省理工学院