@aiplumber/session-recall 1.5.2 → 1.6.6

package/README.md

@@ -122,6 +122,40 @@ session-recall checkpoints
 session-recall last 1 --after "finished research"
 ```
 
+### tags - Mark Important Content
+
+Tag any session content for later recall. Critical items auto-surface.
+
+```bash
+# 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
 
 ```bash
@@ -190,6 +224,27 @@ session-recall tools --show 014opBVN
 session-recall last 3 -f text > context.txt
 ```
 
+### 5. Tag Critical Discoveries
+
+```bash
+# 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 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiplumber/session-recall",
-  "version": "1.5.2",
+  "version": "1.6.6",
   "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"

package/session-recall

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
 
+const VERSION = '1.6.6';
+
 const fs = require('fs');
 const path = require('path');
 
@@ -333,6 +335,25 @@ function getToolResultText(msg) {
   return typeof result.content === 'string' ? result.content : JSON.stringify(result.content);
 }
 
+// Extract tool_result content from user message (for marker-based search)
+function getToolResultContent(msg) {
+  if (msg.type !== 'user') return null;
+
+  // Check toolUseResult.stdout
+  if (msg.toolUseResult?.stdout) return msg.toolUseResult.stdout;
+
+  // Check message.content array
+  if (msg.message?.content && Array.isArray(msg.message.content)) {
+    for (const block of msg.message.content) {
+      if (block.type === 'tool_result' && block.content) {
+        return typeof block.content === 'string' ? block.content : JSON.stringify(block.content);
+      }
+    }
+  }
+
+  return null;
+}
+
 function cmdRinse(inputPath, opts) {
   // Check if input is a directory or file
   const stat = fs.statSync(inputPath);
@@ -679,6 +700,42 @@ function cmdTools(opts) {
   console.log(`Use: session-recall tools --show ${exampleId} to see specific result`);
 }
 
+// Checkpoint marker pattern for discovery (search tool_result content, not command strings)
+const CHECKPOINT_MARKER_PATTERN = /@@SESSION-CHECKPOINT@@\s+"([^"]+)"(?:\s+uuid="([^"]*)")?(?:\s+stopped_at="([^"]*)")?(?:\s+next="([^"]*)")?(?:\s+blocker="([^"]*)")?(?:\s+decision="([^"]*)")?(?:\s+gotcha="([^"]*)")?\s+ts=(\S+)/;
+// Groups: [1]=name, [2]=uuid, [3]=stopped_at, [4]=next, [5]=blocker, [6]=decision, [7]=gotcha, [8]=timestamp
+
+// Scan session messages for checkpoint markers in tool_result content
+function scanSessionCheckpoints(messages, sessionFile) {
+  const checkpoints = [];
+
+  for (const msg of messages) {
+    // Look for checkpoint markers in tool_result content (user messages)
+    const resultContent = getToolResultContent(msg);
+    if (!resultContent) continue;
+
+    const match = resultContent.match(CHECKPOINT_MARKER_PATTERN);
+    if (match) {
+      const fields = {};
+      if (match[3]) fields.stopped_at = match[3];
+      if (match[4]) fields.next = match[4];
+      if (match[5]) fields.blocker = match[5];
+      if (match[6]) fields.decision = match[6];
+      if (match[7]) fields.gotcha = match[7];
+
+      checkpoints.push({
+        name: match[1],
+        uuid: match[2] || sessionFile.replace('.jsonl', ''),  // Use embedded uuid or fallback to session file
+        fields,
+        timestamp: match[8],  // Use timestamp from marker
+        msgTimestamp: msg.timestamp,  // Also keep message timestamp
+        session: sessionFile
+      });
+    }
+  }
+
+  return checkpoints;
+}
+
 function cmdCheckpoints(opts) {
   const dir = cwdToProjectFolder();
   if (!dir) {
@@ -698,26 +755,8 @@ function cmdCheckpoints(opts) {
   for (const file of jsonlFiles) {
     const filePath = path.join(dir, file);
     const msgs = readJsonl(filePath);
-
-    for (const msg of msgs) {
-      // Look for Bash tool calls with session-recall --checkpoint
-      if (msg.type === 'assistant' && msg.message?.content && Array.isArray(msg.message.content)) {
-        for (const block of msg.message.content) {
-          if (block.type === 'tool_use' && block.name === 'Bash') {
-            const cmd = block.input?.command || '';
-            const match = cmd.match(/session-recall\s+--checkpoint\s+["']?([^"'\n]+)["']?/);
-            if (match) {
-              checkpoints.push({
-                name: match[1].trim(),
-                timestamp: msg.timestamp,
-                toolId: block.id,
-                session: file
-              });
-            }
-          }
-        }
-      }
-    }
+    const sessionCheckpoints = scanSessionCheckpoints(msgs, file);
+    checkpoints.push(...sessionCheckpoints);
   }
 
   if (checkpoints.length === 0) {
@@ -729,19 +768,51 @@ function cmdCheckpoints(opts) {
   // Sort by timestamp
   checkpoints.sort((a, b) => new Date(a.timestamp) - new Date(b.timestamp));
 
+  // If --show, display specific checkpoint details
+  if (opts.show) {
+    const cp = checkpoints.find(c => c.name.toLowerCase().includes(opts.show.toLowerCase()));
+    if (!cp) {
+      console.error(`Checkpoint not found: "${opts.show}"`);
+      console.error(`\nAvailable checkpoints:`);
+      checkpoints.forEach(c => console.error(`  "${c.name}"`));
+      process.exit(1);
+    }
+
+    console.log(`=== CHECKPOINT: ${cp.name} ===`);
+    console.log(`UUID: ${cp.uuid}`);
+    console.log(`Time: ${cp.timestamp ? new Date(cp.timestamp).toISOString().substring(11, 19) : 'unknown'}`);
+    console.log(``);
+
+    const fieldNames = ['stopped_at', 'next', 'blocker', 'decision', 'gotcha'];
+    let hasFields = false;
+    for (const field of fieldNames) {
+      if (cp.fields[field]) {
+        console.log(`${field}: ${cp.fields[field]}`);
+        hasFields = true;
+      }
+    }
+    if (!hasFields) {
+      console.log(`(no structured fields)`);
+    }
+    return;
+  }
+
+  // List all checkpoints
   console.log(`=== CHECKPOINTS (${checkpoints.length} total) ===`);
   console.log(``);
-  console.log(`#   TIME      ID            NAME`);
+  console.log(`#   TIME      NAME                              FIELDS`);
   console.log(`────────────────────────────────────────────────────────────────────`);
 
   checkpoints.forEach((cp, i) => {
     const ts = cp.timestamp ? new Date(cp.timestamp).toISOString().substring(11, 19) : '??:??:??';
-    const shortId = cp.toolId ? cp.toolId.substring(5, 17) : '????????????';
-    console.log(`${String(i + 1).padStart(2)}  ${ts}  ${shortId}  ${cp.name}`);
+    const name = cp.name.substring(0, 32).padEnd(32);
+    const fieldList = Object.keys(cp.fields).filter(k => cp.fields[k]).join(', ') || '-';
+    console.log(`${String(i + 1).padStart(2)}  ${ts}  ${name}  ${fieldList}`);
   });
 
   console.log(``);
