thread-archive 0.0.9

Serverless-native local archive for AI conversations: JSONL truth log + rebuildable SQLite index, searched and read locally, exposed over MCP.

thread-archive

A local-first archive for the AI agents that work on your machine — built by Claude Code, for Claude Code. Every session your agent harnesses record lands in one durable, append-only archive you own, on your own disk — and your agents can search and read all of it, mid-conversation, over MCP.

Your agent's transcripts are temporary by default. Claude Code writes each session to ~/.claude as JSONL, keeps it for 30 days, and deletes it — a sensible default for a harness's working files, a lossy one for the only record of how the work got decided. Nothing searches them in the meantime either.

Quickstart

pip install thread-archive
thread-archive setup

setup discovers this machine's conversation stores and shows what it found — counts, sizes, date ranges — before touching anything. Whatever is still on disk imports as a head start; from then on a background watcher keeps the archive current and the 30-day window stops mattering. It also wires the MCP server into your client and starts a local web viewer at http://127.0.0.1:8787. Every choice is skippable.

Minutes after setup, ask mid-conversation:

"what did we decide about the auth flow?"

Your agent searches, reads around the hits, and comes back with what you decided and why — a few thread_search calls and a couple of thread_reads, the way it would work through a codebase it hadn't seen. What it reads is an efficient representation of the conversation itself, not a summary someone made of one. No workflow to adopt, no notes you were supposed to be taking — from here on the record is being written.

What you get

• Search, three doors, one implementation — MCP tools (thread_search, thread_read) for agents, the same verbs on the CLI (thread-archive search "auth flow" --since 30d), and a local web viewer for reading. What you get at a prompt is what your agent gets.
• Full-text and semantic search, fused and re-ranked, filterable by time, source, tool, and content type; an empty query browses recent activity.
• Indexed by code, not just by words — ask which conversations worked on a file (thread_search(path='rank.py')), which sessions a commit is made of (thread_search(commit='31bade5')), or what a session actually changed.
• Built like a database, not a folder of exports — plain JSONL as the source of truth, crash-safe writes with intent journaling, built-in backup with nightly restore drills. The index is a disposable projection that rebuilds at any time.
• Import drift is loud and repairable — when a provider changes its transcript format, coverage checks catch it, raw files are preserved before the provider prunes them, and thread-archive source fix scaffolds the repair for you (or your agent) to finish.
• No hosted backend. No cloud. No subscription to lose your history to. Every process runs locally, on your machine.

Claude Code is the supported, first-class source. The other harnesses it reads — Codex, Cursor, OpenCode, Grok, and friends — are best-effort and community-maintainable via the plugin API. Web chats (claude.ai, ChatGPT, xAI) import from account exports you download by hand.

Documentation

• Install — the setup wizard, optional semantic search, updating, from-source, uninstall
• Search and retrieval — the two tools, filters, and the code index
• CLI — every verb, grouped by what it acts on
• MCP — server modes and client wiring
• Web viewer — the local UI and its supported URLs
• How it works — the event model, durability, platform assumptions, repo layout
• Stability — the four public interfaces and what may change
• When an import drifts — the support tier and the repair loop
• Not supported — the deliberate scope: one machine, one user, macOS/Linux
• On-disk format · Provider plugin API · Search quality · Related projects

Scope

Deliberately narrow: one machine, one user, macOS and Linux only. The archive preserves and retrieves — it never writes back to a harness store and never sends a message. Live capture of web chats is out; account exports are the path. The reasoning behind each line is in docs/scope.md.

Similar and related projects

Preserving and searching AI conversation history is a crowded space, and a lot of the work in it is good — session-search neighbors (CASS, ctx, deja-vu, episodic-memory, synty, and more), agent memory layers (mem0, Letta, Zep), and the prior art outside AI (notmuch). The annotated survey lives in docs/related.md. The short version of the difference: most tools treat the harness's own files as the record and their index as a cache over it; archive treats preservation as the product — its own append-only truth log, backup with restore drills, and unmodeled provider fields preserved verbatim.

License

MIT — see LICENSE. The pre-built web viewer bundle contains third-party open-source packages (all MIT/ISC/BSD); their license texts ship in src/thread_archive/_web/THIRD_PARTY_NOTICES.md (regenerate with scripts/gen_third_party_notices.py when frontend dependencies change).

Origin

thread-archive is the standalone member of a larger personal project ("thread"), built to stand on its own — self-contained, no hosted backend or external services. It's young, though: expect the occasional rough edge.