@aiplumber/session-recall 1.6.8 → 1.8.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiplumber/session-recall",
-  "version": "1.6.8",
+  "version": "1.8.4",
   "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,6 +1,6 @@
 #!/usr/bin/env node
 
-const VERSION = '1.6.8';
+const VERSION = '1.8.4';
 
 const fs = require('fs');
 const path = require('path');
@@ -14,6 +14,10 @@ const NOISE_TYPES = ['progress', 'file-history-snapshot', 'system', 'queue-opera
 const MAX_USER_MSG_LENGTH = 200;
 const ACTIVE_SESSION_THRESHOLD_MS = 60000; // Sessions with activity in last 60s are "active"
 
+// Compaction detection constants
+const COMPACTION_DEDUP_WINDOW_MS = 120000; // 120 seconds - markers within this window are same event
+const COMPACTION_DEDUP_MAX_MESSAGES = 5; // Max discourse messages between markers to be same event
+
 // Token estimation (~4 chars per token for English, conservative)
 function estimateTokens(text) {
   if (!text) return 0;
@@ -29,6 +33,12 @@ const MARKERS = {
   decision: /^[A-D](,\s*[A-D])*$/i
 };
 
+// Tangent marker patterns
+const TANGENT_START_PATTERN = /@@SESSION-TANGENT-START@@\s+"([^"]*)"\s+uuid=(\S+)\s+ts=(\S+)/;
+// Groups: [1]=label, [2]=uuid, [3]=timestamp
+const TANGENT_END_PATTERN = /@@SESSION-TANGENT-END@@\s+start_uuid=(\S+)\s+end_uuid=(\S+)\s+ts=(\S+)/;
+// Groups: [1]=start_uuid, [2]=end_uuid, [3]=timestamp
+
 function readJsonl(filePath) {
   const content = fs.readFileSync(filePath, 'utf-8');
   return content.trim().split('\n').map((line) => {
@@ -1076,6 +1086,10 @@ function cmdLast(arg1, arg2, opts) {
     filterAfterTs = checkpoint.msgTimestamp ? new Date(checkpoint.msgTimestamp).getTime() : new Date(checkpoint.timestamp).getTime();
   }
 
+  // If --before-compaction is specified, we'll find the most recent compaction and filter before it
+  // This variable will be set later after we load the session messages
+  let filterBeforeCompactionLine = null;
+
   // Helper: get session start timestamp from first line of jsonl
   function getSessionStartTs(filePath) {
     try {
@@ -1146,12 +1160,18 @@ function cmdLast(arg1, arg2, opts) {
 
   // Exclude currently active sessions (activity within threshold)
   const now = Date.now();
-  const inactiveSessions = allSessions.slice(0, candidateCount).filter(s => {
+  let 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;
   });
 
+  // Issue 001 fix: If only 1 session exists and it's active, include it anyway
+  // This handles post-compaction recall where you want your own session
+  if (inactiveSessions.length === 0 && allSessions.length > 0) {
+    inactiveSessions = allSessions.slice(0, n);
+  }
+
   // Take last N from inactive sessions
   const selected = inactiveSessions.slice(0, n);
 
@@ -1160,6 +1180,197 @@ function cmdLast(arg1, arg2, opts) {
     process.exit(1);
   }
 
+  // Handle --compactions mode: show last N compaction phases instead of sessions
+  if (opts.compactionPhases) {
+    const session = selected[0];  // Use only the most recent session
+    const compactions = scanCompactionMarkers(session.msgs);
+
+    if (compactions.length === 0) {
+      console.log('[session-recall v' + VERSION + '] No compaction events found - showing full session as single phase');
+      console.log('---');
+      // Fall through to normal processing for full session
+    } else {
+      // Determine which phases to show
+      const phasesToShow = Math.min(n, compactions.length + 1);  // +1 for current phase after last compaction
+      const startPhaseNum = Math.max(1, compactions.length + 2 - phasesToShow);
+
+      // Print header
+      console.log(`[session-recall v${VERSION}] Showing last ${phasesToShow} compaction phase${phasesToShow === 1 ? '' : 's'}`);
+      console.log('---');
+
+      // Calculate phase boundaries
+      // Phase 1: session start → compaction #1
+      // Phase i: compaction #(i-1) → compaction #i
+      // Phase N: last compaction → now (current session end)
+
+      const sessionMsgs = session.msgs.slice().sort((a, b) => new Date(a.timestamp || 0) - new Date(b.timestamp || 0));
+      const sessionStartTs = sessionMsgs.length > 0 && sessionMsgs[0].timestamp ? new Date(sessionMsgs[0].timestamp).getTime() : 0;
+      const sessionEndTs = sessionMsgs.length > 0 && sessionMsgs[sessionMsgs.length - 1].timestamp ? new Date(sessionMsgs[sessionMsgs.length - 1].timestamp).getTime() : Date.now();
+
+      // Build phase data for each phase to display
+      const phases = [];
+      for (let phaseNum = startPhaseNum; phaseNum <= compactions.length + 1; phaseNum++) {
+        const phaseMsgs = [];
+        let phaseStartTs, phaseEndTs;
+
+        if (phaseNum === 1) {
+          // Phase 1: session start to compaction #1
+          phaseStartTs = sessionStartTs;
+          phaseEndTs = compactions[0].timestampMs;
+        } else if (phaseNum <= compactions.length) {
+          // Phase i: compaction #(i-1) to compaction #i
+          phaseStartTs = compactions[phaseNum - 2].timestampMs;
+          phaseEndTs = compactions[phaseNum - 1].timestampMs;
+        } else {
+          // Current phase: after last compaction to now
+          phaseStartTs = compactions[compactions.length - 1].timestampMs;
+          phaseEndTs = sessionEndTs;
+        }
+
+        // Filter messages for this phase
+        for (const msg of sessionMsgs) {
+          const msgTs = msg.timestamp ? new Date(msg.timestamp).getTime() : 0;
+          if (msgTs >= phaseStartTs && msgTs < phaseEndTs) {
+            phaseMsgs.push(msg);
+          }
+        }
+
+        // For the current phase, include messages at endTs too
+        if (phaseNum === compactions.length + 1) {
+          for (const msg of sessionMsgs) {
+            const msgTs = msg.timestamp ? new Date(msg.timestamp).getTime() : 0;
+            if (msgTs === phaseEndTs && !phaseMsgs.includes(msg)) {
+              phaseMsgs.push(msg);
+            }
+          }
+        }
+
+        const startTime = new Date(phaseStartTs).toISOString().substring(11, 19);
+        const endTime = new Date(phaseEndTs).toISOString().substring(11, 19);
+
+        phases.push({
+          number: phaseNum,
+          startTime,
+          endTime,
+          messages: phaseMsgs,
+          messageCount: phaseMsgs.length
+        });
+      }
+
+      // Output each phase with separator
+      const outputLines = [];
+      function addOutput(line = '') {
+        outputLines.push(line);
+      }
+
+      for (const phase of phases) {
+        addOutput(`=== COMPACTION PHASE #${phase.number} (${phase.startTime} - ${phase.endTime}) - ${phase.messageCount} messages ===`);
+        addOutput('');
+
+        // 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
+            };
+          }
+        }
+
+        // Process messages for this phase
+        for (const msg of phase.messages) {
+          if (NOISE_TYPES.includes(msg.type)) continue;
+
+          const toolId = getToolUseId(msg);
+          const msgUuid = toolId || msg.uuid;
+          const tag = msgUuid ? tagMap[msgUuid] : null;
+          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';
+                addOutput(`[${ts}] ${marker} ${tag.level.toUpperCase()} [${tag.type}] USER: ${text.substring(0, 500)}`);
+                addOutput(`         Reason: "${tag.reason}"`);
+              } else {
+                addOutput(`[${ts}] USER: ${text.substring(0, 500)}`);
+              }
+            }
+          } else if (msg.type === 'assistant') {
+            const text = getAssistantText(msg);
+            const resultMeta = buildToolResultMeta(phase.messages);
+            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) {
+                addOutput(`[${ts}] ${marker} ${tag.level.toUpperCase()} [${tag.type}] ASSISTANT: ${text.substring(0, 500)}`);
+              } else if (toolSummary) {
+                addOutput(`[${ts}] ${marker} ${tag.level.toUpperCase()} [${tag.type}] ${toolSummary}`);
+              }
+              addOutput(`         Reason: "${tag.reason}"`);
+            } else {
+              if (text) {
+                addOutput(`[${ts}] ASSISTANT: ${text.substring(0, 500)}`);
+              } else if (toolSummary) {
+                addOutput(`[${ts}] ASSISTANT: ${toolSummary}`);
+              }
+            }
+          }
+        }
+
+        addOutput('');
+      }
+
+      // Calculate token metrics
+      let rawTokens = 0;
+      for (const msg of sessionMsgs) {
+        if (msg.message?.content) {
+          const content = msg.message.content;
+          if (typeof content === 'string') {
+            rawTokens += estimateTokens({length: content.length});
+          } else if (Array.isArray(content)) {
+            for (const block of content) {
+              if (block.text) {
+                rawTokens += estimateTokens({length: block.text.length});
+              }
+            }
+          }
+        }
+      }
+
+      const filteredTokenChars = outputLines.reduce((sum, line) => sum + line.length, 0);
+      const returnedTokens = estimateTokens({length: filteredTokenChars});
+      const filteredTokens = Math.max(0, rawTokens - returnedTokens);
+      const compressionPct = rawTokens > 0 ? Math.round((filteredTokens / rawTokens) * 100) : 0;
+
+      const returnedK = Math.round(returnedTokens / 1000);
+      const filteredK = Math.round(filteredTokens / 1000);
+
+      // Print metrics
+      console.log(`Returned: ~${returnedK}k tokens | Filtered: ~${filteredK}k tokens (${compressionPct}% compression)`);
+      console.log(`---`);
+
+      // Print collected output
+      for (const line of outputLines) {
+        console.log(line);
+      }
+
+      console.log('');
+      console.log('---');
+      console.log(`Session file: ${session.filePath}`);
+
+      return;  // Exit after compaction phases output
+    }
+  }
+
   // Count excluded active sessions for reporting (only from candidates we checked)
   const excludedActive = candidateCount - inactiveSessions.length;
 
@@ -1185,6 +1396,25 @@ function cmdLast(arg1, arg2, opts) {
         return msgTs > filterAfterTs;
       });
     }
+    // Apply before-compaction filter for dry-run
+    if (opts.beforeCompaction && selected.length > 0) {
+      const compactions = scanCompactionMarkers(selected[0].msgs);
+      if (compactions.length > 0) {
+        const n = opts.beforeCompactionN || compactions.length;
+        if (n < 1 || n > compactions.length) {
+          console.error(`Error: Compaction #${n} not found. Available: 1-${compactions.length}`);
+          process.exit(1);
+        }
+        const targetCompaction = compactions[n - 1];  // 1-indexed to 0-indexed
+        const compactionTs = targetCompaction.timestampMs;
+        allMsgs = allMsgs.filter(msg => {
+          const msgTs = msg.timestamp ? new Date(msg.timestamp).getTime() : 0;
+          return msgTs < compactionTs;
+        });
+        const compactionTime = new Date(compactionTs).toISOString().substring(11, 19);
+        console.log(`(Filtering to content BEFORE compaction #${n} @ ${compactionTime})`);
+      }
+    }
     const output = [];
     for (const msg of allMsgs) {
       if (NOISE_TYPES.includes(msg.type)) continue;
@@ -1205,9 +1435,32 @@ function cmdLast(arg1, arg2, opts) {
     return;
   }
 
-  // Print header
-  console.log(`[session-recall v${VERSION}] This context has been stripped of most tool results to reduce noise.`);
-  console.log(`---`);
+  // Calculate metrics before filtering
+  let rawTokens = 0;
+  for (const session of selected) {
+    for (const msg of session.msgs) {
+      if (msg.message?.content) {
+        const content = msg.message.content;
+        if (typeof content === 'string') {
+          rawTokens += estimateTokens({length: content.length});
+        } else if (Array.isArray(content)) {
+          for (const block of content) {
+            if (block.text) {
+              rawTokens += estimateTokens({length: block.text.length});
+            }
+          }
+        }
+      }
+    }
+  }
+
+  // Collect output lines to calculate metrics
+  const outputLines = [];
+
+  // Helper to add to output
+  function addOutput(line = '') {
+    outputLines.push(line);
+  }
 
   // Process each session separately to add separators
   for (let sessionIdx = 0; sessionIdx < selected.length; sessionIdx++) {
@@ -1225,6 +1478,35 @@ function cmdLast(arg1, arg2, opts) {
       });
     }
 
