engrm 0.4.15 → 0.4.17

package/README.md

@@ -228,6 +228,28 @@ The MCP server exposes tools that supported agents can call directly:
 | `capture_repo_scan` | Run a lightweight repo scan and save reduced findings as memory |
 | `capture_openclaw_content` | Save OpenClaw content, research, and follow-up work as plugin memory |
 
+### Public MCP Starter Set
+
+If you are evaluating Engrm as an MCP server, start with this small set first:
+
+- `capture_git_worktree`
+  - save a meaningful local git diff before it disappears into commit history
+- `capture_repo_scan`
+  - capture a quick architecture, implementation, or risk scan as reusable memory
+- `capture_openclaw_content`
+  - save posted content, research, outcomes, and next actions from OpenClaw work
+- `tool_memory_index`
+  - 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
+
+These are the tools we should be comfortable pointing people to publicly first:
+
+- thin input surface
+- local-first execution
+- durable memory output instead of raw transcript dumping
+- easy local inspection after capture
+
 ### Thin Tools, Thick Memory
 
 Engrm now has a real thin-tool layer, not just a plugin spec.
@@ -301,6 +323,18 @@ That lets you:
 - capture the current repo state with a thin tool
 - verify whether that tool produced reusable memory
 
+### MCP Examples
+
+These are the kinds of prompts Engrm's current MCP slice is designed for:
+
+- "Capture this current git worktree as memory before I switch tasks."
+- "Run a lightweight repo scan focused on auth and validation."
+- "Show which tools are actually creating durable memory in this repo."
+- "Tell me whether raw prompt/tool capture is healthy on this machine."
+- "Save this OpenClaw research/posting run as reusable memory."
+
+For concrete example flows and reducer outputs, see [MCP_EXAMPLES.md](/Volumes/Data/devs/candengo-mem/MCP_EXAMPLES.md).
+
 ### Observation Types
 
 | Type | What it captures |

package/dist/hooks/session-start.js

