/ Directory / Playground / Claude Historian
← All servers ↗ GitHub
● Community Vvkmnn ⚡ Instant

Claude Historian

by Vvkmnn · Vvkmnn/claude-historian-mcp

Search your own Claude Code history — find past solutions, errors, plans, and sessions without a separate index.

claude-historian-mcp treats your local ~/.claude/conversations/ as a searchable corpus. Two tools: search queries across 11 scopes (conversations, errors, plans, config, tasks, sessions, tools, similar queries, memories…) with TF-IDF-inspired scoring, fuzzy matching, and workflow-pattern detection; inspect returns an intelligent summary of any session by full UUID or short prefix. No persistent index — it processes projects in parallel on demand. Use it to avoid re-solving the same bug, reuse a plan, or surface a half-remembered command.

▶ Watch demo 📦 Install 💡 Use Cases

Why use it

Key features

Live Demo

What it looks like in practice

claude-historian-mcp.replay ▶ ready
0/0

Install

Pick your client

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "claude-historian-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "claude-historian-mcp"
      ]
    }
  }
}

Open Claude Desktop → Settings → Developer → Edit Config. Restart after saving.

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "claude-historian-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "claude-historian-mcp"
      ]
    }
  }
}

Cursor uses the same mcpServers schema as Claude Desktop. Project config wins over global.

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "claude-historian-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "claude-historian-mcp"
      ]
    }
  }
}

Click the MCP Servers icon in the Cline sidebar, then "Edit Configuration".

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "claude-historian-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "claude-historian-mcp"
      ]
    }
  }
}

Same shape as Claude Desktop. Restart Windsurf to pick up changes.

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "claude-historian-mcp",
      "command": "npx",
      "args": [
        "-y",
        "claude-historian-mcp"
      ]
    }
  ]
}

Continue uses an array of server objects rather than a map.

~/.config/zed/settings.json
{
  "context_servers": {
    "claude-historian-mcp": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "claude-historian-mcp"
        ]
      }
    }
  }
}

Add to context_servers. Zed hot-reloads on save.

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

One-liner. Verify with claude mcp list. Remove with claude mcp remove.

Use Cases

Real-world ways to use Claude Historian

Find how you fixed a similar bug before

👤 Developers who use Claude Code across many sessions ⏱ ~5 min beginner

When to use: You're hitting an error that feels familiar; you want to see what worked last time.

Prerequisites
  • Claude Code with existing conversation history — Default — history lives in ~/.claude/conversations/
Flow
  1. Search errors
    Search my history for 'ECONNREFUSED redis' — scope: errors.✓ Copied
    → Ranked list of prior sessions where that error came up
  2. Inspect the best hit
    Inspect session abc12345 — what was the fix?✓ Copied
    → Summary names the root cause and the applied fix

Outcome: A concrete precedent in seconds, not a re-debug from scratch.

Pitfalls
  • Trusting the summary without reading the session — Use inspect for the summary, then open the session file for the actual diffs
Combine with: filesystem

Pull up a past implementation plan to reuse

👤 Anyone who frequently plans tasks with Claude ⏱ ~10 min beginner

When to use: New feature looks like one you planned months ago — you want the skeleton back.

Flow
  1. Search plans
    Search scope: plans, for 'background job retry with exponential backoff'.✓ Copied
    → Hits include the plan headings and the session ID
  2. Inspect and adapt
    Inspect the top hit; summarize the plan and adapt for Postgres-backed queues.✓ Copied
    → Adapted plan in the same structure as the original

Outcome: Reused thinking without re-generating the scaffold.

Combine with: codebase-memory

Warm-start a new session with past context

👤 Heavy Claude Code users ⏱ ~10 min intermediate

When to use: You start a fresh chat on an old project and don't want to re-explain context.

Flow
  1. Search for project mentions
    Search scope: sessions for 'acme-api billing', group by project.✓ Copied
    → The most relevant 3–5 sessions for that project
  2. Inspect to hydrate
    Inspect session 7f3e2a10. Summarize architectural decisions and known bugs.✓ Copied
    → Clean summary that grounds the new session

Outcome: New session picks up where the last useful one left off.

Pitfalls
  • Loading too many sessions at once and drowning in context — Cap to top-5 by score; use inspect on just the best one
Combine with: memory-bank-mcp

Combinations

Pair with other MCPs for X10 leverage

claude-historian-mcp + filesystem

After inspect, open the referenced files for the actual diffs

Inspect session X. Then open the files mentioned and show the relevant parts.✓ Copied
claude-historian-mcp + memory-bank-mcp

Promote a one-off fix into durable memory

The fix from session X looks load-bearing; add it to memory-bank/<project>/bugs.md.✓ Copied
claude-historian-mcp + codebase-memory

Ground the historian's text hits in the code graph

Session X touches fn retryBilling — show me current callers via codebase-memory.✓ Copied

Tools

What this MCP exposes

ToolInputsWhen to callCost
search query: str, scope: one-of (conversations|errors|plans|config|tasks|sessions|tools|similar|memories|…), limit?: int Find prior conversations that relate to your current task 0
inspect session_id: str (full UUID or short prefix) Get a human-readable recap of a single session 0

Cost & Limits

What this costs to run

API quota
None — local file scan
Tokens per call
Depends on result size; cap with limit
Monetary
Free
Tip
Use narrow scopes (errors, plans) instead of 'conversations' to keep responses small.

Security

Permissions, secrets, blast radius

Credential storage: No credentials. Operates on local files only.
Data egress: Nothing leaves your machine. The MCP server only reads ~/.claude/conversations/.

Troubleshooting

Common errors and fixes

No results even though you know the conversation exists

Try scope='conversations' and relax the query; check ~/.claude/conversations/ is not empty.

Verify: ls ~/.claude/conversations/ | head
Inspect says session not found for a short prefix

Another session starts with the same prefix. Use more characters.

Verify: Grep session IDs: grep -r -l '<prefix>' ~/.claude/conversations/
Slow on very large histories

Pass narrower scope and limit; the tool scans on demand, so huge histories cost more per query.

Verify: du -sh ~/.claude/conversations/

Alternatives

Claude Historian vs others

AlternativeWhen to use it insteadTradeoff
memory-bank-mcpYou want curated, project-scoped memory rather than raw history searchHas to be populated; not free-form retrieval
codebase-memoryYou want a symbol graph of code, not conversation searchDifferent layer
filesystemYou'd rather grep conversations yourselfLose scoring, fuzzy matching, and session summaries

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills