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.10.0 · 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.

Briefing packs (v1.10.0): claude-archive-brief --project <slug> writes a deterministic, read-only markdown pack answering what happened here recently, what is still open, what was decided, and what to open next -- every line carrying a locator you can open. Same library behind python scripts\brief.py, the viewer's /brief page, and the plugin's /archive:brief. It is an out-of-process surface, not a twelfth tool. See docs/BRIEFING.md.

Curated memory (v1.10.0, opt-in): an append-only store of Decision / Entity / Thread objects in a separate memory.db beside the archive. Curation is out of process -- claude-archive-curate carries six verbs (correct, supersede, dispute, pin, merge, forget), each an append, so no wording is ever rewritten; python scripts\memory.py and the viewer's /memory page read it. When the store exists, search_chats and find_related_chats rows gain a curated_status label (current / superseded / disputed / null) -- a label only, changing no count, no ordering and no selection. With no memory.db the key is absent, so responses are byte-identical to an install that never curated anything. No archive migration and no new MCP tool.

Install

See docs/INSTALL.md. In short (Windows PowerShell 5.1 -- these commands are 5.1-clean and run unchanged under 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 (eleven): Home (recent conversations), Search (full-text, ranked), Conversation (with within-chat search, and a link to its Related page -- related is no longer rendered inline), Related (one conversation's neighbours across the structural, embedding and sidecar tiers, as its own actively-visited page), 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), Observability (read-only adoption panels: archive tool adoption, web-UI engagement, and sidecar coverage), Brief (a briefing pack for one project or query), Cockpit (nine continuity health surfaces on one page), and Memory (the curated-memory objects, read-only). 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

Plan of record:

• ROADMAP.md -- the canonical product roadmap (north star, principles, horizons, release sequence, do-not-reopen register)
• docs/PROGRAM.md -- the operational truth layer (per-horizon state, evidence gates, closed rulings, dated baselines, recorded policies)
• docs/ROADMAP-archive-mcp.md -- FROZEN-HISTORICAL as of 2026-08-13; prior-cycle evidence, not a plan

Reference:

• 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/BRIEFING.md -- the briefing pack: running it, reading it, freshness
• 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
• SECURITY.md -- posture, the loopback-only invariant, and artifact integrity
• 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.