@@ -1154,7 +1154,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.15";
+var CLIENT_VERSION = "0.4.17";
 function hashFile(filePath) {
   try {
     if (!existsSync3(filePath))
@@ -3133,11 +3133,13 @@ function formatSplashScreen(data) {
   lines.push("");
   lines.push(`  ${c2.dim}Dashboard: https://engrm.dev/dashboard${c2.reset}`);
   const brief = formatVisibleStartupBrief(data.context);
+  const handoffShownItems = new Set;
   if (brief.length > 0) {
     lines.push("");
     lines.push(`  ${c2.bold}Handoff${c2.reset}`);
     for (const line of brief) {
       lines.push(`  ${line}`);
+      rememberShownItem(handoffShownItems, line);
     }
   }
   const economics = formatContextEconomics(data);
@@ -3154,7 +3156,7 @@ function formatSplashScreen(data) {
       lines.push(`  ${line}`);
     }
   }
-  const contextIndex = formatContextIndex(data.context);
+  const contextIndex = formatContextIndex(data.context, handoffShownItems);
   if (contextIndex.length > 0) {
     lines.push("");
     for (const line of contextIndex) {
@@ -3297,8 +3299,8 @@ function formatLegend() {
     `${c2.dim}Legend:${c2.reset} #id | \u25A0 bugfix | \u25B2 feature | \u2248 refactor | \u25CF change | \u25A1 discovery | \u25C7 decision`
   ];
 }
-function formatContextIndex(context) {
-  const rows = context.observations.filter((obs) => obs.type !== "digest").slice(0, 6).map((obs) => {
+function formatContextIndex(context, shownItems) {
+  const rows = pickContextIndexObservations(context, shownItems).map((obs) => {
     const icon = observationIcon(obs.type);
     const fileHint = extractPrimaryFileHint(obs);
     return `${icon} #${obs.id} ${truncateInline(obs.title, 110)}${fileHint ? ` ${c2.dim}(${fileHint})${c2.reset}` : ""}`;
@@ -3496,6 +3498,69 @@ function extractPrimaryFileHint(obs) {
   const firstModified = parseJsonArraySafe(obs.files_modified)[0];
   return firstModified ?? firstRead ?? null;
 }
+function pickContextIndexObservations(context, shownItems) {
+  const now = Date.now();
+  const hidden = shownItems ?? new Set;
+  const picked = [];
+  const scoreObservation = (obs) => {
+    let score = 0;
+    const ageMs = Math.max(0, now - new Date(obs.created_at).getTime());
+    const ageDays = ageMs / 86400000;
+    score += Math.max(0, 30 - ageDays) * 0.2;
+    score += obs.quality * 2;
+    switch (obs.type) {
+      case "bugfix":
+        score += 2.4;
+        break;
+      case "feature":
+        score += 2.2;
+        break;
+      case "change":
+        score += 1.6;
+        break;
+      case "discovery":
+        score += 1.4;
+        break;
+      case "refactor":
+        score += 1.2;
+        break;
+      case "decision":
+        if (ageDays <= 7)
+          score += 1.1;
+        else if (ageDays <= 21)
+          score += 0.2;
+        else if (ageDays <= 45)
+          score -= 1.2;
+        else
+          score -= 2.8;
+        break;
+      default:
+        score += 0.4;
+        break;
+    }
+    if (extractPrimaryFileHint(obs))
+      score += 0.4;
+    if (context.recentOutcomes?.some((item) => titlesRoughlyMatch(item, obs.title)))
+      score += 2.5;
+    return score;
+  };
+  for (const obs of context.observations.filter((obs2) => obs2.type !== "digest").filter((obs2) => {
+    const normalized = normalizeStartupItem(obs2.title);
+    return normalized && !hidden.has(normalized);
+  }).sort((a, b) => {
+    const scoreDiff = scoreObservation(b) - scoreObservation(a);
+    if (scoreDiff !== 0)
+      return scoreDiff;
+    return new Date(b.created_at).getTime() - new Date(a.created_at).getTime();
+  })) {
+    if (picked.some((existing) => titlesRoughlyMatch(existing.title, obs.title)))
+      continue;
+    picked.push(obs);
+    if (picked.length >= 6)
+      break;
+  }
+  return picked;
+}
 function parseJsonArraySafe(value) {
   if (!value)
     return [];
@@ -3566,7 +3631,24 @@ function hasRequestSection(lines) {
   return lines.some((line) => line.includes("Request:"));
 }
 function normalizeStartupItem(value) {
-  return stripInlineSectionLabel2(value).replace(/^#?\d+:\s*/, "").replace(/^-\s*/, "").toLowerCase().replace(/\s+/g, " ").trim();
+  return stripInlineSectionLabel2(value).replace(/^#?\d+:\s*/, "").replace(/^-\s*/, "").replace(/\([^)]*\)/g, " ").replace(/[^a-z0-9\s]/gi, " ").toLowerCase().replace(/\s+/g, " ").trim();
+}
+function titlesRoughlyMatch(left, right) {
+  const a = normalizeStartupItem(left ?? "");
+  const b = normalizeStartupItem(right ?? "");
+  if (!a || !b)
+    return false;
+  if (a === b)
+    return true;
+  if (a.includes(b) || b.includes(a))
+    return true;
+  const aTokens = a.split(" ").filter((token) => token.length >= 4);
+  const bTokens = b.split(" ").filter((token) => token.length >= 4);
+  if (!aTokens.length || !bTokens.length)
+    return false;
+  const shared = aTokens.filter((token) => bTokens.includes(token));
+  const minSize = Math.min(aTokens.length, bTokens.length);
+  return shared.length >= Math.max(3, Math.ceil(minSize * 0.6));
 }
 function isMeaningfulPrompt2(value) {
   if (!value)

package/dist/hooks/stop.js

@@ -2535,7 +2535,7 @@ function buildBeacon(db, config, sessionId, metrics) {
     sentinel_used: valueSignals.security_findings_count > 0,
     risk_score: riskScore,
     stacks_detected: stacks,
-    client_version: "0.4.15",
+    client_version: "0.4.17",
     context_observations_injected: metrics?.contextObsInjected ?? 0,
     context_total_available: metrics?.contextTotalAvailable ?? 0,
     recall_attempts: metrics?.recallAttempts ?? 0,
@@ -3558,42 +3558,40 @@ async function main() {
   try {
     if (event.session_id) {
       db.completeSession(event.session_id);
+      if (event.last_assistant_message) {
+        try {
+          createAssistantCheckpoint(db, event.session_id, event.cwd, event.last_assistant_message);
+        } catch {}
+      }
       const existing = db.getSessionSummary(event.session_id);
       if (!existing) {
         const observations = db.getObservationsBySession(event.session_id);
-        if (observations.length > 0) {
-          const session = db.getSessionMetrics(event.session_id);
-          const summary = extractRetrospective(observations, event.session_id, session?.project_id ?? null, config.user_id);
-          if (summary) {
-            const row = db.insertSessionSummary(summary);
-            db.addToOutbox("summary", row.id);
-            let securityFindings = [];
-            try {
-              if (session?.project_id) {
-                securityFindings = db.getSecurityFindings(session.project_id, { limit: 100 }).filter((f) => f.session_id === event.session_id);
-              }
-            } catch {}
-            const riskResult = computeRiskScore({
-              observations,
-              securityFindings,
-              filesTouchedCount: session?.files_touched_count ?? 0,
-              toolCallsCount: session?.tool_calls_count ?? 0
-            });
-            try {
-              db.setSessionRiskScore(event.session_id, riskResult.score);
-            } catch {}
-            printRetrospective(summary);
-            console.log(formatRiskTrafficLight(riskResult));
-          }
+        const session = db.getSessionMetrics(event.session_id);
+        const summary = extractRetrospective(observations, event.session_id, session?.project_id ?? null, config.user_id) ?? buildFallbackSessionSummary(db, event.session_id, session?.project_id ?? null, config.user_id, event.last_assistant_message);
+        if (summary) {
+          const row = db.insertSessionSummary(summary);
+          db.addToOutbox("summary", row.id);
+          let securityFindings = [];
+          try {
+            if (session?.project_id) {
+              securityFindings = db.getSecurityFindings(session.project_id, { limit: 100 }).filter((f) => f.session_id === event.session_id);
+            }
+          } catch {}
+          const riskResult = computeRiskScore({
+            observations,
+            securityFindings,
+            filesTouchedCount: session?.files_touched_count ?? 0,
+            toolCallsCount: session?.tool_calls_count ?? 0
+          });
+          try {
+            db.setSessionRiskScore(event.session_id, riskResult.score);
+          } catch {}
+          printRetrospective(summary);
+          console.log(formatRiskTrafficLight(riskResult));
         }
       }
     }
     if (event.last_assistant_message) {
-      if (event.session_id) {
-        try {
-          createAssistantCheckpoint(db, event.session_id, event.cwd, event.last_assistant_message);
-        } catch {}
-      }
       const unsaved = detectUnsavedPlans(event.last_assistant_message);
       if (unsaved.length > 0) {
         console.error("");
@@ -3640,6 +3638,44 @@ async function main() {
   }
   process.exit(0);
 }
+function buildFallbackSessionSummary(db, sessionId, projectId, userId, lastAssistantMessage) {
+  const prompts = db.getSessionUserPrompts(sessionId, 10).filter((prompt) => isMeaningfulSummaryPrompt(prompt));
+  const checkpoint = lastAssistantMessage ? extractAssistantCheckpoint(lastAssistantMessage) : null;
+  const request = selectFallbackRequest(prompts);
+  const completed = checkpoint ? buildCheckpointCompleted(checkpoint) : null;
+  if (!request && !completed)
+    return null;
+  return {
+    session_id: sessionId,
+    project_id: projectId,
+    user_id: userId,
+    request,
+    investigated: null,
+    learned: null,
+    completed,
+    next_steps: null
+  };
+}
+function selectFallbackRequest(prompts) {
+  const preferred = [...prompts].reverse().find((prompt) => !/^\[;ease$/i.test(prompt.prompt.trim()));
+  return preferred?.prompt?.replace(/\s+/g, " ").trim() ?? null;
+}
+function isMeaningfulSummaryPrompt(prompt) {
+  const compact = prompt.prompt.replace(/\s+/g, " ").trim();
+  if (compact.length < 8)
+    return false;
+  if (/^\[;ease$/i.test(compact))
+    return false;
+  return /[a-z]{3,}/i.test(compact);
+}
+function buildCheckpointCompleted(checkpoint) {
+  const lines = [`- ${checkpoint.title}`];
+  for (const fact of checkpoint.facts.slice(0, 2)) {
+    lines.push(`  - ${fact}`);
+  }
+  return lines.join(`
+`);
+}
 function createSessionDigest(db, sessionId, cwd) {
   const observations = db.getObservationsBySession(sessionId);
   if (observations.length < 2)

package/dist/server.js

@@ -19764,7 +19764,7 @@ process.on("SIGTERM", () => {
 });
 var server = new McpServer({
   name: "engrm",
-  version: "0.4.15"
+  version: "0.4.17"
 });
 server.tool("save_observation", "Save an observation to memory", {
   type: exports_external.enum([
@@ -19940,11 +19940,11 @@ Facts: ${reduced.facts.join("; ")}` : "";
     ]
   };
 });
-server.tool("capture_git_worktree", "Read the current git worktree diff, reduce it into durable memory, and save it with plugin provenance", {
-  cwd: exports_external.string().optional().describe("Git repo path; defaults to the current working directory"),
-  staged: exports_external.boolean().optional().describe("Capture staged changes instead of unstaged worktree changes"),
-  summary: exports_external.string().optional().describe("Optional human summary or commit-style title"),
-  session_id: exports_external.string().optional()
+server.tool("capture_git_worktree", "Capture the current git worktree as durable memory. Best for saving a meaningful local diff before context is lost.", {
+  cwd: exports_external.string().optional().describe("Git repo path. Defaults to the current working directory."),
+  staged: exports_external.boolean().optional().describe("If true, capture staged changes instead of unstaged worktree changes."),
+  summary: exports_external.string().optional().describe("Optional human summary or commit-style title to steer the saved memory."),
+  session_id: exports_external.string().optional().describe("Optional session ID to link this capture to active work.")
 }, async (params) => {
   let worktree;
   try {
@@ -20000,12 +20000,12 @@ server.tool("capture_git_worktree", "Read the current git worktree diff, reduce
     ]
   };
 });
-server.tool("capture_repo_scan", "Run a lightweight repository scan, reduce the findings into durable memory, and save it with plugin provenance", {
-  cwd: exports_external.string().optional().describe("Repo path to scan; defaults to the current working directory"),
-  focus: exports_external.array(exports_external.string()).optional().describe("Optional extra topics to search for, like 'billing' or 'validation'"),
-  max_findings: exports_external.number().optional().describe("Maximum findings to keep"),
-  summary: exports_external.string().optional().describe("Optional human summary for the scan"),
-  session_id: exports_external.string().optional()
+server.tool("capture_repo_scan", "Run a lightweight repository scan and save reduced findings as durable memory. Best for quick architecture, risk, or implementation scans.", {
+  cwd: exports_external.string().optional().describe("Repo path to scan. Defaults to the current working directory."),
+  focus: exports_external.array(exports_external.string()).optional().describe("Optional topics to bias the scan toward, for example 'billing', 'auth', or 'validation'."),
+  max_findings: exports_external.number().optional().describe("Maximum findings to keep before reduction."),
+  summary: exports_external.string().optional().describe("Optional human summary for the saved memory."),
+  session_id: exports_external.string().optional().describe("Optional session ID to link this scan to active work.")
 }, async (params) => {
   let scan;
   try {
@@ -20063,15 +20063,15 @@ Findings: ${findingSummary}` : ""}`
     ]
   };
 });
-server.tool("capture_openclaw_content", "Reduce OpenClaw content/research activity into durable memory and save it with plugin provenance", {
-  title: exports_external.string().optional().describe("Short content or campaign title"),
-  posted: exports_external.array(exports_external.string()).optional().describe("Concrete posted items or shipped content outcomes"),
-  researched: exports_external.array(exports_external.string()).optional().describe("Research or discovery items"),
-  outcomes: exports_external.array(exports_external.string()).optional().describe("Meaningful outcomes from the run"),
-  next_actions: exports_external.array(exports_external.string()).optional().describe("Real follow-up actions"),
-  links: exports_external.array(exports_external.string()).optional().describe("Thread or source URLs"),
-  session_id: exports_external.string().optional(),
-  cwd: exports_external.string().optional()
+server.tool("capture_openclaw_content", "Capture OpenClaw content, research, and follow-up work as durable memory. Best for preserving posted outcomes, discoveries, and next actions.", {
+  title: exports_external.string().optional().describe("Short content, campaign, or research title."),
+  posted: exports_external.array(exports_external.string()).optional().describe("Concrete posted items or shipped content outcomes."),
+  researched: exports_external.array(exports_external.string()).optional().describe("Research or discovery items worth retaining."),
+  outcomes: exports_external.array(exports_external.string()).optional().describe("Meaningful outcomes from the run."),
+  next_actions: exports_external.array(exports_external.string()).optional().describe("Real follow-up actions that remain."),
+  links: exports_external.array(exports_external.string()).optional().describe("Thread or source URLs tied to the work."),
+  session_id: exports_external.string().optional().describe("Optional session ID to link this memory to active work."),
+  cwd: exports_external.string().optional().describe("Optional project path for attribution.")
 }, async (params) => {
   const reduced = reduceOpenClawContentToMemory({
     ...params,
@@ -20536,9 +20536,9 @@ server.tool("capture_status", "Show whether Engrm hook registration and recent p
     ]
   };
 });
-server.tool("capture_quality", "Show workspace-wide capture richness, checkpoints, and provenance across projects", {
-  limit: exports_external.number().optional(),
-  user_id: exports_external.string().optional()
+server.tool("capture_quality", "Show how healthy Engrm capture is across the workspace: raw chronology coverage, checkpoints, and provenance by tool.", {
+  limit: exports_external.number().optional().describe("Maximum projects to include in the top-projects section."),
+  user_id: exports_external.string().optional().describe("Optional user override; defaults to the configured user.")
 }, async (params) => {
   const result = getCaptureQuality(db, {
     limit: params.limit,
@@ -20575,11 +20575,11 @@ ${projectLines}`
     ]
   };
 });
-server.tool("tool_memory_index", "Show which source tools are producing durable memory and what kinds of memory they create", {
-  cwd: exports_external.string().optional(),
-  project_scoped: exports_external.boolean().optional(),
-  limit: exports_external.number().optional(),
-  user_id: exports_external.string().optional()
+server.tool("tool_memory_index", "Show which tools are actually producing durable memory, which plugins they exercise, and what memory types they create.", {
+  cwd: exports_external.string().optional().describe("Project path to inspect. Defaults to the current working directory."),
+  project_scoped: exports_external.boolean().optional().describe("If true, limit results to the current project instead of the whole workspace."),
+  limit: exports_external.number().optional().describe("Maximum tools to include."),
+  user_id: exports_external.string().optional().describe("Optional user override; defaults to the configured user.")
 }, async (params) => {
   const result = getToolMemoryIndex(db, {
     cwd: params.cwd ?? process.cwd(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "engrm",
-  "version": "0.4.15",
+  "version": "0.4.17",
   "description": "Shared memory across devices, sessions, and coding agents",
   "mcpName": "io.github.dr12hes/engrm",
   "type": "module",