claude-mem-lite 2.3.1 → 2.5.1

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "2.1.6",
+      "version": "2.3.2",
       "source": "./",
       "description": "Lightweight persistent memory system for Claude Code — FTS5 search, episode batching, error-triggered recall"
     }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "2.2.0",
+  "version": "2.5.1",
   "description": "Lightweight persistent memory system for Claude Code — FTS5 search, episode batching, error-triggered recall",
   "author": {
     "name": "sdsrss"

package/.mcp.json

@@ -1,8 +1,3 @@
 {
-  "mcpServers": {
-    "mem": {
-      "command": "node",
-      "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/launch.mjs"]
-    }
-  }
-}
+  "mcpServers": {}
+}

package/commands/mem.md

@@ -1,4 +1,5 @@
 ---
+name: mem
 description: Search and manage project memory (observations, sessions, prompts)
 ---
 
@@ -13,6 +14,9 @@ Search and browse your project memory efficiently.
 - `/mem save <text>` — Save a manual memory/note
 - `/mem stats` — Show memory statistics
 - `/mem timeline <query>` — Browse timeline around a matching observation
+- `/mem cleanup` — Scan and interactively purge stale data
+- `/mem cleanup [N]d` — Purge stale data older than N days (e.g. `cleanup 60d`)
+- `/mem cleanup keep [N]d` — Purge stale data but retain last N days (e.g. `cleanup keep 14d`)
 
 ## Efficient Search Workflow (3 steps, saves 10x tokens)
 
@@ -29,6 +33,9 @@ When the user invokes `/mem`, parse their intent:
 - `/mem save <text>` → call `mem_save` with the text as content
 - `/mem stats` → call `mem_stats`
 - `/mem timeline <query>` → call `mem_timeline` with the query
+- `/mem cleanup` → run `mem_maintain(action="scan")`, report pending purge count and stale items to user, ask for confirmation, then run `mem_maintain(action="execute", operations=["purge_stale"])` if confirmed
+- `/mem cleanup Nd` (e.g. `60d`) → same as above but use `retain_days=N` to only purge items older than N days
+- `/mem cleanup keep Nd` (e.g. `keep 14d`) → same as above with `retain_days=N`
 - `/mem <query>` (no subcommand) → treat as search, call `mem_search`
 
 Always use the compact index from mem_search first, then mem_get for details only when needed. This minimizes token usage.

package/commands/update.md

@@ -18,10 +18,11 @@ When the user invokes `/mem:update`, perform the following maintenance cycle:
 ### Phase 1: Memory Maintenance
 
 1. Call `mem_maintain(action="scan")` to analyze maintenance candidates
-2. Report scan results to the user (duplicates, stale items, broken items, boostable items)
+2. Report scan results to the user (duplicates, stale items, broken items, boostable items, **pending purge** items)
 3. Call `mem_maintain(action="execute", operations=["cleanup","decay","boost"])` to apply safe automatic changes
 4. If duplicates were found in scan, review them and call `mem_maintain(action="execute", operations=["dedup"], merge_ids=[[keepId, removeId1, ...], ...])` — keep the more important/recent observation in each pair
 5. Run `mem_compress(preview=false)` for old low-value observations
+6. **If pending purge items > 0**: Report the count to the user and ask for confirmation. If confirmed, call `mem_maintain(action="execute", operations=["purge_stale"])`. User may optionally specify `retain_days` (default 30) to control how many days of data to keep. Do NOT purge without explicit user confirmation.
 
 ### Phase 2: Registry Maintenance
 

package/dispatch-feedback.mjs

@@ -165,6 +165,49 @@ function detectOutcome(sessionEvents) {
   return 'success'; // No errors, no edits = informational session, ok
 }
 
