engrm 0.4.30 → 0.4.31

package/README.md

@@ -252,6 +252,10 @@ If you are evaluating Engrm as an MCP server, start with this small set first:
   - verify which tools are actually producing durable memory and which plugins they exercise
 - `capture_quality`
   - check whether raw chronology is healthy across the workspace before judging memory quality
+- `resume_thread`
+  - get one direct “where were we?” resume point with freshness, source, tool trail, and next actions
+- `repair_recall`
+  - repair weak project recall from transcript or Claude history fallback before you give up on continuity
 
 These are the tools we should be comfortable pointing people to publicly first:
 
@@ -259,6 +263,7 @@ These are the tools we should be comfortable pointing people to publicly first:
 - local-first execution
 - durable memory output instead of raw transcript dumping
 - easy local inspection after capture
+- clear continuity recovery when switching devices or resuming long sessions
 
 ### Thin Tools, Thick Memory
 
@@ -339,6 +344,8 @@ For long sessions, Engrm now also supports transcript-backed chat hydration:
 - `resume_thread`
   - gives OpenClaw or Claude one direct “where were we?” action
   - combines the best handoff, the current thread, recent outcomes, recent chat, and unified recall
+  - reports whether the resume point is `strong`, `usable`, or `thin`
+  - can attempt recall repair first when continuity is still weak
   - makes Engrm usable as the primary live continuity layer instead of forcing agents to choose between low-level recall tools
 
 Before Claude compacts, Engrm now also:
@@ -359,13 +366,14 @@ Recommended flow:
 ```text
 1. capture_status
 2. memory_console
-3. activity_feed
-4. recent_sessions
-5. session_story
-6. tool_memory_index
-7. session_tool_memory
-8. project_memory_index
-9. workspace_memory_index
+3. resume_thread
+4. activity_feed
+5. recent_sessions
+6. session_story
+7. tool_memory_index
+8. session_tool_memory
+9. project_memory_index
+10. workspace_memory_index
 ```
 
 What each tool is good for:
@@ -373,9 +381,10 @@ What each tool is good for:
 - `capture_status` tells you whether prompt/tool hooks are live on this machine
 - `capture_quality` shows whether chat recall is transcript-backed, history-backed, or still hook-only across the workspace
 - `memory_console` gives the quickest project snapshot, including whether continuity is `fresh`, `thin`, or `cold`
+- `resume_thread` is the fastest “get me back into the live thread” path when you want freshness, source, next actions, tool trail, and chat in one place
 - `memory_console`, `project_memory_index`, and `session_context` now also show whether project chat recall is transcript-backed, history-backed, or only hook-captured
+- `memory_console`, `project_memory_index`, and `session_context` also expose resume-readiness directly, so you can see whether a repo is `live`, `recent`, or `stale` before drilling deeper
 - when chat continuity is only partial, the workbench and startup hints now prefer `repair_recall`, and still suggest `refresh_chat_recall` when a single session likely just needs transcript hydration
-- `resume_thread` is now the fastest “get me back into the live thread” path when you do not want to think about which continuity lane to inspect
 - the workbench and startup hints now also prefer `search_recall` as the first “what were we just talking about?” path when recent prompts/chat/observations exist
 - `search_chat` now uses hybrid lexical + semantic ranking when sqlite-vec and local embeddings are available, so recent conversation recall is less dependent on exact wording
 - `activity_feed` shows the merged chronology across prompts, tools, chat, handoffs, observations, and summaries

package/dist/hooks/session-start.js

@@ -2939,6 +2939,16 @@ function getRecentOutcomes2(db, projectId, userId, recentSessions) {
 }
 
 // src/tools/project-memory-index.ts
