engrm 0.4.32 → 0.4.33

package/README.md

@@ -403,9 +403,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
+- `resume_thread` is the fastest “get me back into the live thread” path when you want freshness, source, next actions, tool trail, chat, and one exact `load_recall_item(...)` suggestion 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 surface one best exact `load_recall_item(...)` jump, so the workbench can hand you the right deterministic next step instead of only showing recall counts
 - `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

package/dist/hooks/session-start.js

@@ -3144,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.32";
+var CLIENT_VERSION = "0.4.33";
 function hashFile(filePath) {
   try {
     if (!existsSync3(filePath))
@@ -5617,7 +5617,15 @@ function formatSplashScreen(data) {
       lines.push(`  ${line}`);
     }
   }
-  const inspectHints = formatInspectHints(data.context, contextIndex.observationIds);
+  const recallItems = buildStartupRecallItems(data.context);
+  const recallPreview = formatStartupRecallPreview(recallItems);
+  if (recallPreview.length > 0) {
+    lines.push("");
+    for (const line of recallPreview) {
+      lines.push(`  ${line}`);
+    }
+  }
+  const inspectHints = formatInspectHints(data.context, contextIndex.observationIds, recallItems);
   if (inspectHints.length > 0) {
     lines.push("");
     for (const line of inspectHints) {
@@ -5836,7 +5844,7 @@ function formatContextIndex(context, shownItems) {
     observationIds: selected.map((obs) => obs.id)
   };
 }
-function formatInspectHints(context, visibleObservationIds = []) {
+function formatInspectHints(context, visibleObservationIds = [], recallItems = []) {
   const hints = [];
   const continuityState = getStartupContinuityState(context);
   if ((context.recentSessions?.length ?? 0) > 0) {
@@ -5875,12 +5883,90 @@ function formatInspectHints(context, visibleObservationIds = []) {
   if (unique.length === 0)
     return [];
   const ids = visibleObservationIds.slice(0, 5);
+  const openNowItem = recallItems.find((item) => item.kind !== "memory") ?? null;
   const fetchHint = ids.length > 0 ? `get_observations([${ids.join(", ")}])` : null;
   return [
     `${c2.dim}Next look:${c2.reset} ${unique.join(" \xB7 ")}`,
+    ...openNowItem ? [`${c2.dim}Open now:${c2.reset} load_recall_item("${openNowItem.key}")`] : [],
     ...fetchHint ? [`${c2.dim}Pull detail:${c2.reset} ${fetchHint}`] : []
   ];
 }
+function formatStartupRecallPreview(recallItems) {
+  const items = recallItems.slice(0, 3);
+  if (items.length === 0)
+    return [];
+  return [
+    `${c2.dim}Recall preview:${c2.reset} exact keys you can open now`,
+    ...items.map((item) => `${item.key} [${item.kind} \xB7 ${item.freshness}] ${truncateInline(item.title, 110)}`)
+  ];
+}
+function buildStartupRecallItems(context) {
+  const items = [];
+  for (const handoff of context.recentHandoffs?.slice(0, 2) ?? []) {
+    const title = handoff.title.replace(/^Handoff(?: Draft)?:\s*/i, "").replace(/\s+\u00B7\s+\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}Z$/, "").trim();
+    if (!title)
+      continue;
+    const freshness = classifyResumeFreshness(handoff.created_at_epoch);
+    items.push({
+      key: `handoff:${handoff.id}`,
+      kind: "handoff",
+      freshness,
+      title,
+      score: freshnessScore(freshness) + 40
+    });
+  }
+  for (const session of context.recentSessions?.slice(0, 2) ?? []) {
+    const title = chooseMeaningfulSessionSummary(session.request, session.completed);
+    if (!title)
+      continue;
+    const sourceEpoch = session.completed_at_epoch ?? session.started_at_epoch ?? null;
+    const freshness = classifyResumeFreshness(sourceEpoch);
+    items.push({
+      key: `session:${session.session_id}`,
+      kind: "thread",
+      freshness,
+      title,
+      score: freshnessScore(freshness) + 30
+    });
+  }
+  for (const message of context.recentChatMessages?.slice(-2) ?? []) {
+    if (!message.content.trim())
+      continue;
+    const freshness = classifyResumeFreshness(message.created_at_epoch);
+    items.push({
+      key: `chat:${message.id}`,
+      kind: "chat",
+      freshness,
+      title: `[${message.role}] ${message.content.replace(/\s+/g, " ").trim()}`,
+      score: freshnessScore(freshness) + 20
+    });
+  }
+  for (const obs of pickContextIndexObservations(context).slice(0, 2)) {
+    const createdAtEpoch = Math.floor(new Date(obs.created_at).getTime() / 1000);
+    const freshness = classifyResumeFreshness(Number.isFinite(createdAtEpoch) ? createdAtEpoch : null);
+    items.push({
+      key: `obs:${obs.id}`,
+      kind: "memory",
+      freshness,
+      title: obs.title,
+      score: freshnessScore(freshness) + 10
+    });
+  }
+  const seen = new Set;
+  return items.sort((a, b) => b.score - a.score || a.key.localeCompare(b.key)).filter((item) => {
+    if (seen.has(item.key))
+      return false;
+    seen.add(item.key);
+    return true;
+  }).map(({ score: _score, ...item }) => item);
+}
+function freshnessScore(freshness) {
+  if (freshness === "live")
+    return 3;
+  if (freshness === "recent")
+    return 2;
+  return 1;
+}
 function rememberShownItem(shown, value) {
   if (!value)
     return;

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

package/dist/server.js

@@ -18602,6 +18602,7 @@ function getProjectMemoryIndex(db, input) {
 `));
   const continuityState = classifyContinuityState(recentRequestsCount, recentToolsCount, recentHandoffsCount.length, recentChatCount, recentSessions, recentOutcomes.length);
   const sourceTimestamp = pickResumeSourceTimestamp(latestSession, recentChat.messages);
