Session Librarian: Organize Hermes Agent Sessions by Prompt

Session Librarian is a bundled Hermes Agent skill that turns session management into a conversation. Instead of digging through terminal output, you ask for what you need: find sessions about a topic, summarize what was decided, rename them meaningfully, split work into parallel sessions, and propose stale ones for archiving or deletion. It is for anyone whose session library has grown past the point of casual browsing, and who wants a safe, reversible way to keep it useful.

What it does

The skill works across two surfaces. For content-level questions, like "what did we decide about X?", it uses the session_search tool, which runs FTS5 over the message store. For metadata-level sweeps, like "sessions older than 60 days from telegram", it relies on the hermes sessions CLI commands. The skill's job is to combine these surfaces into a single workflow: discover, summarize, plan, act, report.

A typical request might be "find my sessions about Q3 pricing, keep the useful ones, and clean up the duplicates." The agent will search, present a plan, and only mutate your library after you approve. The design is inspired by Perplexity Computer's prompt-driven session management: the agent always shows the plan before touching anything.

Before you start

Session Librarian ships bundled with Hermes Agent, so it is installed by default. You do not need to install anything separately. The skill is available on Linux, macOS, and Windows. It is authored by Hermes Agent and Teknium, released under the MIT license, and lives at skills/productivity/session-librarian (version 1.0.0).

There are no special permissions to grant. The skill operates on your current profile's session database, using the same CLI tools you would use manually. One thing to keep in mind: management commands act on the current profile's DB, and cross-profile session links (@session:/) are read-only from another profile.

Finding sessions by topic

Start with the discovery step. Use session_search with topic keywords, and vary your phrasing: feature name, symptom, project name. A limit of 5-10 results is a good starting point.

session_search(query=..., limit=5-10)

For metadata sweeps, like "sessions older than 60 days from telegram", use the CLI instead:

hermes sessions list --source telegram --limit 50

The discovery result gives you bookend_start (the goal), the match window, and bookend_end (the resolution). These three usually suffice for a summary. Only dump a full session with session_search(session_id=...) when the user asks for decisions in depth.

Report each session as a link in @session: form, followed by a one-line goal and a one-line outcome. That keeps the summary scannable.

Planning before you act

Anything that mutates your library requires a plan first. This is mandatory. Present a table showing which sessions get renamed to what, which get archived, and which are proposed for deletion, with a reason for each: duplicate of which keeper, stale, empty. Wait for the user's go-ahead.

The only exception is a single rename the user explicitly dictated. That can be done directly.

Acting with the safest primitive

When you act, prefer the safest tool. Archive is reversible, so prefer it over delete or prune. For destructive commands, always run with --dry-run first and show the output, then re-run with --yes after confirmation.

hermes sessions archive <session-id>

hermes sessions delete <session-id>

hermes sessions prune <criteria>

Before deleting anything with meaningful content, offer an export as a backup:

hermes sessions export --session-id <id> --format md

Renaming is straightforward:

hermes sessions rename <session-id> <new-title>

If you want to continue work in a new place, you can fork the current session with /branch, or start a fresh session and cite the summary.

Reporting back

After acting, report clearly: renames applied, sessions archived (with count and how to undo), anything exported, and anything skipped and why. Archived sessions remain in the DB and are listed with --include-archived, so the user knows they are not gone.

Parallel workstreams

For "one session per ticket, investigate each, report back", do not try to drive other live sessions. Instead, 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.

When not to use it

This skill is not for driving multiple live sessions at once. If you need parallel investigation, use delegate_task as described above. Also, if you only need a quick metadata listing, the CLI directly may be faster than a conversational request.

Limits and gotchas

• Never delete without a dry-run plus 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, and source filters live in the CLI. Combine both when the request mixes them, like "old sessions about pricing".
• Titles are identity for /resume. When renaming, keep titles short, unique, and prefix-friendly. Warn the user if a rename collides with an existing title.
• Archived is not deleted. Archive hides sessions from default listings only. Say which one you did.
• Cross-profile session links (@session:/) 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.

What pairs with this

For a broader look at how your sessions fit together, the related skill weekly-review-planning complements Session Librarian. Use it to turn your organized library into a regular review cadence.