@aiplumber/session-recall 1.5.0 → 1.5.2

package/README.md

@@ -0,0 +1,228 @@
+# @aiplumber/session-recall
+
+Pull context from previous **[Claude Code](https://docs.anthropic.com/en/docs/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
+
+```bash
+npm install -g @aiplumber/session-recall
+```
+
+Requires Node.js 16+.
+
+## Quick Start
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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"
+```
+
+### rinse - Compress Session Data
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# See what you worked on
+session-recall last 1 -d
+
+# Pull the context
+session-recall last 1 -f text
+```
+
+### 2. Long-Running Implementation
+
+```bash
+# 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
+
+```bash
+# What did that command output?
+session-recall tools
+session-recall tools --show 014opBVN
+```
+
+### 4. Multi-Session Project Context
+
+```bash
+# Combine multiple sessions
+session-recall last 3 -f text > context.txt
+```
+
+## 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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiplumber/session-recall",
-  "version": "1.5.0",
+  "version": "1.5.2",
   "description": "Pull context from previous Claude Code sessions. Sessions end, context resets - this tool lets you continue where you left off.",
   "bin": {
     "session-recall": "./session-recall"