+  const bestRecallItem = pickBestRecallItem(recallIndex.items);
   return {
     project: project.name,
     canonical_id: project.canonical_id,
@@ -18615,6 +18616,9 @@ function getProjectMemoryIndex(db, input) {
       freshness: item.freshness,
       title: item.title
     })),
+    best_recall_key: bestRecallItem?.key ?? null,
+    best_recall_title: bestRecallItem?.title ?? null,
+    best_recall_kind: bestRecallItem?.kind ?? null,
     resume_freshness: classifyResumeFreshness(sourceTimestamp),
     resume_source_session_id: latestSession?.session_id ?? null,
     resume_source_device_id: latestSession?.device_id ?? null,
@@ -18643,6 +18647,9 @@ function getProjectMemoryIndex(db, input) {
     suggested_tools: suggestedTools
   };
 }
+function pickBestRecallItem(items) {
+  return items.find((item) => item.kind !== "memory") ?? items[0] ?? null;
+}
 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;
@@ -18825,6 +18832,9 @@ function getMemoryConsole(db, input) {
       freshness: item.freshness,
       title: item.title
     })),
+    best_recall_key: projectIndex?.best_recall_key ?? (recallIndex.items.find((item) => item.kind !== "memory") ?? recallIndex.items[0] ?? null)?.key ?? null,
+    best_recall_title: projectIndex?.best_recall_title ?? (recallIndex.items.find((item) => item.kind !== "memory") ?? recallIndex.items[0] ?? null)?.title ?? null,
+    best_recall_kind: projectIndex?.best_recall_kind ?? (recallIndex.items.find((item) => item.kind !== "memory") ?? recallIndex.items[0] ?? null)?.kind ?? null,
     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,
@@ -19721,6 +19731,7 @@ function getSessionContext(db, input) {
   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;
+  const bestRecallItem = recallIndex.items.find((item) => item.kind !== "memory") ?? recallIndex.items[0] ?? null;
   return {
     project_name: context.project_name,
     canonical_id: context.canonical_id,
@@ -19734,6 +19745,9 @@ function getSessionContext(db, input) {
       freshness: item.freshness,
       title: item.title
     })),
+    best_recall_key: bestRecallItem?.key ?? null,
+    best_recall_title: bestRecallItem?.title ?? null,
+    best_recall_kind: bestRecallItem?.kind ?? null,
     resume_freshness: classifyResumeFreshness(resumeTimestamp),
     resume_source_session_id: latestSession?.session_id ?? null,
     resume_source_device_id: latestSession?.device_id ?? null,
@@ -20390,6 +20404,7 @@ async function resumeThread(db, config2, input = {}) {
     }
   }
   const { context, handoff, recentChat, recentSessions, recall } = snapshot;
+  const bestRecallItem = pickBestRecallItem2(snapshot.recallIndex.items);
   const latestSession = recentSessions[0] ?? null;
   const latestSummary = latestSession ? db.getSessionSummary(latestSession.session_id) : null;
   const inferredRequest = latestSession?.request?.trim() || null;
