engrm 0.4.30 → 0.4.32

package/README.md

@@ -226,8 +226,10 @@ 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 |
+| `repair_recall` | Use when continuity feels thin; rehydrate recent recall from transcript or Claude history fallback |
+| `list_recall_items` | Use first when continuity feels fuzzy; list the best current handoffs, threads, chat snippets, and memory entries |
+| `load_recall_item` | Use after `list_recall_items`; load one exact recall item key |
+| `resume_thread` | Use first when you want one direct "where were we?" answer 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 |
@@ -252,6 +254,14 @@ 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
+- `list_recall_items`
+  - list the best current handoffs, session threads, chat snippets, and memory entries before opening one exact item
+- `load_recall_item`
+  - open one exact recall key from the index without falling back to fuzzy retrieval
+- `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 +269,23 @@ 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
+
+### Recall Protocol
+
+When continuity feels fuzzy, the default path is:
+
+1. `resume_thread`
+2. `list_recall_items`
+3. `load_recall_item`
+4. `repair_recall`
+
+How to use it:
+
+- `resume_thread` is the fastest "get me back into the live thread" action
+- `list_recall_items` is the deterministic directory-first path when you want to inspect candidates before opening one
+- `load_recall_item` opens an exact handoff, thread, chat, or memory key returned by the index
+- `repair_recall` is the repair step when continuity is still thin, hook-only, or under-captured
 
 ### Thin Tools, Thick Memory
 
@@ -339,6 +366,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 +388,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 +403,12 @@ 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
+- `list_recall_items` is the deterministic directory-first path when you want to inspect the best candidate handoffs/threads before opening one exact item
+- `load_recall_item` completes that protocol by letting agents open one exact recall key directly after listing
 - `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/pre-compact.js

@@ -3673,6 +3673,14 @@ function formatContextForInjection(context) {
     }
     lines.push("");
   }
