Skip to content

Collections (v0.8)

Hand-picked groupings of sessions that cut across projects. Tags are flat and auto-filter; projects are coarse cwd buckets. Collections are the middle layer: a curated, hierarchical taxonomy you build.

When to use them

  • A monorepo internally splits into sub-projects (e.g. Pest-Control-Automation → scraping / sales-flow / ingestion) but cwd makes them one project.
  • You want "the 8 sessions that mattered for the migration" pulled out of 200 noisy sessions in the same project.
  • You're preparing context for a colleague: name a collection "Scraping — current state", drop the relevant sessions in, share the URL.

How they're structured

  • A tree — each collection has an optional parent_id. Nesting limited to 8 levels.
  • A hand-picked membership list — you explicitly add sessions; nothing auto-populates.
  • Soft-deletion only — "archive" hides without erasing. Collections can always be restored.
  • Icon + color — one emoji + an optional color for visual scanning.

How to use them

  1. Hit c (or the + new button in the left pane) to create a collection.
  2. Drag any session row (from the middle pane) onto a collection in the left pane to add it. Works from plain lists and from search results. The target collection flashes orange while you hover.
  3. Or: from any transcript, open the ⋯ menu → 📂 Add to collection… or use Cmd+Shift+A.
  4. Click a collection in the left pane to filter the middle pane. The breadcrumb shows the full path. Selecting a parent automatically includes sessions from every child collection.
  5. To move a session between collections, drag it onto the new one (that adds it), then remove it from the old one via the chip × in the transcript header — or the remove affordance on each row while the old collection is open.
  6. Right-click any collection for: new child · rename · archive · copy link · restore.
  7. Drag one collection onto a sibling to reorder them.

Pane controls

  • The sessions pane (middle) is resizable — grab its right edge and drag. Width persists per-browser.
  • Click the « in the sessions pane header (or hit Cmd+\) to collapse it to a thin rail. Click » to expand again. Handy when you want the transcript to take the whole screen.

URL sharing

The active collection is in the URL hash as col=<uuid>. Paste the URL anywhere — clicking it opens the app filtered to that collection.

Durability — same three layers as tags / notes / aliases

  1. SQLite — collections, collection_sessions, collection_events (append-only audit log of every mutation).
  2. Plain-text mirror — ~/.recall/collections.json, rewritten on every change. Contains both the current state and the full event log, so the tree can be reconstructed from this file alone.
  3. Source JSONLs untouched — ~/.claude/projects/** remains read-only to Recall.

If you delete the SQLite database, collections are recoverable via:

recall restore-collections   # planned, reads the mirror file

Until that subcommand lands, the JSON mirror is still an authoritative backup you can rebuild from.

What they're NOT

  • Not tags. Tags are flat, keyword-ish, and can auto-filter via #tag. Collections are hand-picked and hierarchical. Keep both.
  • Not projects. Projects still reflect cwd; collections cross project boundaries freely.
  • Not folders on disk. Nothing moves in the filesystem.