engrm 0.4.35 → 0.4.37

package/README.md

@@ -288,6 +288,25 @@ How to use it:
 - `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
 
+### Explicit Save Protocol
+
+When something should be remembered on purpose, do not wait for an end-of-session
+digest if an explicit write is more appropriate.
+
+Use:
+
+- `save_observation`
+  - direct durable memory write for a bugfix, decision, discovery, pattern,
+    feature, or change
+- `create_handoff` / `refresh_handoff`
+  - preserve the active thread for another device or a later session
+- `capture_openclaw_content`
+  - save OpenClaw-style research, posting, outcomes, and next actions as
+    reusable memory
+
+Automatic session digests are a safety net.
+They are not the only path for preserving important work.
+
 ### Thin Tools, Thick Memory
 
 Engrm now has a real thin-tool layer, not just a plugin spec.

package/dist/cli.js

@@ -1592,7 +1592,12 @@ class MemDatabase {
   vecChatInsert(chatMessageId, embedding) {
     if (!this.vecAvailable)
       return;
-    this.db.query("INSERT OR REPLACE INTO vec_chat_messages (chat_message_id, embedding) VALUES (?, ?)").run(chatMessageId, new Uint8Array(embedding.buffer));
+    const normalizedId = Number(chatMessageId);
+    if (!Number.isInteger(normalizedId) || normalizedId <= 0)
+      return;
+    try {
+      this.db.query("INSERT OR REPLACE INTO vec_chat_messages (chat_message_id, embedding) VALUES (?, ?)").run(normalizedId, new Uint8Array(embedding.buffer));
+    } catch {}
   }
   searchChatVec(queryEmbedding, projectId, limit = 20, userId) {
     if (!this.vecAvailable)

package/dist/hooks/elicitation-result.js

@@ -2428,7 +2428,12 @@ class MemDatabase {
   vecChatInsert(chatMessageId, embedding) {
     if (!this.vecAvailable)
       return;
-    this.db.query("INSERT OR REPLACE INTO vec_chat_messages (chat_message_id, embedding) VALUES (?, ?)").run(chatMessageId, new Uint8Array(embedding.buffer));
+    const normalizedId = Number(chatMessageId);
+    if (!Number.isInteger(normalizedId) || normalizedId <= 0)
+      return;
+    try {
+      this.db.query("INSERT OR REPLACE INTO vec_chat_messages (chat_message_id, embedding) VALUES (?, ?)").run(normalizedId, new Uint8Array(embedding.buffer));
+    } catch {}
   }
   searchChatVec(queryEmbedding, projectId, limit = 20, userId) {
     if (!this.vecAvailable)

package/dist/hooks/post-tool-use.js

@@ -1770,7 +1770,12 @@ class MemDatabase {
   vecChatInsert(chatMessageId, embedding) {
     if (!this.vecAvailable)
       return;
-    this.db.query("INSERT OR REPLACE INTO vec_chat_messages (chat_message_id, embedding) VALUES (?, ?)").run(chatMessageId, new Uint8Array(embedding.buffer));
+    const normalizedId = Number(chatMessageId);
+    if (!Number.isInteger(normalizedId) || normalizedId <= 0)
+      return;
+    try {
+      this.db.query("INSERT OR REPLACE INTO vec_chat_messages (chat_message_id, embedding) VALUES (?, ?)").run(normalizedId, new Uint8Array(embedding.buffer));
+    } catch {}
   }
   searchChatVec(queryEmbedding, projectId, limit = 20, userId) {
     if (!this.vecAvailable)

package/dist/hooks/pre-compact.js

@@ -1564,7 +1564,12 @@ class MemDatabase {
   vecChatInsert(chatMessageId, embedding) {
     if (!this.vecAvailable)
       return;
-    this.db.query("INSERT OR REPLACE INTO vec_chat_messages (chat_message_id, embedding) VALUES (?, ?)").run(chatMessageId, new Uint8Array(embedding.buffer));
+    const normalizedId = Number(chatMessageId);
+    if (!Number.isInteger(normalizedId) || normalizedId <= 0)
+      return;
+    try {
+      this.db.query("INSERT OR REPLACE INTO vec_chat_messages (chat_message_id, embedding) VALUES (?, ?)").run(normalizedId, new Uint8Array(embedding.buffer));
+    } catch {}
   }
   searchChatVec(queryEmbedding, projectId, limit = 20, userId) {
     if (!this.vecAvailable)

package/dist/hooks/sentinel.js

@@ -1640,7 +1640,12 @@ class MemDatabase {
   vecChatInsert(chatMessageId, embedding) {
     if (!this.vecAvailable)
       return;
-    this.db.query("INSERT OR REPLACE INTO vec_chat_messages (chat_message_id, embedding) VALUES (?, ?)").run(chatMessageId, new Uint8Array(embedding.buffer));
+    const normalizedId = Number(chatMessageId);
+    if (!Number.isInteger(normalizedId) || normalizedId <= 0)
+      return;
+    try {
+      this.db.query("INSERT OR REPLACE INTO vec_chat_messages (chat_message_id, embedding) VALUES (?, ?)").run(normalizedId, new Uint8Array(embedding.buffer));
+    } catch {}
   }
   searchChatVec(queryEmbedding, projectId, limit = 20, userId) {
     if (!this.vecAvailable)

package/dist/hooks/session-start.js

@@ -3225,7 +3225,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.35";
+var CLIENT_VERSION = "0.4.37";
 function hashFile(filePath) {
   try {
     if (!existsSync3(filePath))
@@ -5224,7 +5224,12 @@ class MemDatabase {
   vecChatInsert(chatMessageId, embedding) {
     if (!this.vecAvailable)
       return;
-    this.db.query("INSERT OR REPLACE INTO vec_chat_messages (chat_message_id, embedding) VALUES (?, ?)").run(chatMessageId, new Uint8Array(embedding.buffer));
+    const normalizedId = Number(chatMessageId);
+    if (!Number.isInteger(normalizedId) || normalizedId <= 0)
+      return;
+    try {
+      this.db.query("INSERT OR REPLACE INTO vec_chat_messages (chat_message_id, embedding) VALUES (?, ?)").run(normalizedId, new Uint8Array(embedding.buffer));
+    } catch {}
   }
   searchChatVec(queryEmbedding, projectId, limit = 20, userId) {
     if (!this.vecAvailable)

package/dist/hooks/stop.js

@@ -1797,7 +1797,12 @@ class MemDatabase {
   vecChatInsert(chatMessageId, embedding) {
     if (!this.vecAvailable)
       return;
-    this.db.query("INSERT OR REPLACE INTO vec_chat_messages (chat_message_id, embedding) VALUES (?, ?)").run(chatMessageId, new Uint8Array(embedding.buffer));
+    const normalizedId = Number(chatMessageId);
+    if (!Number.isInteger(normalizedId) || normalizedId <= 0)
+      return;
+    try {
+      this.db.query("INSERT OR REPLACE INTO vec_chat_messages (chat_message_id, embedding) VALUES (?, ?)").run(normalizedId, new Uint8Array(embedding.buffer));
+    } catch {}
   }
   searchChatVec(queryEmbedding, projectId, limit = 20, userId) {
     if (!this.vecAvailable)
@@ -3082,7 +3087,7 @@ function buildBeacon(db, config, sessionId, metrics) {
     sentinel_used: valueSignals.security_findings_count > 0,
     risk_score: riskScore,
     stacks_detected: stacks,
-    client_version: "0.4.35",
+    client_version: "0.4.37",
     context_observations_injected: metrics?.contextObsInjected ?? 0,
     context_total_available: metrics?.contextTotalAvailable ?? 0,
     recall_attempts: metrics?.recallAttempts ?? 0,

package/dist/hooks/user-prompt-submit.js

@@ -1708,7 +1708,12 @@ class MemDatabase {
   vecChatInsert(chatMessageId, embedding) {
     if (!this.vecAvailable)
       return;
-    this.db.query("INSERT OR REPLACE INTO vec_chat_messages (chat_message_id, embedding) VALUES (?, ?)").run(chatMessageId, new Uint8Array(embedding.buffer));
+    const normalizedId = Number(chatMessageId);
+    if (!Number.isInteger(normalizedId) || normalizedId <= 0)
+      return;
+    try {
+      this.db.query("INSERT OR REPLACE INTO vec_chat_messages (chat_message_id, embedding) VALUES (?, ?)").run(normalizedId, new Uint8Array(embedding.buffer));
+    } catch {}
   }
   searchChatVec(queryEmbedding, projectId, limit = 20, userId) {
     if (!this.vecAvailable)

package/dist/server.js

@@ -15114,7 +15114,12 @@ class MemDatabase {
   vecChatInsert(chatMessageId, embedding) {
     if (!this.vecAvailable)
       return;
-    this.db.query("INSERT OR REPLACE INTO vec_chat_messages (chat_message_id, embedding) VALUES (?, ?)").run(chatMessageId, new Uint8Array(embedding.buffer));
+    const normalizedId = Number(chatMessageId);
+    if (!Number.isInteger(normalizedId) || normalizedId <= 0)
+      return;
+    try {
+      this.db.query("INSERT OR REPLACE INTO vec_chat_messages (chat_message_id, embedding) VALUES (?, ?)").run(normalizedId, new Uint8Array(embedding.buffer));
+    } catch {}
   }
   searchChatVec(queryEmbedding, projectId, limit = 20, userId) {
     if (!this.vecAvailable)
@@ -16387,11 +16392,13 @@ function mergeResults(ftsResults, vecResults, limit) {
   return Array.from(scores.entries()).map(([id, score]) => ({ id, score })).sort((a, b) => b.score - a.score).slice(0, limit);
 }
 function sanitizeFtsQuery(query) {
-  let safe = query.replace(/[{}()[\]^~*:]/g, " ");
-  safe = safe.replace(/\s+/g, " ").trim();
-  if (!safe)
+  const normalized = String(query ?? "").normalize("NFKC").replace(/[^\p{L}\p{N}_\s]+/gu, " ").replace(/\s+/g, " ").trim();
+  if (!normalized)
     return "";
-  return safe;
+  const terms = normalized.split(" ").map((term) => term.trim()).filter(Boolean).slice(0, 16);
+  if (terms.length === 0)
+    return "";
+  return terms.map((term) => `"${term}"`).join(" ");
 }
 
 // src/tools/recent-chat.ts
@@ -18947,6 +18954,7 @@ function getMemoryConsole(db, input) {
     recent_outcomes: projectIndex?.recent_outcomes ?? [],
     hot_files: projectIndex?.hot_files ?? [],
     provenance_summary: projectIndex?.provenance_summary ?? [],
+    provenance_type_mix: collectProvenanceTypeMix(observations),
     assistant_checkpoint_count: projectIndex?.assistant_checkpoint_count,
     assistant_checkpoint_types: projectIndex?.assistant_checkpoint_types ?? [],
     top_types: projectIndex?.top_types ?? [],
@@ -18954,6 +18962,24 @@ function getMemoryConsole(db, input) {
     suggested_tools: projectIndex?.suggested_tools ?? buildFallbackSuggestedTools(sessions.length, requests.length, tools.length, observations.length, recentHandoffs.length, recentChat.messages.length, recentChat.coverage_state, activeAgents.length)
   };
 }
+function collectProvenanceTypeMix(observations) {
+  const grouped = new Map;
+  for (const observation of observations) {
+    if (!observation.source_tool)
+      continue;
+    const typeCounts = grouped.get(observation.source_tool) ?? new Map;
+    typeCounts.set(observation.type, (typeCounts.get(observation.type) ?? 0) + 1);
+    grouped.set(observation.source_tool, typeCounts);
+  }
+  return Array.from(grouped.entries()).map(([tool, typeCounts]) => {
+    const topTypes = Array.from(typeCounts.entries()).map(([type, count]) => ({ type, count })).sort((a, b) => b.count - a.count || a.type.localeCompare(b.type)).slice(0, 4);
+    return {
+      tool,
+      count: topTypes.reduce((sum, item) => sum + item.count, 0),
+      top_types: topTypes
+    };
+  }).sort((a, b) => b.count - a.count || a.tool.localeCompare(b.tool)).slice(0, 6);
+}
 function buildFallbackSuggestedTools(sessionCount, requestCount, toolCount, observationCount, handoffCount, chatCount, chatCoverageState, activeAgentCount) {
   const suggested = [];
   if (sessionCount > 0)
@@ -20686,7 +20712,12 @@ async function repairRecall(db, config2, input = {}) {
   let sessionsWithImports = 0;
   for (const session of targetSessions) {
     const sessionCwd = session.project_id !== null ? db.getProjectById(session.project_id)?.local_path ?? cwd : cwd;
-    const syncResult = await syncTranscriptChat(db, config2, session.session_id, sessionCwd, input.transcript_path);
+    let syncResult = { imported: 0, total: 0 };
+    try {
+      syncResult = await syncTranscriptChat(db, config2, session.session_id, sessionCwd, input.transcript_path);
+    } catch {
+      syncResult = { imported: 0, total: 0 };
+    }
     const chatMessages = db.getSessionChatMessages(session.session_id, 200);
     const prompts = db.getSessionUserPrompts(session.session_id, 200);
     const sourceSummary = summarizeChatSources(chatMessages);
@@ -22842,9 +22873,9 @@ process.on("SIGTERM", () => {
 });
 var server = new McpServer({
   name: "engrm",
-  version: "0.4.35"
+  version: "0.4.37"
 });
-server.tool("save_observation", "Save an observation to memory", {
+server.tool("save_observation", "Directly save a durable memory item now. Use this when something should be remembered on purpose instead of waiting for an end-of-session digest.", {
   type: exports_external.enum([
     "bugfix",
     "discovery",
@@ -23141,7 +23172,7 @@ Findings: ${findingSummary}` : ""}`
     ]
   };
 });
-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.", {
+server.tool("capture_openclaw_content", "Directly save OpenClaw content, research, and follow-up work as durable memory. Best for preserving posted outcomes, discoveries, and next actions during or right after the run.", {
   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."),
@@ -23815,7 +23846,7 @@ server.tool("memory_console", "Show a high-signal local overview of what Engrm c
 `) : "- (none)";
   const provenanceLines = result.provenance_summary.length > 0 ? result.provenance_summary.map((item) => `- ${item.tool}: ${item.count}`).join(`
 `) : "- (none)";