+  const recallIndexLines = buildRecallIndexLines(context);
+  if (recallIndexLines.length > 0) {
+    lines.push("## Recall Index");
+    for (const line of recallIndexLines) {
+      lines.push(line);
+    }
+    lines.push("");
+  }
   if (context.recentChatMessages && context.recentChatMessages.length > 0) {
     lines.push("## Recent Chat");
     for (const message of context.recentChatMessages.slice(0, 4).reverse()) {
@@ -3775,6 +3783,25 @@ function formatContextForInjection(context) {
   return lines.join(`
 `);
 }
+function buildRecallIndexLines(context) {
+  const lines = [];
+  for (const handoff of context.recentHandoffs?.slice(0, 2) ?? []) {
+    const title = handoff.title.replace(/^Handoff(?: Draft)?:\s*/i, "").replace(/\s+·\s+\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}Z$/, "").trim();
+    if (!title)
+      continue;
+    lines.push(`- handoff:${handoff.id} — ${truncateText(title, 140)}`);
+  }
+  for (const session of context.recentSessions?.slice(0, 2) ?? []) {
+    const title = session.current_thread ?? session.request ?? session.completed ?? session.session_id;
+    if (!title)
+      continue;
+    lines.push(`- session:${session.session_id} — ${truncateText(title.replace(/\s+/g, " ").trim(), 140)}`);
+  }
+  for (const message of context.recentChatMessages?.slice(0, 2) ?? []) {
+    lines.push(`- chat:${message.id} — ${truncateText(message.content.replace(/\s+/g, " ").trim(), 140)}`);
+  }
+  return Array.from(new Set(lines)).slice(0, 5);
+}
 function formatSessionBrief(summary) {
   const lines = [];
   const heading = summary.request ? `### ${truncateText(summary.request, 120)}` : `### Session ${summary.session_id.slice(0, 8)}`;

package/dist/hooks/session-start.js

@@ -1943,6 +1943,14 @@ function formatContextForInjection(context) {
     }
     lines.push("");
   }
+  const recallIndexLines = buildRecallIndexLines(context);
+  if (recallIndexLines.length > 0) {
+    lines.push("## Recall Index");
+    for (const line of recallIndexLines) {
+      lines.push(line);
+    }
+    lines.push("");
+  }
   if (context.recentChatMessages && context.recentChatMessages.length > 0) {
     lines.push("## Recent Chat");
     for (const message of context.recentChatMessages.slice(0, 4).reverse()) {
@@ -2045,6 +2053,25 @@ function formatContextForInjection(context) {
   return lines.join(`
 `);
 }
+function buildRecallIndexLines(context) {
+  const lines = [];
+  for (const handoff of context.recentHandoffs?.slice(0, 2) ?? []) {
+    const title = handoff.title.replace(/^Handoff(?: Draft)?:\s*/i, "").replace(/\s+·\s+\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}Z$/, "").trim();
+    if (!title)
+      continue;
+    lines.push(`- handoff:${handoff.id} — ${truncateText(title, 140)}`);
+  }
+  for (const session of context.recentSessions?.slice(0, 2) ?? []) {
+    const title = session.current_thread ?? session.request ?? session.completed ?? session.session_id;
+    if (!title)
+      continue;
+    lines.push(`- session:${session.session_id} — ${truncateText(title.replace(/\s+/g, " ").trim(), 140)}`);
+  }
+  for (const message of context.recentChatMessages?.slice(0, 2) ?? []) {
+    lines.push(`- chat:${message.id} — ${truncateText(message.content.replace(/\s+/g, " ").trim(), 140)}`);
+  }
+  return Array.from(new Set(lines)).slice(0, 5);
+}
 function formatSessionBrief(summary) {
   const lines = [];
   const heading = summary.request ? `### ${truncateText(summary.request, 120)}` : `### Session ${summary.session_id.slice(0, 8)}`;
@@ -2618,6 +2645,14 @@ function formatContextForInjection2(context) {
     }
     lines.push("");
   }
+  const recallIndexLines = buildRecallIndexLines2(context);
+  if (recallIndexLines.length > 0) {
+    lines.push("## Recall Index");
+    for (const line of recallIndexLines) {
+      lines.push(line);
+    }
+    lines.push("");
+  }
   if (context.recentChatMessages && context.recentChatMessages.length > 0) {
     lines.push("## Recent Chat");
     for (const message of context.recentChatMessages.slice(0, 4).reverse()) {
@@ -2720,6 +2755,25 @@ function formatContextForInjection2(context) {
   return lines.join(`
 `);
 }
+function buildRecallIndexLines2(context) {
+  const lines = [];
+  for (const handoff of context.recentHandoffs?.slice(0, 2) ?? []) {
+    const title = handoff.title.replace(/^Handoff(?: Draft)?:\s*/i, "").replace(/\s+·\s+\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}Z$/, "").trim();
+    if (!title)
+      continue;
+    lines.push(`- handoff:${handoff.id} — ${truncateText2(title, 140)}`);
+  }
+  for (const session of context.recentSessions?.slice(0, 2) ?? []) {
+    const title = session.current_thread ?? session.request ?? session.completed ?? session.session_id;
+    if (!title)
+      continue;
+    lines.push(`- session:${session.session_id} — ${truncateText2(title.replace(/\s+/g, " ").trim(), 140)}`);
+  }
+  for (const message of context.recentChatMessages?.slice(0, 2) ?? []) {
+    lines.push(`- chat:${message.id} — ${truncateText2(message.content.replace(/\s+/g, " ").trim(), 140)}`);
+  }
+  return Array.from(new Set(lines)).slice(0, 5);
+}
 function formatSessionBrief2(summary) {
   const lines = [];
   const heading = summary.request ? `### ${truncateText2(summary.request, 120)}` : `### Session ${summary.session_id.slice(0, 8)}`;
@@ -2939,6 +2993,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 +3144,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.32";
 function hashFile(filePath) {
   try {
     if (!existsSync3(filePath))
@@ -5590,6 +5654,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 +5778,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 = [];
@@ -5763,6 +5848,8 @@ 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("list_recall_items");
+    hints.push("load_recall_item");
     hints.push("resume_thread");
     hints.push("search_recall");
   }

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.32",
     context_observations_injected: metrics?.contextObsInjected ?? 0,
     context_total_available: metrics?.contextTotalAvailable ?? 0,
     recall_attempts: metrics?.recallAttempts ?? 0,