@@ -20418,6 +20433,7 @@ async function resumeThread(db, config2, input = {}) {
     currentThread
   });
   const suggestedTools = Array.from(new Set([
+    ...bestRecallItem ? ["load_recall_item"] : [],
     "search_recall",
     ...recentChat.coverage_state !== "transcript-backed" && recentChat.messages.length > 0 ? ["repair_recall", "refresh_chat_recall"] : [],
     ...handoff ? ["load_handoff"] : [],
@@ -20432,6 +20448,9 @@ async function resumeThread(db, config2, input = {}) {
     resume_source_device_id: handoff?.device_id ?? latestSession?.device_id ?? null,
     resume_confidence: resumeConfidence,
     resume_basis: resumeBasis,
+    best_recall_key: bestRecallItem?.key ?? null,
+    best_recall_title: bestRecallItem?.title ?? null,
+    best_recall_kind: bestRecallItem?.kind ?? null,
     repair_attempted: shouldRepair,
     repair_result: repairResult ? {
       imported_chat_messages: repairResult.imported_chat_messages,
@@ -20490,14 +20509,25 @@ async function buildResumeSnapshot(db, cwd, userId, currentDeviceId, limit) {
     user_id: userId,
     limit
   });
+  const recallIndex = listRecallItems(db, {
+    cwd,
+    project_scoped: true,
+    user_id: userId,
+    current_device_id: currentDeviceId,
+    limit
+  });
   return {
     context,
     handoff: handoffResult.handoff,
     recentChat,
     recentSessions,
-    recall
+    recall,
+    recallIndex
   };
 }
+function pickBestRecallItem2(items) {
+  return items.find((item) => item.kind !== "memory") ?? items[0] ?? null;
+}
 function extractCurrentThread(handoff) {
   const narrative = handoff?.narrative ?? "";
   const match = narrative.match(/Current thread:\s*(.+)/i);
@@ -22429,7 +22459,7 @@ process.on("SIGTERM", () => {
 });
 var server = new McpServer({
   name: "engrm",
-  version: "0.4.32"
+  version: "0.4.33"
 });
 server.tool("save_observation", "Save an observation to memory", {
   type: exports_external.enum([
@@ -23023,6 +23053,8 @@ server.tool("resume_thread", "USE FIRST when you want one direct 'where were we?
   const handoffLine = result.handoff ? `Handoff: #${result.handoff.id} ${result.handoff.title}${result.handoff.source ? ` (${result.handoff.source})` : ""}
 ` : `Handoff: (none)
 `;
+  const openExactLine = result.best_recall_key ? `Open exact: load_recall_item("${result.best_recall_key}")${result.best_recall_title ? `  # ${result.best_recall_title}` : ""}
+` : "";
   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(`
@@ -23057,7 +23089,7 @@ server.tool("resume_thread", "USE FIRST when you want one direct 'where were we?
 ` + `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)"}
+` + repairLine + openExactLine + `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)"}
@@ -23395,6 +23427,8 @@ server.tool("memory_console", "Show a high-signal local overview of what Engrm c
 `) : "- (none)";
   const recallPreviewLines = result.recall_index_preview.length > 0 ? result.recall_index_preview.map((item) => `- ${item.key} [${item.kind} · ${item.freshness}] ${item.title}`).join(`
 `) : "- (none)";
+  const openExactLine = result.best_recall_key ? `Open exact: load_recall_item("${result.best_recall_key}")${result.best_recall_title ? `  # ${result.best_recall_title}` : ""}
+` : "";
   const projectLine = result.project ? `Project: ${result.project}
 
 ` : "";
@@ -23416,7 +23450,7 @@ server.tool("memory_console", "Show a high-signal local overview of what Engrm c
 ` + `${typeof result.estimated_read_tokens === "number" ? `Estimated read cost: ~${result.estimated_read_tokens}t
 ` : ""}` + `Suggested tools: ${result.suggested_tools.join(", ") || "(none)"}
 
-` + `Recall preview:
+` + openExactLine + `Recall preview:
 ${recallPreviewLines}
 
 ` + `Next actions:
@@ -23617,6 +23651,7 @@ server.tool("session_context", "Preview the exact project memory context Engrm w
 ` + `Canonical ID: ${result.canonical_id}
 ` + `Continuity: ${result.continuity_state} — ${result.continuity_summary}
 ` + `Recall index: ${result.recall_mode} · ${result.recall_items_ready} items ready
+` + `Open exact: ${result.best_recall_key ? `load_recall_item("${result.best_recall_key}")` : "(none)"}
 ` + `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}
@@ -23697,6 +23732,8 @@ server.tool("project_memory_index", "Show a typed local memory index for the cur
 `) : "- (none)";
   const recallPreviewLines = result.recall_index_preview.length > 0 ? result.recall_index_preview.map((item) => `- ${item.key} [${item.kind} · ${item.freshness}] ${item.title}`).join(`
 `) : "- (none)";
+  const openExactLine = result.best_recall_key ? `Open exact: load_recall_item("${result.best_recall_key}")${result.best_recall_title ? `  # ${result.best_recall_title}` : ""}
+` : "";
   return {
     content: [
       {
@@ -23720,7 +23757,7 @@ 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)"}
 
-` + `Recall preview:
+` + openExactLine + `Recall preview:
 ${recallPreviewLines}
 
 ` + `Next actions:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "engrm",
-  "version": "0.4.32",
+  "version": "0.4.33",
   "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",