engrm 0.4.31 → 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,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
+- `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`
@@ -265,6 +271,22 @@ These are the tools we should be comfortable pointing people to publicly first:
 - 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
 
 Engrm now has a real thin-tool layer, not just a plugin spec.
@@ -382,6 +404,8 @@ What each tool is good for:
 - `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

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)}`;
@@ -3090,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.31";
+var CLIENT_VERSION = "0.4.32";
 function hashFile(filePath) {
   try {
     if (!existsSync3(filePath))
@@ -5794,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.31",
+    client_version: "0.4.32",
     context_observations_injected: metrics?.contextObsInjected ?? 0,
     context_total_available: metrics?.contextTotalAvailable ?? 0,
     recall_attempts: metrics?.recallAttempts ?? 0,

package/dist/server.js

@@ -17976,6 +17976,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()) {
@@ -18078,6 +18086,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)}`;
@@ -18296,6 +18323,187 @@ function getRecentOutcomes(db, projectId, userId, recentSessions) {
   return picked;
 }
 
+// src/tools/list-recall-items.ts
+function listRecallItems(db, input) {
+  const limit = Math.max(3, Math.min(input.limit ?? 12, 30));
+  const projectScoped = input.project_scoped !== false;
+  let projectName;
+  if (projectScoped) {
+    const cwd = input.cwd ?? process.cwd();
+    const detected = detectProject(cwd);
+    const project = db.getProjectByCanonicalId(detected.canonical_id);
+    projectName = project?.name;
+  }
+  const handoffs = getRecentHandoffs(db, {
+    cwd: input.cwd,
+    project_scoped: projectScoped,
+    user_id: input.user_id,
+    current_device_id: input.current_device_id,
+    limit
+  }).handoffs;
+  const sessions = getRecentSessions(db, {
+    cwd: input.cwd,
+    project_scoped: projectScoped,
+    user_id: input.user_id,
+    limit: Math.min(limit, 8)
+  }).sessions;
+  const chat = getRecentChat(db, {
+    cwd: input.cwd,
+    project_scoped: projectScoped,
+    user_id: input.user_id,
+    limit: Math.min(limit * 2, 20)
+  }).messages;
+  const observations = getRecentActivity(db, {
+    cwd: input.cwd,
+    project_scoped: projectScoped,
+    user_id: input.user_id,
+    limit: Math.min(limit * 2, 24)
+  }).observations;
+  const items = [
+    ...handoffs.map((handoff) => ({
+      key: `handoff:${handoff.id}`,
+      kind: "handoff",
+      title: stripHandoffPrefix(handoff.title),
+      detail: summarizeHandoffDetail(handoff.narrative),
+      created_at_epoch: handoff.created_at_epoch,
+      freshness: classifyFreshness(handoff.created_at_epoch),
+      session_id: handoff.session_id,
+      source_device_id: handoff.device_id ?? null
+    })),
+    ...sessions.filter((session) => Boolean(session.request || session.completed || session.current_thread)).map((session) => ({
+      key: `session:${session.session_id}`,
+      kind: "thread",
+      title: session.current_thread ?? session.request ?? session.completed ?? session.session_id,
+      detail: buildSessionDetail(session),
+      created_at_epoch: session.completed_at_epoch ?? session.started_at_epoch ?? 0,
+      freshness: classifyFreshness(session.completed_at_epoch ?? session.started_at_epoch ?? null),
+      session_id: session.session_id,
+      source_device_id: session.device_id ?? null
+    })),
+    ...dedupeChatIndex(chat).map((message) => {
+      const origin = getChatCaptureOrigin(message);
+      return {
+        key: `chat:${message.id}`,
+        kind: "chat",
+        title: `${message.role} [${origin}]`,
+        detail: truncateInline(message.content.replace(/\s+/g, " ").trim(), 180),
+        created_at_epoch: message.created_at_epoch,
+        freshness: classifyFreshness(message.created_at_epoch),
+        session_id: message.session_id,
+        source_device_id: message.device_id ?? null
+      };
+    }),
+    ...observations.filter((obs) => obs.type !== "message").filter((obs) => !looksLikeFileOperationTitle3(obs.title)).map((obs) => ({
+      key: `obs:${obs.id}`,
+      kind: "memory",
+      title: `[${obs.type}] ${obs.title}`,
+      detail: truncateInline(firstNonEmpty2(obs.narrative, previewFacts(obs.facts), obs.project_name ?? "") ?? obs.type, 180),
+      created_at_epoch: obs.created_at_epoch,
+      freshness: classifyFreshness(obs.created_at_epoch),
+      session_id: obs.session_id ?? null,
+      source_device_id: obs.device_id ?? null
+    }))
+  ];
+  const deduped = dedupeRecallItems(items).sort((a, b) => compareRecallItems(a, b, input.current_device_id)).slice(0, limit);
+  return {
+    project: projectName,
+    continuity_mode: deduped.some((item) => item.kind === "handoff" || item.kind === "thread") ? "direct" : "indexed",
+    items: deduped
+  };
+}
+function compareRecallItems(a, b, currentDeviceId) {
+  const priority = (item) => {
+    const freshness = item.freshness === "live" ? 0 : item.freshness === "recent" ? 1 : 2;
+    const kind = item.kind === "handoff" ? 0 : item.kind === "thread" ? 1 : item.kind === "chat" ? 2 : 3;
+    const remoteBoost = currentDeviceId && item.source_device_id && item.source_device_id !== currentDeviceId ? -0.5 : 0;
+    const draftPenalty = item.kind === "handoff" && /draft/i.test(item.title) ? 0.25 : 0;
+    return freshness * 10 + kind + remoteBoost + draftPenalty;
+  };
+  const priorityDiff = priority(a) - priority(b);
+  if (priorityDiff !== 0)
+    return priorityDiff;
+  return b.created_at_epoch - a.created_at_epoch;
+}
+function dedupeRecallItems(items) {
+  const best = new Map;
+  for (const item of items) {
+    const key = `${item.kind}::${normalize(item.title)}::${normalize(item.detail)}`;
+    const existing = best.get(key);
+    if (!existing || compareRecallItems(item, existing) < 0) {
+      best.set(key, item);
+    }
+  }
+  return Array.from(best.values());
+}
+function dedupeChatIndex(messages) {
+  const byKey = new Map;
+  for (const message of messages) {
+    const key = `${message.session_id}::${message.role}::${normalize(message.content)}`;
+    const existing = byKey.get(key);
+    if (!existing || message.created_at_epoch > existing.created_at_epoch) {
+      byKey.set(key, message);
+    }
+  }
+  return Array.from(byKey.values());
+}
+function summarizeHandoffDetail(narrative) {
+  if (!narrative)
+    return "";
+  const line = narrative.split(/\n+/).map((item) => item.trim()).find((item) => /^Current thread:|^Completed:|^Next Steps:/i.test(item));
+  return line ? truncateInline(line.replace(/^(Current thread:|Completed:|Next Steps:)\s*/i, ""), 180) : truncateInline(narrative.replace(/\s+/g, " ").trim(), 180);
+}
+function buildSessionDetail(session) {
+  const pieces = [
+    session.request,
+    session.completed,
+    session.current_thread
+  ].filter((item) => Boolean(item && item.trim())).map((item) => item.replace(/\s+/g, " ").trim());
+  return truncateInline(pieces[0] ?? `prompts ${session.prompt_count}, tools ${session.tool_event_count}`, 180);
+}
+function stripHandoffPrefix(value) {
+  return value.replace(/^Handoff(?: Draft)?:\s*/i, "").replace(/\s+·\s+\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}Z$/, "").trim();
+}
+function classifyFreshness(createdAtEpoch) {
+  if (!createdAtEpoch)
+    return "stale";
+  const ageMs = Date.now() - createdAtEpoch * 1000;
+  if (ageMs <= 15 * 60 * 1000)
+    return "live";
+  if (ageMs <= 3 * 24 * 60 * 60 * 1000)
+    return "recent";
+  return "stale";
+}
+function normalize(value) {
+  return value.toLowerCase().replace(/\s+/g, " ").trim();
+}
+function truncateInline(text, maxLen) {
+  if (text.length <= maxLen)
+    return text;
+  return `${text.slice(0, maxLen - 1).trimEnd()}…`;
+}
+function firstNonEmpty2(...values) {
+  for (const value of values) {
+    if (value && value.trim())
+      return value.trim();
+  }
+  return null;
+}
+function previewFacts(facts) {
+  if (!facts)
+    return null;
+  try {
+    const parsed = JSON.parse(facts);
+    if (!Array.isArray(parsed) || parsed.length === 0)
+      return null;
+    return parsed.filter((item) => typeof item === "string" && item.trim().length > 0).slice(0, 2).join(" | ");
+  } catch {
+    return facts;
+  }
+}
+function looksLikeFileOperationTitle3(value) {
+  return /^(modified|updated|edited|touched|changed|extended|refactored|redesigned)\s+[A-Za-z0-9_.\-\/]+(?:\s*\([^)]*\))?$/i.test(value.trim());
+}
+
 // src/tools/project-memory-index.ts
 function getProjectMemoryIndex(db, input) {
   const cwd = input.cwd ?? process.cwd();
@@ -18371,9 +18579,15 @@ function getProjectMemoryIndex(db, input) {
     limit: 20
   });
   const recentChatCount = recentChat.messages.length;
+  const recallIndex = listRecallItems(db, {
+    cwd,
+    project_scoped: true,
+    user_id: input.user_id,
+    limit: 10
+  });
   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 recentOutcomes = observations.filter((obs) => ["bugfix", "feature", "refactor", "change", "decision"].includes(obs.type)).map((obs) => obs.title.trim()).filter((title) => title.length > 0 && !looksLikeFileOperationTitle4(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);
   const suggestedTools = buildSuggestedTools(recentSessions, recentRequestsCount, recentToolsCount, observations.length, recentChatCount, recentChat.coverage_state);
@@ -18393,6 +18607,14 @@ function getProjectMemoryIndex(db, input) {
     canonical_id: project.canonical_id,
     continuity_state: continuityState,
     continuity_summary: describeContinuityState(continuityState),
+    recall_mode: recallIndex.continuity_mode,
+    recall_items_ready: recallIndex.items.length,
+    recall_index_preview: recallIndex.items.slice(0, 3).map((item) => ({
+      key: item.key,
+      kind: item.kind,
+      freshness: item.freshness,
+      title: item.title
+    })),
     resume_freshness: classifyResumeFreshness(sourceTimestamp),
     resume_source_session_id: latestSession?.session_id ?? null,
     resume_source_device_id: latestSession?.device_id ?? null,
@@ -18475,7 +18697,7 @@ function extractPaths(value) {
     return [];
   }
 }
-function looksLikeFileOperationTitle3(value) {
+function looksLikeFileOperationTitle4(value) {
   return /^(modified|updated|edited|touched|changed|extended|refactored|redesigned)\s+[A-Za-z0-9_.\-\/]+(?:\s*\([^)]*\))?$/i.test(value.trim());
 }
 function summarizeCaptureState(sessions) {
@@ -18512,6 +18734,8 @@ function buildSuggestedTools(sessions, requestCount, toolCount, observationCount
     suggested.push("activity_feed");
   }
   if (requestCount > 0 || recentChatCount > 0 || observationCount > 0) {
+    suggested.push("list_recall_items");
+    suggested.push("load_recall_item");
     suggested.push("resume_thread");
     suggested.push("search_recall");
   }
@@ -18577,6 +18801,12 @@ function getMemoryConsole(db, input) {
     user_id: input.user_id,
     limit: 6
   });
+  const recallIndex = listRecallItems(db, {
+    cwd,
+    project_scoped: projectScoped,
+    user_id: input.user_id,
+    limit: 10
+  });
   const projectIndex = projectScoped ? getProjectMemoryIndex(db, {
     cwd,
     user_id: input.user_id
@@ -18587,6 +18817,14 @@ 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),
+    recall_mode: projectIndex?.recall_mode ?? recallIndex.continuity_mode,
+    recall_items_ready: projectIndex?.recall_items_ready ?? recallIndex.items.length,
+    recall_index_preview: projectIndex?.recall_index_preview ?? recallIndex.items.slice(0, 3).map((item) => ({
+      key: item.key,
+      kind: item.kind,
+      freshness: item.freshness,
+      title: item.title
+    })),
     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,
@@ -18620,7 +18858,9 @@ function buildFallbackSuggestedTools(sessionCount, requestCount, toolCount, obse
   if (requestCount > 0 || toolCount > 0)
     suggested.push("activity_feed");
   if (requestCount > 0 || chatCount > 0 || observationCount > 0)
-    suggested.push("resume_thread", "search_recall");
+    suggested.push("load_recall_item", "resume_thread", "search_recall");
+  if (requestCount > 0 || chatCount > 0 || observationCount > 0)
+    suggested.unshift("list_recall_items");
   if ((sessionCount > 0 || chatCount > 0) && chatCoverageState !== "transcript-backed")
     suggested.push("repair_recall");
   if (observationCount > 0)
@@ -19467,6 +19707,13 @@ function getSessionContext(db, input) {
     limit: 8
   });
   const recentChatMessages = recentChat.messages.length;
+  const recallIndex = listRecallItems(db, {
+    cwd,
+    project_scoped: true,
+    user_id: input.user_id,
+    current_device_id: input.current_device_id,
+    limit: 10
+  });
   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";
@@ -19479,6 +19726,14 @@ function getSessionContext(db, input) {
     canonical_id: context.canonical_id,
     continuity_state: continuityState,
     continuity_summary: describeContinuityState(continuityState),
+    recall_mode: recallIndex.continuity_mode,
+    recall_items_ready: recallIndex.items.length,
+    recall_index_preview: recallIndex.items.slice(0, 3).map((item) => ({
+      key: item.key,
+      kind: item.kind,
+      freshness: item.freshness,
+      title: item.title
+    })),
     resume_freshness: classifyResumeFreshness(resumeTimestamp),
     resume_source_session_id: latestSession?.session_id ?? null,
     resume_source_device_id: latestSession?.device_id ?? null,
@@ -19541,6 +19796,8 @@ function buildSuggestedTools2(context, chatCoverageState) {
     tools.push("activity_feed");
   }
   if ((context.recentPrompts?.length ?? 0) > 0 || (context.recentChatMessages?.length ?? 0) > 0 || context.observations.length > 0) {
+    tools.push("list_recall_items");
+    tools.push("load_recall_item");
     tools.push("resume_thread");
     tools.push("search_recall");
   }
@@ -19565,6 +19822,139 @@ function buildSuggestedTools2(context, chatCoverageState) {
   return Array.from(new Set(tools)).slice(0, 5);
 }
 
+// src/tools/load-recall-item.ts
+function loadRecallItem(db, input) {
+  const [kind, rawId] = input.key.split(":", 2);
+  if (!kind || !rawId) {
+    return {
+      kind: "unknown",
+      key: input.key,
+      title: null,
+      detail: "Malformed recall key",
+      session_id: null,
+      source_device_id: null,
+      payload: null
+    };
+  }
+  if (kind === "handoff") {
+    const id = Number.parseInt(rawId, 10);
+    const result = loadHandoff(db, {
+      id,
+      cwd: input.cwd,
+      user_id: input.user_id,
+      current_device_id: input.current_device_id
+    });
+    if (!result.handoff) {
+      return missing(input.key, "handoff");
+    }
+    return {
+      kind: "handoff",
+      key: input.key,
+      title: result.handoff.title,
+      detail: summarizeNarrative(result.handoff.narrative),
+      session_id: result.handoff.session_id ?? null,
+      source_device_id: result.handoff.device_id ?? null,
+      payload: {
+        type: "handoff",
+        handoff_id: result.handoff.id,
+        narrative: result.handoff.narrative ?? null
+      }
+    };
+  }
+  if (kind === "session") {
+    const story = getSessionStory(db, { session_id: rawId });
+    if (!story.session) {
+      return missing(input.key, "thread");
+    }
+    return {
+      kind: "thread",
+      key: input.key,
+      title: story.summary?.current_thread ?? story.latest_request ?? story.summary?.completed ?? story.session.session_id,
+      detail: story.summary?.next_steps ?? story.summary?.completed ?? null,
+      session_id: story.session.session_id,
+      source_device_id: story.session.device_id ?? null,
+      payload: {
+        type: "thread",
+        latest_request: story.latest_request,
+        current_thread: story.summary?.current_thread ?? null,
+        recent_outcomes: story.recent_outcomes,
+        hot_files: story.hot_files
+      }
+    };
+  }
+  if (kind === "chat") {
+    const id = Number.parseInt(rawId, 10);
+    const messages = getRecentChat(db, {
+      cwd: input.cwd,
+      project_scoped: false,
+      user_id: input.user_id,
+      limit: 200
+    }).messages;
+    const message = messages.find((item) => item.id === id);
+    if (!message) {
+      return missing(input.key, "chat");
+    }
+    const source = message.source_kind === "transcript" ? "transcript" : message.remote_source_id?.startsWith("history:") ? "history" : "hook";
+    return {
+      kind: "chat",
+      key: input.key,
+      title: `${message.role} [${source}]`,
+      detail: message.content,
+      session_id: message.session_id,
+      source_device_id: message.device_id ?? null,
+      payload: {
+        type: "chat",
+        role: message.role,
+        content: message.content,
+        source
+      }
+    };
+  }
+  if (kind === "obs") {
+    const id = Number.parseInt(rawId, 10);
+    const result = getObservations(db, {
+      ids: [id],
+      user_id: input.user_id
+    });
+    const obs = result.observations[0];
+    if (!obs) {
+      return missing(input.key, "memory");
+    }
+    return {
+      kind: "memory",
+      key: input.key,
+      title: obs.title,
+      detail: obs.narrative ?? obs.facts ?? null,
+      session_id: obs.session_id ?? null,
+      source_device_id: obs.device_id ?? null,
+      payload: {
+        type: "memory",
+        observation_id: obs.id,
+        observation_type: obs.type,
+        narrative: obs.narrative ?? null,
+        facts: obs.facts ?? null
+      }
+    };
+  }
+  return missing(input.key, "unknown");
+}
+function summarizeNarrative(value) {
+  if (!value)
+    return null;
+  return value.split(/\n+/).map((line) => line.trim()).find(Boolean) ?? null;
+}
+function missing(key, kind) {
+  return {
+    kind,
+    key,
+    title: null,
+    detail: "Recall item not found",
+    session_id: null,
+    source_device_id: null,
+    payload: null
+  };
+}
+
 // src/tools/capture-git-worktree.ts
 import { execSync as execSync2 } from "node:child_process";
 import { existsSync as existsSync4 } from "node:fs";
@@ -21613,7 +22003,7 @@ var REFACTOR_HINTS = [
   "extract",
   "move"
 ];
-function normalize(text) {
+function normalize2(text) {
   return text.toLowerCase().replace(/\s+/g, " ").trim();
 }
 function uniq(items) {
@@ -21642,7 +22032,7 @@ function countLinesByPrefix(diff, prefix) {
 `).filter((line) => line.startsWith(prefix) && !line.startsWith(`${prefix}${prefix}${prefix}`)).length;
 }
 function detectType(summary, diff, files) {
-  const corpus = normalize([summary ?? "", diff, files.join(" ")].join(" "));
+  const corpus = normalize2([summary ?? "", diff, files.join(" ")].join(" "));
   if (BUGFIX_HINTS.some((hint) => corpus.includes(hint)))
     return "bugfix";
   if (DECISION_HINTS.some((hint) => corpus.includes(hint)))
@@ -21702,7 +22092,7 @@ function buildFacts(diff, files) {
   if (added > 0 || removed > 0) {
     facts.push(`Diff footprint: +${added} / -${removed}`);
   }
-  const lower = normalize(diff);
+  const lower = normalize2(diff);
   if (lower.includes("auth") || lower.includes("token") || lower.includes("oauth")) {
     facts.push("Touches authentication or credential flow");
   }
@@ -22039,7 +22429,7 @@ process.on("SIGTERM", () => {
 });
 var server = new McpServer({
   name: "engrm",
-  version: "0.4.31"
+  version: "0.4.32"
 });
 server.tool("save_observation", "Save an observation to memory", {
   type: exports_external.enum([
@@ -22484,7 +22874,138 @@ ${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.", {
+server.tool("list_recall_items", "USE FIRST when continuity feels fuzzy. List the best current handoffs, session threads, chat snippets, and memory entries before opening one exact item.", {
+  cwd: exports_external.string().optional().describe("Optional cwd override for project-scoped recall"),
+  project_scoped: exports_external.boolean().optional().describe("Scope to project (default: true)"),
+  user_id: exports_external.string().optional().describe("Optional user override"),
+  limit: exports_external.number().optional().describe("Max recall items to list")
+}, async (params) => {
+  const result = listRecallItems(db, {
+    cwd: params.cwd ?? process.cwd(),
+    project_scoped: params.project_scoped,
+    user_id: params.user_id ?? config2.user_id,
+    current_device_id: config2.device_id,
+    limit: params.limit
+  });
+  if (result.items.length === 0) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: result.project ? `No recall items found yet for project ${result.project}` : "No recall items found yet."
+        }
+      ]
+    };
+  }
+  const projectLine = result.project ? `Project: ${result.project}
+` : "";
+  const rows = result.items.map((item) => `- ${item.key} [${item.kind} · ${item.freshness}] ${item.title}${item.source_device_id ? ` (${item.source_device_id})` : ""}
+  ${item.detail}`).join(`
+`);
+  return {
+    content: [
+      {
+        type: "text",
+        text: `${projectLine}Recall index (${result.continuity_mode} mode):
+` + `${rows}
+
+` + `Suggested next step: use load_handoff for handoff:* items, get_observations([...]) for obs:* items, or resume_thread when you want one merged resume point.`
+      }
+    ]
+  };
+});
+server.tool("load_recall_item", "USE AFTER list_recall_items. Load one exact recall item key so you can inspect a specific handoff, thread, chat message, or memory entry without fuzzy recall guessing.", {
+  key: exports_external.string().describe("Exact recall key from list_recall_items, such as handoff:12, session:sess-1, chat:55, or obs:402"),
+  cwd: exports_external.string().optional().describe("Optional cwd override"),
+  user_id: exports_external.string().optional().describe("Optional user override")
+}, async (params) => {
+  const result = loadRecallItem(db, {
+    key: params.key,
+    cwd: params.cwd ?? process.cwd(),
+    user_id: params.user_id ?? config2.user_id,
+    current_device_id: config2.device_id
+  });
+  if (!result.payload) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `No recall item found for ${params.key}`
+        }
+      ]
+    };
+  }
+  if (result.payload.type === "handoff") {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Recall item ${result.key} [handoff]
+` + `Title: ${result.title}
+` + `Session: ${result.session_id ?? "(unknown)"}
+` + `Source: ${result.source_device_id ?? "(unknown)"}
+
+` + `${result.payload.narrative ?? "(no narrative)"}`
+        }
+      ]
+    };
+  }
+  if (result.payload.type === "thread") {
+    const outcomes = result.payload.recent_outcomes.length > 0 ? result.payload.recent_outcomes.map((item) => `- ${item}`).join(`
+`) : "- (none)";
+    const hotFiles = result.payload.hot_files.length > 0 ? result.payload.hot_files.map((item) => `- ${item.path}${item.count > 1 ? ` (${item.count})` : ""}`).join(`
+`) : "- (none)";
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Recall item ${result.key} [thread]
+` + `Title: ${result.title}
+` + `Session: ${result.session_id ?? "(unknown)"}
+` + `Source: ${result.source_device_id ?? "(unknown)"}
+` + `Latest request: ${result.payload.latest_request ?? "(none)"}
+` + `Current thread: ${result.payload.current_thread ?? "(none)"}
+
+` + `Recent outcomes:
+${outcomes}
+
+` + `Hot files:
+${hotFiles}`
+        }
+      ]
+    };
+  }
+  if (result.payload.type === "chat") {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Recall item ${result.key} [chat]
+` + `Title: ${result.title}
+` + `Session: ${result.session_id ?? "(unknown)"}
+` + `Source: ${result.source_device_id ?? "(unknown)"}
+
+` + `${result.payload.content}`
+        }
+      ]
+    };
+  }
+  return {
+    content: [
+      {
+        type: "text",
+        text: `Recall item ${result.key} [memory]
+` + `Title: ${result.title}
+` + `Session: ${result.session_id ?? "(unknown)"}
+` + `Source: ${result.source_device_id ?? "(unknown)"}
+` + `Type: ${result.payload.observation_type}
+
+` + `${result.payload.narrative ?? result.payload.facts ?? "(no detail)"}`
+      }
+    ]
+  };
+});
+server.tool("resume_thread", "USE FIRST when you want one direct 'where were we?' answer. 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"),
@@ -22871,6 +23392,8 @@ server.tool("memory_console", "Show a high-signal local overview of what Engrm c
   const checkpointTypeLines = result.assistant_checkpoint_types.length > 0 ? result.assistant_checkpoint_types.map((item) => `- ${item.type}: ${item.count}`).join(`
 `) : "- (none)";
   const topTypes = result.top_types.length > 0 ? result.top_types.map((item) => `- ${item.type}: ${item.count}`).join(`
+`) : "- (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 projectLine = result.project ? `Project: ${result.project}
 
@@ -22885,6 +23408,7 @@ 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}
+` + `Recall index: ${result.recall_mode} · ${result.recall_items_ready} items ready
 ` + `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}
