@aiplumber/session-recall

Pull context from previous Claude Code sessions. Sessions end, context resets - this tool lets you continue where you left off.

What is Claude Code? Anthropic's official CLI for Claude - an agentic coding assistant that runs in your terminal. This tool parses Claude Code's conversation logs stored in ~/.claude/projects/.

The Problem

Every Claude Code session starts fresh. Yesterday's breakthroughs, decisions, and momentum - gone. You're left explaining context again, losing the thread of what you were building.

The Solution

session-recall extracts the signal from your session logs, filtering out the noise. Import previous context without blowing your token budget.

Installation

npm install -g @aiplumber/session-recall

Requires Node.js 16+.

Quick Start

# Check what sessions exist (CWD project)
session-recall last 3 -d

# Pull last session context
session-recall last 1 -f text

# List tool calls from last session
session-recall tools

# Get specific tool result
session-recall tools --show 014opBVN

What Gets Filtered (Noise)

Session-recall strips out the bloat that eats tokens without adding value:

Tool Artifacts:

• File contents you read (they exist in files, don't duplicate)
• Code you generated (it's in the codebase now)
• Command outputs (already processed, outcome captured)
• Error logs user pasted (dealt with, moved on)

Operational Chatter:

• "Let me read that file" (just read it)
• "I'll run this command" (just the result matters)
• Shell commands without context (ls, cd, npm install)
• System reminders and progress updates

Message Types Filtered:

• type: progress - tool execution noise
• type: system - system messages
• type: file-history-snapshot - file state snapshots
• Tool results (unless --logistics mode)
• User messages > 200 chars (usually pasted logs)

What's Kept (Signal)

The discourse that matters:

Short user messages:

• "nooooo" (3 words, massive redirection)
• "for real?" (pushback, led to honesty)
• "A, B, C" (decisions locked in)

Questions that shaped direction:

• "how do you think we will get clarity?"
• "what is the workproduct?"

Aha moments:

• "did we just discover..."
• "YES. Now I see..."

The rule: Short = signal. Long = usually noise.

User's 3-word redirection carries more weight than assistant's 500-word explanation.

Commands

last - Pull Recent Sessions

# Check what's available (dry run)
session-recall last 3 -d

# Pull last session from current project
session-recall last 1 -f text

# Pull last 2 sessions
session-recall last 2 -f text

# Scan all projects (not just CWD)
session-recall last 5 --all -d

tools - Inspect Tool Calls

# List all tool calls from last session
session-recall tools

# Get specific tool result by ID
session-recall tools --show 014opBVN

checkpoints - Mark Progress Points

# Create a checkpoint (marker that gets logged)
session-recall --checkpoint "finished research"
session-recall --checkpoint "starting implementation"

# List all checkpoints
session-recall checkpoints

# Recall only messages AFTER a checkpoint
session-recall last 1 --after "finished research"

tags - Mark Important Content

Tag any session content for later recall. Critical items auto-surface.

# Preview what would be tagged (without tagging)
session-recall --back 3 toolcall

# Tag most recent tool call as critical
session-recall tag toolcall critical "found the root cause"

# Tag tool call from 3 calls ago
session-recall tag toolcall --back 3 important "useful data here"

# Tag other content types
session-recall tag agentcall critical "minion discovered pattern"
session-recall tag discourse important "user clarified requirement"
session-recall tag checkpoint critical "breakthrough moment"

# List all tags
session-recall tags

# Filter tags
session-recall tags critical      # Only critical level
session-recall tags toolcall      # Only tool calls

Types: toolcall, agentcall, discourse, checkpoint

Levels:

• critical - Auto-injected in recall output (always shown)
• important - Shown with --show-important flag
• bookmark - Lookup only, never injected

rinse - Compress Session Data

# Compress with tool calls collapsed (action mode)
session-recall rinse session.jsonl --gotime

# Keep tool results truncated (see what was done)
session-recall rinse session.jsonl --logistics

# Check token cost first
session-recall rinse session.jsonl --gotime -d

Other Commands

# Show session stats
session-recall state session.jsonl

# Compare import costs
session-recall cost session.jsonl

# Extract last N exchanges
session-recall hot session.jsonl --last 30

# Parse to filtered jsonl
session-recall parse session.jsonl -f text

Use Cases

1. Continue Yesterday's Work

# See what you worked on
session-recall last 1 -d

# Pull the context
session-recall last 1 -f text

2. Long-Running Implementation

# Mark milestones as you go
session-recall --checkpoint "research complete"
session-recall --checkpoint "design approved"
session-recall --checkpoint "implementation started"

# Tomorrow, resume from any point
session-recall last 1 --after "design approved"

3. Debug a Tool Result

# What did that command output?
session-recall tools
session-recall tools --show 014opBVN

4. Multi-Session Project Context

# Combine multiple sessions
session-recall last 3 -f text > context.txt

5. Tag Critical Discoveries

# Run commands, discover something important
Bash: grep "API_KEY" .env
# Output: API_KEY=sk-live-abc123...

# Realize that was important (2 tool calls ago)
session-recall --back 2 toolcall
# Shows: UUID abc123 | grep "API_KEY" .env | API_KEY=sk-...

# Tag it
session-recall tag toolcall --back 2 critical "found exposed API key"

# Next session - critical items auto-surface in recall
session-recall last 2
# [16:42:15] ⚠ CRITICAL [toolcall] grep "API_KEY" .env
#            Reason: "found exposed API key"
#            Result: API_KEY=sk-live-abc123...

Output Modes

| Flag | Tool Results | Use Case | |------|--------------|----------| | --gotime | [Ran: ls -la] | Action mode - let's move | | --logistics | drwxr-xr-x... (truncated) | Planning - show me the receipts |

Token Economics

Session-recall helps you fit more context in less tokens:

| Raw Session | After Rinse | Savings | |-------------|-------------|---------| | 750 messages | ~250 messages | 67% | | ~50k tokens | ~7k tokens | 86% |

The filtering isn't lossy - it's removing redundancy. The signal-to-noise ratio goes up dramatically.

How It Works

Claude Code stores conversations in ~/.claude/projects/<project>/ as JSONL files. Each line is a message with metadata.

Session-recall:

1. Maps your CWD to the project folder
2. Reads the JSONL conversation logs
3. Filters out noise (tool results, system messages, long pastes)
4. Collapses tool calls to summaries
5. Outputs clean discourse

License

MIT

Author

Hung Nguyen (@aiplumber)