claude-historian

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

install

Requirements:

• Claude Code

From shell:

From inside Claude (restart required):

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

That's it; there is no as there are no external dependencies or local databases, only search algorithms.

However, in the unlikely event that you pull the wrong package / npx registry is out of date, you can force resolution issues in certain environments with:

features

MCP server that gives Claude access to your conversation history. Fast search with smart prioritization.

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

methodology

How claude-historian works:

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 (formatSearchResults): Code blocks, errors, and file paths get full preservation

• Query similarity clustering (findSimilarQueries): Semantic expansion and pattern grouping for related questions

File access:

• Reads from: ~/.claude/conversations/

• Zero persistent storage or indexing

• Never leaves your machine

development

Package requirements:

• Node.js: >=20.0.0 (ES modules support)

• npm: >=10.0.0 (package-lock v3)

• Runtime: Only @modelcontextprotocol/sdk dependency

• Zero external dependencies for production deployment

• Optimized: 50% token reduction with parallel processing

Development workflow:

Contributing:

• Please 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 - NPM package development guide

desktop

Claude Desktop support is currently blocked by LevelDB locks and Electron sandboxing. You will still search Claude Desktop from Claude Code, but only when the Claude app is closed.

A DXT package and build is available for future compatibility; further investigations are ongoing. Feel free to test with it.

license

MIT

Claude Fauchet (1744-1793), French Historian