/session-history

name: alive:session-history
description: "Revive sessions (quick or heavy), browse, and search — 'what happened recently?', 'find the session where we discussed X', 'revive yesterday's session'. For single-session recall and multi-session browsing. If the human needs to merge multiple sessions into one working context or detect conflicts between parallel sessions, use alive:session-context-rebuild instead."
user-invocable: true

History

Session timeline and recent activity. The system's short-term memory.

Not a search (that's find — searches content across walnuts). History searches SESSIONS — what squirrels did, what was discussed, what was decided. For deep context extraction from source material, use `alive:mine-for-context`.

---

How It Works

Two tiers of data. Always start with tier 1. Go to tier 2 via revive.

**Tier 1 — Squirrel Entries** (`.alive/_squirrels/*.yaml`, with fallback to per-walnut `_kernel/_squirrels/*.yaml`) Structured, fast, indexed. Session ID, walnut, model, timestamps, stash items, transcript path. Every squirrel leaves one of these.

**Tier 2 — Session Transcripts** (path stored in squirrel YAML `transcript:`) The full conversation. Every message, every agent response, every tool call, every result. This is the deep context — the actual thinking, the back-and-forth, the nuance that didn't make it into the stash.

---

Modes

Browse (no args)

Show recent sessions across all walnuts. **Default filter:** only show sessions with `saves > 0` or non-empty stash. Cap at 10 results. Add a summary line: "N empty shells not shown." Use `history --shells` to include them.

**Data source:** prefer `.alive/_index.yaml` `recent_sessions:` as primary data. Fall back to direct `.alive/_squirrels/` YAML walk only if the index is missing or returns fewer results than requested.

╭─ squirrel history — recent sessions
│
│   1. 2a8c95e9  nova-station     today       opus-4-6
│      System architecture, telemetry pipeline, 8 modules configured, shipped v0.1-beta
│
│   2. a44d04aa  nova-station     yesterday   opus-4-6
│      Supply chain mapped, vendor shortlist locked, timeline set
│
│   3. 5551126e  nova-station     Feb 22      opus-4-6
│      Companion app, test harness, integration v0.1-beta released
│
│   4. fb6ec273  nova-station     Feb 21      opus-4-6
│      Transcript extraction, dashboard built, requirements captured
│
│   5. 224e54bb  stellarforge  Feb 22      opus-4-6
│      stellarforge infrastructure, telemetry, comms, access system
│
│  number to dive in, or describe what you're looking for.
╰─

Unsaved Sessions

After listing sessions, check for unsaved entries (`saves: 0`) in `.alive/_squirrels/`. These represent sessions that never checkpointed — the human may have lost stash items. Check transcript file size to distinguish "opened and closed" from "real work, never saved."

Surface them with a visual marker:

╭─ squirrel history — recent sessions
│
│   1. 2a8c95e9  nova-station  today       opus-4-6
│      System architecture, 8 skills built
│
│   2. a44d04aa  nova-station     yesterday   opus-4-6
│      Website rebuild, brand locked
│
│   unsaved c48b658d  (unsaved)    today       opus-4-6
│     Session never saved. Stash may be unrouted.
│     -> Review transcript?
│
│  number to dive in, or describe what you're looking for.
╰─

If the human selects an unsaved session, present the stash items from the YAML and offer to route them now (invoke save flow for those items) or dismiss (dismiss the entry by setting `ended:` to current time and `saves:` to -1 (dismissed)).

Query (by walnut, date, topic, person)

"What sessions touched nova-station this month?" "Find the session where we discussed shielding vendors" "Show me all sessions with Jax" "What happened last week?"

Search tier 1 first (squirrel YAML frontmatter + stash content). If no match, offer tier 2 search (full transcript grep).

Temporal Queries

"What happened last week" -> filter squirrel entries + log entries by date range, show across all active walnuts.

"What changed since Tuesday" -> scan `_kernel/now.json` updated timestamps + recent log entries.

"History of nova-station" -> show `_kernel/log.md` frontmatter (entry count, summary) + offer to load recent entries.

Revive (single session)

The human selects a session. Show the tier 1 metadata, then offer the choice:

╭─ squirrel history — session:{id}
│
│  Walnut: {walnut}
│  Date: {date}, {duration}
│  Model: {engine}
│  Stash: {count} items
│
│  -> Quick revive or heavy revive?
╰─

Use AskUserQuestion with two options:

• **Quick revive** — "Structured briefing. One agent reads the full transcript and returns a handoff document covering what happened, why, and what comes next. ~2 minutes."
• **Heavy revive** — "Full context transplant. Five parallel agents each extract a different dimension — narrative arc, decisions, verbatim quotes, technical substance, and open threads. Reconstructs the session's awareness in the current context window. ~5 minutes."

Before dispatching either mode, resolve the transcript path (see Transcript Discovery below). If no transcript is found, tell the human and offer a tier-1-only summary from the YAML stash data instead.

Quick Revive

One agent. Reads the full JSONL transcript. Returns a structured handoff directly into the conversation.

Dispatch a single Agent tool call with `subagent_type: "general-purpose"`. Use this prompt, substituting `{transcript_path}` with the resolved path:

You are reconstructing a previous work session from its full transcript.

Read the JSONL transcript at: {transcript_path}

The transcript is JSONL — one JSON object per line. Each line has a "type" field
(user, assistant, tool_use, tool_result, progress, file-history-snapshot, etc.)
and typically a "message" field with content. Focus on "user" and "assistant" types
for the conversation, and "tool_use"/"tool_result" for understanding what work was done.

For