claude-archive-mcp

Local stdio MCP server that exposes your unified Claude chat history (claude.ai export + Claude Code sessions) to Claude Code as ranked, scoped, structured search.

Status: v1.7.2 · Author: Mike Andersen · License: MIT

When you reference past work — "did we settle this in nortam_dev last month?", "find the TAP routing analysis", "what did Claude Code commit on April 14?" — Claude Code reaches for this server instead of asking you to summarize.

Two sources, one index

Both feed one conversations table; the same tools search across both.

Tools

search_chats · get_chat · list_projects · list_recent_chats · search_within_chat · archive_stats · timeline · find_related_chats · get_digest · recall · get_session_lineage — eleven read-only, source-aware tools. See docs/TOOLS.md. The server also exposes a per-project resource (claude-archive://project/{source}/{identifier}) — a dynamic markdown project overview.

Digest: get_digest (tool) or python scripts/digest.py --weekly (also /digest) — a markdown activity recap over a rolling daily/weekly window; both share one aggregator.

Semantic search (optional): find_related_chats ranks conversations by embedding cosine. It needs the optional extra — pip install -e .[embeddings], then python scripts/embed.py --backfill (also /embed). The server itself stays inference-free.

Comprehension sidecars (v1.4.0): search_chats and find_related_chats each carry an additive semantic sidecar tier — matches against per-conversation, LLM-authored comprehension sidecars (an abstract plus entities/identifiers), searched by FTS and typed separately from the lexical and embedding rows. It is graceful under partial coverage (an un-covered conversation simply cannot appear), so it never regresses the existing results. Keeping the sidecar store current is an attended, Mike-armed task — see docs/SIDECAR_REFRESH.md.

Install

See docs/INSTALL.md. In short (Windows, PowerShell 7):

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .[dev]
python scripts\reindex.py        # build the index from both sources
python scripts\install_mcp.py    # register the server in ~/.claude.json

Then start a new Claude Code session and ask away (see INSTALL.md for details).

Web viewer (read-only, localhost)

A plain, server-rendered web UI for browsing the same index in a browser — a second, read-only consumer of the query layer (it adds no MCP tool and changes no contract).

python -m claude_archive_mcp.webui                 # opens http://127.0.0.1:8766/
python -m claude_archive_mcp.webui --port 9000     # same, on a different port

• Pages (seven): Home (recent conversations), Search (full-text, ranked), Conversation (with within-chat search and a Related-conversations section via embedding similarity), Timeline (a topic's activity over time, filterable by source/project), Digest (rolling daily/weekly activity digest), Stats (archive statistics with near-duplicate project names collapsed for reading), and Observability (read-only adoption panels: archive tool adoption, web-UI engagement, and sidecar coverage). The query logic is reused from the same handlers the MCP tools wrap — no duplicate logic, no MCP transport.
• Posture (all enforced in code, proven by tests): binds 127.0.0.1 only (no config to widen it); opens the SQLite DB mode=ro, so it can never write or migrate; GET-only; no JavaScript; stdlib http.server (no extra dependencies).
• Port: defaults to 8766; override with CLAUDE_ARCHIVE_WEBUI_PORT or the --port flag (the flag wins). The host is a hard rail — --port changes the port only, never the loopback bind. Index first (python scripts\reindex.py) — the viewer reads an existing DB and will not create one.
• Freshness: the long-running viewer records a running-code stamp when it starts; python scripts\check_webui_stale.py reports whether the live process is serving stale code. Restarting the live process is a deliberate, attended action.

Documentation

• docs/CONTRACT.md — the frozen 1.0 surface + the 1.x semver policy
• docs/INSTALL.md — Windows install walkthrough
• docs/TOOLS.md — per-tool reference + examples
• docs/ARCHITECTURE.md — design + rationale
• docs/SOURCES.md — how each source is parsed, edge cases
• docs/SIDECAR_REFRESH.md — keeping the comprehension-sidecar store current (attended)
• docs/STATE_RECOVERY.md — recover every regenerable local-state surface
• CHANGELOG.md

Development

pip install -e .[dev]
ruff check .
ruff format --check .
mypy --strict src/
pytest

Conventions live in CLAUDE.md. The project is built in gated phases; do not chain past a phase gate.