chronicle

chronicle

Cold-storage warehouse + searchable recall for Claude Code session transcripts. Every compacted, retired, or old session you ever ran — moved to a vault, indexed by full-text search, and one command away from being pulled back into context.

---

The problem

~/.claude/projects/ accumulates a JSONL transcript for every Claude Code session you ever start. After a few months it's gigabytes, your shell autocompletes for-ever, and the interesting sessions — the ones you'd want to recall and resume — are buried under hundreds of throwaway ones. Compaction lossy-summarises them; rotation deletes them outright.

You want all of it, forever, but you want it off your laptop, scannable, and rehydratable on demand.

The fix

chronicle sweeps old sessions out of ~/.claude/projects/, copies them onto a network/SSD vault you point it at (default /Volumes/storage/chronicle), and writes an FTS5-indexed SQLite catalog to ~/.chronicle/index.db.

chronicle archive            # sweep sessions older than 30 days
chronicle search "wellrx foamer"
chronicle rehydrate 1b3f...  # copy back into ~/.claude/projects so /resume sees it

The transcripts are never deleted — they're moved. The catalog stores per-session metadata (project, timestamps, message count, callsign, tool usage, files touched, compacted summary if present, full FTS over user/assistant prose) so you can answer "which session was that wellrx foamer thing?" in milliseconds.

---

Demo

$ chronicle archive
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
┃ CHRONICLE ▸ v0.1.0                             ┃
┃ scanned 187 · archived 184 · skipped 3         ┃
┃ vault: /Volumes/storage/chronicle              ┃
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

$ chronicle stats
sessions     : 184 (archived=184 rehydrated=0)
messages     : 412,338
size on disk : 612.4MB
oldest       : 2025-12-04T18:11:02Z
newest       : 2026-05-12T07:44:51Z

top projects :
   58  -Users-daniel
   31  -Users-daniel-AI-wellrx_REDESIGN
   18  -Users-daniel-GIT-callsign
   ...

$ chronicle search "wellrx foamer diff pressure"
⸺ 7f3b…  2026-04-21T18:02:11  -Users-daniel-AI-wellrx_REDESIGN
   …FSC 600 is a foamer (not corrosion/scale); decline alerts use «diff pressure»…
   ▸ /Volumes/storage/chronicle/sessions/2026/04/-Users-daniel-AI-wellrx_REDESIGN/7f3b...jsonl

$ chronicle rehydrate 7f3b...
rehydrated → /Users/daniel/.claude/projects/-Users-daniel-AI-wellrx_REDESIGN/7f3b...jsonl
open in Claude Code via /resume 7f3b...  (or read the JSONL directly)

---

Install

git clone https://github.com/heyfinal/chronicle ~/GIT/chronicle
cd ~/GIT/chronicle
./install.sh

That:

• creates a venv at ~/.local/share/chronicle/venv
• symlinks ~/.local/bin/chronicle
• installs a launchd plist that runs chronicle archive daily at 04:17
• creates ~/.chronicle/ (index db, logs)
• runs chronicle init to bring up the vault dir on whatever SMB/SSD you point at

Uninstall: ./install.sh --uninstall (keeps ~/.chronicle/ and the vault — only removes the binary, venv, and launchd job).

Default vault is /Volumes/storage/chronicle. Override with CHRONICLE_VAULT=/some/other/path or edit ~/.chronicle/config.toml:

vault_path            = "/Volumes/storage/chronicle"
age_days              = 30
keep_recent_per_project = 3

---

How it works

┌──────────────────────────────┐         ┌────────────────────────────────────┐
│  ~/.claude/projects/         │         │  $CHRONICLE_VAULT                  │
│  └─ -Users-daniel-AI-X/      │         │  └─ sessions/                      │
│      ├─ 7f3b…jsonl  (8 MB)   │         │      └─ 2026/04/                   │
│      └─ 1c2a…jsonl  (3 MB)   │ ──────▶ │          └─ -Users-daniel-AI-X/    │
└──────────────────────────────┘  move   │              ├─ 7f3b…jsonl         │
                                  +verify│              └─ 7f3b…meta.json    │
                                  (sha256)└────────────────────────────────────┘
                                                       │
                                                       ▼
                                          ┌───────────────────────────┐
                                          │ ~/.chronicle/index.db     │
                                          │  sessions  (metadata)     │
                                          │  sessions_fts (FTS5)      │
                                          └───────────────────────────┘

Design choices: