recall — Cross-session context for Claude Code

README.md

recall — Cross-session context for Claude Code

A skill that lets Claude Code load context from past conversations so you can pick up where you left off. Say /recall the discussion about X and get a structured brief of what happened, what was decided, and where it stopped.

Claude Code works best in short, intense bursts — but that means you're constantly /clearing context. Recall bridges those gaps.

How it works

1. You say /recall <topic or session ID>
2. Claude searches your conversation history using DuckDB (fast, even across hundreds of sessions)
3. You get a synthesized Context Brief — not a raw dump, but a structured summary focused on where it left off

Prerequisites

• Claude Code
• DuckDB — brew install duckdb or apt install duckdb

Install

# 1. Put the search script on your PATH
cp recall-search ~/.local/bin/
chmod +x ~/.local/bin/recall-search

# 2. Install the skill into your project
mkdir -p /path/to/your/project/.claude/skills/recall
cp SKILL.md /path/to/your/project/.claude/skills/recall/SKILL.md

Repeat step 2 for each project where you want recall available. The search script only needs to be installed once.

Make sure ~/.local/bin is on your PATH. If it isn't:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc  # or ~/.zshrc

Usage

Inside Claude Code:

/recall the actor model discussion
/recall my most recent session
/recall 471982bc
/recall that script we built for zombie processes

You can also use the search script directly from your terminal:

recall-search sessions              # list recent sessions
recall-search search actor model    # keyword search
recall-search spine 471982bc        # full conversation text
recall-search context 471982bc      # compact: first 10 + last 20 messages
recall-search topics                # topic overview of all sessions
recall-search stats                 # usage dashboard
recall-search impact                # most engaged sessions

How conversation history is stored

Claude Code saves conversations as JSONL files at:

~/.claude/projects/{project-slug}/*.jsonl

The project slug is your working directory with / replaced by -. For example:

• /home/user/projects/myapp becomes -home-user-projects-myapp

Each file is one session. The search script reads these directly with DuckDB — no indexing step, no server, no setup beyond having DuckDB installed.

Environment variables

Variable	Default	Description
CLAUDE_PROJECT_DIR	$(pwd)	Override project directory for history lookup
RECALL_LIMIT	20	Max results for search/sessions commands

recall-search

#!/usr/bin/env bash
# recall-search — Search Claude Code conversation history using DuckDB
#
# Usage:
#   recall-search search <keywords>        Search user messages for keywords
#   recall-search sessions                 List all sessions (most recent first)
#   recall-search spine <session-id>       Extract conversation spine (user + assistant text)
#   recall-search context <session-id>     Compact context: first 10 + last 20 messages
#   recall-search topics                   Extract topics from all sessions
#   recall-search stats                    Project-level usage dashboard
#   recall-search impact [N]               Most impactful sessions by engagement
#
# Environment:
#   CLAUDE_PROJECT_DIR  Override auto-detected project dir (default: cwd-based)
#   RECALL_LIMIT        Max results for search/sessions (default: 20)
#
# Prerequisites:
#   - DuckDB (brew install duckdb / apt install duckdb)
#   - Claude Code conversation history at ~/.claude/projects/

set -euo pipefail

# Resolve project directory from cwd
CWD="${CLAUDE_PROJECT_DIR:-$(pwd)}"
PROJECT_SLUG=$(echo "$CWD" | sed 's|/|-|g')
HISTORY_DIR="$HOME/.claude/projects/$PROJECT_SLUG"
LIMIT="${RECALL_LIMIT:-20}"

if [ ! -d "$HISTORY_DIR" ]; then
  echo "No conversation history at $HISTORY_DIR" >&2
  exit 1
fi

FILE_COUNT=$(ls "$HISTORY_DIR"/*.jsonl 2>/dev/null | wc -l | tr -d ' ')
if [ "$FILE_COUNT" = "0" ]; then
  echo "No .jsonl files in $HISTORY_DIR" >&2
  exit 1
fi

GLOB="$HISTORY_DIR/*.jsonl"

# Common DuckDB flags
DUCK="duckdb -markdown"

# Base CTE: parse raw JSONL lines into structured fields
# Using read_csv with null delimiter treats each line as a single field
BASE_CTE="
WITH raw AS (
  SELECT
    json_extract_string(column0, '\$.type') as msg_type,
    json_extract_string(column0, '\$.sessionId') as session_id,
    json_extract_string(column0, '\$.timestamp') as ts,
    json_extract_string(column0, '\$.gitBranch') as branch,
    json_extract_string(column0, '\$.message.role') as role,
    json_extract_string(column0, '\$.message.content') as content
  FROM read_csv('$GLOB',
    delim=chr(0), header=false, ignore_errors=true, max_line_size=10000000)
),
-- Filter to real text messages (not tool results which start with '[')
msgs AS (
  SELECT * FROM raw
  WHERE content IS NOT NULL
    AND length(content) > 2
    AND left(content, 1) != '['
    AND left(content, 1) != '{'
)
"

cmd="${1:-help}"
shift || true

case "$cmd" in
  search)
    if [ $# -eq 0 ]; then
      echo "Usage: recall-search search <keywords>" >&2
      exit 1
    fi
    # Build ILIKE conditions for each keyword
    KEYWORDS="$*"
    WHERE_CLAUSES=""
    for word in $KEYWORDS; do
      if [ -n "$WHERE_CLAUSES" ]; then
        WHERE_CLAUSES="$WHERE_CLAUSES OR"
      fi
      WHERE_CLAUSES="$WHERE_CLAUSES content ILIKE '%${word}%'"
    done

    $DUCK -c "
    $BASE_CTE
    , matches AS (
      SELECT
        session_id,
        ts,
        branch,
        content,
        role
      FROM msgs
      WHERE msg_type IN ('user', 'assistant')
        AND ($WHERE_CLAUSES)
    ),
    scored AS (
      SELECT
        session_id,
        branch,
        min(ts) as first_ts,
        max(ts) as last_ts,
        count(*) FILTER (WHERE role = 'user') as user_hits,
        count(*) as total_hits,
        first(content ORDER BY ts) FILTER (WHERE role = 'user') as first_user_msg
      FROM matches
      GROUP BY session_id, branch
    )
    SELECT
      left(session_id, 8) as session,
      strftime(first_ts::timestamp, '%Y-%m-%d %H:%M') as started,
      branch,
      total_hits as hits,
      left(first_user_msg, 120) as first_message
    FROM scored
    ORDER BY total_hits DESC, last_ts DESC
    LIMIT $LIMIT
    "
    ;;

  sessions)
    $DUCK -c "
    $BASE_CTE
    , session_stats AS (
      SELECT
        session_id,
        branch,
        min(ts) as first_ts,
        max(ts) as last_ts,
        count(*) FILTER (WHERE msg_type = 'user' AND role = 'user') as user_msgs,
        count(*) FILTER (WHERE msg_type = 'assistant') as asst_msgs,
        first(content ORDER BY ts) FILTER (WHERE msg_type = 'user' AND role = 'user') as first_msg
      FROM msgs
      WHERE msg_type IN ('user', 'assistant')
      GROUP BY session_id, branch
    )
    SELECT
      left(session_id, 8) as session,
      strftime(first_ts::timestamp, '%Y-%m-%d %H:%M') as started,
      branch,
      user_msgs as msgs,
      left(first_msg, 100) as first_message
    FROM session_stats
    WHERE user_msgs > 0
    ORDER BY last_ts DESC
    LIMIT $LIMIT
    "
    ;;

  spine)
    if [ $# -eq 0 ]; then
      echo "Usage: recall-search spine <session-id-prefix>" >&2
      exit 1
    fi
    SESSION_PREFIX="$1"
    $DUCK -c "
    $BASE_CTE
    SELECT
      role,
      ts,
      left(content, 500) as content
    FROM msgs
    WHERE msg_type IN ('user', 'assistant')
      AND session_id LIKE '${SESSION_PREFIX}%'
    ORDER BY ts ASC
    "
    ;;

  context)
    if [ $# -eq 0 ]; then
      echo "Usage: recall-search context <session-id-prefix>" >&2
      exit 1
    fi
    SESSION_PREFIX="$1"
    $DUCK -c "
    $BASE_CTE
    , session_msgs AS (
      SELECT
        role,
        ts,
        content,
        row_number() OVER (ORDER BY ts ASC) as rn,
        count(*) OVER () as total
      FROM msgs
      WHERE msg_type IN ('user', 'assistant')
        AND session_id LIKE '${SESSION_PREFIX}%'
    )
    SELECT
      role,
      ts,
      left(content, 500) as content
    FROM session_msgs
    WHERE rn <= 10 OR rn > total - 20
    ORDER BY ts ASC
    "
    ;;

  topics)
    $DUCK -c "
    $BASE_CTE
    , session_info AS (
      SELECT
        session_id,
        branch,
        min(ts) as first_ts,
        max(ts) as last_ts,
        count(*) FILTER (WHERE msg_type = 'user' AND role = 'user') as user_msgs,
        sum(length(content)) FILTER (WHERE msg_type = 'user' AND role = 'user') as user_chars,
        first(content ORDER BY ts) FILTER (WHERE msg_type = 'user' AND role = 'user') as first_msg
      FROM msgs
      WHERE msg_type IN ('user', 'assistant')
      GROUP BY session_id, branch
    )
    SELECT
      left(session_id, 8) as session,
      strftime(first_ts::timestamp, '%Y-%m-%d') as date,
      user_msgs as msgs,
      printf('%.0f', extract(epoch FROM last_ts::timestamp - first_ts::timestamp) / 60.0) || 'min' as duration,
      left(first_msg, 100) as topic
    FROM session_info
    WHERE user_msgs > 2
      AND left(first_msg, 1) != '<'
    ORDER BY first_ts DESC
    LIMIT $LIMIT
    "
    ;;

  stats)
    echo "## Project Stats"
    echo ""
    $DUCK -c "
    $BASE_CTE
    , usage AS (
      SELECT
        json_extract_string(column0, '\$.message.model') as model,
        CAST(json_extract(column0, '\$.message.usage.output_tokens') AS BIGINT) as out_tok,
        CAST(json_extract(column0, '\$.message.usage.cache_read_input_tokens') AS BIGINT) as cache_read,
        CAST(json_extract(column0, '\$.message.usage.cache_creation_input_tokens') AS BIGINT) as cache_write
      FROM read_csv('$GLOB',
        delim=chr(0), header=false, ignore_errors=true, max_line_size=10000000)
      WHERE json_extract_string(column0, '\$.type') = 'assistant'
        AND json_extract_string(column0, '\$.message.model') IS NOT NULL
    )
    SELECT
      model,
      count(*) as turns,
      printf('%.1fM', sum(out_tok) / 1e6) as output_tokens,
      printf('%.1fB', sum(cache_read) / 1e9) as cache_read,
      printf('%.1fM', sum(cache_write) / 1e6) as cache_write
    FROM usage
    GROUP BY model
    ORDER BY count(*) DESC
    "
    echo ""
    echo "### Daily Activity"
    echo ""
    $DUCK -c "
    WITH raw_counts AS (
      SELECT
        json_extract_string(column0, '\$.type') as msg_type,
        json_extract_string(column0, '\$.sessionId') as session_id,
        json_extract_string(column0, '\$.timestamp') as ts
      FROM read_csv('$GLOB',
        delim=chr(0), header=false, ignore_errors=true, max_line_size=10000000)
      WHERE json_extract_string(column0, '\$.type') IN ('user', 'assistant')
    )
    SELECT
      strftime(ts::TIMESTAMP, '%Y-%m-%d') as day,
      count(DISTINCT session_id) as sessions,
      count(*) FILTER (WHERE msg_type = 'user') as user_msgs,
      count(*) FILTER (WHERE msg_type = 'assistant') as asst_turns
    FROM raw_counts
    GROUP BY day
    ORDER BY day
    "
    echo ""
    echo "### Session Duration Distribution"
    echo ""
    $DUCK -c "
    $BASE_CTE
    , bounds AS (
      SELECT
        session_id,
        min(ts::TIMESTAMP) as started,
        max(ts::TIMESTAMP) as ended,
        count(*) FILTER (WHERE msg_type = 'user') as user_msgs
      FROM msgs
      WHERE msg_type IN ('user', 'assistant')
      GROUP BY session_id
    )
    SELECT
      CASE
        WHEN extract(epoch FROM ended - started) / 3600 < 0.5 THEN '<30min'
        WHEN extract(epoch FROM ended - started) / 3600 < 1 THEN '30min-1hr'
        WHEN extract(epoch FROM ended - started) / 3600 < 2 THEN '1-2hr'
        WHEN extract(epoch FROM ended - started) / 3600 < 4 THEN '2-4hr'
        ELSE '4hr+'
      END as duration,
      count(*) as sessions,
      avg(user_msgs)::INT as avg_msgs
    FROM bounds
    WHERE user_msgs > 0
    GROUP BY duration
    ORDER BY min(extract(epoch FROM ended - started))
    "
    ;;

  impact)
    # Find the most impactful sessions by engagement (user messages x content length)
    COUNT="${1:-15}"
    $DUCK -c "
    $BASE_CTE
    , session_info AS (
      SELECT
        session_id,
        branch,
        min(ts) as first_ts,
        max(ts) as last_ts,
        count(*) FILTER (WHERE msg_type = 'user' AND role = 'user') as user_msgs,
        sum(length(content)) FILTER (WHERE msg_type = 'user' AND role = 'user') as user_chars,
        first(content ORDER BY ts) FILTER (WHERE msg_type = 'user' AND role = 'user') as first_msg
      FROM msgs
      WHERE msg_type IN ('user', 'assistant')
      GROUP BY session_id, branch
    )
    SELECT
      left(session_id, 8) as session,
      strftime(first_ts::timestamp, '%Y-%m-%d') as date,
      user_msgs as msgs,
      printf('%.0f', user_chars / 1000.0) || 'k' as chars,
      printf('%.1fhr', extract(epoch FROM last_ts::timestamp - first_ts::timestamp) / 3600.0) as duration,
      left(first_msg, 90) as topic
    FROM session_info
    WHERE user_msgs > 3
      AND first_msg IS NOT NULL
      AND left(first_msg, 1) != '<'
    ORDER BY user_msgs DESC
    LIMIT $COUNT
    "
    ;;

  help|*)
    echo "recall-search — Search Claude Code conversation history"
    echo ""
    echo "Usage:"
    echo "  search <keywords>     Search user+assistant messages for keywords"
    echo "  sessions              List all sessions (most recent first)"
    echo "  spine <session-id>    Extract conversation spine"
    echo "  context <session-id>  First 10 + last 20 messages (compact)"
    echo "  topics                Extract topics from all sessions"
    echo "  stats                 Project-level usage dashboard"
    echo "  impact [N]            Most impactful sessions by engagement"
    echo ""
    echo "Project: $HISTORY_DIR"
    echo "Files: $FILE_COUNT sessions"
    ;;
esac

SKILL.md

name	description
recall	Load context from a past conversation into this fresh session so you can resume work. Not a search tool — a context handoff mechanism across /clear boundaries.

You are loading context from a past conversation so the user can continue where they left off. This is the most common thing you'll do — the user works in fast, intense bursts, clearing context constantly, and /recall bridges those gaps.

What You're Given

The user's query will be one of:

1. A topic — "we were chatting about the actor model", "the discussion about modularizing the prompt"
2. A session ID fragment — "471982bc...", a UUID or prefix of one
3. A vague description — "that script we built for zombie processes", "the s3-send thing"
4. A recency reference — "the last conversation", "my most recent session"
5. A request to review — "read the agent output from my most recent convo", "why did this session run out of context?"

Where Conversations Live

Conversation history is stored as JSONL files at:

~/.claude/projects/{project-dir}/*.jsonl

The {project-dir} is the working directory path with / replaced by - and a leading -. For example:

• /home/user/projects/myapp → -home-user-projects-myapp

Each .jsonl file is one conversation session. The filename (minus .jsonl) is the session UUID.

JSONL Record Structure

Each line is a JSON object. The important fields:

• type: "user", "assistant", "progress", "file-history-snapshot"
• message.role: "user" or "assistant"
• message.content: string (user messages) or array of content blocks (assistant messages — look for type: "text" blocks)
• timestamp: ISO 8601
• sessionId: UUID of the session
• gitBranch: branch at time of message
• cwd: working directory

Only type: "user" and type: "assistant" records with text content matter. Skip progress, file-history-snapshot, tool use blocks, and thinking blocks.

Tools

A DuckDB-powered search script called recall-search should be on your PATH (installed to ~/.local/bin/ or similar). It searches all conversation JSONL files in seconds. Always use this script first — it replaces manual grep/jq parsing.

# Search for sessions mentioning keywords (ranked by hit count)
recall-search search <keyword1> <keyword2> ...

# List all sessions (most recent first)
recall-search sessions

# Extract conversation spine (all user + assistant text messages)
recall-search spine <session-id-prefix>

# Compact context: first 10 + last 20 messages (for long sessions)
recall-search context <session-id-prefix>

Process

Phase 1: Find the Conversation

If session ID fragment: Run recall-search spine <prefix> directly.

If "last" / "most recent": Run recall-search sessions and take the most recent (excluding the current session).

If topic or vague description: Extract 2-4 keywords and run recall-search search <keywords>. Results are ranked by hit count with session ID, date, branch, and first user message.

If there's a single strong match, skip the selection step and load it directly. If no matches in the current project, fall back to grep across ~/.claude/projects/.

Phase 2: Load and Extract

Use recall-search spine <session-id> to get the full conversation spine (user + assistant text only, no tool calls or thinking blocks).

For very long conversations (>100 messages in output), use recall-search context <session-id> instead — it returns the first 10 + last 20 messages, which captures the topic setup and where things left off.

For targeted extraction within a loaded spine, search for key decision language ("let's go with", "decided", "the plan is", "changed to").

Phase 3: Synthesize the Context Brief

Do not dump the raw conversation. Synthesize a structured brief designed for continuation:

## Context Brief: [topic in 5-10 words]

**Session:** [id fragment] | [date] | branch: [branch]
**Duration:** [first timestamp] → [last timestamp] ([N] user messages)

### What We Were Doing
[1-3 sentences: the goal, the approach, the scope]

### Key Decisions
- [decision 1 — what was chosen and why]
- [decision 2]
[only include if decisions were actually made]

### Where It Left Off
[what was the last thing discussed, what was the next step,
 what was unresolved — this is the most important section]

### Files Touched
[list files that were read, edited, or created — extract from tool calls if visible]

### Open Threads
[questions raised but not answered, deferred items, things to revisit]

Adjust the format to fit the conversation. Short sessions might only need "What We Were Doing" and "Where It Left Off". Review/audit requests might need more emphasis on "Key Decisions" and critique. Drop any section that has nothing useful to say.

Phase 4: Present and Stand By

After presenting the brief, stop and wait. The user will tell you what to do next — resume the work, dig deeper into a specific thread, or load a different conversation. Don't proactively start working on whatever the past conversation was about.

Principles

• Speed over completeness. The user is trying to get back to work. A good-enough brief in 15 seconds beats a perfect one in 60.
• The "where it left off" section is the whole point. Everything else is scaffolding for that. If you can only produce one section, make it that one.
• Don't editorialize. Report what happened, not what you think about it — unless the user specifically asks for review/critique.
• Conversations are private context. Don't be surprised by informal language, false starts, or abandoned approaches. That's normal working context.
• When in doubt, show options. If multiple conversations could match, list them rather than guessing wrong.