+function classifyResumeFreshness(sourceTimestamp) {
+  if (!sourceTimestamp)
+    return "stale";
+  const ageMs = Date.now() - sourceTimestamp * 1000;
+  if (ageMs <= 15 * 60 * 1000)
+    return "live";
+  if (ageMs <= 3 * 24 * 60 * 60 * 1000)
+    return "recent";
+  return "stale";
+}
 function classifyContinuityState(recentRequestsCount, recentToolsCount, recentHandoffsCount, recentChatCount, recentSessions, recentOutcomesCount) {
   const hasRaw = recentRequestsCount > 0 || recentToolsCount > 0;
   const hasResume = recentHandoffsCount > 0 || recentChatCount > 0;
@@ -3080,7 +3090,7 @@ import { existsSync as existsSync3, readFileSync as readFileSync2, writeFileSync
 import { join as join3 } from "node:path";
 import { homedir } from "node:os";
 var STATE_PATH = join3(homedir(), ".engrm", "config-fingerprint.json");
-var CLIENT_VERSION = "0.4.30";
+var CLIENT_VERSION = "0.4.31";
 function hashFile(filePath) {
   try {
     if (!existsSync3(filePath))
@@ -5590,6 +5600,10 @@ function formatVisibleStartupBrief(context) {
     }
   }
   lines.push(`${c2.cyan}Continuity:${c2.reset} ${continuityState} \u2014 ${truncateInline(describeContinuityState(continuityState), 160)}`);
+  const resumeReadiness = buildResumeReadinessLine(context);
+  if (resumeReadiness) {
+    lines.push(`${c2.cyan}Resume:${c2.reset} ${truncateInline(resumeReadiness, 160)}`);
+  }
   if (promptLines.length > 0) {
     lines.push(`${c2.cyan}Asked recently:${c2.reset}`);
     for (const item of promptLines) {
@@ -5710,6 +5724,23 @@ function buildLatestHandoffLines(context) {
   }
   return Array.from(new Set(lines.filter(Boolean))).slice(0, 2);
 }
+function buildResumeReadinessLine(context) {
+  const latestSession = context.recentSessions?.[0] ?? null;
+  const latestHandoff = context.recentHandoffs?.[0] ?? null;
+  const latestChatEpoch = (context.recentChatMessages ?? []).length > 0 ? context.recentChatMessages?.[context.recentChatMessages.length - 1]?.created_at_epoch ?? null : null;
+  const sourceTimestamp = latestChatEpoch ?? latestSession?.completed_at_epoch ?? latestSession?.started_at_epoch ?? latestHandoff?.created_at_epoch ?? null;
+  if (!sourceTimestamp)
+    return null;
+  const freshness = classifyResumeFreshness(sourceTimestamp);
+  const sourceSessionId = latestSession?.session_id ?? latestHandoff?.session_id ?? null;
+  const sourceDevice = latestSession?.device_id ?? latestHandoff?.device_id ?? null;
+  const bits = [freshness];
+  if (sourceDevice)
+    bits.push(`from ${sourceDevice}`);
+  if (sourceSessionId)
+    bits.push(sourceSessionId);
+  return bits.join(" \xB7 ");
+}
 function formatContextEconomics(data) {
   const totalMemories = Math.max(0, data.loaded + data.available);
   const parts = [];

package/dist/hooks/stop.js

@@ -3082,7 +3082,7 @@ function buildBeacon(db, config, sessionId, metrics) {
     sentinel_used: valueSignals.security_findings_count > 0,
     risk_score: riskScore,
     stacks_detected: stacks,
-    client_version: "0.4.30",
+    client_version: "0.4.31",
     context_observations_injected: metrics?.contextObsInjected ?? 0,
     context_total_available: metrics?.contextTotalAvailable ?? 0,
     recall_attempts: metrics?.recallAttempts ?? 0,

package/dist/server.js

@@ -16395,10 +16395,25 @@ function sanitizeFtsQuery(query) {
 }
 
 // src/tools/recent-chat.ts
+function dedupeChatMessages(messages) {
+  const bestByKey = new Map;
+  for (const message of messages) {
+    const key = buildDedupKey(message);
+    const existing = bestByKey.get(key);
+    if (!existing || compareChatPriority(message, existing) < 0) {
+      bestByKey.set(key, message);
+    }
+  }
+  return Array.from(bestByKey.values()).sort((a, b) => {
+    if (b.created_at_epoch !== a.created_at_epoch)
+      return b.created_at_epoch - a.created_at_epoch;
+    return b.id - a.id;
+  });
+}
 function getRecentChat(db, input) {
   const limit = Math.max(1, Math.min(input.limit ?? 20, 100));
   if (input.session_id) {
-    const messages2 = db.getSessionChatMessages(input.session_id, limit).slice(-limit).reverse();
+    const messages2 = dedupeChatMessages(db.getSessionChatMessages(input.session_id, limit * 3)).slice(0, limit);
     return {
       messages: messages2,
       session_count: countDistinctSessions(messages2),
@@ -16419,7 +16434,7 @@ function getRecentChat(db, input) {
       projectName = project.name;
     }
   }
-  const messages = db.getRecentChatMessages(projectId, limit, input.user_id);
+  const messages = dedupeChatMessages(db.getRecentChatMessages(projectId, limit * 3, input.user_id)).slice(0, limit);
   return {
     messages,
     project: projectName,
@@ -16456,6 +16471,25 @@ function getChatCaptureOrigin(message) {
   }
   return "hook";
 }
+function buildDedupKey(message) {
+  return [
+    message.session_id,
+    message.role,
+    message.content.toLowerCase().replace(/\s+/g, " ").trim()
+  ].join("::");
+}
+function compareChatPriority(a, b) {
+  const originScore = (message) => {
+    const origin = getChatCaptureOrigin(message);
+    return origin === "transcript" ? 0 : origin === "history" ? 1 : 2;
+  };
+  const originDelta = originScore(a) - originScore(b);
+  if (originDelta !== 0)
+    return originDelta;
+  if (b.created_at_epoch !== a.created_at_epoch)
+    return b.created_at_epoch - a.created_at_epoch;
+  return b.id - a.id;
+}
 
 // src/tools/search-chat.ts
 async function searchChat(db, input) {
@@ -16490,7 +16524,7 @@ async function searchChat(db, input) {
     semantic = db.searchChatVec(queryEmbedding, projectId, limit * 3, input.user_id);
   }
   const messageIds = mergeChatResults(db, lexical, semantic, normalizedQuery, limit);
-  const messages = messageIds.length > 0 ? db.getChatMessagesByIds(messageIds) : [];
+  const messages = messageIds.length > 0 ? dedupeChatMessages(db.getChatMessagesByIds(messageIds)).slice(0, limit) : [];
   return {
     messages,
     project: projectName,
@@ -16652,11 +16686,12 @@ function mergeRecallResults(memory, chat, limit, recentThreadQuery, sessionPrior
   }
   for (let index = 0;index < chat.length; index++) {
     const item = chat[index];
+    const origin = getChatCaptureOrigin(item);
     const base = 1 / (60 + index + 1);
     const ageHours = Math.max(0, (nowEpoch - item.created_at_epoch) / 3600);
     const immediacyBoost = ageHours < 1 ? 1.2 : ageHours < 6 ? 0.55 : 0;
     const recencyBoost = ageHours < 24 ? 0.18 : ageHours < 72 ? 0.08 : 0.02;
-    const sourceBoost = item.source_kind === "transcript" ? 0.1 : 0.04;
+    const sourceBoost = origin === "transcript" ? 0.1 : origin === "history" ? 0.07 : 0.04;
     const continuityBoost = recentThreadQuery ? 0.35 : 0;
     const sessionBoost = sessionPriority.get(item.session_id) ?? 0;
     scored.push({
@@ -16666,8 +16701,8 @@ function mergeRecallResults(memory, chat, limit, recentThreadQuery, sessionPrior
       session_id: item.session_id,
       id: item.id,
       role: item.role,
-      source_kind: getChatCaptureOrigin(item),
-      title: `${item.role} [${getChatCaptureOrigin(item)}]`,
+      source_kind: origin,
+      title: `${item.role} [${origin}]`,
       detail: item.content.replace(/\s+/g, " ").trim()
     });
   }
@@ -18336,6 +18371,8 @@ function getProjectMemoryIndex(db, input) {
     limit: 20
   });
   const recentChatCount = recentChat.messages.length;
+  const latestSession = recentSessions[0] ?? null;
+  const latestSummary = latestSession ? db.getSessionSummary(latestSession.session_id) : null;
   const recentOutcomes = observations.filter((obs) => ["bugfix", "feature", "refactor", "change", "decision"].includes(obs.type)).map((obs) => obs.title.trim()).filter((title) => title.length > 0 && !looksLikeFileOperationTitle3(title)).slice(0, 8);
   const captureSummary = summarizeCaptureState(recentSessions);
   const topTypes = Object.entries(counts).map(([type, count]) => ({ type, count })).sort((a, b) => b.count - a.count || a.type.localeCompare(b.type)).slice(0, 5);
@@ -18350,11 +18387,16 @@ function getProjectMemoryIndex(db, input) {
   ].filter(Boolean).join(`
 `));
   const continuityState = classifyContinuityState(recentRequestsCount, recentToolsCount, recentHandoffsCount.length, recentChatCount, recentSessions, recentOutcomes.length);
+  const sourceTimestamp = pickResumeSourceTimestamp(latestSession, recentChat.messages);
   return {
     project: project.name,
     canonical_id: project.canonical_id,
     continuity_state: continuityState,
     continuity_summary: describeContinuityState(continuityState),
+    resume_freshness: classifyResumeFreshness(sourceTimestamp),
+    resume_source_session_id: latestSession?.session_id ?? null,
+    resume_source_device_id: latestSession?.device_id ?? null,
+    resume_next_actions: collectNextActions(latestSummary?.next_steps),
     observation_counts: counts,
     recent_sessions: recentSessions,
     recent_outcomes: recentOutcomes,
@@ -18379,6 +18421,28 @@ function getProjectMemoryIndex(db, input) {
     suggested_tools: suggestedTools
   };
 }
+function pickResumeSourceTimestamp(latestSession, messages) {
+  const latestChatEpoch = messages.length > 0 ? messages[messages.length - 1]?.created_at_epoch ?? null : null;
+  return latestChatEpoch ?? latestSession?.completed_at_epoch ?? latestSession?.started_at_epoch ?? null;
+}
+function classifyResumeFreshness(sourceTimestamp) {
+  if (!sourceTimestamp)
+    return "stale";
+  const ageMs = Date.now() - sourceTimestamp * 1000;
+  if (ageMs <= 15 * 60 * 1000)
+    return "live";
+  if (ageMs <= 3 * 24 * 60 * 60 * 1000)
+    return "recent";
+  return "stale";
+}
+function collectNextActions(value) {
+  if (!value)
+    return [];
+  const normalized = value.split(/\n+/).map((line) => line.replace(/^[\s*-]+/, "").trim()).filter((line) => line.length > 0);
+  if (normalized.length > 1)
+    return normalized.slice(0, 5);
+  return value.split(/[.;](?:\s+|$)/).map((item) => item.replace(/^[\s*-]+/, "").trim()).filter((item) => item.length > 0).slice(0, 5);
+}
 function classifyContinuityState(recentRequestsCount, recentToolsCount, recentHandoffsCount, recentChatCount, recentSessions, recentOutcomesCount) {
   const hasRaw = recentRequestsCount > 0 || recentToolsCount > 0;
   const hasResume = recentHandoffsCount > 0 || recentChatCount > 0;
@@ -18523,6 +18587,10 @@ function getMemoryConsole(db, input) {
     capture_mode: requests.length > 0 || tools.length > 0 ? "rich" : "observations-only",
     continuity_state: continuityState,
     continuity_summary: projectIndex?.continuity_summary ?? describeContinuityState(continuityState),
+    resume_freshness: projectIndex?.resume_freshness ?? "stale",
+    resume_source_session_id: projectIndex?.resume_source_session_id ?? sessions[0]?.session_id ?? null,
+    resume_source_device_id: projectIndex?.resume_source_device_id ?? sessions[0]?.device_id ?? null,
+    resume_next_actions: projectIndex?.resume_next_actions ?? [],
     sessions,
     requests,
     tools,
@@ -19399,14 +19467,22 @@ function getSessionContext(db, input) {
     limit: 8
   });
   const recentChatMessages = recentChat.messages.length;
+  const latestSession = context.recentSessions?.[0] ?? null;
+  const latestSummary = latestSession ? db.getSessionSummary(latestSession.session_id) : null;
   const captureState = recentRequests > 0 && recentTools > 0 ? "rich" : recentRequests > 0 || recentTools > 0 ? "partial" : "summary-only";
   const hotFiles = buildHotFiles(context);
   const continuityState = classifyContinuityState(recentRequests, recentTools, recentHandoffs, recentChatMessages, context.recentSessions ?? [], (context.recentOutcomes ?? []).length);
+  const latestChatEpoch = recentChat.messages.length > 0 ? recentChat.messages[recentChat.messages.length - 1]?.created_at_epoch ?? null : null;
+  const resumeTimestamp = latestChatEpoch ?? latestSession?.completed_at_epoch ?? latestSession?.started_at_epoch ?? null;
   return {
     project_name: context.project_name,
     canonical_id: context.canonical_id,
     continuity_state: continuityState,
     continuity_summary: describeContinuityState(continuityState),
+    resume_freshness: classifyResumeFreshness(resumeTimestamp),
+    resume_source_session_id: latestSession?.session_id ?? null,
+    resume_source_device_id: latestSession?.device_id ?? null,
+    resume_next_actions: collectNextActions2(latestSummary?.next_steps),
     session_count: context.session_count,
     total_active: context.total_active,
     recent_requests: recentRequests,
@@ -19429,6 +19505,14 @@ function getSessionContext(db, input) {
     preview
   };
 }
+function collectNextActions2(value) {
+  if (!value)
+    return [];
+  const normalized = value.split(/\n+/).map((line) => line.replace(/^[\s*-]+/, "").trim()).filter((line) => line.length > 0);
+  if (normalized.length > 1)
+    return normalized.slice(0, 5);
+  return value.split(/[.;](?:\s+|$)/).map((item) => item.replace(/^[\s*-]+/, "").trim()).filter((item) => item.length > 0).slice(0, 5);
+}
 function buildHotFiles(context) {
   const counts = new Map;
   for (const obs of context.observations) {
@@ -19896,45 +19980,53 @@ async function repairRecall(db, config2, input = {}) {
 }
 
 // src/tools/resume-thread.ts
-async function resumeThread(db, input = {}) {
+async function resumeThread(db, config2, input = {}) {
   const cwd = input.cwd ?? process.cwd();
   const limit = Math.max(2, Math.min(input.limit ?? 5, 8));
+  const repairIfNeeded = input.repair_if_needed !== false;
   const detected = detectProject(cwd);
   const project = db.getProjectByCanonicalId(detected.canonical_id);
-  const context = getSessionContext(db, {
-    cwd,
-    user_id: input.user_id,
-    current_device_id: input.current_device_id
-  });
-  const handoffResult = loadHandoff(db, {
-    cwd,
-    project_scoped: true,
-    user_id: input.user_id,
-    current_device_id: input.current_device_id
-  });
-  const handoff = handoffResult.handoff;
-  const recentChat = getRecentChat(db, {
-    cwd,
-    project_scoped: true,
-    user_id: input.user_id,
-    limit: Math.max(limit, 4)
-  });
-  const recentSessions = getRecentSessions(db, {
-    cwd,
-    project_scoped: true,
-    user_id: input.user_id,
-    limit: 3
-  }).sessions;
-  const recall = await searchRecall(db, {
-    query: "what were we just talking about",
-    cwd,
-    project_scoped: true,
-    user_id: input.user_id,
-    limit
-  });
+  let snapshot = await buildResumeSnapshot(db, cwd, input.user_id, input.current_device_id, limit);
+  let repairResult = null;
+  const shouldRepair = repairIfNeeded && snapshot.recentChat.coverage_state !== "transcript-backed" && (snapshot.recentChat.messages.length > 0 || snapshot.recentSessions.length > 0 || snapshot.context?.continuity_state !== "cold");
+  if (shouldRepair) {
+    repairResult = await repairRecall(db, config2, {
+      cwd,
+      user_id: input.user_id,
+      limit: Math.max(limit, 4)
+    });
+    if (repairResult.imported_chat_messages > 0) {
+      snapshot = await buildResumeSnapshot(db, cwd, input.user_id, input.current_device_id, limit);
+    }
+  }
+  const { context, handoff, recentChat, recentSessions, recall } = snapshot;
   const latestSession = recentSessions[0] ?? null;
+  const latestSummary = latestSession ? db.getSessionSummary(latestSession.session_id) : null;
   const inferredRequest = latestSession?.request?.trim() || null;
   const currentThread = extractCurrentThread(handoff) || latestSession?.current_thread?.trim() || inferredRequest || context?.recent_outcomes[0] || recentChat.messages[recentChat.messages.length - 1]?.content.replace(/\s+/g, " ").trim().slice(0, 180) || null;
+  const toolTrail = collectToolTrail(latestSession);
+  const hotFiles = collectHotFiles2(latestSession, context?.hot_files ?? []);
+  const nextActions = collectNextActions3(latestSummary?.next_steps);
+  const sourceTimestamp = pickSourceTimestamp(latestSession, recentChat.messages);
+  const resumeBasis = buildResumeBasis({
+    handoff,
+    continuityState: context?.continuity_state ?? "cold",
+    chatCoverageState: recentChat.coverage_state,
+    latestRequest: inferredRequest,
+    currentThread,
+    recallHits: recall.results,
+    recentOutcomes: context?.recent_outcomes ?? [],
+    toolTrail,
+    hotFiles,
+    nextActions
+  });
+  const resumeConfidence = classifyResumeConfidence({
+    handoff,
+    continuityState: context?.continuity_state ?? "cold",
+    chatCoverageState: recentChat.coverage_state,
+    recallHits: recall.results,
+    currentThread
+  });
   const suggestedTools = Array.from(new Set([
     "search_recall",
     ...recentChat.coverage_state !== "transcript-backed" && recentChat.messages.length > 0 ? ["repair_recall", "refresh_chat_recall"] : [],
@@ -19945,6 +20037,16 @@ async function resumeThread(db, input = {}) {
     project_name: project?.name ?? context?.project_name ?? null,
     continuity_state: context?.continuity_state ?? "cold",
     continuity_summary: context?.continuity_summary ?? "No fresh repo-local continuity yet; older memory should be treated cautiously.",
+    resume_freshness: classifyResumeFreshness2(sourceTimestamp),
+    resume_source_session_id: latestSession?.session_id ?? null,
+    resume_source_device_id: handoff?.device_id ?? latestSession?.device_id ?? null,
+    resume_confidence: resumeConfidence,
+    resume_basis: resumeBasis,
+    repair_attempted: shouldRepair,
+    repair_result: repairResult ? {
+      imported_chat_messages: repairResult.imported_chat_messages,
+      sessions_with_imports: repairResult.sessions_with_imports
+    } : null,
     latest_request: inferredRequest,
     current_thread: currentThread,
     handoff: handoff ? {
@@ -19952,6 +20054,9 @@ async function resumeThread(db, input = {}) {
       title: handoff.title,
       source: extractHandoffSource(handoff)
     } : null,
+    tool_trail: toolTrail,
+    hot_files: hotFiles,
+    next_actions: nextActions,
     recent_outcomes: context?.recent_outcomes ?? [],
     chat_coverage_state: recentChat.coverage_state,
     recent_chat: recentChat.messages.slice(-4).map((message) => ({
@@ -19964,6 +20069,45 @@ async function resumeThread(db, input = {}) {
     suggested_tools: suggestedTools
   };
 }
+async function buildResumeSnapshot(db, cwd, userId, currentDeviceId, limit) {
+  const context = getSessionContext(db, {
+    cwd,
+    user_id: userId,
+    current_device_id: currentDeviceId
+  });
+  const handoffResult = loadHandoff(db, {
+    cwd,
+    project_scoped: true,
+    user_id: userId,
+    current_device_id: currentDeviceId
+  });
+  const recentChat = getRecentChat(db, {
+    cwd,
+    project_scoped: true,
+    user_id: userId,
+    limit: Math.max(limit, 4)
+  });
+  const recentSessions = getRecentSessions(db, {
+    cwd,
+    project_scoped: true,
+    user_id: userId,
+    limit: 3
+  }).sessions;
+  const recall = await searchRecall(db, {
+    query: "what were we just talking about",
+    cwd,
+    project_scoped: true,
+    user_id: userId,
+    limit
+  });
+  return {
+    context,
+    handoff: handoffResult.handoff,
+    recentChat,
+    recentSessions,
+    recall
+  };
+}
 function extractCurrentThread(handoff) {
   const narrative = handoff?.narrative ?? "";
   const match = narrative.match(/Current thread:\s*(.+)/i);
@@ -19972,6 +20116,87 @@ function extractCurrentThread(handoff) {
 function extractHandoffSource(handoff) {
   return handoff.device_id ?? null;
 }
+function pickSourceTimestamp(latestSession, messages) {
+  const latestChatEpoch = messages.length > 0 ? messages[messages.length - 1]?.created_at_epoch ?? null : null;
+  return latestChatEpoch ?? latestSession?.completed_at_epoch ?? latestSession?.started_at_epoch ?? null;
+}
+function classifyResumeFreshness2(sourceTimestamp) {
+  if (!sourceTimestamp)
+    return "stale";
+  const ageMs = Date.now() - sourceTimestamp * 1000;
+  if (ageMs <= 15 * 60 * 1000)
+    return "live";
+  if (ageMs <= 3 * 24 * 60 * 60 * 1000)
+    return "recent";
+  return "stale";
+}
+function classifyResumeConfidence(input) {
+  const hasStrongChat = input.chatCoverageState === "transcript-backed" || input.chatCoverageState === "history-backed";
+  const hasRecall = input.recallHits.length > 0;
+  if (input.handoff && input.currentThread && (input.continuityState === "fresh" || hasStrongChat || hasRecall)) {
+    return "strong";
+  }
+  if (input.currentThread && (input.continuityState !== "cold" || hasStrongChat || hasRecall)) {
+    return "usable";
+  }
+  return "thin";
+}
+function buildResumeBasis(input) {
+  const basis = [];
+  if (input.handoff)
+    basis.push("explicit handoff available");
+  if (input.currentThread)
+    basis.push("current thread recovered");
+  if (input.latestRequest)
+    basis.push("latest request recovered");
+  if (input.recentOutcomes.length > 0)
+    basis.push("recent outcomes available");
+  if (input.nextActions.length > 0)
+    basis.push("next actions available");
+  if (input.toolTrail.length > 0)
+    basis.push("recent tool trail available");
+  if (input.hotFiles.length > 0)
+    basis.push("hot files available");
+  if (input.recallHits.some((item) => item.kind === "chat"))
+    basis.push("live chat recall available");
+  if (input.chatCoverageState === "transcript-backed")
+    basis.push("transcript-backed chat continuity");
+  if (input.chatCoverageState === "history-backed")
+    basis.push("history-backed chat continuity");
+  if (input.continuityState === "fresh")
+    basis.push("fresh repo-local continuity");
+  if (basis.length === 0)
+    basis.push("thin fallback only");
+  return basis.slice(0, 6);
+}
+function collectToolTrail(session) {
+  const parsed = parseJsonArray4(session?.recent_tool_names);
+  return parsed.slice(0, 5);
+}
+function collectHotFiles2(session, fallback) {
+  const parsed = parseJsonArray4(session?.hot_files).map((path) => ({ path, count: 1 }));
+  if (parsed.length > 0)
+    return parsed.slice(0, 5);
+  return fallback.slice(0, 5);
+}
+function collectNextActions3(value) {
+  if (!value)
+    return [];
+  const normalized = value.split(/\n+/).map((line) => line.replace(/^[\s*-]+/, "").trim()).filter((line) => line.length > 0);
+  if (normalized.length > 1)
+    return normalized.slice(0, 5);
+  return value.split(/[.;](?:\s+|$)/).map((item) => item.replace(/^[\s*-]+/, "").trim()).filter((item) => item.length > 0).slice(0, 5);
+}
+function parseJsonArray4(value) {
+  if (!value)
+    return [];
+  try {
+    const parsed = JSON.parse(value);
+    return Array.isArray(parsed) ? parsed.filter((item) => typeof item === "string" && item.trim().length > 0) : [];
+  } catch {
+    return [];
+  }
+}
 
 // src/tools/send-message.ts
 async function sendMessage(db, config2, input) {
@@ -20511,8 +20736,8 @@ function buildSessionHandoffMetadata(prompts, toolEvents, observations) {
   const recentToolNames = [...new Set(toolEvents.slice(-8).map((tool) => tool.tool_name).filter(Boolean))];
   const recentToolCommands = [...new Set(toolEvents.slice(-5).map((tool) => (tool.command ?? tool.file_path ?? "").trim()).filter(Boolean))];
   const hotFiles = [...new Set(observations.flatMap((obs) => [
-    ...parseJsonArray4(obs.files_modified),
-    ...parseJsonArray4(obs.files_read)
+    ...parseJsonArray5(obs.files_modified),
+    ...parseJsonArray5(obs.files_read)
   ]).filter(Boolean))].slice(0, 6);
   const recentOutcomes = observations.filter((obs) => ["bugfix", "feature", "refactor", "change", "decision"].includes(obs.type)).map((obs) => obs.title.trim()).filter((title) => title.length > 0).slice(0, 6);
   const captureState = prompts.length > 0 && toolEvents.length > 0 ? "rich" : prompts.length > 0 || toolEvents.length > 0 ? "partial" : "summary-only";
@@ -20570,7 +20795,7 @@ function compactFileHint(value) {
     return value;
   return parts.slice(-2).join("/");
 }
-function parseJsonArray4(value) {
+function parseJsonArray5(value) {
   if (!value)
     return [];
   try {
@@ -21814,7 +22039,7 @@ process.on("SIGTERM", () => {
 });
 var server = new McpServer({
   name: "engrm",
-  version: "0.4.30"
+  version: "0.4.31"
 });
 server.tool("save_observation", "Save an observation to memory", {
   type: exports_external.enum([
@@ -22262,19 +22487,31 @@ ${rows}`
 server.tool("resume_thread", "Build a clear resume point for the current project by combining handoff, live recall, current thread, and recent chat continuity.", {
   cwd: exports_external.string().optional().describe("Optional cwd override for the project to resume"),
   limit: exports_external.number().optional().describe("Max recall hits/chat snippets to include"),
-  user_id: exports_external.string().optional().describe("Optional user override")
+  user_id: exports_external.string().optional().describe("Optional user override"),
+  repair_if_needed: exports_external.boolean().optional().describe("If true, attempt recall repair before resuming when continuity is still weak")
 }, async (params) => {
-  const result = await resumeThread(db, {
+  const result = await resumeThread(db, config2, {
     cwd: params.cwd ?? process.cwd(),
     limit: params.limit,
     user_id: params.user_id ?? config2.user_id,
-    current_device_id: config2.device_id
+    current_device_id: config2.device_id,
+    repair_if_needed: params.repair_if_needed
   });
   const projectLine = result.project_name ? `Project: ${result.project_name}
 ` : "";
   const handoffLine = result.handoff ? `Handoff: #${result.handoff.id} ${result.handoff.title}${result.handoff.source ? ` (${result.handoff.source})` : ""}
 ` : `Handoff: (none)
 `;
+  const basisLines = result.resume_basis.length > 0 ? result.resume_basis.map((item) => `- ${item}`).join(`
+`) : "- (none)";
+  const toolTrailLines = result.tool_trail.length > 0 ? result.tool_trail.map((item) => `- ${item}`).join(`
+`) : "- (none)";
+  const hotFileLines = result.hot_files.length > 0 ? result.hot_files.map((item) => `- ${item.path}${item.count > 1 ? ` (${item.count})` : ""}`).join(`
+`) : "- (none)";
+  const nextActionLines = result.next_actions.length > 0 ? result.next_actions.map((item) => `- ${item}`).join(`
+`) : "- (none)";
+  const repairLine = result.repair_attempted ? `Recall repair: attempted${result.repair_result ? ` · imported ${result.repair_result.imported_chat_messages} chat across ${result.repair_result.sessions_with_imports} session(s)` : ""}
+` : "";
   const outcomes = result.recent_outcomes.length > 0 ? result.recent_outcomes.map((item) => `- ${item}`).join(`
 `) : "- (none)";
   const chatLines = result.recent_chat.length > 0 ? result.recent_chat.map((item) => `- [${item.role}] [${item.source}] ${item.content.slice(0, 180)}`).join(`
@@ -22296,11 +22533,26 @@ server.tool("resume_thread", "Build a clear resume point for the current project
       {
         type: "text",
         text: `${projectLine}` + `Continuity: ${result.continuity_state} — ${result.continuity_summary}
-` + `Current thread: ${result.current_thread ?? "(unknown)"}
+` + `Freshness: ${result.resume_freshness}
+` + `Source: ${result.resume_source_session_id ?? "(unknown session)"}${result.resume_source_device_id ? ` (${result.resume_source_device_id})` : ""}
+` + `Resume confidence: ${result.resume_confidence}
+` + repairLine + `Current thread: ${result.current_thread ?? "(unknown)"}
 ` + `Latest request: ${result.latest_request ?? "(none)"}
 ` + `${handoffLine}` + `Chat recall: ${result.chat_coverage_state}
 ` + `Suggested tools: ${result.suggested_tools.join(", ") || "(none)"}
 
+` + `Resume basis:
+${basisLines}
+
+` + `Tool trail:
+${toolTrailLines}
+
+` + `Hot files:
+${hotFileLines}
+
+` + `Next actions:
+${nextActionLines}
+
 ` + `Recent outcomes:
 ${outcomes}
 
@@ -22633,12 +22885,17 @@ server.tool("memory_console", "Show a high-signal local overview of what Engrm c
       {
         type: "text",
         text: `${projectLine}` + `${captureLine}` + `Continuity: ${result.continuity_state} — ${result.continuity_summary}
+` + `Resume readiness: ${result.resume_freshness} · ${result.resume_source_session_id ?? "(unknown session)"}${result.resume_source_device_id ? ` (${result.resume_source_device_id})` : ""}
 ` + `Chat recall: ${result.chat_coverage_state} · ${result.recent_chat.length} messages across ${result.recent_chat_sessions} sessions (transcript ${result.chat_source_summary.transcript}, history ${result.chat_source_summary.history}, hook ${result.chat_source_summary.hook})
 ` + `${typeof result.assistant_checkpoint_count === "number" ? `Assistant checkpoints: ${result.assistant_checkpoint_count}
 ` : ""}` + `Handoffs: ${result.saved_handoffs} saved, ${result.rolling_handoff_drafts} rolling drafts
 ` + `${typeof result.estimated_read_tokens === "number" ? `Estimated read cost: ~${result.estimated_read_tokens}t
 ` : ""}` + `Suggested tools: ${result.suggested_tools.join(", ") || "(none)"}
 
+` + `Next actions:
+${result.resume_next_actions.length > 0 ? result.resume_next_actions.map((item) => `- ${item}`).join(`
+`) : "- (none)"}
+
 ` + `Top types:
 ${topTypes}
 
@@ -22832,6 +23089,7 @@ server.tool("session_context", "Preview the exact project memory context Engrm w
         text: `Project: ${result.project_name}
 ` + `Canonical ID: ${result.canonical_id}
 ` + `Continuity: ${result.continuity_state} — ${result.continuity_summary}
+` + `Resume readiness: ${result.resume_freshness} · ${result.resume_source_session_id ?? "(unknown session)"}${result.resume_source_device_id ? ` (${result.resume_source_device_id})` : ""}
 ` + `Loaded observations: ${result.session_count}
 ` + `Searchable total: ${result.total_active}
 ` + `Recent requests: ${result.recent_requests}
@@ -22842,6 +23100,7 @@ server.tool("session_context", "Preview the exact project memory context Engrm w
 ` + `Recent chat messages: ${result.recent_chat_messages}
 ` + `Chat recall: ${result.chat_coverage_state} · ${result.recent_chat_sessions} sessions (transcript ${result.chat_source_summary.transcript}, history ${result.chat_source_summary.history}, hook ${result.chat_source_summary.hook})
 ` + `Latest handoff: ${result.latest_handoff_title ?? "(none)"}
+` + `Next actions: ${result.resume_next_actions.length > 0 ? result.resume_next_actions.join(" | ") : "(none)"}
 ` + `Raw chronology active: ${result.raw_capture_active ? "yes" : "no"}
 
 ` + result.preview
@@ -22914,6 +23173,7 @@ server.tool("project_memory_index", "Show a typed local memory index for the cur
         text: `Project: ${result.project}
 ` + `Canonical ID: ${result.canonical_id}
 ` + `Continuity: ${result.continuity_state} — ${result.continuity_summary}
+` + `Resume readiness: ${result.resume_freshness} · ${result.resume_source_session_id ?? "(unknown session)"}${result.resume_source_device_id ? ` (${result.resume_source_device_id})` : ""}
 ` + `Recent requests captured: ${result.recent_requests_count}
 ` + `Recent tools captured: ${result.recent_tools_count}
 
@@ -22928,6 +23188,10 @@ server.tool("project_memory_index", "Show a typed local memory index for the cur
 ` + `Estimated read cost: ~${result.estimated_read_tokens}t
 ` + `Suggested tools: ${result.suggested_tools.join(", ") || "(none)"}
 
+` + `Next actions:
+${result.resume_next_actions.length > 0 ? result.resume_next_actions.map((item) => `- ${item}`).join(`
+`) : "- (none)"}
+
 ` + `Observation counts:
 ${counts}
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "engrm",
-  "version": "0.4.30",
-  "description": "Shared memory across devices, sessions, and coding agents",
+  "version": "0.4.31",
+  "description": "Shared memory across devices, sessions, and agents, with thin MCP tools for durable capture and live continuity",
   "mcpName": "io.github.dr12hes/engrm",
   "type": "module",
   "main": "dist/server.js",