+    // Filter to only show messages BEFORE the selected compaction boundary
+    if (opts.beforeCompaction) {
+      const compactions = scanCompactionMarkers(session.msgs);
+      if (compactions.length > 0) {
+        const n = opts.beforeCompactionN || compactions.length;
+        if (n < 1 || n > compactions.length) {
+          console.error(`Error: Compaction #${n} not found. Available: 1-${compactions.length}`);
+          process.exit(1);
+        }
+        // Get the selected compaction (1-indexed to 0-indexed)
+        const targetCompaction = compactions[n - 1];
+        const compactionTs = targetCompaction.timestampMs;
+
+        // Filter to messages BEFORE the compaction
+        sessionMsgs = sessionMsgs.filter(msg => {
+          const msgTs = msg.timestamp ? new Date(msg.timestamp).getTime() : 0;
+          return msgTs < compactionTs;
+        });
+
+        // Print a notice about what we're showing
+        const compactionTime = new Date(compactionTs).toISOString().substring(11, 19);
+        addOutput(`[BEFORE COMPACTION #${n} @ ${compactionTime}]`);
+        addOutput(``);
+      } else {
+        addOutput(`[No compaction events found - showing all content]`);
+        addOutput(``);
+      }
+    }
+
     // Build tool result metadata (size, duration)
     const resultMeta = buildToolResultMeta(sessionMsgs);
 