-  const provenanceMixLines2 = result.provenance_type_mix.length > 0 ? result.provenance_type_mix.map((item) => `- ${item.tool}: ${item.top_types.map((entry) => `${entry.type} ${entry.count}`).join(", ")}`).join(`
+  const provenanceMixLines = result.provenance_type_mix.length > 0 ? result.provenance_type_mix.map((item) => `- ${item.tool}: ${item.top_types.map((entry) => `${entry.type} ${entry.count}`).join(", ")}`).join(`
 `) : "- (none)";
   const checkpointTypeLines = result.assistant_checkpoint_types.length > 0 ? result.assistant_checkpoint_types.map((item) => `- ${item.type}: ${item.count}`).join(`
 `) : "- (none)";
@@ -23935,6 +23966,8 @@ server.tool("capture_quality", "Show how healthy Engrm capture is across the wor
   const provenanceLines = result.provenance_summary.length > 0 ? result.provenance_summary.map((item) => `- ${item.tool}: ${item.count}`).join(`
 `) : "- (none)";
   const checkpointTypeLines = result.assistant_checkpoint_types.length > 0 ? result.assistant_checkpoint_types.map((item) => `- ${item.type}: ${item.count}`).join(`
+`) : "- (none)";
+  const provenanceMixLines = result.provenance_type_mix.length > 0 ? result.provenance_type_mix.map((item) => `- ${item.tool}: ${item.top_types.map((entry) => `${entry.type} ${entry.count}`).join(", ")}`).join(`
 `) : "- (none)";
   const projectLines = result.top_projects.length > 0 ? result.top_projects.map((project) => `- ${project.name} [${project.raw_capture_state}] obs=${project.observation_count} sessions=${project.session_count} prompts=${project.prompt_count} tools=${project.tool_event_count} checkpoints=${project.assistant_checkpoint_count} chat=${project.chat_message_count} (${project.chat_coverage_state})`).join(`
 `) : "- (none)";

package/package.json

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