# Claude Historian Mcp

> 📜 An MCP server for conversation history search and retrieval in Claude Code

- **Type:** MCP server
- **Install:** `agentstack add mcp-vvkmnn-claude-historian-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Vvkmnn](https://agentstack.voostack.com/s/vvkmnn)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Vvkmnn](https://github.com/Vvkmnn)
- **Source:** https://github.com/Vvkmnn/claude-historian-mcp
- **Website:** https://www.npmjs.com/package/claude-historian-mcp

## Install

```sh
agentstack add mcp-vvkmnn-claude-historian-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# claude-historian-mcp

An [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for searching your [Claude Code](https://docs.anthropic.com/en/docs/claude-code) conversation history. Find past solutions, track file changes, and learn from previous work.

[](https://www.npmjs.com/package/claude-historian-mcp) [](https://opensource.org/licenses/MIT) [](https://www.typescriptlang.org/) [](https://nodejs.org/) [](#) [](https://github.com/Vvkmnn/claude-historian-mcp) 

---

## install

**Requirements:**

[](https://claude.ai/code)

**From shell:**

```bash
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.)

```json
{
  "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:

```bash
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](.claude/skills/claude-historian)

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

```bash
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](https://github.com/Vvkmnn/claude-emporium)

For automatic history search with hooks and commands, install from the [claude-emporium](https://github.com/Vvkmnn/claude-emporium) marketplace:

```bash
/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 `

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

## features

[MCP server](https://modelcontextprotocol.io/) 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
```

```json
📜 ── 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"] }
  }]
}
```

```json
📜 ── 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"
  }]
}
```

```json
📜 ── 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
```

```json
📜 ── 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](https://github.com/Vvkmnn/claude-historian-mcp) [works](https://github.com/Vvkmnn/claude-historian-mcp/tree/master/src):

```
"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](https://github.com/Vvkmnn/claude-historian-mcp/blob/master/src/search.ts#L174): `Promise.allSettled` for 6x speed improvement across projects and files
- [workflow detection](https://github.com/Vvkmnn/claude-historian-mcp/blob/master/src/search.ts#L1122): Captures tool sequences like "Edit → Read → Bash" patterns
- [enhanced file matching](https://github.com/Vvkmnn/claude-historian-mcp/blob/master/src/search.ts#L793): Comprehensive path variations with case-insensitive matching
- [intelligent deduplication](https://github.com/Vvkmnn/claude-historian-mcp/blob/master/src/search-helpers.ts#L40): Content-based deduplication preserving highest-scoring results
- [intelligent truncation](https://github.com/Vvkmnn/claude-historian-mcp/blob/master/src/formatter.ts#L46): Never truncates mid-function or mid-error
- [Claude-optimized formatting](https://github.com/Vvkmnn/claude-historian-mcp/blob/master/src/formatter.ts#L26): Rich metadata with technical content prioritization

**Search strategies:**

- **[JSON streaming parser](https://en.wikipedia.org/wiki/JSON_streaming)** ([parseJsonlFile](https://github.com/Vvkmnn/claude-historian-mcp/blob/master/src/parser.ts#L16)): Reads Claude Code conversation files on-demand without full deserialization
- **[LRU caching]()** ([messageCache](https://github.com/Vvkmnn/claude-historian-mcp/blob/master/src/search.ts#L27)): In-memory cache with intelligent eviction for frequently accessed conversations
- **[TF-IDF inspired scoring](https://en.wikipedia.org/wiki/Tf%E2%80%93idf)** ([calculateRelevanceScore](https://github.com/Vvkmnn/claude-historian-mcp/blob/master/src/utils.ts#L267)): Term frequency scoring with document frequency weighting for relevance
- **[Query classification](https://en.wikipedia.org/wiki/Text_classification)** ([classifyQueryType](https://github.com/Vvkmnn/claude-historian-mcp/blob/master/src/search.ts#L642)): Naive Bayes-style classification (error/implementation/analysis/general) with adaptive limits
- **[Edit distance](https://en.wikipedia.org/wiki/Edit_distance)** ([calculateQuerySimilarity](https://github.com/Vvkmnn/claude-historian-mcp/blob/master/src/search-helpers.ts#L157)): Fuzzy matching for technical terms and typo tolerance
- **[Exponential time decay](https://en.wikipedia.org/wiki/Exponential_decay)** (getTimeRangeFilter): Recent messages weighted higher with configurable half-life
- **[Parallel file processing](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/allSettled)** ([getErrorSolutions](https://github.com/Vvkmnn/claude-historian-mcp/blob/master/src/search.ts#L985)): Concurrent project scanning with early termination for 0.8s response times
- **[Workflow pattern recognition](https://en.wikipedia.org/wiki/Sequential_pattern_mining)** ([getToolPatterns](https://github.com/Vvkmnn/claude-historian-mcp/blob/master/src/search.ts#L1122)): Detects tool usage sequences and related workflows for learning
- **[Enhanced file context]()** ([findFileContext](https://github.com/Vvkmnn/claude-historian-mcp/blob/master/src/search.ts#L793)): Multi-project search with comprehensive path matching
- **[Content-aware truncation](https://en.wikipedia.org/wiki/Text_segmentation)** ([smartTruncation](https://github.com/Vvkmnn/claude-historian-mcp/blob/master/src/formatter.ts#L46)): Intelligent content boundaries over arbitrary character limits
- **[Technical content prioritization](https://en.wikipedia.org/wiki/Information_extraction)** ([BeautifulFormatter](https://github.com/Vvkmnn/claude-historian-mcp/blob/master/src/formatter.ts#L26)): Code blocks, errors, and file paths get full preservation
- **[Query similarity clustering](https://en.wikipedia.org/wiki/Cluster_analysis)** ([findSimilarQueries](https://github.com/Vvkmnn/claude-historian-mcp/blob/master/src/search.ts#L912)): 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](./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](#methodology)**  | 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](https://docs.anthropic.com/en/docs/claude-code/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](https://github.com/thedotmack/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](https://github.com/kateleext/deja)** -- Python skill that indexes sessions by episodes and accomplishments. Uses weighted signal ranking (todos > files > text). Requires Python and TodoWrite integration.

**[conversation-search](https://github.com/ticpu/claude-conversation-search-mcp)** -- 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](https://github.com/Level/level#open) and [Electron sandboxing](https://www.electronjs.org/docs/latest/tutorial/sandbox).

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 **o

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Vvkmnn](https://github.com/Vvkmnn)
- **Source:** [Vvkmnn/claude-historian-mcp](https://github.com/Vvkmnn/claude-historian-mcp)
- **License:** MIT
- **Homepage:** https://www.npmjs.com/package/claude-historian-mcp

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-vvkmnn-claude-historian-mcp
- Seller: https://agentstack.voostack.com/s/vvkmnn
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.