engrm 0.4.14 → 0.4.16

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.14";
+var CLIENT_VERSION = "0.4.16";
 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}Startup context${c2.reset}`);
+    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) {
@@ -3186,7 +3188,7 @@ function formatVisibleStartupBrief(context) {
   const projectSignals = buildProjectSignalLine(context);
   const shownItems = new Set;
   if (promptLines.length > 0) {
-    lines.push(`${c2.cyan}Recent Requests:${c2.reset}`);
+    lines.push(`${c2.cyan}Asked recently:${c2.reset}`);
     for (const item of promptLines) {
       lines.push(`  - ${truncateInline(item, 160)}`);
       rememberShownItem(shownItems, item);
@@ -3218,13 +3220,13 @@ function formatVisibleStartupBrief(context) {
       }
     }
   } else if (currentRequest && !duplicatesPromptLine(currentRequest, latestPromptLine)) {
-    lines.push(`${c2.cyan}Current Request:${c2.reset}`);
+    lines.push(`${c2.cyan}What you're on:${c2.reset}`);
     lines.push(`  - ${truncateInline(currentRequest, 160)}`);
     rememberShownItem(shownItems, currentRequest);
     if (toolFallbacks.length > 0) {
       const additiveTools = filterAdditiveToolFallbacks(toolFallbacks, shownItems);
       if (additiveTools.length > 0) {
-        lines.push(`${c2.cyan}Recent Tools:${c2.reset}`);
+        lines.push(`${c2.cyan}Tool trail:${c2.reset}`);
         for (const item of additiveTools) {
           lines.push(`  - ${truncateInline(item, 160)}`);
           rememberShownItem(shownItems, item);
@@ -3233,12 +3235,12 @@ function formatVisibleStartupBrief(context) {
     }
   }
   if (latest && currentRequest && !hasRequestSection(lines) && !duplicatesPromptLine(currentRequest, latestPromptLine)) {
-    lines.push(`${c2.cyan}Current Request:${c2.reset}`);
+    lines.push(`${c2.cyan}What you're on:${c2.reset}`);
     lines.push(`  - ${truncateInline(currentRequest, 160)}`);
     rememberShownItem(shownItems, currentRequest);
   }
   if (recentOutcomeLines.length > 0) {
-    lines.push(`${c2.cyan}Recent Work:${c2.reset}`);
+    lines.push(`${c2.cyan}What's moved:${c2.reset}`);
     for (const item of recentOutcomeLines) {
       lines.push(`  - ${truncateInline(item, 160)}`);
       rememberShownItem(shownItems, item);
@@ -3247,7 +3249,7 @@ function formatVisibleStartupBrief(context) {
   if (toolFallbacks.length > 0 && latest) {
     const additiveTools = filterAdditiveToolFallbacks(toolFallbacks, shownItems);
     if (additiveTools.length > 0) {
-      lines.push(`${c2.cyan}Recent Tools:${c2.reset}`);
+      lines.push(`${c2.cyan}Tool trail:${c2.reset}`);
       for (const item of additiveTools) {
         lines.push(`  - ${truncateInline(item, 160)}`);
         rememberShownItem(shownItems, item);
@@ -3255,13 +3257,13 @@ function formatVisibleStartupBrief(context) {
     }
   }
   if (sessionFallbacks.length > 0) {
-    lines.push(`${c2.cyan}Recent Sessions:${c2.reset}`);
+    lines.push(`${c2.cyan}Recent threads:${c2.reset}`);
     for (const item of sessionFallbacks) {
       lines.push(`  - ${truncateInline(item, 160)}`);
     }
   }
   if (projectSignals) {
-    lines.push(`${c2.cyan}Project Signals:${c2.reset}`);
+    lines.push(`${c2.cyan}Signal mix:${c2.reset}`);
     lines.push(`  - ${truncateInline(projectSignals, 160)}`);
   }
   const stale = pickRelevantStaleDecision(context, latest);
@@ -3294,11 +3296,11 @@ function formatContextEconomics(data) {
 }
 function formatLegend() {
   return [
-    `${c2.dim}Legend:${c2.reset} #id | \uD83D\uDD34 bugfix | \uD83D\uDFE3 feature | \uD83D\uDD04 refactor | \u2705 change | \uD83D\uDD35 discovery | \u2696\uFE0F decision`
+    `${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}` : ""}`;
@@ -3306,7 +3308,7 @@ function formatContextIndex(context) {
   if (rows.length === 0)
     return [];
   return [
-    `${c2.dim}Context index:${c2.reset} use IDs to fetch deeper detail when needed`,
+    `${c2.dim}Handoff index:${c2.reset} use IDs when you want the deeper thread`,
     ...rows
   ];
 }
@@ -3328,8 +3330,8 @@ function formatInspectHints(context) {
   const ids = context.observations.slice(0, 5).map((obs) => obs.id);
   const fetchHint = ids.length > 0 ? `get_observations([${ids.join(", ")}])` : null;
   return [
-    `${c2.dim}Inspect:${c2.reset} ${unique.join(" \xB7 ")}`,
-    ...fetchHint ? [`${c2.dim}Fetch by ID:${c2.reset} ${fetchHint}`] : []
+    `${c2.dim}Next look:${c2.reset} ${unique.join(" \xB7 ")}`,
+    ...fetchHint ? [`${c2.dim}Pull detail:${c2.reset} ${fetchHint}`] : []
   ];
 }
 function rememberShownItem(shown, value) {
@@ -3452,23 +3454,41 @@ function chooseMeaningfulSessionSummary(request, completed) {
 function buildProjectSignalLine(context) {
   if (!context.projectTypeCounts)
     return null;
-  const top = Object.entries(context.projectTypeCounts).sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, 4).map(([type, count]) => `${type} ${count}`).join("; ");
+  const top = Object.entries(context.projectTypeCounts).sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, 4).map(([type, count]) => `${signalGlyph(type)} ${type} ${count}`).join("; ");
   return top || null;
 }
+function signalGlyph(type) {
+  switch (type) {
+    case "bugfix":
+      return "\u25A0";
+    case "feature":
+      return "\u25B2";
+    case "refactor":
+      return "\u2248";
+    case "change":
+      return "\u25CF";
+    case "discovery":
+      return "\u25A1";
+    case "decision":
+      return "\u25C7";
+    default:
+      return "\xB7";
+  }
+}
 function observationIcon(type) {
   switch (type) {
     case "bugfix":
-      return "\uD83D\uDD34";
+      return "\u25A0";
     case "feature":
-      return "\uD83D\uDFE3";
+      return "\u25B2";
     case "refactor":
-      return "\uD83D\uDD04";
+      return "\u2248";
     case "change":
-      return "\u2705";
+      return "\u25CF";
     case "discovery":
-      return "\uD83D\uDD35";
+      return "\u25A1";
     case "decision":
-      return "\u2696\uFE0F";
+      return "\u25C7";
     default:
       return "\u2022";
   }
@@ -3478,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 [];
@@ -3548,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.14",
+    client_version: "0.4.16",
     context_observations_injected: metrics?.contextObsInjected ?? 0,
     context_total_available: metrics?.contextTotalAvailable ?? 0,
     recall_attempts: metrics?.recallAttempts ?? 0,

package/dist/server.js

@@ -19764,7 +19764,7 @@ process.on("SIGTERM", () => {
 });
 var server = new McpServer({
   name: "engrm",
-  version: "0.4.14"
+  version: "0.4.16"
 });
 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.14",
+  "version": "0.4.16",
   "description": "Shared memory across devices, sessions, and coding agents",
   "mcpName": "io.github.dr12hes/engrm",
   "type": "module",