claude-historian-mcp

An Model Context Protocol (MCP) server for searching your Claude Code conversation history. Find past solutions, track file changes, and learn from previous work.

---

install

Requirements:

From shell:

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

From inside Claude (restart required):

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

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

From any manually configurable mcp.json: (Cursor, Windsurf, etc.)

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

There is no npm install required -- no external dependencies or local databases, only search algorithms.

However, if npx resolves the wrong package, you can force resolution with:

npm install -g claude-historian-mcp

renamed: This project was renamed from claude-historian to claude-historian-mcp. Existing users should update your install command and MCP config args to claude-historian-mcp.

skill

Optionally, install the skill to teach Claude when to proactively use historian:

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

This makes Claude automatically check your history before web searches, when encountering errors, or at session start. The MCP works without the skill, but the skill improves discoverability.

plugin

For automatic history search with hooks and commands, install from the claude-emporium marketplace:

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

The claude-historian plugin provides:

Hooks (targeted, zero overhead on success):

• Before WebSearch/WebFetch → Check search scope="similar"
• Before EnterPlanMode → Check search scope="plans"
• Before Task agents → Check search scope="tools"
• After Bash errors → Check search scope="errors"

Command: /historian-search <query>

Requires the MCP server installed first. See the emporium for other Claude Code plugins and MCPs.

features

MCP server that gives Claude access to your conversation history. Two tools, 11 scopes, zero dependencies.

Runs locally (with cool shades [⌐■_■] 📜):

search

Search across conversations, files, errors, plans, config, tasks, sessions, tools, similar queries, and memories.

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

Get an intelligent summary of any session by ID (full UUID or short prefix).

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"]
  }
}

methodology

How claude-historian-mcp works:

"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

Core optimizations:

• parallel processing: Promise.allSettled for 6x speed improvement across projects and files
• workflow detection: Captures tool sequences like "Edit → Read → Bash" patterns
• enhanced file matching: Comprehensive path variations with case-insensitive matching
• intelligent deduplication: Content-based deduplication preserving highest-scoring results
• intelligent truncation: Never truncates mid-function or mid-error
• Claude-optimized formatting: Rich metadata with technical content prioritization

Search strategies:

• JSON streaming parser (parseJsonlFile): Reads Claude Code conversation files on-demand without full deserialization
• LRU caching (messageCache): In-memory cache with intelligent eviction for frequently accessed conversations
• TF-IDF inspired scoring (calculateRelevanceScore): Term frequency scoring with document frequency weighting for relevance
• Query classification (classifyQueryType): Naive Bayes-style classification (error/implementation/analysis/general) with adaptive limits
• Edit distance (calculateQuerySimilarity): Fuzzy matching for technical terms and typo tolerance
• Exponential time decay (getTimeRangeFilter): Recent messages weighted higher with configurable half-life
• Parallel file processing (getErrorSolutions): Concurrent project scanning with early termination for 0.8s response times
• Workflow pattern recognition (getToolPatterns): Detects tool usage sequences and related workflows for learning
• Enhanced file context (findFileContext): Multi-project search with comprehensive path matching
• Content-aware truncation (smartTruncation): Intelligent content boundaries over arbitrary character limits
• Technical content prioritization (BeautifulFormatter): Code blocks, errors, and file paths get full preservation
• Query similarity clustering (findSimilarQueries): Semantic expansion and pattern grouping for related questions

Design principles:

• Universal engine -- single search backend for all Claude Code conversations
• Parallel processing -- concurrent file scanning across session directories
• Semantic expansion -- query synonyms and related terms for better recall
• Zero dependencies -- only @modelcontextprotocol/sdk, no databases required
• Offline -- never leaves your machine, scans local JSONL files only

File access:

• Reads from: ~/.claude/conversations/
• Zero persistent storage or indexing
• Never leaves your machine

Performance: See PERFORMANCE.md for benchmarks, optimization history, and quality scores.

alternatives

Every conversation history tool either loads context always (burning tokens when unused) or requires external runtimes and databases. Historian searches on-demand with zero dependencies.

Feature	historian	Claude Memory	claude-mem	deja	conversation-search
Dependencies	Zero	Built-in	Bun + Python + SQLite + Chroma	Python	Rust toolchain
Background service	No	No	Yes (port 37777)	No	No
Writes to disk	Never	Yes (auto-memory files)	Yes (SQLite + Chroma DB)	Yes (breadcrumbs)	Yes (~10% index overhead)
Session startup	0 tokens	~200 lines loaded	5-8k tokens every session	Skill prompt loaded	0 tokens
Token cost (idle)	0	200 lines/session	5-8k/session	Skill prompt/session	0
Search algorithms	12	None (file read)	Vector + keyword	Weighted signals	BM25 full-text
Fuzzy matching	Yes	No	Yes (vector similarity)	No	No
Workflow detection	Yes	No	No	No	No
Raw conversations	Yes	No (summaries only)	No (compressed observations)	Yes	Yes (filtered)
Maintenance	Zero	Zero	Worker daemons, migrations	Skill config	Index rebuilds

Claude Memory -- Claude's built-in memory (CLAUDE.md + auto-memory). Persists project rules and preferences across sessions. Forward-looking ("always use ESM imports"); not conversation search. Complementary: memory for rules, historian for past solutions.

claude-mem -- Plugin that captures observations via lifecycle hooks, compresses them into SQLite + Chroma, and loads context every session. Requires Bun, Python, and a background worker on port 37777. Real-world testing (270+ sessions): 95% of sessions never query history -- always-on tools pay 5-8k tokens per session regardless. Historian pays 0 tokens idle, 500-2k per query, saving ~475k tokens over 100 sessions. Known issues: creates stub session files that break --continue, worker daemon version conflicts, security hooks blocking valid edits.

deja -- Python skill that indexes sessions by episodes and accomplishments. Uses weighted signal ranking (todos > files > text). Requires Python and TodoWrite integration.

conversation-search -- Rust MCP server using Tantivy BM25 full-text search. Fast indexing (~1000 conversations/second) but requires Rust toolchain and persistent disk index.

desktop

Note: Claude Desktop stores conversations server-side, not locally. The local LevelDB files (~/Library/Application Support/Claude/) contain only session tokens, UI preferences, and Intercom state - not conversation content. Claude Desktop support is also blocked by LevelDB locks and Electron sandboxing.

This means local history search for Claude Desktop is not currently possible. This project focuses on Claude Code, which stores full conversation history locally in ~/.claude/projects/.

You may get some Claude Desktop from Claude Code, but only when the Claude app is closed. Furthermore A DXT package and build is available for future compatibility; further investigations are ongoing. Feel free to test with it.

development

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

Package requirements:

• Node.js: >=20.0.0 (ES modules)
• Runtime: @modelcontextprotocol/sdk
• Zero external databases -- works with npx

Development workflow:

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 hooks (via Husky):

• pre-commit: Auto-formats staged .ts files with Prettier and ESLint
• pre-push: Runs full validation (format, lint, type-check, build) before push

Contributing:

• Fork the repository and create feature branches
• Test with large conversation histories before submitting PRs
• Follow TypeScript strict mode and MCP protocol standards

Learn from examples:

• Official MCP servers for reference implementations
• TypeScript SDK for best practices
• Creating Node.js modules for npm package development

license

MIT

---

Appius Claudius Caecus in the Senate by Cesare Maccari (1888). Roman statesman and father of Latin prose.