session-recall

What this skill does

# Session Recall

Search and retrieve context from past Claude Code sessions across multiple machines.

## Important Behavior

### Choosing the Right Tool: Search vs Transcript

This skill has two primary retrieval modes. **Choosing correctly is critical.**

| User intent | Tool | Why |
|---|---|---|
| Find sessions **about a topic** ("what did we discuss about auth?") | `scripts/search` | Full-text search across outlines, prompts, tools, files |
| Review **what happened during a time period** ("what did I do today?", "show me yesterday's work") | `scripts/transcript --after ... --before ...` (no session ID) | Cross-session temporal transcript |
| Check **when** work happened ("when was I active?", "how much time on X?") | `scripts/activity --days N` | Activity time ranges per session |
| Read the **content of a specific session** | `scripts/transcript <session-id>` | Per-session transcript |
| Read part of a session within a **time window** | `scripts/transcript <session-id> --after ... --before ...` | Per-session filtered transcript |

**Key rule**: If the user's question is about a **time period** (today, yesterday, this morning, last week, Monday, a date range), use the **cross-session transcript** endpoint — not search. Search finds sessions by topic keywords; the transcript endpoint reconstructs what actually happened during a time window.

### Recognizing Temporal Queries

Use the **cross-session transcript** (no session ID, with `--after`/`--before`) when the user asks anything like:

- "What did I work on today/yesterday/this week?"
- "What happened on Monday?"
- "Show me everything from last Tuesday"
- "Give me a standup summary"
- "What did I do this morning/afternoon/evening?"
- "Review my work from March 15 to March 20"
- "What's been going on across my projects this week?"
- "Summarize my activity for the past 3 days"

Convert relative time references to ISO 8601 timestamps:

- "today" → `--after <today 00:00 local>` `--before <now>`
- "yesterday" → `--after <yesterday 00:00>` `--before <yesterday 23:59:59>`
- "this morning" → `--after <today 06:00>` `--before <today 12:00>`
- "this week" → `--after <Monday 00:00>` `--before <now>`
- "last Tuesday" → `--after <last Tue 00:00>` `--before <last Tue 23:59:59>`

Timestamps must be ISO 8601 (e.g., `2026-03-25T00:00:00Z`). Date-only formats like `2026-03-25` also work (interpreted as midnight UTC).

### Use the bundled scripts

The `scripts/` directory contains executable wrappers for all API endpoints. **Always use these scripts** instead of raw curl commands — they handle URL construction, JSON formatting, and URL encoding.

Run scripts using their full path relative to this skill's base directory (provided when the skill is loaded). For example: `<skill-base-dir>/scripts/search --query "test"`

All scripts default to `http://localhost:2529`. Override with `CLAUDE_ASSIST_SERVER` env var.

Available scripts: `search`, `transcript`, `details`, `stats`, `activity`, `machines`, `sync`, `outlines`, `outline-progress`

### Filter Out Subagent Sessions

Always include `--min-user-messages 2` by default to hide single-prompt subagent sessions. Only omit this filter if the user specifically asks about subagent or automated sessions.

### Default to Current Project

When searching sessions, **always filter by the current project path** unless:

- The user explicitly asks to search across all projects
- The user asks about work on "another project" or "different repo"
- The context clearly implies cross-project search is needed

The `project=` parameter matches any substring of the project path, so use a **minimally unique string** that appropriately scopes the search. For example:

- For `/Users/chris/repos/claude-assist`, use `project=claude-assist` (not the full path)
- For `/home/dev/projects/api-server`, use `project=api-server`

This keeps queries concise while still filtering effectively.

## Quick Start

Search sessions by topic (scoped to current project):

```bash
scripts/search --query "RTD proposal" --days 14 --project myproject --min-user-messages 2
```

Review what happened during a time period (cross-session):

```bash
scripts/transcript --after 2026-03-28T00:00:00Z --before 2026-03-29T00:00:00Z
scripts/transcript --after 2026-03-24T00:00:00Z --before 2026-03-29T00:00:00Z --project claude-assist
```

## Available Endpoints

### Search Sessions

```bash
scripts/search --query "..." --days N --project PATH --tools Edit,Bash --machine ID
```

Parameters:

- `search` - Full-text search query (weighted: user prompts + outlines > tools/files > project)
- `days` - Limit to sessions within N days (default: 30)
- `since` - Absolute start date (ISO 8601, e.g., `2025-01-01T00:00:00Z`). Overrides `days` when set
- `until` - Absolute end date (ISO 8601). Can combine with `since` or use alone with `days`
- `forever` - Set to `true` to search all sessions with no date limit. Use when the user's query indicates they want an absolute answer regardless of recency (e.g., "have we ever...", "did I ever...")
- `tools` - Filter by tools used (comma-separated, e.g., `Edit,Bash`)
- `machine` - Filter by machine ID (e.g., `localhost`, `laptop`)
- `project` - Filter by project path (partial match)
- `min_user_messages` - Minimum number of user messages (useful for hiding subagent sessions, e.g., `--min-user-messages 2`)
- `limit` - Max results (default: 20, max: 100)
- `offset` - Pagination offset

**Date filtering:** By default, searches are limited to the last 30 days. Use `days` for relative filtering, `since`/`until` for absolute date ranges, or `forever=true` to search all time. When `since` or `until` is provided, they take precedence over `days`. `forever=true` disables all date filtering.

Response schema: see [schemas/search.json](schemas/search.json)

**Note:** The `outline` field contains an AI-generated summary of the session (if available). The `title` field is a short AI-generated title.

### Get Session Transcript (Preferred)

```bash
# Full session transcript
scripts/transcript <session-id>

# Only messages from a specific time window within the session
scripts/transcript <session-id> --after 2026-03-25T00:00:00Z --before 2026-03-26T00:00:00Z

# Just the afternoon portion
scripts/transcript <session-id> --after 2026-03-25T12:00:00Z --before 2026-03-25T18:00:00Z
```

Returns a **compact, token-efficient text format** of the session—the same format used for AI outline generation. This is the **recommended way to read full session content**.

Optional time-range params trim the transcript to only messages within the window. Useful for long-running sessions where you only care about a specific period:

- `--after` - Only include messages after this ISO 8601 timestamp
- `--before` - Only include messages before this ISO 8601 timestamp

Both params are optional and can be used independently (just `--after` to get everything from a point onward, or just `--before` to get everything up to a point).

Format:

- `[U] <text>` - Full user messages
- `[A] <snippet>` - Assistant responses (truncated to ~280 chars)
- `[T] <tool_name> <target>` - Tool calls with file paths, commands, etc.

Example response: see [schemas/transcript.txt](schemas/transcript.txt) (text/plain, not JSON)

**Use this endpoint when:**

- Reading a full session's conversation flow
- Understanding what happened in a session
- Copying session context for continuation
- Trimming a long session to just the relevant time window (e.g., "what did this session do after 3pm?")

**Use `--raw` only when:**

- You need exact tool inputs/outputs
- You need token usage per message
- You need raw content blocks (thinking, tool results)

### Cross-Session Transcript (Time Range)

```bash
# All work across all projects today
scripts/transcript --after 2026-03-29T00:00:00Z --before 2026-03-29T23:59:59Z

# Chronological order instead of grouped by project
scripts/transcript --after 2026-03-29T00:00:00Z --before 2026-03-29T23:59:59Z --group time

# Scope