+// ─── Rejection Classification ────────────────────────────────────────────────
+
+/**
+ * Classify why a recommendation was not adopted.
+ * Analyzes post-recommendation events to determine the reason.
+ * @param {object} invocation Invocation record with created_at
+ * @param {object[]} sessionEvents All session tool events
+ * @returns {string} Rejection reason
+ */
+function classifyRejection(invocation, sessionEvents) {
+  if (!sessionEvents || sessionEvents.length === 0) return 'session_end';
+
+  const recTime = new Date(invocation.created_at).getTime();
+  const afterEvents = sessionEvents.filter(e =>
+    (e.timestamp || 0) > recTime || !e.timestamp
+  );
+
+  if (afterEvents.length <= 2) return 'session_end';
+
+  // Alternative: Claude used a different skill/agent instead
+  const { resource_type, invocation_name, resource_name } = invocation;
+  for (const e of afterEvents) {
+    if (resource_type === 'skill' && e.tool_name === 'Skill') {
+      const used = (e.tool_input?.skill || '').toLowerCase();
+      const expected = (invocation_name || resource_name || '').toLowerCase();
+      if (used && used !== expected && !used.includes(expected)) return 'alternative';
+    }
+    if (resource_type === 'agent' && e.tool_name === 'Agent') {
+      return 'alternative';
+    }
+  }
+
+  // Manual: Claude completed work without any skill/agent
+  const hasEdits = afterEvents.some(e => EDIT_TOOLS.has(e.tool_name));
+  const noSkillAgent = !afterEvents.some(e => e.tool_name === 'Skill' || e.tool_name === 'Agent');
+  if (hasEdits && noSkillAgent) return 'manual';
+
+  // Context switch: lots of activity but unrelated
+  if (afterEvents.length > 5) return 'context_switch';
+
+  return 'unknown';
+}
+
 // ─── Main Feedback Collection ────────────────────────────────────────────────
 
 /**
@@ -190,12 +233,14 @@ export async function collectFeedback(db, sessionId, sessionEvents = []) {
       const adopted = detectAdoption(inv, sessionEvents);
       const outcome = adopted ? detectOutcome(sessionEvents) : 'ignored';
       const score = adopted ? (outcome === 'success' ? 1.0 : outcome === 'partial' ? 0.5 : 0.2) : 0;
+      const rejection_reason = adopted ? null : classifyRejection(inv, sessionEvents);
 
       // Update invocation record
       updateInvocation(db, inv.id, {
         adopted: adopted ? 1 : 0,
         outcome,
         score,
+        rejection_reason,
       });
 
       // Update resource stats

package/dispatch-inject.mjs

@@ -2,7 +2,7 @@
 // Formats resource recommendations for Claude Code's additionalContext
 
 import { existsSync, readFileSync } from 'fs';
-import { join } from 'path';
+import { join, resolve } from 'path';
 import { homedir } from 'os';
 import { truncate } from './utils.mjs';
 import { DB_DIR } from './schema.mjs';
@@ -18,13 +18,14 @@ function truncateContent(str, max) {
 
 // Allowed base directories for resource file reads (defense-in-depth)
 const ALLOWED_BASES = [
-  join(homedir(), '.claude'),
-  join(DB_DIR, 'managed'),
+  resolve(join(homedir(), '.claude')),
+  resolve(join(DB_DIR, 'managed')),
 ];
 
 function isAllowedPath(filePath) {
   if (!filePath) return false;
-  return ALLOWED_BASES.some(base => filePath === base || filePath.startsWith(base + '/'));
+  const resolved = resolve(filePath);
+  return ALLOWED_BASES.some(base => resolved === base || resolved.startsWith(base + '/'));
 }
 
 // ─── Template Detection ──────────────────────────────────────────────────────
@@ -142,9 +143,10 @@ ${truncatedDef}
  * Enforces MAX_INJECTION_CHARS hard limit.
  *
  * @param {object} resource Resource object from DB
+ * @param {string} [reason] Brief reason why this resource was recommended
  * @returns {string} Injection text for additionalContext
  */