@@ -1241,6 +1523,38 @@ function cmdLast(arg1, arg2, opts) {
       }
     }
 
+    // Scan for tangents if needed for filtering
+    let tangents = [];
+    if (opts.noTangents || opts.tangentsOnly) {
+      tangents = scanSessionTangents(session.filePath);
+    }
+
+    // Build tangent boundaries map for filtering
+    const tangentRanges = [];
+    for (const tangent of tangents) {
+      if (tangent.endUuid) {
+        tangentRanges.push({
+          label: tangent.label,
+          startUuid: tangent.startUuid,
+          endUuid: tangent.endUuid,
+          unclosed: false
+        });
+      }
+    }
+
+    // Check if message UUID falls within any tangent range
+    function isInTangent(msgUuid) {
+      if (!msgUuid) return false;
+      for (const range of tangentRanges) {
+        if (msgUuid === range.startUuid || msgUuid === range.endUuid) return true;
+        // Note: For full range checking, we'd need to track message order
+      }
+      return false;
+    }
+
+    let inTangentRange = null;
+    let tangentMessageCount = 0;
+
     for (const msg of sessionMsgs) {
       if (NOISE_TYPES.includes(msg.type)) continue;
 
@@ -1255,6 +1569,34 @@ function cmdLast(arg1, arg2, opts) {
         (tag.level === 'important' && opts.showImportant)
       );
 
+      // Check tangent boundaries
+      if (opts.noTangents || opts.tangentsOnly) {
+        for (const range of tangentRanges) {
+          if (msgUuid === range.startUuid) {
+            inTangentRange = range;
+            tangentMessageCount = 0;
+          }
+          if (msgUuid === range.endUuid) {
+            if (opts.noTangents && inTangentRange) {
+              addOutput(`=== TANGENT: "${inTangentRange.label}" (skipped ${tangentMessageCount} messages) ===`);
+            }
+            inTangentRange = null;
+            tangentMessageCount = 0;
+            continue;
+          }
+        }
+      }
+
+      // Apply tangent filtering
+      const inTangent = inTangentRange !== null;
+      if (opts.noTangents && inTangent) {
+        tangentMessageCount++;
+        continue;
+      }
+      if (opts.tangentsOnly && !inTangent) {
+        continue;
+      }
+
       if (msg.type === 'user') {
         if (isToolResult(msg)) continue;
         const text = getUserText(msg);
@@ -1262,10 +1604,10 @@ function cmdLast(arg1, arg2, opts) {
           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}"`);
+            addOutput(`[${ts}] ${marker} ${tag.level.toUpperCase()} [${tag.type}] USER: ${text.substring(0, 500)}`);
+            addOutput(`         Reason: "${tag.reason}"`);
           } else {
-            console.log(`[${ts}] USER: ${text.substring(0, 500)}`);
+            addOutput(`[${ts}] USER: ${text.substring(0, 500)}`);
           }
         }
       } else if (msg.type === 'assistant') {
@@ -1276,29 +1618,59 @@ function cmdLast(arg1, arg2, opts) {
         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)}`);
+            addOutput(`[${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}`);
+            addOutput(`[${ts}] ${marker} ${tag.level.toUpperCase()} [${tag.type}] ${toolSummary}`);
           }
-          console.log(`         Reason: "${tag.reason}"`);
+          addOutput(`         Reason: "${tag.reason}"`);
         } else {
           if (text) {
-            console.log(`[${ts}] ASSISTANT: ${text.substring(0, 500)}`);
+            addOutput(`[${ts}] ASSISTANT: ${text.substring(0, 500)}`);
           } else if (toolSummary) {
-            console.log(`[${ts}] ASSISTANT: ${toolSummary}`);
+            addOutput(`[${ts}] ASSISTANT: ${toolSummary}`);
           }
         }
       }
     }
 
+    // Warn if tangent was unclosed
+    for (const tangent of tangents) {
+      if (tangent.unclosed) {
+        addOutput(``);
+        addOutput(`[session-recall] Warning: Tangent "${tangent.label}" was never closed.`);
+        addOutput(`Treating remaining messages as regular conversation.`);
+      }
+    }
+
     // 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`);
