claude-mem-lite 2.3.3 → 2.5.2

package/.claude-plugin/plugin.json

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

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

@@ -143,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') {
@@ -162,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,6 +29,10 @@ 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.
@@ -657,6 +661,54 @@ export function isSessionCapped(db, 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: Session cap (loop-invariant — callers should prefer isSessionCapped for filter loops)
   if (sessionId) {
@@ -669,10 +721,14 @@ export function isRecentlyRecommended(db, 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;
 }
 
@@ -756,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'
@@ -805,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 ─────────────────────────────────────────────────
 
 /**
@@ -857,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, {
@@ -894,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;
@@ -926,7 +1012,7 @@ export async function dispatchOnUserPrompt(db, userPrompt, sessionId, { sessionE
           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 }));
           }
         }
       }
@@ -943,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;
@@ -998,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;
@@ -1028,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();
@@ -1068,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/haiku-client.mjs

@@ -150,6 +150,7 @@ function callHaikuCLI(prompt, { timeout }) {
       encoding: 'utf8',
       env: { ...process.env, CLAUDE_MEM_HOOK_RUNNING: '1' },
       stdio: ['pipe', 'pipe', 'pipe'],
+      cwd: '/tmp', // Prevent ghost sessions in user's /resume list
     });
     const text = result.trim();
     return text ? { text } : 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;
+}

package/hook-llm.mjs

@@ -16,12 +16,13 @@ import {
 
 // ─── Save Observation to DB ─────────────────────────────────────────────────
 
-/** Build the FTS5 text field from observation data (concepts + facts + CJK bigrams). */
+/** Build the FTS5 text field from observation data (concepts + facts + searchAliases + CJK bigrams). */
 function buildFtsTextField(obs) {
   const conceptsText = Array.isArray(obs.concepts) ? obs.concepts.join(' ') : '';
   const factsText = Array.isArray(obs.facts) ? obs.facts.join(' ') : '';
+  const aliasesText = obs.searchAliases || '';
   const bigramText = cjkBigrams((obs.title || '') + ' ' + (obs.narrative || ''));
-  return { conceptsText, factsText, textField: [conceptsText, factsText, bigramText].filter(Boolean).join(' ') };
+  return { conceptsText, factsText, textField: [conceptsText, factsText, aliasesText, bigramText].filter(Boolean).join(' ') };
 }
 
 export function saveObservation(obs, projectOverride, sessionIdOverride, externalDb) {
@@ -69,8 +70,8 @@ export function saveObservation(obs, projectOverride, sessionIdOverride, externa
     const { conceptsText, factsText, textField } = buildFtsTextField(obs);
 
     const result = db.prepare(`
-      INSERT INTO observations (memory_session_id, project, text, type, title, subtitle, narrative, concepts, facts, files_read, files_modified, importance, minhash_sig, created_at, created_at_epoch)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      INSERT INTO observations (memory_session_id, project, text, type, title, subtitle, narrative, concepts, facts, files_read, files_modified, importance, minhash_sig, lesson_learned, search_aliases, created_at, created_at_epoch)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `).run(
       sessionId, project,
       textField, obs.type, obs.title, obs.subtitle || '',
@@ -81,6 +82,8 @@ export function saveObservation(obs, projectOverride, sessionIdOverride, externa
       JSON.stringify(obs.files || []),
       obs.importance ?? 1,
       minhashSig,
+      obs.lessonLearned || null,
+      obs.searchAliases || null,
       now.toISOString(), now.getTime()
     );
     return Number(result.lastInsertRowid);
@@ -265,9 +268,11 @@ File: ${episode.files.join(', ') || 'unknown'}
 Action: ${e.desc}
 Error: ${e.isError ? 'yes' : 'no'}
 
-JSON: {"type":"decision|bugfix|feature|refactor|discovery|change","title":"concise ≤80 char description","narrative":"what changed, why, and outcome (2-3 sentences)","concepts":["kw1","kw2"],"facts":["fact1","fact2"],"importance":1}
+JSON: {"type":"decision|bugfix|feature|refactor|discovery|change","title":"concise ≤80 char description","narrative":"what changed, why, and outcome (2-3 sentences)","concepts":["kw1","kw2"],"facts":["fact1","fact2"],"importance":1,"lesson_learned":"non-obvious insight or null if routine","search_aliases":["alt query 1","alt query 2"]}
 Facts: each MUST be (1) atomic—one claim, (2) self-contained—no pronouns, include file/function name, (3) specific—"refreshToken() in auth.ts:45 uses 1h TTL" not "handles tokens"
-importance: 0=not worth saving (pure browsing, trivial query, no learning value), 1=routine, 2=notable (error fix, arch decision, config change), 3=critical (breaking change, security fix, data migration)`;
+importance: 0=not worth saving (pure browsing, trivial query, no learning value), 1=routine, 2=notable (error fix, arch decision, config change), 3=critical (breaking change, security fix, data migration)
+lesson_learned: If this episode revealed something NON-OBVIOUS (a debugging insight, a gotcha, a design reason), capture it as a reusable lesson. null if routine.
+search_aliases: 2-6 alternative search terms someone might use to find this memory later (include CJK if project uses Chinese)`;
   } else {
     const actionList = episode.entries.map((e, i) =>
       `${i + 1}. [${e.tool}] ${e.desc}${e.isError ? ' (ERROR)' : ''}`
@@ -280,9 +285,11 @@ Files: ${fileList}
 Actions (${episode.entries.length} total):
 ${actionList}
 
-JSON: {"type":"decision|bugfix|feature|refactor|discovery|change","title":"coherent ≤80 char summary","narrative":"what was done, why, and outcome (3-5 sentences)","concepts":["keyword1","keyword2"],"facts":["specific fact 1","specific fact 2"],"importance":1}
+JSON: {"type":"decision|bugfix|feature|refactor|discovery|change","title":"coherent ≤80 char summary","narrative":"what was done, why, and outcome (3-5 sentences)","concepts":["keyword1","keyword2"],"facts":["specific fact 1","specific fact 2"],"importance":1,"lesson_learned":"non-obvious insight or null if routine","search_aliases":["alt query 1","alt query 2"]}
 Facts: each MUST be (1) atomic—one claim, (2) self-contained—no pronouns, include file/function name, (3) specific—"refreshToken() in auth.ts:45 uses 1h TTL" not "handles tokens"
-importance: 0=not worth saving (pure browsing, trivial query, no learning value), 1=routine, 2=notable (error fix, arch decision, config change), 3=critical (breaking change, security fix, data migration)`;
+importance: 0=not worth saving (pure browsing, trivial query, no learning value), 1=routine, 2=notable (error fix, arch decision, config change), 3=critical (breaking change, security fix, data migration)
+lesson_learned: If this episode revealed something NON-OBVIOUS (a debugging insight, a gotcha, a design reason), capture it as a reusable lesson. null if routine.
+search_aliases: 2-6 alternative search terms someone might use to find this memory later (include CJK if project uses Chinese)`;
   }
 
   const ruleImportance = computeRuleImportance(episode);
@@ -316,6 +323,11 @@ importance: 0=not worth saving (pure browsing, trivial query, no learning value)
         return;
       }
 
+      const lessonLearned = typeof parsed.lesson_learned === 'string' ? parsed.lesson_learned.slice(0, 500) : null;
+      const searchAliases = Array.isArray(parsed.search_aliases)
+        ? parsed.search_aliases.slice(0, 6).join(' ')
+        : null;
+
       obs = {
         type: validTypes.has(parsed.type) ? parsed.type : 'change',
         title: truncate(parsed.title, 120),
@@ -326,6 +338,8 @@ importance: 0=not worth saving (pure browsing, trivial query, no learning value)
         files: episode.files,
         filesRead: episode.filesRead || [],
         importance: Math.max(ruleImportance, clampImportance(parsed.importance)),
+        lessonLearned,
+        searchAliases,
       };
     }
   }
@@ -353,7 +367,7 @@ importance: 0=not worth saving (pure browsing, trivial query, no learning value)
       const minhashSig = computeMinHash((obs.title || '') + ' ' + (obs.narrative || ''));
       db.prepare(`
         UPDATE observations SET type=?, title=?, subtitle=?, narrative=?, concepts=?, facts=?,
-          text=?, importance=?, files_read=?, minhash_sig=?
+          text=?, importance=?, files_read=?, minhash_sig=?, lesson_learned=?, search_aliases=?
         WHERE id = ?
       `).run(
         obs.type, truncate(obs.title, 120), obs.subtitle || '',
@@ -362,6 +376,8 @@ importance: 0=not worth saving (pure browsing, trivial query, no learning value)
         obs.importance,
         JSON.stringify(obs.filesRead || []),
         minhashSig,
+        obs.lessonLearned || null,
+        obs.searchAliases || null,
         episode.savedId
       );
       savedId = episode.savedId;
@@ -432,7 +448,9 @@ Project: ${project}${promptCtx}
 Observations (${recentObs.length} total):
 ${obsList}
 
-JSON: {"request":"what the user was working on","completed":"specific items accomplished with file names","remaining_items":"specific unfinished items from the original request — compare investigation scope with actual changes to infer what was NOT yet done; be precise with file:issue format, or empty string if all done","next_steps":"suggested follow-up"}`;
+JSON: {"request":"what the user was working on","completed":"specific items accomplished with file names","remaining_items":"specific unfinished items from the original request — compare investigation scope with actual changes to infer what was NOT yet done; be precise with file:issue format, or empty string if all done","next_steps":"suggested follow-up","lessons":["non-obvious insights discovered during this session"],"key_decisions":["important design choices made and WHY"]}
+lessons: Only genuinely non-obvious insights (debugging discoveries, gotchas, architectural reasons). Empty array if routine.
+key_decisions: Only decisions with lasting impact (library choices, architecture, data model). Include reasoning. Empty array if none.`;
 
     if (!(await acquireLLMSlot())) {
       debugLog('WARN', 'llm-summary', 'semaphore timeout, skipping summary');
@@ -449,14 +467,19 @@ JSON: {"request":"what the user was working on","completed":"specific items acco
 
     if (llmParsed && llmParsed.request) {
       const now = new Date();
+      const lessonsJson = Array.isArray(llmParsed.lessons) && llmParsed.lessons.length > 0
+        ? JSON.stringify(llmParsed.lessons) : null;
+      const decisionsJson = Array.isArray(llmParsed.key_decisions) && llmParsed.key_decisions.length > 0
+        ? JSON.stringify(llmParsed.key_decisions) : null;
       db.prepare(`
-        INSERT INTO session_summaries (memory_session_id, project, request, investigated, learned, completed, next_steps, remaining_items, files_read, files_edited, notes, created_at, created_at_epoch)
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?, '[]', '[]', '', ?, ?)
+        INSERT INTO session_summaries (memory_session_id, project, request, investigated, learned, completed, next_steps, remaining_items, files_read, files_edited, notes, lessons, key_decisions, created_at, created_at_epoch)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, '[]', '[]', '', ?, ?, ?, ?)
       `).run(
         sessionId, project,
         llmParsed.request || '', llmParsed.investigated || '', llmParsed.learned || '',
         llmParsed.completed || '', llmParsed.next_steps || '',
         llmParsed.remaining_items || '',
+        lessonsJson, decisionsJson,
         now.toISOString(), now.getTime()
       );
     }