-  console.log(`Use: session-recall last 1 --after "checkpoint name" to recall from checkpoint`);
+  console.log(`Use: session-recall checkpoints --show "name" for details`);
+  console.log(`Use: session-recall last 1 --after "name" to recall from checkpoint`);
 }
 
 function calcSessionCosts(messages) {
@@ -970,74 +1041,54 @@ function cmdLast(arg1, arg2, opts) {
     const jsonlFiles = fs.readdirSync(dir).filter(f => f.endsWith('.jsonl'));
     let checkpoint = null;
 
+    // Collect all checkpoints using marker-based search
+    const allCheckpoints = [];
     for (const file of jsonlFiles) {
       const filePath = path.join(dir, file);
       const msgs = readJsonl(filePath);
-
-      for (const msg of msgs) {
-        // Look for Bash tool calls with session-recall --checkpoint
-        if (msg.type === 'assistant' && msg.message?.content && Array.isArray(msg.message.content)) {
-          for (const block of msg.message.content) {
-            if (block.type === 'tool_use' && block.name === 'Bash') {
-              const cmd = block.input?.command || '';
-              const match = cmd.match(/session-recall\s+--checkpoint\s+["']?([^"'\n]+)["']?/);
-              if (match && match[1].trim() === opts.after) {
-                checkpoint = {
-                  name: match[1].trim(),
-                  timestamp: msg.timestamp,
-                  session: file
-                };
-                break;
-              }
-            }
-          }
-        }
-        if (checkpoint) break;
-      }
-      if (checkpoint) break;
+      const sessionCheckpoints = scanSessionCheckpoints(msgs, file);
+      allCheckpoints.push(...sessionCheckpoints);
     }
 
+    // Find the matching checkpoint
+    checkpoint = allCheckpoints.find(cp => cp.name === opts.after);
+
     if (!checkpoint) {
       console.error(`Checkpoint not found: "${opts.after}"`);
       console.error(`Available checkpoints:`);
 
-      // List all available checkpoints
-      const checkpoints = [];
-      for (const file of jsonlFiles) {
-        const filePath = path.join(dir, file);
-        const msgs = readJsonl(filePath);
-
-        for (const msg of msgs) {
-          if (msg.type === 'assistant' && msg.message?.content && Array.isArray(msg.message.content)) {
-            for (const block of msg.message.content) {
-              if (block.type === 'tool_use' && block.name === 'Bash') {
-                const cmd = block.input?.command || '';
-                const match = cmd.match(/session-recall\s+--checkpoint\s+["']?([^"'\n]+)["']?/);
-                if (match) {
-                  checkpoints.push({
-                    name: match[1].trim(),
-                    timestamp: msg.timestamp
-                  });
-                }
-              }
-            }
-          }
-        }
-      }
-
-      if (checkpoints.length === 0) {
+      if (allCheckpoints.length === 0) {
         console.error('  (none)');
       } else {
-        checkpoints.sort((a, b) => new Date(a.timestamp) - new Date(b.timestamp));
-        checkpoints.forEach(cp => {
-          const ts = cp.timestamp ? new Date(cp.timestamp).toISOString().substring(11, 19) : '??:??:??';
+        allCheckpoints.sort((a, b) => new Date(a.timestamp) - new Date(b.timestamp));
+        allCheckpoints.forEach(cp => {
+          const ts = cp.timestamp ? cp.timestamp.substring(11, 19) : '??:??:??';
           console.error(`  "${cp.name}" (${ts})`);
         });
       }
       process.exit(1);
     }
 
-    filterAfterTs = checkpoint.timestamp ? new Date(checkpoint.timestamp).getTime() : null;
+    // Use msgTimestamp for filtering (timestamp from jsonl message, not marker)
+    filterAfterTs = checkpoint.msgTimestamp ? new Date(checkpoint.msgTimestamp).getTime() : new Date(checkpoint.timestamp).getTime();
+  }
+
+  // Helper: get session start timestamp from first line of jsonl
+  function getSessionStartTs(filePath) {
+    try {
+      const content = fs.readFileSync(filePath, 'utf-8');
+      const firstLine = content.split('\n')[0];
+      if (!firstLine) return null;
+      const obj = JSON.parse(firstLine);
+      // Check snapshot.timestamp first (common in first line), then top-level timestamp
+      let ts = obj.snapshot?.timestamp || obj.timestamp;
+      if (ts) return new Date(ts);
+      // Fallback: find first timestamp in file
+      const match = content.match(/"timestamp":"([^"]+)"/);
+      return match ? new Date(match[1]) : null;
+    } catch (e) {
+      return null;
+    }
   }
 
   // Collect all sessions
@@ -1048,10 +1099,9 @@ function cmdLast(arg1, arg2, opts) {
     const jsonlFiles = fs.readdirSync(dir).filter(f => f.endsWith('.jsonl'));
     for (const file of jsonlFiles) {
       const filePath = path.join(dir, file);
-      const msgs = readJsonl(filePath);
-      const timestamps = msgs.filter(m => m.timestamp).map(m => new Date(m.timestamp));
-      const lastTs = timestamps.length > 0 ? new Date(Math.max(...timestamps)) : null;
-      allSessions.push({ filePath, msgs, lastTs, project: path.basename(dir) });
+      const startTs = getSessionStartTs(filePath);
+      // Defer full read until needed
+      allSessions.push({ filePath, startTs, project: path.basename(dir), _msgs: null });
     }
   } else {
     // Scan all projects
@@ -1069,10 +1119,8 @@ function cmdLast(arg1, arg2, opts) {
       for (const file of jsonlFiles) {
         const filePath = path.join(projPath, file);
         try {
-          const msgs = readJsonl(filePath);
-          const timestamps = msgs.filter(m => m.timestamp).map(m => new Date(m.timestamp));
-          const lastTs = timestamps.length > 0 ? new Date(Math.max(...timestamps)) : null;
-          allSessions.push({ filePath, msgs, lastTs, project: proj });
+          const startTs = getSessionStartTs(filePath);
+          allSessions.push({ filePath, startTs, project: proj, _msgs: null });
         } catch (e) {
           // Skip unreadable files
         }
@@ -1080,12 +1128,22 @@ function cmdLast(arg1, arg2, opts) {
     }
   }
 
-  // Sort by last timestamp descending
-  allSessions.sort((a, b) => (b.lastTs || 0) - (a.lastTs || 0));
+  // Sort by session start timestamp descending (most recent first)
+  allSessions.sort((a, b) => (b.startTs || 0) - (a.startTs || 0));
+
+  // Now load messages for top candidates and compute lastTs for active filter
+  // We check more than n to account for filtering out active sessions
+  const candidateCount = Math.min(allSessions.length, n + 5);
+  for (let i = 0; i < candidateCount; i++) {
+    const s = allSessions[i];
+    s.msgs = readJsonl(s.filePath);
+    const timestamps = s.msgs.filter(m => m.timestamp).map(m => new Date(m.timestamp));
+    s.lastTs = timestamps.length > 0 ? new Date(Math.max(...timestamps)) : s.startTs;
+  }
 
   // Exclude currently active sessions (activity within threshold)
   const now = Date.now();
-  const inactiveSessions = allSessions.filter(s => {
+  const inactiveSessions = allSessions.slice(0, candidateCount).filter(s => {
     if (!s.lastTs) return true; // Include sessions with no timestamp
     const ageMs = now - s.lastTs.getTime();
     return ageMs > ACTIVE_SESSION_THRESHOLD_MS;
@@ -1099,8 +1157,8 @@ function cmdLast(arg1, arg2, opts) {
     process.exit(1);
   }
 
-  // Count excluded active sessions for reporting
-  const excludedActive = allSessions.length - inactiveSessions.length;
+  // Count excluded active sessions for reporting (only from candidates we checked)
+  const excludedActive = candidateCount - inactiveSessions.length;
 
   if (opts.dryRun) {
     console.log(`--- DRY RUN: last ${n} ---`);
@@ -1144,47 +1202,104 @@ function cmdLast(arg1, arg2, opts) {
     return;
   }
 
-  // Output combined rinse (gotime mode)
-  let allMsgs = selected.flatMap(s => s.msgs);
-  // Sort by timestamp
-  allMsgs.sort((a, b) => new Date(a.timestamp || 0) - new Date(b.timestamp || 0));
+  // Print header
+  console.log(`[session-recall v${VERSION}] This context has been stripped of most tool results to reduce noise.`);
+  console.log(`---`);
 
-  // Filter by checkpoint timestamp if --after was specified
-  if (filterAfterTs) {
-    allMsgs = allMsgs.filter(msg => {
-      const msgTs = msg.timestamp ? new Date(msg.timestamp).getTime() : 0;
-      return msgTs > filterAfterTs;
-    });
-  }
+  // Process each session separately to add separators
+  for (let sessionIdx = 0; sessionIdx < selected.length; sessionIdx++) {
+    const session = selected[sessionIdx];
+    let sessionMsgs = session.msgs;
 
-  // Build tool result metadata (size, duration)
-  const resultMeta = buildToolResultMeta(allMsgs);
+    // Sort by timestamp
+    sessionMsgs.sort((a, b) => new Date(a.timestamp || 0) - new Date(b.timestamp || 0));
 
-  for (const msg of allMsgs) {
-    if (NOISE_TYPES.includes(msg.type)) continue;
-    if (msg.type === 'user') {
-      if (isToolResult(msg)) continue;
-      const text = getUserText(msg);
-      if (text) {
-        const ts = msg.timestamp ? new Date(msg.timestamp).toISOString().substring(11, 19) : '';
-        console.log(`[${ts}] USER: ${text.substring(0, 500)}`);
+    // Filter by checkpoint timestamp if --after was specified
+    if (filterAfterTs) {
+      sessionMsgs = sessionMsgs.filter(msg => {
+        const msgTs = msg.timestamp ? new Date(msg.timestamp).getTime() : 0;
+        return msgTs > filterAfterTs;
+      });
+    }
+
+    // Build tool result metadata (size, duration)
+    const resultMeta = buildToolResultMeta(sessionMsgs);
+
+    // Build tag map for this session
+    const tagMap = {};
+    const sessionTags = scanSessionTags(session.filePath);
+    for (const tag of sessionTags) {
+      if (tag.targetUuid) {
+        tagMap[tag.targetUuid] = {
+          type: tag.type,
+          level: tag.level,
+          reason: tag.reason
+        };
       }
-    } else if (msg.type === 'assistant') {
-      const text = getAssistantText(msg);
-      const toolSummary = collapseToolCall(msg, resultMeta);
-      const ts = msg.timestamp ? new Date(msg.timestamp).toISOString().substring(11, 19) : '';
-      if (text) {
-        console.log(`[${ts}] ASSISTANT: ${text.substring(0, 500)}`);
-      } else if (toolSummary) {
-        console.log(`[${ts}] ASSISTANT: ${toolSummary}`);
+    }
+
+    for (const msg of sessionMsgs) {
+      if (NOISE_TYPES.includes(msg.type)) continue;
+
+      // Check if this message has a tag
+      const toolId = getToolUseId(msg);
+      const msgUuid = toolId || msg.uuid;
+      const tag = msgUuid ? tagMap[msgUuid] : null;
+
+      // Determine if we should show this tag
+      const showTag = tag && (
+        tag.level === 'critical' ||
+        (tag.level === 'important' && opts.showImportant)
+      );
+
+      if (msg.type === 'user') {
+        if (isToolResult(msg)) continue;
+        const text = getUserText(msg);
+        if (text) {
+          const ts = msg.timestamp ? new Date(msg.timestamp).toISOString().substring(11, 19) : '';
+          if (showTag) {
+            const marker = tag.level === 'critical' ? '\u26A0' : '\u2139';
+            console.log(`[${ts}] ${marker} ${tag.level.toUpperCase()} [${tag.type}] USER: ${text.substring(0, 500)}`);
+            console.log(`         Reason: "${tag.reason}"`);
+          } else {
+            console.log(`[${ts}] USER: ${text.substring(0, 500)}`);
+          }
+        }
+      } else if (msg.type === 'assistant') {
+        const text = getAssistantText(msg);
+        const toolSummary = collapseToolCall(msg, resultMeta);
+        const ts = msg.timestamp ? new Date(msg.timestamp).toISOString().substring(11, 19) : '';
+
+        if (showTag) {
+          const marker = tag.level === 'critical' ? '\u26A0' : '\u2139';
+          if (text) {
+            console.log(`[${ts}] ${marker} ${tag.level.toUpperCase()} [${tag.type}] ASSISTANT: ${text.substring(0, 500)}`);
+          } else if (toolSummary) {
+            console.log(`[${ts}] ${marker} ${tag.level.toUpperCase()} [${tag.type}] ${toolSummary}`);
+          }
+          console.log(`         Reason: "${tag.reason}"`);
+        } else {
+          if (text) {
+            console.log(`[${ts}] ASSISTANT: ${text.substring(0, 500)}`);
+          } else if (toolSummary) {
+            console.log(`[${ts}] ASSISTANT: ${toolSummary}`);
+          }
+        }
       }
     }
+
+    // Print session separator if not the last session
+    if (sessionIdx < selected.length - 1) {
+      const nextSession = selected[sessionIdx + 1];
+      const nextTs = nextSession.lastTs ? nextSession.lastTs.toISOString().replace('T', ' ').substring(0, 16) : 'unknown';
+      console.log(`\n=== END SESSION ${sessionIdx + 1} === NEXT SESSION: ${nextSession.project} (${nextTs}) ===\n`);
+    }
   }
 
   // Print instructions for Claude
   console.log(``);
   console.log(`---`);
-  console.log(`To get a specific tool result: session-recall tools --show <id>`);
+  console.log(`Tool results: Most are noise. Only fetch with "session-recall tools --show <id>" when you see something you actually need.`);
   console.log(`Session file: ${selected[0]?.filePath || 'unknown'}`);
 }
 
@@ -1219,16 +1334,39 @@ COMMANDS:
   last [N] [folder]          Get last N sessions (default: 1, CWD project only)
     -a, --all                Scan all projects (not just CWD)
     -d, --dry-run            Show what would be pulled without output
+    --show-important         Include important-level tags in output
 
   tools                      List tool calls in most recent session (CWD project)
     --show <id>              Show specific tool result by ID (partial match)
 
   checkpoints                List all checkpoints in current project
+    --show "name"            Show checkpoint details (partial match)
 
-  --checkpoint "name"        Create a checkpoint marker (use as standalone flag)
+  --checkpoint "name"        Create a checkpoint marker
+    --stopped_at "point"     Where work stopped (file:line, step N of M)
+    --next "action"          Single next action to take
+    --blocker "issue"        What's blocking progress (optional)
+    --decision "choice"      Decision made + reasoning (optional)
+    --gotcha "trap"          Gotcha for next session (optional)
 
   last [N] --after "name"    Recall from after a checkpoint
 
+TAGGING:
+  --back N [type]            Preview message N positions back (for tagging)
+                             Types: toolcall, agentcall, discourse, checkpoint
+
+  tag <type> [--back N] <level> "reason"
+                             Tag a message for recall surfacing
+                             Types: toolcall, agentcall, discourse, checkpoint
+                             Levels: critical (auto-show), important (opt-in), bookmark (lookup)
+
+  tags [filter]              List all tags in current project
+                             Filter by type or level
+
+OPTIONS:
+  -v, --version              Show version number
+  -h, --help                 Show this help
+
 EXAMPLES:
   session-recall last 1 -d                          # Check what's available
   session-recall last 1 -f text                     # Pull last session
@@ -1236,12 +1374,401 @@ EXAMPLES:
   session-recall tools --show 014opBVN             # Get specific tool result
 
   # Checkpoints - mark progress, recall from any point
-  session-recall --checkpoint "finished research"   # Create checkpoint
+  session-recall --checkpoint "finished research"   # Simple checkpoint
+  session-recall --checkpoint "hit blocker" --stopped_at "auth.ts:42" --blocker "API 403"
   session-recall checkpoints                        # List all checkpoints
+  session-recall checkpoints --show "blocker"       # Show checkpoint details
   session-recall last 1 --after "finished research" # Recall from checkpoint
+
+  # Tagging - mark important moments
+  session-recall --back 3 toolcall                  # Preview 3rd previous tool call
+  session-recall tag toolcall critical "found the bug"  # Tag most recent
+  session-recall tag toolcall --back 3 important "useful data"  # Tag 3 back
+  session-recall tags                               # List all tags
+  session-recall tags critical                      # List only critical tags
+  session-recall last 1                             # Critical tags auto-surface
+  session-recall last 1 --show-important            # Include important tags
 `);
 }
 
+// ========== MESSAGE TYPE CLASSIFICATION ==========
+
+// Classify a message by its tagging type: toolcall, agentcall, discourse, checkpoint
+function classifyMessageType(msg, checkpointToolIds = new Set()) {
+  if (!msg) return null;
+
+  // Check for checkpoint (Bash tool calls with session-recall --checkpoint)
+  if (msg.type === 'assistant' && msg.message?.content && Array.isArray(msg.message.content)) {
+    for (const block of msg.message.content) {
+      if (block.type === 'tool_use' && block.name === 'Bash') {
+        const cmd = block.input?.command || '';
+        if (cmd.match(/session-recall\s+--checkpoint/)) {
+          return 'checkpoint';
+        }
+      }
+    }
+  }
+
+  // Check for tool_use in assistant messages
+  if (msg.type === 'assistant' && msg.message?.content && Array.isArray(msg.message.content)) {
+    const toolUses = msg.message.content.filter(c => c.type === 'tool_use');
+    if (toolUses.length > 0) {
+      // Check if any are Task tools (agentcall)
+      const hasTask = toolUses.some(t => t.name === 'Task');
+      if (hasTask) return 'agentcall';
+      return 'toolcall';
+    }
+  }
+
+  // Check for discourse (user messages without tool_result, or assistant with text)
+  if (msg.type === 'user') {
+    if (!isToolResult(msg)) {
+      const text = getUserText(msg);
+      if (text && text.length > 0) return 'discourse';
+    }
+    return null;
+  }
+
+  if (msg.type === 'assistant') {
+    const text = getAssistantText(msg);
+    if (text && text.length > 0) return 'discourse';
+  }
+
+  return null;
+}
+
+// Get message preview for --back display
+function getMessagePreview(msg, msgType) {
+  if (msgType === 'toolcall' || msgType === 'agentcall') {
+    if (msg.message?.content && Array.isArray(msg.message.content)) {
+      const toolUse = msg.message.content.find(c => c.type === 'tool_use');
+      if (toolUse) {
+        const name = toolUse.name;
+        const input = toolUse.input || {};
+        if (name === 'Task') {
+          return `Task: ${input.description?.substring(0, 60) || 'subagent task'}`;
+        } else if (name === 'Bash') {
+          return `Bash: ${input.command?.substring(0, 60) || 'command'}`;
+        } else if (name === 'Read') {
+          return `Read: ${input.file_path}`;
+        } else if (name === 'Edit' || name === 'Write') {
+          return `${name}: ${input.file_path}`;
+        } else if (name === 'Grep') {
+          return `Grep: ${input.pattern?.substring(0, 40)}`;
+        } else if (name === 'Glob') {
+          return `Glob: ${input.pattern}`;
+        } else {
+          return `${name}`;
+        }
+      }
+    }
+  }
+
+  if (msgType === 'checkpoint') {
+    if (msg.message?.content && Array.isArray(msg.message.content)) {
+      for (const block of msg.message.content) {
+        if (block.type === 'tool_use' && block.name === 'Bash') {
+          const cmd = block.input?.command || '';
+          const match = cmd.match(/session-recall\s+--checkpoint\s+["']([^"']+)["']/);
+          if (match) return `Checkpoint: "${match[1]}"`;
+        }
+      }
+    }
+  }
+
+  if (msgType === 'discourse') {
+    if (msg.type === 'user') {
+      const text = getUserText(msg);
+      return `User: ${text?.substring(0, 60) || '(empty)'}`;
+    } else {
+      const text = getAssistantText(msg);
+      return `Assistant: ${text?.substring(0, 60) || '(empty)'}`;
+    }
+  }
+
+  return '(unknown)';
+}
+
+// Get the tool_use ID from a message (for toolcall/agentcall)
+function getToolUseId(msg) {
+  if (msg.message?.content && Array.isArray(msg.message.content)) {
+    const toolUse = msg.message.content.find(c => c.type === 'tool_use');
+    if (toolUse) return toolUse.id;
+  }
+  return null;
+}
+
+// ========== --back PREVIEW COMMAND ==========
+
+function cmdBack(backN, filterType, opts) {
+  const dir = cwdToProjectFolder();
+  if (!dir) {
+    console.error(`No project folder found for CWD: ${process.cwd()}`);
+    process.exit(1);
+  }
+
+  // Get most recent session (INCLUDING active)
+  const jsonlFiles = fs.readdirSync(dir).filter(f => f.endsWith('.jsonl'));
+  if (jsonlFiles.length === 0) {
+    console.error('No sessions found');
+    process.exit(1);
+  }
+
+  // Sort by modification time to get most recent
+  const filesWithStats = jsonlFiles.map(f => {
+    const filePath = path.join(dir, f);
+    const stat = fs.statSync(filePath);
+    return { filePath, mtime: stat.mtime };
+  });
+  filesWithStats.sort((a, b) => b.mtime - a.mtime);
+
+  // Use the most recent session (even if active)
+  const session = filesWithStats[0];
+  const messages = readJsonl(session.filePath);
+
+  // Filter messages by type
+  const validTypes = ['toolcall', 'agentcall', 'discourse', 'checkpoint'];
+  if (filterType && !validTypes.includes(filterType)) {
+    console.error(`Invalid type: ${filterType}`);
+    console.error(`Valid types: ${validTypes.join(', ')}`);
+    process.exit(1);
+  }
+
+  // Classify all messages and filter
+  const classified = [];
+  for (const msg of messages) {
+    const msgType = classifyMessageType(msg);
+    if (msgType && (!filterType || msgType === filterType)) {
+      // Skip session-recall tag commands (they're toolcalls but shouldn't be counted)
+      if (msgType === 'toolcall' && msg.message?.content && Array.isArray(msg.message.content)) {
+        const toolUse = msg.message.content.find(c => c.type === 'tool_use');
+        if (toolUse && toolUse.name === 'Bash') {
+          const cmd = toolUse.input?.command || '';
+          if (cmd.match(/session-recall\s+tag\s+/)) continue;
+          if (cmd.match(/session-recall\s+--back\s+/)) continue;
+        }
+      }
+      classified.push({ msg, msgType });
+    }
+  }
+
+  if (classified.length === 0) {
+    console.error(`No ${filterType || 'messages'} found in session`);
+    process.exit(1);
+  }
+
+  // Count back N from end
+  const targetIndex = classified.length - backN;
+  if (targetIndex < 0) {
+    console.error(`Only ${classified.length} ${filterType || 'messages'} found, cannot go back ${backN}`);
+    process.exit(1);
+  }
+
+  const target = classified[targetIndex];
+  const toolId = getToolUseId(target.msg);
+  const uuid = toolId || target.msg.uuid || '(no uuid)';
+  const ts = target.msg.timestamp ? new Date(target.msg.timestamp).toISOString().substring(11, 19) : '??:??:??';
+  const preview = getMessagePreview(target.msg, target.msgType);
+
+  console.log(`UUID:     ${uuid}`);
+  console.log(`Type:     ${target.msgType}`);
+  console.log(`Time:     ${ts}`);
+  console.log(`Content:  ${preview}`);
+  console.log(``);
+  console.log(`To tag this: session-recall tag ${target.msgType}${backN > 1 ? ' --back ' + backN : ''} <level> "reason"`);
+}
+
+// ========== TAG COMMAND ==========
+
+function cmdTag(tagType, level, reason, backN, opts) {
+  const validTypes = ['toolcall', 'agentcall', 'discourse', 'checkpoint'];
+  const validLevels = ['critical', 'important', 'bookmark'];
+
+  if (!validTypes.includes(tagType)) {
+    console.error(`Invalid type: ${tagType}`);
+    console.error(`Valid types: ${validTypes.join(', ')}`);
+    process.exit(1);
+  }
+
+  if (!validLevels.includes(level)) {
+    console.error(`Invalid level: ${level}`);
+    console.error(`Valid levels: ${validLevels.join(', ')}`);
+    process.exit(1);
+  }
+
+  if (level === 'critical' && !reason) {
+    console.error(`Critical tags require a reason`);
+    process.exit(1);
+  }
+
+  const dir = cwdToProjectFolder();
+  if (!dir) {
+    console.error(`No project folder found for CWD: ${process.cwd()}`);
+    process.exit(1);
+  }
+
+  // Get most recent session (INCLUDING active - this is the current session)
+  const jsonlFiles = fs.readdirSync(dir).filter(f => f.endsWith('.jsonl'));
+  if (jsonlFiles.length === 0) {
+    console.error('No sessions found');
+    process.exit(1);
+  }
+
+  // Sort by modification time to get most recent
+  const filesWithStats = jsonlFiles.map(f => {
+    const filePath = path.join(dir, f);
+    const stat = fs.statSync(filePath);
+    return { filePath, mtime: stat.mtime };
+  });
+  filesWithStats.sort((a, b) => b.mtime - a.mtime);
+
+  // Use the most recent session
+  const session = filesWithStats[0];
+  const messages = readJsonl(session.filePath);
+
+  // Classify all messages and filter by type
+  const classified = [];
+  for (const msg of messages) {
+    const msgType = classifyMessageType(msg);
+    if (msgType === tagType) {
+      // Skip session-recall tag/back commands
+      if (msgType === 'toolcall' && msg.message?.content && Array.isArray(msg.message.content)) {
+        const toolUse = msg.message.content.find(c => c.type === 'tool_use');
+        if (toolUse && toolUse.name === 'Bash') {
+          const cmd = toolUse.input?.command || '';
+          if (cmd.match(/session-recall\s+tag\s+/)) continue;
+          if (cmd.match(/session-recall\s+--back\s+/)) continue;
+        }
+      }
+      classified.push({ msg, msgType });
+    }
+  }
+
+  if (classified.length === 0) {
+    console.error(`No ${tagType} found in session`);
+    process.exit(1);
+  }
+
+  // Count back N from end
+  const targetIndex = classified.length - backN;
+  if (targetIndex < 0) {
+    console.error(`Only ${classified.length} ${tagType} found, cannot go back ${backN}`);
+    process.exit(1);
+  }
+
+  const target = classified[targetIndex];
+  const toolId = getToolUseId(target.msg);
+  const uuid = toolId || target.msg.uuid || '(no uuid)';
+  const isoTimestamp = target.msg.timestamp ? new Date(target.msg.timestamp).toISOString().replace(/\.\d{3}Z$/, 'Z') : new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+
+  // Output marker format - this IS the tag storage (searched in tool_result)
+  // Format: @@SESSION-TAG@@ <type> <level> "<reason>" uuid=<uuid> ts=<timestamp>
+  console.log(`@@SESSION-TAG@@ ${tagType} ${level} "${reason || ''}" uuid=${uuid} ts=${isoTimestamp}`);
+}
+
+// ========== TAGS LISTING COMMAND ==========
+
+// Marker regex patterns for discovery (search tool_result content, not command strings)
+const TAG_MARKER_PATTERN = /@@SESSION-TAG@@\s+(\S+)\s+(\S+)\s+"([^"]*)"\s+uuid=(\S+)\s+ts=(\S+)/;
+// Groups: [1]=type, [2]=level, [3]=reason, [4]=uuid, [5]=timestamp
+
+// Scan a session for tags by searching tool_result content for @@SESSION-TAG@@ markers
+function scanSessionTags(filePath) {
+  const messages = readJsonl(filePath);
+  const tags = [];
+
+  for (const msg of messages) {
+    // Look for tag markers in tool_result content (user messages)
+    const resultContent = getToolResultContent(msg);
+    if (!resultContent) continue;
+
+    const match = resultContent.match(TAG_MARKER_PATTERN);
+    if (match) {
+      const tagType = match[1];
+      const level = match[2];
+      const reason = match[3];
+      const uuid = match[4];
+      const timestamp = match[5];
+
+      tags.push({
+        type: tagType,
+        level,
+        reason,
+        targetUuid: uuid,
+        targetTimestamp: timestamp,
+        tagTimestamp: msg.timestamp,
+        session: path.basename(filePath)
+      });
+    }
+  }
+
+  return tags;
+}
+
+function cmdTags(filterArg, opts) {
+  const dir = cwdToProjectFolder();
+  if (!dir) {
+    console.error(`No project folder found for CWD: ${process.cwd()}`);
+    process.exit(1);
+  }
+
+  const jsonlFiles = fs.readdirSync(dir).filter(f => f.endsWith('.jsonl'));
+  if (jsonlFiles.length === 0) {
+    console.error('No sessions found');
+    process.exit(1);
+  }
+
+  // Collect all tags from all sessions
+  const allTags = [];
+  for (const file of jsonlFiles) {
+    const filePath = path.join(dir, file);
+    const sessionTags = scanSessionTags(filePath);
+    allTags.push(...sessionTags);
+  }
+
+  // Apply filter if provided
+  let filteredTags = allTags;
+  const validTypes = ['toolcall', 'agentcall', 'discourse', 'checkpoint'];
+  const validLevels = ['critical', 'important', 'bookmark'];
+
+  if (filterArg) {
+    if (validTypes.includes(filterArg)) {
+      filteredTags = allTags.filter(t => t.type === filterArg);
+    } else if (validLevels.includes(filterArg)) {
+      filteredTags = allTags.filter(t => t.level === filterArg);
+    } else {
+      console.error(`Invalid filter: ${filterArg}`);
+      console.error(`Valid filters: ${[...validTypes, ...validLevels].join(', ')}`);
+      process.exit(1);
+    }
+  }
+
+  if (filteredTags.length === 0) {
+    console.log('No tags found.');
+    console.log('Create one with: session-recall tag <type> <level> "reason"');
+    return;
+  }
+
+  // Sort by target timestamp
+  filteredTags.sort((a, b) => new Date(a.targetTimestamp) - new Date(b.targetTimestamp));
+
+  console.log(`=== TAGS (${filteredTags.length} total) ===`);
+  console.log(``);
+  console.log(`TYPE        LEVEL      TIME      REASON`);
+  console.log(`────────────────────────────────────────────────────────────────────`);
+
+  for (const tag of filteredTags) {
+    const ts = tag.targetTimestamp ? new Date(tag.targetTimestamp).toISOString().substring(11, 19) : '??:??:??';
+    const typePad = tag.type.padEnd(10);
+    const levelPad = tag.level.padEnd(10);
+    const reason = tag.reason.substring(0, 40);
+    console.log(`${typePad}  ${levelPad}  ${ts}  ${reason}`);
+  }
+
+  console.log(``);
+  console.log(`Use: session-recall last 1 to see critical tags in context`);
+}
+
 // ========== ARGUMENT PARSING ==========
 
 function parseArgs(args) {
@@ -1272,8 +1799,24 @@ function parseArgs(args) {
       opts.checkpoint = args[++i];
     } else if (arg === '--after') {
       opts.after = args[++i];
+    } else if (arg === '--stopped_at') {
+      opts.stopped_at = args[++i];
+    } else if (arg === '--next') {
+      opts.next = args[++i];
+    } else if (arg === '--blocker') {
+      opts.blocker = args[++i];
+    } else if (arg === '--decision') {
+      opts.decision = args[++i];
+    } else if (arg === '--gotcha') {
+      opts.gotcha = args[++i];
+    } else if (arg === '--back') {
+      opts.back = parseInt(args[++i]);
+    } else if (arg === '--show-important') {
+      opts.showImportant = true;
     } else if (arg === '-h' || arg === '--help') {
       opts.help = true;
+    } else if (arg === '-v' || arg === '--version') {
+      opts.version = true;
     } else if (!arg.startsWith('-')) {
       positional.push(arg);
     }
@@ -1287,11 +1830,103 @@ function parseArgs(args) {
 const args = process.argv.slice(2);
 const { opts, positional } = parseArgs(args);
 
+// Handle --version flag
+if (opts.version) {
+  console.log(`session-recall v${VERSION}`);
+  process.exit(0);
+}
+
 // Handle --checkpoint flag first (no-op marker that gets logged)
 if (opts.checkpoint) {
-  console.log(`✓ Checkpoint: ${opts.checkpoint}`);
-  console.log(`  Time: ${new Date().toISOString()}`);
-  console.log(`  Use 'session-recall checkpoints' to list all checkpoints`);
+  // Output marker format - this IS the checkpoint storage (searched in tool_result)
+  // Format: @@SESSION-CHECKPOINT@@ "<name>" uuid="<uuid>" stopped_at="<val>" next="<val>" blocker="<val>" decision="<val>" gotcha="<val>" ts=<timestamp>
+  const isoTimestamp = new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+
+  // Detect current session UUID by finding most recently modified .jsonl
+  let currentUuid = 'unknown';
+  const claudeProjectsDir = path.join(process.env.HOME, '.claude', 'projects');
+  if (fs.existsSync(claudeProjectsDir)) {
+    let newestFile = null;
+    let newestTime = 0;
+    const scanDir = (dir) => {
+      try {
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+          const fullPath = path.join(dir, entry.name);
+          if (entry.isDirectory()) {
+            scanDir(fullPath);
+          } else if (entry.name.endsWith('.jsonl')) {
+            const stat = fs.statSync(fullPath);
+            if (stat.mtimeMs > newestTime) {
+              newestTime = stat.mtimeMs;
+              newestFile = entry.name;
+            }
+          }
+        }
+      } catch (e) { /* ignore permission errors */ }
+    };
+    scanDir(claudeProjectsDir);
+    if (newestFile) {
+      currentUuid = newestFile.replace('.jsonl', '');
+    }
+  }
+
+  let marker = `@@SESSION-CHECKPOINT@@ "${opts.checkpoint}" uuid="${currentUuid}"`;
+  if (opts.stopped_at) marker += ` stopped_at="${opts.stopped_at}"`;
+  if (opts.next) marker += ` next="${opts.next}"`;
+  if (opts.blocker) marker += ` blocker="${opts.blocker}"`;
+  if (opts.decision) marker += ` decision="${opts.decision}"`;
+  if (opts.gotcha) marker += ` gotcha="${opts.gotcha}"`;
+  marker += ` ts=${isoTimestamp}`;
+  console.log(marker);
+  process.exit(0);
+}
+
+// Handle 'tag' command: session-recall tag <type> [--back N] <level> "reason"
+// Must come before --back handler since tag command can have --back option
+if (positional[0] === 'tag') {
+  // Parse tag command arguments
+  // Format: tag <type> [--back N] <level> "reason"
+  // Note: --back is parsed by parseArgs into opts.back
+  const tagArgs = positional.slice(1);
+  let tagType = null;
+  let level = null;
+  let reason = null;
+  let backN = opts.back || 1;  // Use opts.back if available
+
+  for (let i = 0; i < tagArgs.length; i++) {
+    const arg = tagArgs[i];
+    if (!tagType) {
+      tagType = arg;
+    } else if (!level) {
+      level = arg;
+    } else if (!reason) {
+      reason = arg;
+    }
+  }
+
+  if (!tagType || !level) {
+    console.error('Usage: session-recall tag <type> [--back N] <level> "reason"');
+    console.error('Types: toolcall, agentcall, discourse, checkpoint');
+    console.error('Levels: critical, important, bookmark');
+    process.exit(1);
+  }
+
+  cmdTag(tagType, level, reason, backN, opts);
+  process.exit(0);
+}
+
+// Handle 'tags' command: session-recall tags [filter]
+if (positional[0] === 'tags') {
+  const filterArg = positional[1] || null;
+  cmdTags(filterArg, opts);
+  process.exit(0);
+}
+
+// Handle --back N [type] preview command
+if (opts.back) {
+  const filterType = positional[0] || null;
+  cmdBack(opts.back, filterType, opts);
   process.exit(0);
 }