+      addOutput(`\n=== END SESSION ${sessionIdx + 1} === NEXT SESSION: ${nextSession.project} (${nextTs}) ===\n`);
     }
   }
 
+  // Calculate filtered tokens and compression
+  const filteredTokenChars = outputLines.reduce((sum, line) => sum + line.length, 0);
+  const returnedTokens = estimateTokens({length: filteredTokenChars});
+  const filteredTokens = Math.max(0, rawTokens - returnedTokens);
+  const compressionPct = rawTokens > 0 ? Math.round((filteredTokens / rawTokens) * 100) : 0;
+
+  // Format as k tokens with rounding
+  const returnedK = Math.round(returnedTokens / 1000);
+  const filteredK = Math.round(filteredTokens / 1000);
+
+  // Print header with metrics
+  console.log(`[session-recall v${VERSION}] This context has been stripped of most tool results to reduce noise.`);
+  console.log(`Returned: ~${returnedK}k tokens | Filtered: ~${filteredK}k tokens (${compressionPct}% compression)`);
+  console.log(`DO NOT read raw session files - this IS the context you need.`);
+  console.log(`---`);
+
+  // Print collected output
+  for (const line of outputLines) {
+    console.log(line);
+  }
+
   // Print instructions for Claude
   console.log(``);
   console.log(`---`);
@@ -1338,6 +1710,11 @@ COMMANDS:
     -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
+    --before-compaction [N]  Return content BEFORE compaction #N (default: most recent)
+    --compactions            Show last N compaction phases (not sessions)
+
+  compactions <jsonl>        List compaction events (context window resets)
+                             Deduplicates retry markers into single events
 
   tools                      List tool calls in most recent session (CWD project)
     --show <id>              Show specific tool result by ID (partial match)
@@ -1354,6 +1731,19 @@ COMMANDS:
 
   last [N] --after "name"    Recall from after a checkpoint
 
+TANGENTS:
+  --tangent-start "label"    Start marking a tangent in real-time
+    [--back N]               Or mark retroactively N positions back
+
+  --tangent-end              End the current tangent
+    [--back N]               Or end retroactively N positions back
+
+  tangent-start [--back N] "label"  Alternative syntax for tangent-start
+  tangent-end [--back N]            Alternative syntax for tangent-end
+
+  last [N] --no-tangents     Show session, skip tangent-tagged content
+  last [N] --tangents-only   Show only messages inside tangents
+
 TAGGING:
   --back N [type]            Preview message N positions back (for tagging)
                              Types: toolcall, agentcall, discourse, checkpoint
@@ -1391,6 +1781,17 @@ EXAMPLES:
   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