@@ -22892,6 +23416,9 @@ 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:
+${recallPreviewLines}
+
 ` + `Next actions:
 ${result.resume_next_actions.length > 0 ? result.resume_next_actions.map((item) => `- ${item}`).join(`
 `) : "- (none)"}
@@ -23089,6 +23616,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}
+` + `Recall index: ${result.recall_mode} · ${result.recall_items_ready} items ready
 ` + `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}
@@ -23101,6 +23629,7 @@ server.tool("session_context", "Preview the exact project memory context Engrm w
 ` + `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)"}
+` + `Recall preview: ${result.recall_index_preview.length > 0 ? result.recall_index_preview.map((item) => item.key).join(", ") : "(none)"}
 ` + `Raw chronology active: ${result.raw_capture_active ? "yes" : "no"}
 
 ` + result.preview
@@ -23165,6 +23694,8 @@ server.tool("project_memory_index", "Show a typed local memory index for the cur
   const topTypes = result.top_types.length > 0 ? result.top_types.map((item) => `- ${item.type}: ${item.count}`).join(`
 `) : "- (none)";
   const topTitles = result.top_titles.length > 0 ? result.top_titles.map((item) => `- #${item.id} [${item.type}] ${item.title}`).join(`
+`) : "- (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)";
   return {
     content: [
@@ -23173,6 +23704,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}
+` + `Recall index: ${result.recall_mode} · ${result.recall_items_ready} items ready
 ` + `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}
@@ -23188,6 +23720,9 @@ 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:
+${recallPreviewLines}
+
 ` + `Next actions:
 ${result.resume_next_actions.length > 0 ? result.resume_next_actions.map((item) => `- ${item}`).join(`
 `) : "- (none)"}
@@ -23368,7 +23903,7 @@ Transcript messages seen: ${result.total}`
     ]
   };
 });
-server.tool("repair_recall", "Rehydrate recent session recall for the current project from Claude transcripts or history fallback when chat feels missing or under-captured", {
+server.tool("repair_recall", "USE WHEN recall feels thin or under-captured. Rehydrate recent session recall for the current project from Claude transcripts or history fallback before resuming.", {
   session_id: exports_external.string().optional().describe("Optional single session ID to repair instead of scanning recent project sessions"),
   cwd: exports_external.string().optional().describe("Project directory used to resolve project sessions and Claude history/transcript files"),
   limit: exports_external.number().optional().describe("How many recent sessions to inspect when repairing a project"),

package/package.json

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