Claude History MCP

An MCP server that makes your Claude Code conversation history searchable and proactively useful. Indexes all past sessions with hybrid BM25 + TF-IDF search, extracts knowledge (decisions, solutions, error fixes), and auto-injects project context at session start.

What it does

Claude Code stores full conversation transcripts as JSONL files in ~/.claude/projects/. This MCP server indexes them and provides 6 tools:

Tool	Purpose
search_history	Full-text search across all conversations with filter syntax
find_solutions	Find how you fixed errors/problems before
get_session_summary	Structured summary of any session
list_projects	List all projects with session counts and dates
find_patterns	Discover recurring topics, workflows, and issues
get_project_context	Full project context (recent sessions, decisions, knowledge)
cloud_sync_push	Push knowledge and sessions to cloud server
cloud_sync_pull	Pull knowledge and sessions from cloud server
cloud_sync_status	Check cloud sync configuration and connection

Key features

• Hybrid search: BM25 (keyword precision) + TF-IDF (semantic recall) fused with Reciprocal Rank Fusion
• Filter syntax: project:name, before:7d, after:2024-01-15, tool:Bash
• Knowledge extraction: Automatically extracts decisions, solutions, and error→fix patterns from conversations
• Proactive context: Session-start hook injects relevant project history into new sessions
• Incremental indexing: File watcher detects new/changed sessions and re-indexes automatically
• Fast: Index build ~9s for 170 sessions, searches <200ms

How it works

┌──────────────────────────────────────────────────────┐
│                  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

Search engine

1. Tokenizer: lowercase → strip markdown → split → remove stop words → Porter stem → bigrams
2. BM25: Inverted index for keyword precision (Okapi BM25, k1=1.2, b=0.75)
3. TF-IDF: Sparse vectors + cosine similarity for semantic recall
4. Fusion: Reciprocal Rank Fusion (RRF) combining both rankings
5. Boosting: recency (7d=1.2x, 30d=1.1x) + project-match (1.3x if cwd matches)

Knowledge extraction

When sessions end (file stops changing for 5+ minutes), the system automatically extracts:

• Decisions: "decided to", "going with", "chose" patterns
• Solutions: "fixed", "solved", "the issue was" patterns
• Error fixes: error → resolution sequences

Data storage

Runtime data stored at ~/.claude-history-mcp/: