engrm 0.4.29 → 0.4.31

package/README.md

@@ -226,6 +226,8 @@ The MCP server exposes tools that supported agents can call directly:
 | `recent_handoffs` | List recent saved handoffs for the current project or workspace |
 | `load_handoff` | Open a saved handoff as a resume point for a new session |
 | `refresh_chat_recall` | Rehydrate the separate chat lane from a Claude transcript when a long session feels under-captured |
+| `repair_recall` | Rehydrate recent project/session recall from transcript or Claude history fallback when chat feels missing |
+| `resume_thread` | Build one clear resume point from handoff, current thread, recent chat, and unified recall |
 | `recent_chat` | Inspect the separate synced chat lane without mixing it into durable memory |
 | `search_chat` | Search recent chat recall with hybrid lexical + semantic matching, separately from reusable memory observations |
 | `search_recall` | Search durable memory and chat recall together when you do not want to guess the right lane |
@@ -250,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:
 
@@ -257,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
 
@@ -328,6 +335,19 @@ For long sessions, Engrm now also supports transcript-backed chat hydration:
   - fills gaps in the separate chat lane with transcript-backed messages
   - keeps those rows marked separately from hook-edge chat so recall can prefer the fuller thread
 
+- `repair_recall`
+  - scans recent sessions for the current project
+  - rehydrates recall from transcript files when they exist
+  - falls back to Claude `history.jsonl` when transcript/session alignment is missing
+  - reports whether recovered chat is `transcript-backed`, `history-backed`, or still only `hook-only`
+
+- `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:
 
 - refreshes transcript-backed chat recall for the active session
@@ -346,22 +366,25 @@ 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:
 
 - `capture_status` tells you whether prompt/tool hooks are live on this machine
-- `capture_quality` shows whether chat recall is transcript-backed or still hook-only across the workspace
+- `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`
-- `memory_console`, `project_memory_index`, and `session_context` now also show whether project chat recall is transcript-backed or only hook-captured
-- when chat continuity is only hook-captured, the workbench and startup hints now prefer `refresh_chat_recall`
+- `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
 - 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
@@ -371,7 +394,7 @@ What each tool is good for:
 - `session_tool_memory` shows which tool calls in one session turned into reusable memory and which did not
 - `project_memory_index` shows typed memory by repo, including continuity state and hot files
 - `workspace_memory_index` shows coverage across all repos on the machine
-- `recent_chat` / `search_chat` now report transcript-vs-hook coverage too, and `search_chat` will also mark when semantic ranking was available, so weak OpenClaw recall is easier to diagnose and refresh
+- `recent_chat` / `search_chat` now report transcript-vs-history-vs-hook coverage too, and `search_chat` will also mark when semantic ranking was available, so weak OpenClaw recall is easier to diagnose and repair
 
 ### Thin Tool Workflow
 

package/dist/hooks/post-tool-use.js

@@ -4007,6 +4007,22 @@ async function saveTranscriptResults(db, config, results, sessionId, cwd) {
 }
 
 // src/tools/recent-chat.ts