-export function renderInjection(resource) {
+export function renderInjection(resource, reason) {
   let injection;
 
   if (resource.type === 'skill') {
@@ -161,6 +163,8 @@ export function renderInjection(resource) {
     injection = injectAgent(resource);
   }
 
+  if (reason) injection += `\nReason: ${reason}`;
+
   // Hard limit enforcement
   if (injection.length > MAX_INJECTION_CHARS) {
     injection = injection.slice(0, MAX_INJECTION_CHARS - 3) + '...';

package/dispatch-workflow.mjs

@@ -66,22 +66,32 @@ export const SUITE_AUTO_FLOWS = {
   },
 };
 
+const SUITE_MOMENTUM_MAX_DISTANCE = 20;
+const SUITE_MOMENTUM_MAX_AGE_MS = 15 * 60 * 1000; // 15 minutes
+
 /**
  * Detect if a suite auto-flow is active based on recent Skill tool events.
- * Scans backwards to find the most recent Skill invocation from a known suite.
+ * Scans backwards with momentum decay: suite influence fades after 20 tool calls or 15 minutes.
  * @param {object[]} sessionEvents Array of tool events
- * @returns {{suite: string, flow: object, lastSkill: string}|null}
+ * @returns {{suite: string, flow: object, lastSkill: string, distance: number}|null}
  */
 export function detectActiveSuite(sessionEvents) {
   if (!sessionEvents || sessionEvents.length === 0) return null;
 
   for (let i = sessionEvents.length - 1; i >= 0; i--) {
+    const distance = sessionEvents.length - 1 - i;
+
+    // Momentum decay: suite influence fades after 20 tool calls
+    if (distance > SUITE_MOMENTUM_MAX_DISTANCE) return null;
+
     const e = sessionEvents[i];
     if (e.tool_name === 'Skill' && e.tool_input?.skill) {
       const skill = e.tool_input.skill;
       const suite = skill.split(':')[0];
       if (SUITE_AUTO_FLOWS[suite]) {
-        return { suite, flow: SUITE_AUTO_FLOWS[suite], lastSkill: skill };
+        // Time decay: suite influence expires after 15 minutes
+        if (e.timestamp && (Date.now() - e.timestamp) > SUITE_MOMENTUM_MAX_AGE_MS) return null;
+        return { suite, flow: SUITE_AUTO_FLOWS[suite], lastSkill: skill, distance };
       }
     }
   }
@@ -113,11 +123,16 @@ export function shouldRecommendForStage(activeSuite, currentStage) {
  * @param {{lastSkill: string}|null} activeSuite Active suite info
  * @returns {string|null} Stage name or null
  */
-export function inferCurrentStage(primaryIntent, activeSuite) {
+export function inferCurrentStage(primaryIntent, activeSuite, suppressedIntents = []) {
   if (activeSuite?.lastSkill && SKILL_STAGE_MAP[activeSuite.lastSkill]) {
     return SKILL_STAGE_MAP[activeSuite.lastSkill];
   }
-  return INTENT_STAGE_MAP[primaryIntent] || null;
+  if (INTENT_STAGE_MAP[primaryIntent]) return INTENT_STAGE_MAP[primaryIntent];
+  // Check suppressed intents — still the user's actual intent, just not used for FTS search
+  for (const si of suppressedIntents) {
+    if (INTENT_STAGE_MAP[si]) return INTENT_STAGE_MAP[si];
+  }
+  return null;
 }
 
 // ─── Explicit Request Detection ──────────────────────────────────────────────

package/dispatch.mjs

@@ -29,25 +29,35 @@ export const SESSION_RECOMMEND_CAP = 3;
 // this filters only near-zero noise matches from incidental text overlap.
 export const BM25_MIN_THRESHOLD = 1.5;
 
+// Minimum confidence from Haiku semantic dispatch to replace FTS5 results.
+// Prevents low-confidence Haiku queries (e.g. 0.2) from overriding good FTS5 matches.
+export const HAIKU_CONFIDENCE_THRESHOLD = 0.6;
+
 // ─── Haiku Circuit Breaker ──────────────────────────────────────────────────
 // Prevents cascading latency when Haiku API is down or slow.
 // After BREAKER_THRESHOLD consecutive failures, disable for BREAKER_RESET_MS.
+// KNOWN LIMITATION: File-based state has a TOCTOU race under concurrent hook
+// processes. Worst case: breaker trips on failure N+1 instead of N. This is
+// acceptable — the breaker is a latency guard, not a correctness mechanism.
 
 const BREAKER_THRESHOLD = 3;
 const BREAKER_RESET_MS = 5 * 60 * 1000; // 5 minutes
-const BREAKER_FILE = join(RUNTIME_DIR, 'haiku-breaker.json');
+let breakerFile = join(RUNTIME_DIR, 'haiku-breaker.json');
 
 function _readBreakerState() {
   try {
-    if (!existsSync(BREAKER_FILE)) return { failures: 0, openUntil: 0 };
-    return JSON.parse(readFileSync(BREAKER_FILE, 'utf8'));
+    if (!existsSync(breakerFile)) return { failures: 0, openUntil: 0 };
+    return JSON.parse(readFileSync(breakerFile, 'utf8'));
   } catch { return { failures: 0, openUntil: 0 }; }
 }
 
 function _writeBreakerState(state) {
-  try { writeFileSync(BREAKER_FILE, JSON.stringify(state)); } catch {}
+  try { writeFileSync(breakerFile, JSON.stringify(state)); } catch {}
 }
 
+/** Override breaker file path (for testing isolation). */
+export function _setBreakerFile(path) { breakerFile = path; }
+
 function isHaikuCircuitOpen() {
   const state = _readBreakerState();
   if (state.openUntil > 0 && Date.now() < state.openUntil) return true;
@@ -636,25 +646,89 @@ JSON: {"query":"search keywords for finding the right skill or agent","type":"sk
 
 // ─── Cooldown & Dedup (DB-persisted, survives process restarts) ─────────────
 
+/**
+ * Check if session has hit the recommendation cap.
+ * Separated from per-resource check so callers in filter loops can hoist this.
+ * @param {Database} db Registry database
+ * @param {string} sessionId Session identifier
+ * @returns {boolean} true if session cap is reached
+ */
+export function isSessionCapped(db, sessionId) {
+  if (!sessionId) return false;
+  const sessionCount = db.prepare(
+    'SELECT COUNT(*) as cnt FROM invocations WHERE session_id = ? AND recommended = 1'
+  ).get(sessionId);
+  return sessionCount.cnt >= SESSION_RECOMMEND_CAP;
+}
+
+/**
+ * Compute adaptive cooldown based on recent adoption rate.
+ * High adoption → shorter cooldown (user welcomes recommendations).
+ * Low adoption → longer cooldown (reduce noise).
+ * @param {Database} db Registry database
+ * @returns {number} Cooldown in minutes
+ */
+function getAdaptiveCooldown(db) {
+  try {
+    const stats = db.prepare(`
+      SELECT COUNT(*) as total,
+             SUM(CASE WHEN adopted = 1 THEN 1 ELSE 0 END) as adopted
+      FROM invocations
+      WHERE recommended = 1 AND created_at > datetime('now', '-7 days')
+    `).get();
+    if (!stats || stats.total < 5) return COOLDOWN_MINUTES; // Not enough data, use default
+    const rate = stats.adopted / stats.total;
+    if (rate > 0.5) return 30;   // High adoption: 30 min
+    if (rate > 0.2) return 60;   // Medium: 60 min (default)
+    if (rate > 0.1) return 120;  // Low: 2 hours
+    return 240;                   // Very low: 4 hours
+  } catch { return COOLDOWN_MINUTES; }
+}
+
+const CONSECUTIVE_REJECT_THRESHOLD = 5;
+const CONSECUTIVE_REJECT_WINDOW_DAYS = 7;
+
+/**
+ * Check if a resource has been consecutively rejected (not adopted) in recent history.
+ * @param {Database} db Registry database
+ * @param {number} resourceId Resource ID
+ * @returns {boolean} true if resource should be silenced
+ */
+function isConsecutivelyRejected(db, resourceId) {
+  try {
+    const recent = db.prepare(`
+      SELECT adopted FROM invocations
+      WHERE resource_id = ? AND recommended = 1 AND outcome IS NOT NULL
+        AND created_at > datetime('now', '-${CONSECUTIVE_REJECT_WINDOW_DAYS} days')
+      ORDER BY created_at DESC
+      LIMIT ?
+    `).all(resourceId, CONSECUTIVE_REJECT_THRESHOLD);
+
+    if (recent.length < CONSECUTIVE_REJECT_THRESHOLD) return false;
+    return recent.every(r => r.adopted === 0);
+  } catch { return false; }
+}
+
 export function isRecentlyRecommended(db, resourceId, sessionId) {
-  // Check 1 & 2: Session-scoped checks (cap + dedup) — only when sessionId is available
+  // Check 1: Session cap (loop-invariant — callers should prefer isSessionCapped for filter loops)
   if (sessionId) {
-    const sessionCount = db.prepare(
-      'SELECT COUNT(*) as cnt FROM invocations WHERE session_id = ? AND recommended = 1'
-    ).get(sessionId);
-    if (sessionCount.cnt >= SESSION_RECOMMEND_CAP) return true;
+    if (isSessionCapped(db, sessionId)) return true;
 
-    // Already recommended in this session (session dedup)
+    // Check 2: Already recommended in this session (session dedup)
     const sessionHit = db.prepare(
       'SELECT 1 FROM invocations WHERE resource_id = ? AND session_id = ? AND recommended = 1 LIMIT 1'
     ).get(resourceId, sessionId);
     if (sessionHit) return true;
   }
 
-  // Check 3: Recommended within cooldown window (cross-session cooldown)
+  // Check 3: Consecutive rejection silencing
+  if (isConsecutivelyRejected(db, resourceId)) return true;
+
+  // Check 4: Recommended within adaptive cooldown window (cross-session cooldown)
+  const cooldown = getAdaptiveCooldown(db);
   const cooldownHit = db.prepare(
     `SELECT 1 FROM invocations WHERE resource_id = ? AND created_at > datetime('now', ?) LIMIT 1`
-  ).get(resourceId, `-${COOLDOWN_MINUTES} minutes`);
+  ).get(resourceId, `-${cooldown} minutes`);
   return !!cooldownHit;
 }
 
@@ -738,14 +812,14 @@ function applyAdoptionDecay(results, db) {
  * @returns {object[]} Filtered results that pass the gate
  */
 function passesConfidenceGate(results, signals) {
-  // BM25 absolute minimum: filter out weak text matches regardless of intent.
-  // Only apply when enough results exist (BM25 IDF is unreliable with < 3 matches).
-  if (results.length >= 3) {
-    results = results.filter(r => {
-      const score = Math.abs(r.composite_score ?? r.relevance);
-      return score >= BM25_MIN_THRESHOLD;
-    });
-  }
+  // BM25 absolute minimum: filter weak text matches.
+  // Stricter threshold for 3+ results (reliable IDF); gentler floor for 1-2 results.
+  const minThreshold = results.length >= 3 ? BM25_MIN_THRESHOLD : 0.5;
+  results = results.filter(r => {
+    const raw = r.composite_score ?? r.relevance;
+    if (raw === null || raw === undefined) return true; // no score → pass (pre-scored or synthetic result)
+    return Math.abs(raw) >= minThreshold;
+  });
 
   // signals.intent is a comma-separated string (e.g. "test,fix"), not an array
   const intentTokens = typeof signals?.intent === 'string'
@@ -787,6 +861,36 @@ function postProcessResults(results, signals, db, limit = 3) {
   return results.slice(0, limit);
 }
 
+// ─── Recommendation Reason ──────────────────────────────────────────────────
+
+const INTENT_LABELS = {
+  test: 'testing', fix: 'debugging', review: 'code review', commit: 'git workflow',
+  deploy: 'deployment', plan: 'planning', clean: 'refactoring', doc: 'documentation',
+  db: 'database', api: 'API', secure: 'security', infra: 'infrastructure',
+  build: 'build tooling', fast: 'performance', lint: 'code style', design: 'UI/frontend',
+};
+
+/**
+ * Build a brief human-readable reason for why a resource was recommended.
+ * @param {object} signals Context signals from extractContextSignals
+ * @param {object} [options]
+ * @param {boolean} [options.explicit] Whether this was an explicit user request
+ * @returns {string} Brief reason string
+ */
+function buildRecommendReason(signals, { explicit = false } = {}) {
+  if (explicit) return 'Matched your explicit request';
+
+  const parts = [];
+  if (signals?.primaryIntent) {
+    const label = INTENT_LABELS[signals.primaryIntent] || signals.primaryIntent;
+    parts.push(`${label} intent detected`);
+  }
+  if (signals?.rawKeywords?.length > 0) {
+    parts.push(`keywords: ${signals.rawKeywords.slice(0, 3).join(', ')}`);
+  }
+  return parts.join('; ') || '';
+}
+
 // ─── Main Dispatch Functions ─────────────────────────────────────────────────
 
 /**
@@ -839,7 +943,7 @@ export async function dispatchOnSessionStart(db, userPrompt, sessionId, { hasHan
     if (needsHaikuDispatch(results)) {
       tier = 3;
       const haikuResult = await haikuDispatch(userPrompt, '');
-      if (haikuResult?.query) {
+      if (haikuResult?.query && (haikuResult.confidence ?? 0) >= HAIKU_CONFIDENCE_THRESHOLD) {
         const haikuQuery = buildQueryFromText(haikuResult.query);
         if (haikuQuery) {
           let haikuResults = retrieveResources(db, haikuQuery, {
@@ -857,7 +961,8 @@ export async function dispatchOnSessionStart(db, userPrompt, sessionId, { hasHan
 
     if (results.length === 0) return null;
 
-    // Filter by DB-persisted cooldown + session dedup
+    // Filter by DB-persisted cooldown + session dedup (hoisted cap check avoids N queries)
+    if (sessionId && isSessionCapped(db, sessionId)) return null;
     const viable = sessionId
       ? results.filter(r => !isRecentlyRecommended(db, r.id, sessionId))
       : results;
@@ -875,7 +980,7 @@ export async function dispatchOnSessionStart(db, userPrompt, sessionId, { hasHan
     });
     updateResourceStats(db, best.id, 'recommend_count');
 
-    return renderInjection(best);
+    return renderInjection(best, buildRecommendReason(signals));
   } catch (e) {
     debugCatch(e, 'dispatchOnSessionStart');
     return null;
@@ -895,18 +1000,19 @@ export async function dispatchOnUserPrompt(db, userPrompt, sessionId, { sessionE
   if (!userPrompt || !db) return null;
 
   try {
-    // 1. Explicit request → highest priority, bypass all restrictions
+    // 1. Explicit request → highest priority, bypass cooldown but apply adoption decay
     const explicit = detectExplicitRequest(userPrompt);
     if (explicit.isExplicit) {
       const textQuery = buildQueryFromText(explicit.searchTerm);
       if (textQuery) {
-        const explicitResults = retrieveResources(db, textQuery, { limit: 3, projectDomains: detectProjectDomains() });
+        let explicitResults = retrieveResources(db, textQuery, { limit: 3, projectDomains: detectProjectDomains() });
+        explicitResults = applyAdoptionDecay(explicitResults, db);
         if (explicitResults.length > 0) {
           const best = explicitResults[0];
           if (!sessionId || !isRecentlyRecommended(db, best.id, sessionId)) {
             recordInvocation(db, { resource_id: best.id, session_id: sessionId, trigger: 'user_prompt', tier: 1, recommended: 1 });
             updateResourceStats(db, best.id, 'recommend_count');
-            return renderInjection(best);
+            return renderInjection(best, buildRecommendReason(null, { explicit: true }));
           }
         }
       }
@@ -923,7 +1029,7 @@ export async function dispatchOnUserPrompt(db, userPrompt, sessionId, { sessionE
 
     // Check if active suite covers the current stage
     if (activeSuite) {
-      const currentStage = inferCurrentStage(signals.primaryIntent, activeSuite);
+      const currentStage = inferCurrentStage(signals.primaryIntent, activeSuite, signals.suppressedIntents);
       if (currentStage) {
         const { shouldRecommend } = shouldRecommendForStage(activeSuite, currentStage);
         if (!shouldRecommend) return null;
@@ -960,7 +1066,8 @@ export async function dispatchOnUserPrompt(db, userPrompt, sessionId, { sessionE
     // Low confidence → skip (no Haiku in user_prompt path — stay fast)
     if (needsHaikuDispatch(results)) return null;
 
-    // Filter by cooldown + session dedup (prevents double-recommend with SessionStart)
+    // Filter by cooldown + session dedup (hoisted cap check avoids N queries)
+    if (sessionId && isSessionCapped(db, sessionId)) return null;
     const viable = sessionId
       ? results.filter(r => !isRecentlyRecommended(db, r.id, sessionId))
       : results;
@@ -977,7 +1084,7 @@ export async function dispatchOnUserPrompt(db, userPrompt, sessionId, { sessionE
     });
     updateResourceStats(db, best.id, 'recommend_count');
 
-    return renderInjection(best);
+    return renderInjection(best, buildRecommendReason(signals));
   } catch (e) {
     debugCatch(e, 'dispatchOnUserPrompt');
     return null;
@@ -1007,13 +1114,17 @@ export async function dispatchOnPreToolUse(db, event, sessionCtx = {}) {
     const events = peekToolEvents();
     const activeSuite = detectActiveSuite(events);
     if (activeSuite) {
-      const stage = inferCurrentStage(signals.primaryIntent, activeSuite);
+      const stage = inferCurrentStage(signals.primaryIntent, activeSuite, signals.suppressedIntents);
       if (stage) {
         const { shouldRecommend } = shouldRecommendForStage(activeSuite, stage);
         if (!shouldRecommend) return null;
       }
     }
-    const query = buildEnhancedQuery(signals);
+    let query = buildEnhancedQuery(signals);
+    if (!query && sessionCtx?.userPrompt) {
+      query = buildQueryFromText(sessionCtx.userPrompt);
+      if (!query) return null;
+    }
     if (!query) return null;
 
     const projectDomains = detectProjectDomains();
@@ -1028,8 +1139,9 @@ export async function dispatchOnPreToolUse(db, event, sessionCtx = {}) {
     // Low-confidence results: skip recommendation rather than suggest unreliable match
     if (needsHaikuDispatch(results)) return null;
 
-    // Apply DB-persisted cooldown and session dedup (filter all, not just top)
+    // Apply DB-persisted cooldown and session dedup (hoisted cap check avoids N queries)
     const sid = sessionCtx.sessionId || null;
+    if (sid && isSessionCapped(db, sid)) return null;
     const viable = sid
       ? results.filter(r => !isRecentlyRecommended(db, r.id, sid))
       : results;
@@ -1046,7 +1158,7 @@ export async function dispatchOnPreToolUse(db, event, sessionCtx = {}) {
     });
     updateResourceStats(db, best.id, 'recommend_count');
 
-    return renderInjection(best);
+    return renderInjection(best, buildRecommendReason(signals));
   } catch (e) {
     debugCatch(e, 'dispatchOnPreToolUse');
     return null;

package/hook-context.mjs

@@ -3,7 +3,7 @@
 
 import { join } from 'path';
 import { readFileSync, writeFileSync, renameSync } from 'fs';
-import { estimateTokens, debugLog, debugCatch } from './utils.mjs';
+import { estimateTokens, truncate, debugLog, debugCatch } from './utils.mjs';
 
 /**
  * Infer the project directory from environment variables or cwd.
@@ -173,3 +173,34 @@ export function updateClaudeMd(contextBlock) {
     debugLog('ERROR', 'updateClaudeMd', `CLAUDE.md write failed: ${e.message}`);
   }
 }
+
+/**
+ * Build summary lines from a latestSummary row.
+ * Extracted for testability — used by handleSessionStart.
+ * @param {object} latestSummary Row from session_summaries with request, completed, etc.
+ * @returns {string[]} Lines to include in context output
+ */
+export function buildSummaryLines(latestSummary) {
+  const lines = [];
+  if (!latestSummary) return lines;
+
+  lines.push('### Last Session');
+  if (latestSummary.request) lines.push(`Request: ${truncate(latestSummary.request, 120)}`);
+  if (latestSummary.completed) lines.push(`Completed: ${truncate(latestSummary.completed, 120)}`);
+  if (latestSummary.remaining_items) lines.push(`Remaining: ${truncate(latestSummary.remaining_items, 120)}`);
+  if (latestSummary.next_steps) lines.push(`Next: ${truncate(latestSummary.next_steps, 120)}`);
+  if (latestSummary.lessons) {
+    try {
+      const lessons = JSON.parse(latestSummary.lessons);
+      if (lessons.length > 0) lines.push(`Lessons: ${lessons.slice(0, 3).join('; ')}`);
+    } catch {}
+  }
+  if (latestSummary.key_decisions) {
+    try {
+      const decisions = JSON.parse(latestSummary.key_decisions);
+      if (decisions.length > 0) lines.push(`Decisions: ${decisions.slice(0, 3).join('; ')}`);
+    } catch {}
+  }
+  lines.push('');
+  return lines;
+}

package/hook-handoff.mjs

@@ -116,6 +116,14 @@ export function buildAndSaveHandoff(db, sessionId, project, type, episodeSnapsho
  * @returns {boolean}
  */
 export function detectContinuationIntent(db, promptText, project) {
+  // Stage 0: Non-expired 'clear' handoff = always continue (/clear means user is resuming)
+  const clearHandoff = db.prepare(`
+    SELECT created_at_epoch FROM session_handoffs WHERE project = ? AND type = 'clear'
+  `).get(project);
+  if (clearHandoff && (Date.now() - clearHandoff.created_at_epoch <= HANDOFF_EXPIRY_CLEAR)) {
+    return true;
+  }
+
   // Stage 1: Explicit keyword match — always works, even without handoff
   if (CONTINUE_KEYWORDS.test(promptText)) return true;
 
@@ -220,3 +228,22 @@ export function renderHandoffInjection(db, project) {
 
   return lines.join('\n');
 }
+
+// Separator used by buildAndSaveHandoff to join pending entries with narrative history.
+const UNFINISHED_NARRATIVE_SEP = '\n---\n';
+const UNFINISHED_ENTRY_SEP = '; ';
+
+/**
+ * Extract the pending-work portion of the unfinished field (before narrative history).
+ * @param {string} unfinished Raw unfinished text from session_handoffs
+ * @param {number} [maxItems=3] Max number of pending entries to return
+ * @returns {string} Pending work summary (empty string if none)
+ */
+export function extractUnfinishedSummary(unfinished, maxItems = 3) {
+  if (!unfinished) return '';
+  const pending = unfinished.split(UNFINISHED_NARRATIVE_SEP)[0];
+  if (maxItems > 0) {
+    return pending.split(UNFINISHED_ENTRY_SEP).slice(0, maxItems).join(UNFINISHED_ENTRY_SEP);
+  }
+  return pending;
+}