Session Librarian

Manage the user's session library conversationally: find past sessions about a topic, summarize what they decided, rename them meaningfully, split work into parallel sessions, and propose stale ones for archive or deletion — all from a plain-language request like "find my sessions about Q3 pricing, keep the useful ones, and clean up the duplicates."

Inspired by Perplexity Computer's prompt-driven session management (Aug 2026): the agent starts, organizes, and cleans up the user's own session library, and always shows the plan before touching anything.

When to Use

"What sessions do I have about X?" / "What did we decide about X?"
"Rename these sessions to something meaningful."
"Clean up my session library" / "archive the stale ones."
"Fork that session into a follow-up focused on Y."
"Split this into one session per ticket" (see Parallel workstreams below).

The Two Surfaces

Task	Surface
Find sessions by topic, read content, summarize decisions	`session_search` tool (FTS5 over the message store)
List/filter by metadata (age, source, cost, tokens, workspace)	`hermes sessions list` / `stats` via terminal
Rename	`hermes sessions rename <session_id> <title...>`
Bulk soft-hide (reversible)	`hermes sessions archive <filters>`
Delete (destructive)	`hermes sessions delete` / `hermes sessions prune <filters>`
Export before deleting anything valuable	`hermes sessions export --session-id <id> --format md`
Continue work in a new place	`/branch` (fork current session) or start a fresh session and cite the summary

Procedure

① Discover. Use session_search(query=..., limit=5-10) with topic keywords; vary phrasing (feature name, symptom, project name). For metadata sweeps ("sessions older than 60 days from telegram"), use hermes sessions list --source telegram --limit 50 instead.

② Summarize per session. The discovery result's bookend_start (goal), match window, and bookend_end (resolution) usually suffice — only dump a full session (session_search(session_id=...)) when the user asks for decisions in depth. Report each as: link (@session: form) — one-line goal — one-line outcome.

③ Plan before acting (MANDATORY for anything that mutates). Present a plan table first: which sessions get renamed to what, which get archived, which are proposed for deletion and why (duplicate of which keeper, stale, empty). Wait for the user's go-ahead. Exception: a single rename the user explicitly dictated can be done directly.

④ Act with the safest primitive.

Prefer archive (reversible soft-hide) over delete/prune.
Always run destructive commands with --dry-run first and show the output, then re-run with --yes after confirmation.
Before deleting anything with meaningful content, offer hermes sessions export --format md as a backup.

⑤ Report. Renames applied, sessions archived (count + how to undo: archived sessions remain in the DB and are listed with --include-archived), anything exported, anything skipped and why.

Parallel Workstreams

For "one session per ticket, investigate each, report back": do NOT try to drive other live sessions. Use delegate_task with one task per workstream — each subagent runs in its own session automatically — then synthesize their summaries. Mention that each delegation's transcript is itself searchable later via session_search.

Pitfalls

Never delete without a dry-run + explicit confirmation in this conversation. A standing "clean things up" is authority to propose, not to prune.
session_search finds content, not metadata. Age/cost/source filters live in the CLI; combine both when the request mixes them ("old sessions about pricing").
Titles are identity for /resume <title>. When renaming, keep titles short, unique, and prefix-friendly; warn the user if a rename collides with an existing title.
Archived ≠ deleted. Archive hides sessions from default listings only. Say which one you did.
Cross-profile session links (@session:<profile>/<id>) are read-only from another profile; management commands act on the current profile's DB.

Verification

After a cleanup pass, re-run the discovery query and hermes sessions list to confirm the library reflects the plan (keepers present with new titles, archived ones gone from the default listing).

4.7 KiB Raw Blame History