Claude Historian

🚀 claude-historian

A Model Context Protocol (MCP) server enabling you to search your Claude Code conversation history. It helps you find past solutions, track file changes, and learn from previous work.

🚀 Quick Start

Prerequisites

• Claude Code

Installation Methods

• From shell:

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

• From inside Claude (restart required):

Add this to our global mcp config: npx claude-historian
Install this mcp: https://github.com/Vvkmnn/claude-historian

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

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

No npm install is needed as there are no external dependencies or local databases, only search algorithms.

✨ Features

It is an MCP server that allows Claude to access your conversation history. It offers fast search with smart prioritization.

It runs locally (with the cool symbol [⌐■_■]):

[⌐■_■] search_conversations query=<query>
  > "How did we fix that Redis connection pooling nightmare?"
  > "Docker container keeps crashing on Kubernetes deployment"
  > "React infinite re-render loop - useEffect dependency hell"

[⌐□_□] find_file_context filepath=<filepath>
  > "package.json changes that broke everything last month"
  > "When we accidentally committed .env to main branch"
  > "Authentication service refactor - before/after comparison"

[⌐×_×] get_error_solutions error_pattern=<error>
  > "MODULE_NOT_FOUND - the classic npm/yarn version mismatch"
  > "CORS preflight failing - but only on production Fridays?"
  > "Database deadlock during Black Friday traffic spike"

[⌐◆_◆] find_similar_queries query=<query>
  > "Database queries slower than my morning coffee brewing"
  > "How to implement error boundaries without losing sanity"
  > "State management: Redux vs Zustand vs just useState"

[⌐○_○] list_recent_sessions
  > "Tuesday debugging marathon: 9pm - 3am flaky test hunt"
  > "Performance optimization sprint - reduced bundle 40%"
  > "The great TypeScript migration of 2024"

[⌐⎚_⎚] find_tool_patterns tool_name=<tool>
  > "Read → Edit → Bash combo for rapid prototyping"
  > "When I use Grep vs Task for different searches"
  > "Git operations during feature branch management"

🔧 Technical Details

How claude-historian Works (source)

"docker auth" query
      |
      ├─> Classify: implementation query -> boost tool examples
      |
      ├─> Stream & Filter:
      |   • Summary messages -> priority queue *****
      |   • Tool usage context -> high value ****
      |   • Error solutions -> targeted ***
      |
      ├─> Smart Ranking:
      |   • "Fixed Docker auth with Read tool" (2h ago) *****
      |   • "OAuth implementation approach" (yesterday) ****
      |   • "Container auth debug" (last week) ***
      |
      └─> Return Claude Code optimized results

Key Technologies

• JSON streaming parser: Reads Claude Code conversation files on-demand without full deserialization.
• LRU caching: In-memory cache with intelligent eviction for frequently accessed conversations.
• TF - IDF inspired scoring: Term frequency scoring with document frequency weighting for relevance.
• Query classification: Naive Bayes - style classification (error/implementation/analysis/general) with adaptive limits.
• Edit distance: Fuzzy matching for technical terms and typo tolerance.
• Exponential time decay: Recent messages weighted higher with configurable half - life.

File Access

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

📦 Installation

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

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.

Learning Resources

• Official MCP servers for reference implementations.
• TypeScript SDK for best practices.

📄 License

MIT

Claude Fauchet (1744 - 1793), French Historian