+function summarizeChatSources(messages) {
+  return messages.reduce((summary, message) => {
+    summary[getChatCaptureOrigin(message)] += 1;
+    return summary;
+  }, { transcript: 0, history: 0, hook: 0 });
+}
+function getChatCoverageState(messagesOrSummary) {
+  const summary = Array.isArray(messagesOrSummary) ? summarizeChatSources(messagesOrSummary) : messagesOrSummary;
+  if (summary.transcript > 0)
+    return "transcript-backed";
+  if (summary.history > 0)
+    return "history-backed";
+  if (summary.hook > 0)
+    return "hook-only";
+  return "none";
+}
 function getChatCaptureOrigin(message) {
   if (message.source_kind === "transcript")
     return "transcript";
@@ -4038,7 +4054,7 @@ function getSessionStory(db, input) {
     prompts,
     chat_messages: chatMessages,
     chat_source_summary: summarizeChatSources(chatMessages),
-    chat_coverage_state: chatMessages.some((message) => message.source_kind === "transcript") ? "transcript-backed" : chatMessages.length > 0 ? "hook-only" : "none",
+    chat_coverage_state: getChatCoverageState(chatMessages),
     tool_events: toolEvents,
     observations,
     handoffs,
@@ -4136,12 +4152,6 @@ function collectProvenanceSummary(observations) {
   }
   return Array.from(counts.entries()).map(([tool, count]) => ({ tool, count })).sort((a, b) => b.count - a.count || a.tool.localeCompare(b.tool)).slice(0, 6);
 }
-function summarizeChatSources(messages) {
-  return messages.reduce((summary, message) => {
-    summary[getChatCaptureOrigin(message)] += 1;
-    return summary;
-  }, { transcript: 0, history: 0, hook: 0 });
-}
 
 // src/tools/handoffs.ts
 async function upsertRollingHandoff(db, config, input) {

package/dist/hooks/pre-compact.js

@@ -2204,6 +2204,22 @@ function computeObservationPriority(obs, nowEpoch) {
 }
 
 // src/tools/recent-chat.ts
+function summarizeChatSources(messages) {
+  return messages.reduce((summary, message) => {
+    summary[getChatCaptureOrigin(message)] += 1;
+    return summary;
+  }, { transcript: 0, history: 0, hook: 0 });
+}
+function getChatCoverageState(messagesOrSummary) {
+  const summary = Array.isArray(messagesOrSummary) ? summarizeChatSources(messagesOrSummary) : messagesOrSummary;
+  if (summary.transcript > 0)
+    return "transcript-backed";
+  if (summary.history > 0)
+    return "history-backed";
+  if (summary.hook > 0)
+    return "hook-only";
+  return "none";
+}
 function getChatCaptureOrigin(message) {
   if (message.source_kind === "transcript")
     return "transcript";
@@ -2235,7 +2251,7 @@ function getSessionStory(db, input) {
     prompts,
     chat_messages: chatMessages,
     chat_source_summary: summarizeChatSources(chatMessages),
-    chat_coverage_state: chatMessages.some((message) => message.source_kind === "transcript") ? "transcript-backed" : chatMessages.length > 0 ? "hook-only" : "none",
+    chat_coverage_state: getChatCoverageState(chatMessages),
     tool_events: toolEvents,
     observations,
     handoffs,
@@ -2333,12 +2349,6 @@ function collectProvenanceSummary(observations) {
   }
   return Array.from(counts.entries()).map(([tool, count]) => ({ tool, count })).sort((a, b) => b.count - a.count || a.tool.localeCompare(b.tool)).slice(0, 6);
 }
-function summarizeChatSources(messages) {
-  return messages.reduce((summary, message) => {
-    summary[getChatCaptureOrigin(message)] += 1;
-    return summary;
-  }, { transcript: 0, history: 0, hook: 0 });
-}
 
 // src/tools/save.ts
 import { relative, isAbsolute } from "node:path";

package/dist/hooks/session-start.js

@@ -474,6 +474,22 @@ function normalizeItem(value) {
 }
 
 // src/tools/recent-chat.ts
+function summarizeChatSources(messages) {
+  return messages.reduce((summary, message) => {
+    summary[getChatCaptureOrigin(message)] += 1;
+    return summary;
+  }, { transcript: 0, history: 0, hook: 0 });
+}
+function getChatCoverageState(messagesOrSummary) {
+  const summary = Array.isArray(messagesOrSummary) ? summarizeChatSources(messagesOrSummary) : messagesOrSummary;
+  if (summary.transcript > 0)
+    return "transcript-backed";
+  if (summary.history > 0)
+    return "history-backed";
+  if (summary.hook > 0)
+    return "hook-only";
+  return "none";
+}
 function getChatCaptureOrigin(message) {
   if (message.source_kind === "transcript")
     return "transcript";
@@ -505,7 +521,7 @@ function getSessionStory(db, input) {
     prompts,
     chat_messages: chatMessages,
     chat_source_summary: summarizeChatSources(chatMessages),
-    chat_coverage_state: chatMessages.some((message) => message.source_kind === "transcript") ? "transcript-backed" : chatMessages.length > 0 ? "hook-only" : "none",
+    chat_coverage_state: getChatCoverageState(chatMessages),
     tool_events: toolEvents,
     observations,
     handoffs,
@@ -603,12 +619,6 @@ function collectProvenanceSummary(observations) {
   }
   return Array.from(counts.entries()).map(([tool, count]) => ({ tool, count })).sort((a, b) => b.count - a.count || a.tool.localeCompare(b.tool)).slice(0, 6);
 }
-function summarizeChatSources(messages) {
-  return messages.reduce((summary, message) => {
-    summary[getChatCaptureOrigin(message)] += 1;
-    return summary;
-  }, { transcript: 0, history: 0, hook: 0 });
-}
 
 // src/tools/save.ts
 import { relative, isAbsolute } from "node:path";
@@ -2929,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;
@@ -3070,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.29";
+var CLIENT_VERSION = "0.4.31";
 function hashFile(filePath) {
   try {
     if (!existsSync3(filePath))
@@ -5580,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) {
@@ -5700,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 = [];
@@ -5753,6 +5794,7 @@ function formatInspectHints(context, visibleObservationIds = []) {
     hints.push("activity_feed");
   }
   if ((context.recentPrompts?.length ?? 0) > 0 || (context.recentChatMessages?.length ?? 0) > 0 || context.observations.length > 0) {
+    hints.push("resume_thread");
     hints.push("search_recall");
   }
   if (context.observations.length > 0) {
@@ -5765,8 +5807,9 @@ function formatInspectHints(context, visibleObservationIds = []) {
   if ((context.recentChatMessages?.length ?? 0) > 0) {
     hints.push("recent_chat");
   }
-  if (hasHookOnlyRecentChat(context)) {
+  if (hasNonTranscriptRecentChat(context)) {
     hints.push("refresh_chat_recall");
+    hints.push("repair_recall");
   }
   if (continuityState !== "fresh") {
     hints.push("recent_chat");
@@ -6240,7 +6283,7 @@ function hasFreshContinuitySignal(context) {
 function getStartupContinuityState(context) {
   return classifyContinuityState(context.recentPrompts?.length ?? 0, context.recentToolEvents?.length ?? 0, context.recentHandoffs?.length ?? 0, context.recentChatMessages?.length ?? 0, context.recentSessions ?? [], context.recentOutcomes?.length ?? 0);
 }
-function hasHookOnlyRecentChat(context) {
+function hasNonTranscriptRecentChat(context) {
   const recentChat = context.recentChatMessages ?? [];
   return recentChat.length > 0 && !recentChat.some((message) => message.source_kind === "transcript");
 }

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.29",
+    client_version: "0.4.31",
     context_observations_injected: metrics?.contextObsInjected ?? 0,
     context_total_available: metrics?.contextTotalAvailable ?? 0,
     recall_attempts: metrics?.recallAttempts ?? 0,
@@ -4216,6 +4216,22 @@ async function saveTranscriptResults(db, config, results, sessionId, cwd) {
 }
 
 // src/tools/recent-chat.ts
+function summarizeChatSources(messages) {
+  return messages.reduce((summary, message) => {
+    summary[getChatCaptureOrigin(message)] += 1;
+    return summary;
+  }, { transcript: 0, history: 0, hook: 0 });
+}
+function getChatCoverageState(messagesOrSummary) {
+  const summary = Array.isArray(messagesOrSummary) ? summarizeChatSources(messagesOrSummary) : messagesOrSummary;
+  if (summary.transcript > 0)
+    return "transcript-backed";
+  if (summary.history > 0)
+    return "history-backed";
+  if (summary.hook > 0)
+    return "hook-only";
+  return "none";
+}
 function getChatCaptureOrigin(message) {
   if (message.source_kind === "transcript")
     return "transcript";
@@ -4247,7 +4263,7 @@ function getSessionStory(db, input) {
     prompts,
     chat_messages: chatMessages,
     chat_source_summary: summarizeChatSources(chatMessages),
-    chat_coverage_state: chatMessages.some((message) => message.source_kind === "transcript") ? "transcript-backed" : chatMessages.length > 0 ? "hook-only" : "none",
+    chat_coverage_state: getChatCoverageState(chatMessages),
     tool_events: toolEvents,
     observations,
     handoffs,
@@ -4345,12 +4361,6 @@ function collectProvenanceSummary(observations) {
   }
   return Array.from(counts.entries()).map(([tool, count]) => ({ tool, count })).sort((a, b) => b.count - a.count || a.tool.localeCompare(b.tool)).slice(0, 6);
 }
-function summarizeChatSources(messages) {
-  return messages.reduce((summary, message) => {
-    summary[getChatCaptureOrigin(message)] += 1;
-    return summary;
-  }, { transcript: 0, history: 0, hook: 0 });
-}
 
 // src/tools/handoffs.ts
 async function upsertRollingHandoff(db, config, input) {

package/dist/hooks/user-prompt-submit.js

@@ -3100,6 +3100,22 @@ async function saveTranscriptResults(db, config, results, sessionId, cwd) {
 }
 
 // src/tools/recent-chat.ts
+function summarizeChatSources(messages) {
+  return messages.reduce((summary, message) => {
+    summary[getChatCaptureOrigin(message)] += 1;
+    return summary;
+  }, { transcript: 0, history: 0, hook: 0 });
+}
+function getChatCoverageState(messagesOrSummary) {
+  const summary = Array.isArray(messagesOrSummary) ? summarizeChatSources(messagesOrSummary) : messagesOrSummary;
+  if (summary.transcript > 0)
+    return "transcript-backed";
+  if (summary.history > 0)
+    return "history-backed";
+  if (summary.hook > 0)
+    return "hook-only";
+  return "none";
+}
 function getChatCaptureOrigin(message) {
   if (message.source_kind === "transcript")
     return "transcript";
@@ -3131,7 +3147,7 @@ function getSessionStory(db, input) {
     prompts,
     chat_messages: chatMessages,
     chat_source_summary: summarizeChatSources(chatMessages),
-    chat_coverage_state: chatMessages.some((message) => message.source_kind === "transcript") ? "transcript-backed" : chatMessages.length > 0 ? "hook-only" : "none",
+    chat_coverage_state: getChatCoverageState(chatMessages),
     tool_events: toolEvents,
     observations,
     handoffs,
@@ -3229,12 +3245,6 @@ function collectProvenanceSummary(observations) {
   }
   return Array.from(counts.entries()).map(([tool, count]) => ({ tool, count })).sort((a, b) => b.count - a.count || a.tool.localeCompare(b.tool)).slice(0, 6);
 }
-function summarizeChatSources(messages) {
-  return messages.reduce((summary, message) => {
-    summary[getChatCaptureOrigin(message)] += 1;
-    return summary;
-  }, { transcript: 0, history: 0, hook: 0 });
-}
 
 // src/tools/handoffs.ts
 async function upsertRollingHandoff(db, config, input) {