+
+  # Compaction detection - find context window resets
+  session-recall compactions session.jsonl          # List all compaction events
+  session-recall last 1 --before-compaction         # Recall pre-compaction content
+  session-recall last 3 --compactions               # Last 3 compaction phases with separators
+
+  # Tangents - mark side explorations
+  session-recall --tangent-start "session-recall compaction feature"  # Mark tangent start
+  session-recall --tangent-end                                       # Mark tangent end
+  session-recall last 1 --no-tangents                                # Skip tangent content
+  session-recall last 1 --tangents-only                              # Show only tangents
 `);
 }
 
@@ -1772,6 +2173,353 @@ function cmdTags(filterArg, opts) {
   console.log(`Use: session-recall last 1 to see critical tags in context`);
 }
 
+// ========== TANGENT SCANNING ==========
+
+// Scan a session for tangent markers by searching tool_result content
+function scanSessionTangents(filePath) {
+  const messages = readJsonl(filePath);
+  const tangents = [];
+  const openTangents = [];
+
+  for (const msg of messages) {
+    const resultContent = getToolResultContent(msg);
+    if (!resultContent) continue;
+
+    const startMatch = resultContent.match(TANGENT_START_PATTERN);
+    if (startMatch) {
+      const label = startMatch[1];
+      const uuid = startMatch[2];
+      const timestamp = startMatch[3];
+
+      // Skip placeholder patterns from documentation (e.g., uuid=<uuid>)
+      if (uuid.includes('<') || uuid.includes('>')) continue;
+
+      openTangents.push({
+        label,
+        startUuid: uuid,
+        startTimestamp: timestamp,
+        msgTimestamp: msg.timestamp
+      });
+      continue;
+    }
+
+    const endMatch = resultContent.match(TANGENT_END_PATTERN);
+    if (endMatch) {
+      const startUuid = endMatch[1];
+      const endUuid = endMatch[2];
+      const timestamp = endMatch[3];
+
+      // Skip placeholder patterns from documentation
+      if (startUuid.includes('<') || startUuid.includes('>')) continue;
+      if (endUuid.includes('<') || endUuid.includes('>')) continue;
+
+      if (openTangents.length > 0) {
+        const openTangent = openTangents.pop();
+        tangents.push({
+          label: openTangent.label,
+          startUuid: openTangent.startUuid,
+          endUuid: endUuid,
+          startTimestamp: openTangent.startTimestamp,
+          endTimestamp: timestamp,
+          tagTimestamp: msg.timestamp
+        });
+      }
+      continue;
+    }
+  }
+
+  // Handle unclosed tangents - add them as warnings
+  for (const open of openTangents) {
+    tangents.push({
+      label: open.label,
+      startUuid: open.startUuid,
+      endUuid: null,
+      startTimestamp: open.startTimestamp,
+      endTimestamp: null,
+      tagTimestamp: open.msgTimestamp,
+      unclosed: true
+    });
+  }
+
+  return tangents;
+}
+
+// ========== COMPACTION DETECTION ==========
+
+// Check if a message is a compaction marker
+function isCompactionMarker(msg) {
+  if (msg.type !== 'progress') return false;
+  if (!msg.data) return false;
+  return msg.data.type === 'hook_progress' &&
+         msg.data.hookEvent === 'SessionStart' &&
+         msg.data.hookName === 'SessionStart:compact';
+}
+
+// Scan session for compaction markers with deduplication
+// Returns array of compaction events with { timestamp, line, retries, messagesAfter }
+function scanCompactionMarkers(messages) {
+  const markers = [];
+
+  // First pass: collect all raw markers with line numbers
+  for (let i = 0; i < messages.length; i++) {
+    const msg = messages[i];
+    if (isCompactionMarker(msg)) {
+      markers.push({
+        line: i + 1,  // 1-indexed line number
+        timestamp: msg.timestamp,
+        timestampMs: msg.timestamp ? new Date(msg.timestamp).getTime() : 0
+      });
+    }
+  }
+
+  if (markers.length === 0) return [];
+
+  // Second pass: deduplicate markers into compaction events
+  // Markers are same event if within COMPACTION_DEDUP_WINDOW_MS AND fewer than COMPACTION_DEDUP_MAX_MESSAGES between them
+  const compactions = [];
+  let currentCluster = [markers[0]];
+
+  for (let i = 1; i < markers.length; i++) {
+    const prev = currentCluster[currentCluster.length - 1];
+    const curr = markers[i];
+
+    const timeGapMs = curr.timestampMs - prev.timestampMs;
+
+    // Count discourse messages between prev and curr markers
+    const prevLine = prev.line - 1;  // Convert to 0-indexed
+    const currLine = curr.line - 1;
+    let discourseCount = 0;
+    for (let j = prevLine + 1; j < currLine; j++) {
+      if (isDiscourse(messages[j])) {
+        discourseCount++;
+      }
+    }
+
+    // If within time window AND few discourse messages, same cluster
+    if (timeGapMs <= COMPACTION_DEDUP_WINDOW_MS && discourseCount < COMPACTION_DEDUP_MAX_MESSAGES) {
+      currentCluster.push(curr);
+    } else {
+      // New cluster - finalize previous one
+      compactions.push(finalizeCluster(currentCluster, messages));
+      currentCluster = [curr];
+    }
+  }
+
+  // Finalize last cluster
+  compactions.push(finalizeCluster(currentCluster, messages));
+
+  return compactions;
+}
+
+// Convert a cluster of markers into a single compaction event
+function finalizeCluster(cluster, messages) {
+  const first = cluster[0];
+  const retries = cluster.length - 1;
+
+  // Count messages (total raw messages, not just discourse) after this compaction
+  // until end of file or next compaction marker
+  let messagesAfter = 0;
+  const startLine = first.line;  // 1-indexed
+  for (let i = startLine; i < messages.length; i++) {
+    // Stop at next compaction marker
+    if (isCompactionMarker(messages[i])) break;
+    messagesAfter++;
+  }
+
+  return {
+    timestamp: first.timestamp,
+    timestampMs: first.timestampMs,
+    line: first.line,
+    retries: retries,
+    messagesAfter: messagesAfter
+  };
+}
+
+// cmdCompactions: List compaction events in a JSONL file
+function cmdCompactions(jsonlPath, opts) {
+  // Auto-detect if no path provided
+  if (!jsonlPath) {
+    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);
+    }
+
+    // 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);
+    jsonlPath = filesWithStats[0].filePath;
+  }
+
+  const messages = readJsonl(jsonlPath);
+  const compactions = scanCompactionMarkers(messages);
+
+  if (compactions.length === 0) {
+    console.log('No compaction events found.');
+    return;
+  }
+
+  console.log(`=== COMPACTION EVENTS (${compactions.length} total) ===`);
+  console.log(`Source: ${path.basename(jsonlPath)}`);
+  console.log(``);
+
+  for (let i = 0; i < compactions.length; i++) {
+    const c = compactions[i];
+    const ts = c.timestamp ? new Date(c.timestamp).toISOString().substring(11, 19) : '??:??:??';
+    const retryInfo = c.retries > 0 ? `, +${c.retries} retries` : '';
+
+    console.log(`Compaction #${i + 1} @ ${ts} (line ${c.line}${retryInfo})`);
+    console.log(`  Messages after: ${c.messagesAfter}`);
+    console.log(``);
+  }
+
+  // Usage hint
+  console.log(`Use: session-recall last 1 --before-compaction to recall pre-compaction content`);
+}
+
+// ========== TANGENT COMMANDS ==========
+
+function cmdTangentStart(label, backN, 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 - 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);
+
+  const session = filesWithStats[0];
+  const messages = readJsonl(session.filePath);
+
+  // Check for existing open tangent
+  const tangents = scanSessionTangents(session.filePath);
+  const openTangent = tangents.find(t => t.unclosed);
+  if (openTangent) {
+    console.error(`Error: You're already in a tangent ("${openTangent.label}").`);
+    console.error(`Your biological brain is not ready for nested tangents.`);
+    console.error(`Close current tangent first with: session-recall --tangent-end`);
+    process.exit(1);
+  }
+
+  // Classify all messages and filter by discourse
+  const discourseMessages = [];
+  for (const msg of messages) {
+    const msgType = classifyMessageType(msg);
+    if (msgType === 'discourse') {
+      discourseMessages.push(msg);
+    }
+  }
+
+  // If --back N is specified, find the Nth discourse message back; otherwise use next message
+  let targetUuid = null;
+  if (backN && backN > 1) {
+    const targetIndex = discourseMessages.length - backN;
+    if (targetIndex < 0) {
+      console.error(`Only ${discourseMessages.length} discourse messages found, cannot go back ${backN}`);
+      process.exit(1);
+    }
+    const targetMsg = discourseMessages[targetIndex];
+    targetUuid = targetMsg.uuid || '(no uuid)';
+  } else {
+    // Use a UUID for the marker (generate one or use most recent)
+    const uuid = require('crypto').randomUUID();
+    targetUuid = uuid;
+  }
+
+  const isoTimestamp = new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+
+  // Output marker format
+  console.log(`@@SESSION-TANGENT-START@@ "${label}" uuid=${targetUuid} ts=${isoTimestamp}`);
+}
+
+function cmdTangentEnd(backN, 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);
+
+  const session = filesWithStats[0];
+  const messages = readJsonl(session.filePath);
+
+  // Check for open tangent
+  const tangents = scanSessionTangents(session.filePath);
+  const openTangent = tangents.find(t => t.unclosed);
+  if (!openTangent) {
+    console.error(`Error: No open tangent to close.`);
+    console.error(`Start one with: session-recall --tangent-start "label"`);
+    process.exit(1);
+  }
+
+  // Classify all messages and filter by discourse
+  const discourseMessages = [];
+  for (const msg of messages) {
+    const msgType = classifyMessageType(msg);
+    if (msgType === 'discourse') {
+      discourseMessages.push(msg);
+    }
+  }
+
+  // Determine end UUID
+  let endUuid;
+  if (backN && backN > 1) {
+    const targetIndex = discourseMessages.length - backN;
+    if (targetIndex < 0) {
+      console.error(`Only ${discourseMessages.length} discourse messages found, cannot go back ${backN}`);
+      process.exit(1);
+    }
+    const targetMsg = discourseMessages[targetIndex];
+    endUuid = targetMsg.uuid || '(no uuid)';
+  } else {
+    // Use a UUID for the end marker (generate one)
+    const uuid = require('crypto').randomUUID();
+    endUuid = uuid;
+  }
+
+  const isoTimestamp = new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+
+  // Output marker format
+  console.log(`@@SESSION-TANGENT-END@@ start_uuid=${openTangent.startUuid} end_uuid=${endUuid} ts=${isoTimestamp}`);
+}
+
 // ========== ARGUMENT PARSING ==========
 
 function parseArgs(args) {
@@ -1816,6 +2564,23 @@ function parseArgs(args) {
       opts.back = parseInt(args[++i]);
     } else if (arg === '--show-important') {
       opts.showImportant = true;
+    } else if (arg === '--before-compaction') {
+      opts.beforeCompaction = true;
+      // Check if next arg is a number (not another flag)
+      if (i + 1 < args.length && /^\d+$/.test(args[i + 1])) {
+        opts.beforeCompactionN = parseInt(args[i + 1], 10);
+        i++;  // Skip the number in iteration
+      }
+    } else if (arg === '--compactions') {
+      opts.compactionPhases = true;
+    } else if (arg === '--tangent-start') {
+      opts.tangentStart = args[++i];
+    } else if (arg === '--tangent-end') {
+      opts.tangentEnd = true;
+    } else if (arg === '--no-tangents') {
+      opts.noTangents = true;
+    } else if (arg === '--tangents-only') {
+      opts.tangentsOnly = true;
     } else if (arg === '-h' || arg === '--help') {
       opts.help = true;
     } else if (arg === '-v' || arg === '--version') {
@@ -1885,6 +2650,40 @@ if (opts.checkpoint) {
   process.exit(0);
 }
 
+// Handle --tangent-start flag
+if (opts.tangentStart) {
+  const label = opts.tangentStart;
+  const backN = opts.back || 1;
+  cmdTangentStart(label, backN, opts);
+  process.exit(0);
+}
+
+// Handle --tangent-end flag
+if (opts.tangentEnd) {
+  const backN = opts.back || 1;
+  cmdTangentEnd(backN, opts);
+  process.exit(0);
+}
+
+// Handle 'tangent-start' command: session-recall tangent-start [--back N] "label"
+if (positional[0] === 'tangent-start') {
+  const label = opts.tangentStart || positional[1];
+  if (!label) {
+    console.error('Usage: session-recall tangent-start [--back N] "label"');
+    process.exit(1);
+  }
+  const backN = opts.back || 1;
+  cmdTangentStart(label, backN, opts);
+  process.exit(0);
+}
+
+// Handle 'tangent-end' command: session-recall tangent-end [--back N]
+if (positional[0] === 'tangent-end') {
+  const backN = opts.back || 1;
+  cmdTangentEnd(backN, opts);
+  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') {
@@ -1941,15 +2740,16 @@ if (opts.help || positional.length === 0) {
 const command = positional[0];
 const jsonlPath = positional[1];
 
-// 'last', 'tools', and 'checkpoints' commands don't require a path
-if (!jsonlPath && command !== 'help' && command !== 'last' && command !== 'tools' && command !== 'checkpoints') {
+// 'last', 'tools', 'checkpoints', and 'compactions' commands don't require a path
+if (!jsonlPath && command !== 'help' && command !== 'last' && command !== 'tools' && command !== 'checkpoints' && command !== 'compactions') {
   console.error('Error: JSONL path required');
   showHelp();
   process.exit(1);
 }
 
-// For 'last' command, the second arg might be a number, not a path
-if (command !== 'last' && jsonlPath && !fs.existsSync(jsonlPath)) {
+// For 'last' and 'compactions' commands, the second arg might not be a path
+// 'compactions' auto-detects if no path provided, so skip validation
+if (command !== 'last' && command !== 'compactions' && jsonlPath && !fs.existsSync(jsonlPath)) {
   console.error(`Error: File not found: ${jsonlPath}`);
   process.exit(1);
 }
@@ -1979,6 +2779,9 @@ switch (command) {
   case 'checkpoints':
     cmdCheckpoints(opts);
     break;
+  case 'compactions':
+    cmdCompactions(jsonlPath, opts);
+    break;
   case 'help':
     showHelp();
     break;