@joshuaswarren/openclaw-engram 8.3.14 → 8.3.15

package/dist/index.js

@@ -139,6 +139,7 @@ function parseConfig(raw) {
     // Retrieval options
     recencyWeight: typeof cfg.recencyWeight === "number" ? cfg.recencyWeight : 0.2,
     boostAccessCount: cfg.boostAccessCount !== false,
+    recordEmptyRecallImpressions: cfg.recordEmptyRecallImpressions === true,
     // v2.2 Advanced Retrieval (safe defaults: off unless enabled)
     queryExpansionEnabled: cfg.queryExpansionEnabled === true,
     queryExpansionMaxQueries: typeof cfg.queryExpansionMaxQueries === "number" ? cfg.queryExpansionMaxQueries : 4,
@@ -366,8 +367,12 @@ function parseConfig(raw) {
     // v8.2: Multi-graph memory (PR 18)
     multiGraphMemoryEnabled: cfg.multiGraphMemoryEnabled === true,
     graphRecallEnabled: cfg.graphRecallEnabled === true,
+    graphExpandedIntentEnabled: cfg.graphExpandedIntentEnabled !== false,
+    graphAssistInFullModeEnabled: cfg.graphAssistInFullModeEnabled !== false,
+    graphAssistMinSeedResults: typeof cfg.graphAssistMinSeedResults === "number" ? Math.max(1, Math.floor(cfg.graphAssistMinSeedResults)) : 3,
     entityGraphEnabled: cfg.entityGraphEnabled !== false,
     timeGraphEnabled: cfg.timeGraphEnabled !== false,
+    graphWriteSessionAdjacencyEnabled: cfg.graphWriteSessionAdjacencyEnabled !== false,
     causalGraphEnabled: cfg.causalGraphEnabled !== false,
     maxGraphTraversalSteps: typeof cfg.maxGraphTraversalSteps === "number" ? Math.max(0, cfg.maxGraphTraversalSteps) : 3,
     graphActivationDecay: typeof cfg.graphActivationDecay === "number" ? Math.min(1, Math.max(0, cfg.graphActivationDecay)) : 0.7,
@@ -3503,11 +3508,27 @@ var QMD_DAEMON_TIMEOUT_MS = 6e4;
 var QMD_PROBE_TIMEOUT_MS = 8e3;
 var QMD_UPDATE_BACKOFF_MS = 15 * 60 * 1e3;
 var QMD_EMBED_BACKOFF_MS = 60 * 60 * 1e3;
+var QMD_CLI_WARN_THROTTLE_MS = 15 * 60 * 1e3;
 var QMD_FALLBACK_PATHS = [
   path2.join(os2.homedir(), ".bun", "bin", "qmd"),
   "/usr/local/bin/qmd",
   "/opt/homebrew/bin/qmd"
 ];
+var QMD_GLOBAL_STATE_KEY = "__openclawEngramQmdGlobalState";
+function getGlobalQmdState() {
+  const g = globalThis;
+  if (!g[QMD_GLOBAL_STATE_KEY]) {
+    g[QMD_GLOBAL_STATE_KEY] = {
+      warnedGlobalUpdateBehavior: false,
+      lastGlobalUpdateRunAtMs: null,
+      lastGlobalUpdateFailAtMs: null,
+      lastGlobalEmbedRunAtMs: null,
+      lastGlobalEmbedFailAtMs: null,
+      lastCliWarnAtMs: null
+    };
+  }
+  return g[QMD_GLOBAL_STATE_KEY];
+}
 function sleep(ms) {
   return new Promise((r) => setTimeout(r, ms));
 }
@@ -3724,7 +3745,6 @@ var QmdClient = class {
   lastUpdateFailAtMs = null;
   lastEmbedFailAtMs = null;
   lastUpdateRunAtMs = null;
-  warnedGlobalUpdateBehavior = false;
   updateTimeoutMs;
   updateMinIntervalMs;
   slowLog;
@@ -3794,9 +3814,9 @@ ${stderr}`.trim();
         return true;
       } catch (err) {
         markProbeFailure(err);
-        log.warn(`QMD: configured qmdPath failed (${this.configuredQmdPath}): ${this.lastCliProbeError}`);
-        this.available = false;
-        return false;
+        this.logCliProbeWarning(
+          `QMD: configured qmdPath failed (${this.configuredQmdPath}): ${this.lastCliProbeError}`
+        );
       }
     }
     try {
@@ -3827,6 +3847,21 @@ ${stderr}`.trim();
       return false;
     }
   }
+  logCliProbeWarning(message) {
+    const state = getGlobalQmdState();
+    const now = Date.now();
+    const canWarn = state.lastCliWarnAtMs === null || now - state.lastCliWarnAtMs >= QMD_CLI_WARN_THROTTLE_MS;
+    if (!canWarn) {
+      log.debug(message);
+      return;
+    }
+    state.lastCliWarnAtMs = now;
+    if (this.daemonAvailable) {
+      log.debug(message);
+      return;
+    }
+    log.warn(message);
+  }
   /** Re-probe daemon if it was down and recheck interval has elapsed. */
   async maybeProbeDaemon() {
     if (!this.daemonSession) return;
@@ -3951,9 +3986,11 @@ ${stderr}`.trim();
    */
   async hybridSearch(query, collection, maxResults) {
     const n = maxResults ?? this.maxResults;
+    const trimmed = query.trim();
+    if (!trimmed) return [];
     const [bm25Results, vectorResults] = await Promise.all([
-      this.bm25Search(query, collection, n),
-      this.vectorSearch(query, collection, n)
+      this.bm25Search(trimmed, collection, n),
+      this.vectorSearch(trimmed, collection, n)
     ]);
     const merged = /* @__PURE__ */ new Map();
     for (const r of [...bm25Results, ...vectorResults]) {
@@ -4097,6 +4134,7 @@ ${stderr}`.trim();
   }
   async update() {
     if (this.available === false) return;
+    const globalState = getGlobalQmdState();
     if (this.lastUpdateRunAtMs && Date.now() - this.lastUpdateRunAtMs < this.updateMinIntervalMs) {
       log.debug("QMD update: suppressed due to min-interval gate");
       return;
@@ -4105,9 +4143,17 @@ ${stderr}`.trim();
       log.debug("QMD update: suppressed due to recent failures (backoff)");
       return;
     }
+    if (globalState.lastGlobalUpdateRunAtMs && Date.now() - globalState.lastGlobalUpdateRunAtMs < this.updateMinIntervalMs) {
+      log.debug("QMD update: suppressed by global min-interval gate");
+      return;
+    }
+    if (globalState.lastGlobalUpdateFailAtMs && Date.now() - globalState.lastGlobalUpdateFailAtMs < QMD_UPDATE_BACKOFF_MS) {
+      log.debug("QMD update: suppressed by global failure backoff");
+      return;
+    }
     try {
-      if (!this.warnedGlobalUpdateBehavior) {
-        this.warnedGlobalUpdateBehavior = true;
+      if (!globalState.warnedGlobalUpdateBehavior) {
+        globalState.warnedGlobalUpdateBehavior = true;
         log.warn(
           "QMD update runs globally across collections in current CLI versions; Engram now rate-limits update calls to reduce gateway load."
         );
@@ -4118,20 +4164,33 @@ ${stderr}`.trim();
       if (this.slowLog?.enabled && durationMs >= this.slowLog.thresholdMs) {
         log.warn(`SLOW QMD update: durationMs=${durationMs}`);
       }
-      this.lastUpdateRunAtMs = Date.now();
+      const now = Date.now();
+      this.lastUpdateRunAtMs = now;
+      globalState.lastGlobalUpdateRunAtMs = now;
       log.debug("QMD update completed");
     } catch (err) {
-      this.lastUpdateFailAtMs = Date.now();
+      const now = Date.now();
+      this.lastUpdateFailAtMs = now;
+      globalState.lastGlobalUpdateFailAtMs = now;
       const msg = err instanceof Error ? err.message : String(err);
       log.warn(`QMD update failed: ${msg}`);
     }
   }
   async embed() {
     if (this.available === false) return;
+    const globalState = getGlobalQmdState();
     if (this.lastEmbedFailAtMs && Date.now() - this.lastEmbedFailAtMs < QMD_EMBED_BACKOFF_MS) {
       log.debug("QMD embed: suppressed due to recent failures (backoff)");
       return;
     }
+    if (globalState.lastGlobalEmbedRunAtMs && Date.now() - globalState.lastGlobalEmbedRunAtMs < this.updateMinIntervalMs) {
+      log.debug("QMD embed: suppressed by global min-interval gate");
+      return;
+    }
+    if (globalState.lastGlobalEmbedFailAtMs && Date.now() - globalState.lastGlobalEmbedFailAtMs < QMD_EMBED_BACKOFF_MS) {
+      log.debug("QMD embed: suppressed by global failure backoff");
+      return;
+    }
     try {
       const startedAtMs = Date.now();
       await runQmd(["embed", "-c", this.collection], 3e5, this.qmdPath);
@@ -4139,9 +4198,12 @@ ${stderr}`.trim();
       if (this.slowLog?.enabled && durationMs >= this.slowLog.thresholdMs) {
         log.warn(`SLOW QMD embed: durationMs=${durationMs}`);
       }
+      globalState.lastGlobalEmbedRunAtMs = Date.now();
       log.debug("QMD embed completed");
     } catch (err) {
-      this.lastEmbedFailAtMs = Date.now();
+      const now = Date.now();
+      this.lastEmbedFailAtMs = now;
+      globalState.lastGlobalEmbedFailAtMs = now;
       const msg = err instanceof Error ? err.message : String(err);
       log.warn(`QMD embed failed: ${msg}`);
     }
@@ -8341,6 +8403,13 @@ function planRecallMode(prompt) {
   }
   return "full";
 }
+function hasBroadGraphIntent(prompt) {
+  const p = normalizeTextInput(prompt).trim().toLowerCase();
+  if (!p) return false;
+  return /\b(what changed|how did we get here|why did this happen|what led to|cause chain|dependency chain|regression chain|failure chain)\b/i.test(
+    p
+  );
+}
 
 // src/recall-query-policy.ts
 var DEFAULT_STOPWORDS = /* @__PURE__ */ new Set([
@@ -8883,6 +8952,32 @@ import * as fs from "fs";
 import * as path14 from "path";
 import { mkdir as mkdir11, readFile as readFile12, writeFile as writeFile11, readdir as readdir7 } from "fs/promises";
 var TMT_DIR = "tmt";
+var TMT_LEVEL_INPUT_LIMITS = {
+  hour: { totalChars: 48e3, itemChars: 2e3, maxItems: 64 },
+  day: { totalChars: 64e3, itemChars: 1800, maxItems: 96 },
+  week: { totalChars: 72e3, itemChars: 1600, maxItems: 120 },
+  persona: { totalChars: 8e4, itemChars: 1600, maxItems: 120 }
+};
+function capTmtSummaryInputs(inputs, level) {
+  const { totalChars, itemChars, maxItems } = TMT_LEVEL_INPUT_LIMITS[level];
+  if (inputs.length === 0) return [];
+  const capped = [];
+  let usedChars = 0;
+  for (const raw of inputs) {
+    if (capped.length >= maxItems || usedChars >= totalChars) break;
+    const trimmed = raw.trim();
+    if (!trimmed) continue;
+    const next = trimmed.length > itemChars ? `${trimmed.slice(0, itemChars - 1)}\u2026` : trimmed;
+    const separator = capped.length === 0 ? 0 : 2;
+    if (usedChars + separator + next.length > totalChars) break;
+    capped.push(next);
+    usedChars += separator + next.length;
+  }
+  if (capped.length > 0) return capped;
+  const fallback = inputs[0]?.trim() ?? "";
+  if (!fallback) return [];
+  return [fallback.length > itemChars ? `${fallback.slice(0, itemChars - 1)}\u2026` : fallback];
+}
 function tmtDir(baseDir) {
   return path14.join(baseDir, TMT_DIR);
 }
@@ -8979,7 +9074,7 @@ var TmtBuilder = class {
       if (!shouldBuild) continue;
       let summary;
       try {
-        summary = await summarize(entries.map((e) => e.content), "hour");
+        summary = await summarize(capTmtSummaryInputs(entries.map((e) => e.content), "hour"), "hour");
       } catch (err) {
         console.warn(`[engram] tmt: hour node summarize failed for ${key} (ignored): ${err}`);
         continue;
@@ -9044,7 +9139,7 @@ var TmtBuilder = class {
       if (inputs.length === 0) inputs.push(...entries.map((e) => e.content));
       let summary;
       try {
-        summary = await summarize(inputs, "day");
+        summary = await summarize(capTmtSummaryInputs(inputs, "day"), "day");
       } catch (err) {
         console.warn(`[engram] tmt: day node summarize failed for ${date} (ignored): ${err}`);
         continue;
@@ -9114,7 +9209,7 @@ var TmtBuilder = class {
           }
         }
         const inputs = daySummaries.length > 0 ? daySummaries : entries.map((e) => e.content);
-        const summary = await summarize(inputs, "week");
+        const summary = await summarize(capTmtSummaryInputs(inputs, "week"), "week");
         const sortedCreated = entries.map((e) => e.created).sort();
         const fm = {
           level: "week",
@@ -9184,7 +9279,7 @@ var TmtBuilder = class {
         }
       }
       if (!shouldBuild) return;
-      const summary = await summarize(weekSummaries, "persona");
+      const summary = await summarize(capTmtSummaryInputs(weekSummaries, "persona"), "persona");
       const now = (/* @__PURE__ */ new Date()).toISOString();
       const fm = {
         level: "persona",
@@ -10484,7 +10579,10 @@ function computeArtifactRecallLimit(recallMode, recallResultLimit, verbatimArtif
   return base;
 }
 function resolveEffectiveRecallMode(options) {
-  const plannedMode = options.plannerEnabled ? planRecallMode(options.prompt) : "full";
+  let plannedMode = options.plannerEnabled ? planRecallMode(options.prompt) : "full";
+  if (plannedMode !== "graph_mode" && options.plannerEnabled && options.graphExpandedIntentEnabled === true && hasBroadGraphIntent(options.prompt)) {
+    plannedMode = "graph_mode";
+  }
   if (plannedMode === "graph_mode" && (!options.graphRecallEnabled || !options.multiGraphMemoryEnabled)) {
     return "full";
   }
@@ -11190,34 +11288,39 @@ var Orchestrator = class _Orchestrator {
   }
   async fetchQmdMemoryResultsWithArtifactTopUp(prompt, qmdFetchLimit, qmdHybridFetchLimit, options) {
     let fetchLimit = Math.max(qmdFetchLimit, qmdHybridFetchLimit);
-    const maxFetchLimit = Math.min(800, Math.max(fetchLimit, qmdFetchLimit * 8));
-    const MAX_ATTEMPTS = 4;
+    const maxFetchLimit = Math.min(320, Math.max(fetchLimit, qmdFetchLimit * 5));
+    const MAX_ATTEMPTS = 2;
+    const QMD_RECALL_BUDGET_MS = 25e3;
+    const startedAtMs = Date.now();
     let bestFiltered = [];
-    let queryFallbackAttempted = false;
-    const runQueryFallback = async () => {
-      if (queryFallbackAttempted) return [];
-      queryFallbackAttempted = true;
-      const queryResults = await this.qmd.search(prompt, options.collection, fetchLimit);
-      const filteredQueryResults = filterRecallCandidates(queryResults, {
-        namespacesEnabled: options.namespacesEnabled,
-        recallNamespaces: options.recallNamespaces,
-        resolveNamespace: options.resolveNamespace,
-        limit: fetchLimit
-      });
-      if (filteredQueryResults.length > 0) {
-        log.debug(
-          `QMD query fallback returned ${filteredQueryResults.length} candidates after hybrid underfilled`
-        );
-      }
-      return filteredQueryResults;
-    };
     for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt += 1) {
-      const memoryResults = await this.qmd.hybridSearch(
+      if (Date.now() - startedAtMs >= QMD_RECALL_BUDGET_MS) {
+        break;
+      }
+      const primaryResults = await this.qmd.search(
         prompt,
         options.collection,
         fetchLimit
       );
-      const filteredResults = filterRecallCandidates(memoryResults, {
+      let mergedResults = primaryResults;
+      if (primaryResults.length < qmdFetchLimit && Date.now() - startedAtMs < QMD_RECALL_BUDGET_MS) {
+        const hybridResults = await this.qmd.hybridSearch(prompt, options.collection, fetchLimit);
+        if (hybridResults.length > 0) {
+          const mergedByPath = /* @__PURE__ */ new Map();
+          for (const result of [...primaryResults, ...hybridResults]) {
+            const key = result.path || result.docid;
+            const existing = mergedByPath.get(key);
+            if (!existing || result.score > existing.score) {
+              mergedByPath.set(key, {
+                ...result,
+                snippet: result.snippet || existing?.snippet || ""
+              });
+            }
+          }
+          mergedResults = [...mergedByPath.values()].sort((a, b) => b.score - a.score).slice(0, fetchLimit);
+        }
+      }
+      const filteredResults = filterRecallCandidates(mergedResults, {
         namespacesEnabled: options.namespacesEnabled,
         recallNamespaces: options.recallNamespaces,
         resolveNamespace: options.resolveNamespace,
@@ -11229,14 +11332,10 @@ var Orchestrator = class _Orchestrator {
       if (filteredResults.length > bestFiltered.length) {
         bestFiltered = filteredResults;
       }
-      if (memoryResults.length === 0) {
-        const queryFallback = await runQueryFallback();
-        if (queryFallback.length > 0) {
-          return queryFallback.slice(0, qmdFetchLimit);
-        }
+      if (mergedResults.length === 0) {
         return filteredResults;
       }
-      if (memoryResults.length < fetchLimit && filteredResults.length > 0) {
+      if (mergedResults.length < fetchLimit && filteredResults.length > 0) {
         return filteredResults;
       }
       if (fetchLimit >= maxFetchLimit) {
@@ -11245,13 +11344,7 @@ var Orchestrator = class _Orchestrator {
       const growth = Math.max(20, Math.floor(fetchLimit / 2));
       fetchLimit = Math.min(maxFetchLimit, fetchLimit + growth);
     }
-    if (bestFiltered.length === 0) {
-      const queryFallback = await runQueryFallback();
-      if (queryFallback.length > 0) {
-        return queryFallback.slice(0, qmdFetchLimit);
-      }
-    }
-    return bestFiltered;
+    return bestFiltered.slice(0, qmdFetchLimit);
   }
   async expandResultsViaGraph(options) {
     const byNamespace = /* @__PURE__ */ new Map();
@@ -11333,6 +11426,7 @@ var Orchestrator = class _Orchestrator {
   async recallInternal(prompt, sessionKey) {
     const recallStart = Date.now();
     const timings = {};
+    const promptHash = createHash4("sha256").update(prompt).digest("hex");
     const sections = [];
     const queryPolicy = buildRecallQueryPolicy(prompt, sessionKey, {
       cronRecallPolicyEnabled: this.config.cronRecallPolicyEnabled,
@@ -11341,11 +11435,16 @@ var Orchestrator = class _Orchestrator {
       cronConversationRecallMode: this.config.cronConversationRecallMode
     });
     const retrievalQuery = queryPolicy.retrievalQuery || prompt;
+    const retrievalQueryHash = createHash4("sha256").update(retrievalQuery).digest("hex");
+    let impressionRecorded = false;
+    let recallSource = "none";
+    let recalledMemoryCount = 0;
     timings.queryPolicy = `${queryPolicy.promptShape}/${queryPolicy.retrievalBudgetMode}${queryPolicy.skipConversationRecall ? "/skip-conv" : ""}`;
     const recallMode = resolveEffectiveRecallMode({
       plannerEnabled: this.config.recallPlannerEnabled,
       graphRecallEnabled: this.config.graphRecallEnabled,
       multiGraphMemoryEnabled: this.config.multiGraphMemoryEnabled,
+      graphExpandedIntentEnabled: this.config.graphExpandedIntentEnabled === true,
       prompt
     });
     timings.recallPlan = recallMode;
@@ -11366,6 +11465,27 @@ var Orchestrator = class _Orchestrator {
     const embeddingFetchLimit = computedFetchLimit;
     if (recallMode === "no_recall") {
       timings.total = `${Date.now() - recallStart}ms`;
+      this.emitTrace({
+        kind: "recall_summary",
+        traceId: createHash4("sha256").update(`${sessionKey ?? "default"}:${Date.now()}:${promptHash}`).digest("hex").slice(0, 16),
+        operation: "recall",
+        sessionKey,
+        promptHash,
+        promptLength: prompt.length,
+        retrievalQueryHash,
+        retrievalQueryLength: retrievalQuery.length,
+        recallMode,
+        recallResultLimit,
+        qmdEnabled: this.config.qmdEnabled,
+        qmdAvailable: this.qmd.isAvailable(),
+        recallNamespaces: [],
+        source: recallSource,
+        recalledMemoryCount,
+        injected: false,
+        contextChars: 0,
+        durationMs: Date.now() - recallStart,
+        timings: { ...timings }
+      });
       return "";
     }
     const principal = resolvePrincipal(sessionKey, this.config);
@@ -11512,7 +11632,8 @@ ${tmtNode.summary}`);
         );
       }
       memoryResults = memoryResults.filter((r) => !isArtifactMemoryPath(r.path));
-      if (recallMode === "graph_mode") {
+      const shouldRunGraphExpansion = recallMode === "graph_mode" || this.config.multiGraphMemoryEnabled && this.config.graphAssistInFullModeEnabled !== false && recallMode === "full" && memoryResults.length >= Math.max(1, this.config.graphAssistMinSeedResults ?? 3);
+      if (shouldRunGraphExpansion) {
         const {
           merged,
           seedPaths,
@@ -11567,6 +11688,8 @@ ${tmtNode.summary}`);
       }
       memoryResults = memoryResults.slice(0, recallResultLimit);
       if (memoryResults.length > 0) {
+        recallSource = "hot_qmd";
+        recalledMemoryCount = memoryResults.length;
         this.publishRecallResults({
           title: "Relevant Memories",
           results: memoryResults,
@@ -11574,6 +11697,7 @@ ${tmtNode.summary}`);
           retrievalQuery,
           sessionKey
         });
+        impressionRecorded = true;
       } else {
         const embeddingResults = await this.searchEmbeddingFallback(retrievalQuery, embeddingFetchLimit);
         const scopedCandidates = filterRecallCandidates(embeddingResults, {
@@ -11587,6 +11711,8 @@ ${tmtNode.summary}`);
           recallResultLimit
         );
         if (scoped.length > 0) {
+          recallSource = "hot_embedding";
+          recalledMemoryCount = scoped.length;
           this.publishRecallResults({
             title: "Relevant Memories",
             results: scoped,
@@ -11594,6 +11720,7 @@ ${tmtNode.summary}`);
             retrievalQuery,
             sessionKey
           });
+          impressionRecorded = true;
         } else {
           const longTerm = await this.applyColdFallbackPipeline({
             prompt: retrievalQuery,
@@ -11601,6 +11728,8 @@ ${tmtNode.summary}`);
             recallResultLimit
           });
           if (longTerm.length > 0) {
+            recallSource = "cold_fallback";
+            recalledMemoryCount = longTerm.length;
             this.publishRecallResults({
               title: "Long-Term Memories (Fallback)",
               results: longTerm,
@@ -11608,6 +11737,7 @@ ${tmtNode.summary}`);
               retrievalQuery,
               sessionKey
             });
+            impressionRecorded = true;
           }
         }
       }
@@ -11644,6 +11774,8 @@ ${tmtNode.summary}`);
         retrievalQuery
       )).slice(0, recallResultLimit);
       if (scoped.length > 0) {
+        recallSource = "hot_embedding";
+        recalledMemoryCount = scoped.length;
         this.publishRecallResults({
           title: "Relevant Memories",
           results: scoped,
@@ -11651,6 +11783,7 @@ ${tmtNode.summary}`);
           retrievalQuery,
           sessionKey
         });
+        impressionRecorded = true;
       } else {
         const memories = await this.readAllMemoriesForNamespaces(recallNamespaces);
         if (memories.length > 0) {
@@ -11676,6 +11809,8 @@ ${tmtNode.summary}`);
             preloadedMap
           )).sort((a, b) => b.score - a.score).slice(0, recallResultLimit);
           if (recent.length > 0) {
+            recallSource = "recent_scan";
+            recalledMemoryCount = recent.length;
             this.publishRecallResults({
               title: "Recent Memories",
               results: recent,
@@ -11683,6 +11818,7 @@ ${tmtNode.summary}`);
               retrievalQuery,
               sessionKey
             });
+            impressionRecorded = true;
           } else {
             const longTerm = await this.applyColdFallbackPipeline({
               prompt: retrievalQuery,
@@ -11690,6 +11826,8 @@ ${tmtNode.summary}`);
               recallResultLimit
             });
             if (longTerm.length > 0) {
+              recallSource = "cold_fallback";
+              recalledMemoryCount = longTerm.length;
               this.publishRecallResults({
                 title: "Long-Term Memories (Fallback)",
                 results: longTerm,
@@ -11697,6 +11835,7 @@ ${tmtNode.summary}`);
                 retrievalQuery,
                 sessionKey
               });
+              impressionRecorded = true;
             }
           }
         } else {
@@ -11706,6 +11845,8 @@ ${tmtNode.summary}`);
             recallResultLimit
           });
           if (longTerm.length > 0) {
+            recallSource = "cold_fallback";
+            recalledMemoryCount = longTerm.length;
             this.publishRecallResults({
               title: "Long-Term Memories (Fallback)",
               results: longTerm,
@@ -11713,6 +11854,7 @@ ${tmtNode.summary}`);
               retrievalQuery,
               sessionKey
             });
+            impressionRecorded = true;
           }
         }
       }
@@ -11848,8 +11990,32 @@ _Context: ${topQuestion.context}_`);
     timings.total = `${Date.now() - recallStart}ms`;
     const timingParts = Object.entries(timings).map(([k, v]) => `${k}=${v}`).join(", ");
     log.debug(`recall: ${timingParts}`);
-    if (sections.length === 0) return "";
-    return sections.join("\n\n---\n\n");
+    if (!impressionRecorded && sessionKey && this.config.recordEmptyRecallImpressions) {
+      this.lastRecall.record({ sessionKey, query: retrievalQuery, memoryIds: [] }).catch((err) => log.debug(`last recall record failed: ${err}`));
+    }
+    const context = sections.length === 0 ? "" : sections.join("\n\n---\n\n");
+    this.emitTrace({
+      kind: "recall_summary",
+      traceId: createHash4("sha256").update(`${sessionKey ?? "default"}:${Date.now()}:${promptHash}`).digest("hex").slice(0, 16),
+      operation: "recall",
+      sessionKey,
+      promptHash,
+      promptLength: prompt.length,
+      retrievalQueryHash,
+      retrievalQueryLength: retrievalQuery.length,
+      recallMode,
+      recallResultLimit,
+      qmdEnabled: this.config.qmdEnabled,
+      qmdAvailable: this.qmd.isAvailable(),
+      recallNamespaces,
+      source: recallSource,
+      recalledMemoryCount,
+      injected: context.length > 0,
+      contextChars: context.length,
+      durationMs: Date.now() - recallStart,
+      timings: { ...timings }
+    });
+    return context;
   }
   async processTurn(role, content, sessionKey) {
     if (role !== "user" && role !== "assistant") {
@@ -12426,6 +12592,9 @@ _Context: ${topQuestion.context}_`);
       } catch {
       }
     }
+    if (recentInThread.length === 0 && this.config.graphWriteSessionAdjacencyEnabled !== false && fallbackCausalPredecessor && fallbackCausalPredecessor !== memoryRelPath) {
+      recentInThread.push(fallbackCausalPredecessor);
+    }
     const causalPredecessor = recentInThread[recentInThread.length - 1] ?? fallbackCausalPredecessor;
     await this.graphIndexFor(storage).onMemoryWritten({
       memoryPath: memoryRelPath,
@@ -12938,6 +13107,14 @@ ${snippet}`;
 
 ${lines.join("\n\n")}`;
   }
+  emitTrace(event) {
+    try {
+      const cb = globalThis.__openclawEngramTrace;
+      if (typeof cb === "function") cb(event);
+    } catch (err) {
+      log.debug(`trace callback failed: ${err}`);
+    }
+  }
   publishRecallResults(options) {
     const memoryIds = this.extractMemoryIdsFromResults(options.results);
     this.trackMemoryAccess(memoryIds);
@@ -14298,7 +14475,7 @@ mistakes: ${res.mistakesCount} patterns`
 
 // src/cli.ts
 import path33 from "path";
-import { access as access2, readFile as readFile22 } from "fs/promises";
+import { access as access2, readFile as readFile22, readdir as readdir12, unlink as unlink3 } from "fs/promises";
 
 // src/transfer/export-json.ts
 import path25 from "path";
@@ -14769,6 +14946,54 @@ async function detectImportFormat(fromPath) {
 }
 
 // src/cli.ts
+function rankCandidateForKeep(a, b) {
+  const aConfidence = typeof a.frontmatter.confidence === "number" ? a.frontmatter.confidence : 0;
+  const bConfidence = typeof b.frontmatter.confidence === "number" ? b.frontmatter.confidence : 0;
+  if (aConfidence !== bConfidence) return bConfidence - aConfidence;
+  const aTs = Date.parse(a.frontmatter.updated ?? a.frontmatter.created ?? "");
+  const bTs = Date.parse(b.frontmatter.updated ?? b.frontmatter.created ?? "");
+  const aTime = Number.isNaN(aTs) ? 0 : aTs;
+  const bTime = Number.isNaN(bTs) ? 0 : bTs;
+  if (aTime !== bTime) return bTime - aTime;
+  return a.path.localeCompare(b.path);
+}
+function buildDedupePlan(memories, keyBuilder) {
+  const byKey = /* @__PURE__ */ new Map();
+  for (const memory of memories) {
+    const key = keyBuilder(memory);
+    if (key.length === 0) continue;
+    const existing = byKey.get(key);
+    if (existing) {
+      existing.push(memory);
+    } else {
+      byKey.set(key, [memory]);
+    }
+  }
+  const keepPaths = [];
+  const deletePaths = [];
+  let groups = 0;
+  let duplicates = 0;
+  for (const entries of byKey.values()) {
+    if (entries.length <= 1) continue;
+    groups += 1;
+    duplicates += entries.length - 1;
+    const ranked = [...entries].sort(rankCandidateForKeep);
+    keepPaths.push(ranked[0].path);
+    for (let i = 1; i < ranked.length; i += 1) {
+      deletePaths.push(ranked[i].path);
+    }
+  }
+  return { groups, duplicates, keepPaths, deletePaths };
+}
+function normalizeAggressiveBody(content) {
+  return content.normalize("NFKC").replace(/\[([^\]]+)\]\([^)]+\)/g, "$1").replace(/[`*_~>#-]+/g, " ").replace(/[^\p{L}\p{N}\s]/gu, " ").replace(/\s+/g, " ").trim().toLowerCase();
+}
+function planExactDuplicateDeletions(memories) {
+  return buildDedupePlan(memories, (memory) => memory.content.trim());
+}
+function planAggressiveDuplicateDeletions(memories) {
+  return buildDedupePlan(memories, (memory) => normalizeAggressiveBody(memory.content));
+}
 async function getPluginVersion() {
   try {
     const pkgPath = new URL("../package.json", import.meta.url);
@@ -14797,6 +15022,55 @@ async function resolveMemoryDirForNamespace(orchestrator, namespace) {
   }
   return candidate;
 }
+async function readAllMemoryFiles(memoryDir) {
+  const roots = [path33.join(memoryDir, "facts"), path33.join(memoryDir, "corrections")];
+  const out = [];
+  const walk = async (dir) => {
+    let entries;
+    try {
+      entries = await readdir12(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const entryName = typeof entry.name === "string" ? entry.name : entry.name.toString("utf-8");
+      const fullPath = path33.join(dir, entryName);
+      if (entry.isDirectory()) {
+        await walk(fullPath);
+        continue;
+      }
+      if (!entry.isFile() || !entryName.endsWith(".md")) continue;
+      try {
+        const raw = await readFile22(fullPath, "utf-8");
+        const parsed = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+        if (!parsed) continue;
+        const fmRaw = parsed[1];
+        const body = parsed[2] ?? "";
+        const get = (key) => {
+          const match = fmRaw.match(new RegExp(`^${key}:\\s*(.+)$`, "m"));
+          return match ? match[1].trim() : "";
+        };
+        const confidenceRaw = get("confidence");
+        const confidence = confidenceRaw.length > 0 ? Number(confidenceRaw) : void 0;
+        out.push({
+          path: fullPath,
+          content: body,
+          frontmatter: {
+            id: get("id") || void 0,
+            confidence: Number.isFinite(confidence) ? confidence : void 0,
+            updated: get("updated") || void 0,
+            created: get("created") || void 0
+          }
+        });
+      } catch {
+      }
+    }
+  };
+  for (const root of roots) {
+    await walk(root);
+  }
+  return out;
+}
 function registerCli(api, orchestrator) {
   api.registerCli(
     ({ program }) => {
@@ -14935,6 +15209,100 @@ function registerCli(api, orchestrator) {
         });
         console.log("OK");
       });
+      cmd.command("dedupe-exact").description("Delete exact duplicate memory entries (same body text), keeping highest-confidence/newest copy").option("--dry-run", "Show what would be deleted without deleting files").option("--namespace <ns>", "Namespace to dedupe (v3.0+, default: config defaultNamespace)", "").option("--qmd-sync", "Run QMD update/embed after deletions (default: off)").action(async (...args) => {
+        const options = args[0] ?? {};
+        const dryRun = options.dryRun === true;
+        const namespace = options.namespace ? String(options.namespace) : "";
+        const qmdSync = options.qmdSync === true;
+        const memoryDir = await resolveMemoryDirForNamespace(orchestrator, namespace);
+        const memories = await readAllMemoryFiles(memoryDir);
+        const plan = planExactDuplicateDeletions(memories);
+        console.log(`Scanned ${memories.length} memory files in ${memoryDir}`);
+        console.log(`Duplicate groups: ${plan.groups}`);
+        console.log(`Duplicate files to delete: ${plan.deletePaths.length}`);
+        if (plan.deletePaths.length === 0) {
+          console.log("No exact duplicates found.");
+          return;
+        }
+        if (dryRun) {
+          console.log("Dry run enabled. No files deleted.");
+          for (const filePath of plan.deletePaths.slice(0, 50)) {
+            console.log(`  - ${filePath}`);
+          }
+          if (plan.deletePaths.length > 50) {
+            console.log(`  ... and ${plan.deletePaths.length - 50} more`);
+          }
+          return;
+        }
+        let deleted = 0;
+        for (const filePath of plan.deletePaths) {
+          try {
+            await unlink3(filePath);
+            deleted += 1;
+          } catch (err) {
+            console.log(`  failed to delete ${filePath}: ${String(err)}`);
+          }
+        }
+        console.log(`Deleted ${deleted}/${plan.deletePaths.length} duplicate files.`);
+        if (qmdSync) {
+          await orchestrator.qmd.probe();
+          if (orchestrator.qmd.isAvailable()) {
+            await orchestrator.qmd.update();
+            await orchestrator.qmd.embed();
+            console.log("QMD sync complete.");
+          } else {
+            console.log(`QMD unavailable in this process; skipped sync. Status: ${orchestrator.qmd.debugStatus()}`);
+          }
+        }
+      });
+      cmd.command("dedupe-aggressive").description(
+        "Delete aggressively-normalized duplicate memory entries (formatting/case/punctuation-insensitive)"
+      ).option("--dry-run", "Show what would be deleted without deleting files").option("--namespace <ns>", "Namespace to dedupe (v3.0+, default: config defaultNamespace)", "").option("--qmd-sync", "Run QMD update/embed after deletions (default: off)").action(async (...args) => {
+        const options = args[0] ?? {};
+        const dryRun = options.dryRun === true;
+        const namespace = options.namespace ? String(options.namespace) : "";
+        const qmdSync = options.qmdSync === true;
+        const memoryDir = await resolveMemoryDirForNamespace(orchestrator, namespace);
+        const memories = await readAllMemoryFiles(memoryDir);
+        const plan = planAggressiveDuplicateDeletions(memories);
+        console.log(`Scanned ${memories.length} memory files in ${memoryDir}`);
+        console.log(`Duplicate groups: ${plan.groups}`);
+        console.log(`Duplicate files to delete: ${plan.deletePaths.length}`);
+        if (plan.deletePaths.length === 0) {
+          console.log("No aggressive duplicates found.");
+          return;
+        }
+        if (dryRun) {
+          console.log("Dry run enabled. No files deleted.");
+          for (const filePath of plan.deletePaths.slice(0, 50)) {
+            console.log(`  - ${filePath}`);
+          }
+          if (plan.deletePaths.length > 50) {
+            console.log(`  ... and ${plan.deletePaths.length - 50} more`);
+          }
+          return;
+        }
+        let deleted = 0;
+        for (const filePath of plan.deletePaths) {
+          try {
+            await unlink3(filePath);
+            deleted += 1;
+          } catch (err) {
+            console.log(`  failed to delete ${filePath}: ${String(err)}`);
+          }
+        }
+        console.log(`Deleted ${deleted}/${plan.deletePaths.length} duplicate files.`);
+        if (qmdSync) {
+          await orchestrator.qmd.probe();
+          if (orchestrator.qmd.isAvailable()) {
+            await orchestrator.qmd.update();
+            await orchestrator.qmd.embed();
+            console.log("QMD sync complete.");
+          } else {
+            console.log(`QMD unavailable in this process; skipped sync. Status: ${orchestrator.qmd.debugStatus()}`);
+          }
+        }
+      });
       cmd.command("search").argument("<query>", "Search query").option("-n, --max-results <number>", "Max results", "8").description("Search memories via QMD").action(async (...args) => {
         const query = typeof args[0] === "string" ? args[0] : String(args[0] ?? "");
         const options = args[1] ?? {};
@@ -15452,7 +15820,7 @@ var index_default = {
       `initialized (debug=${cfg.debug}, qmdEnabled=${cfg.qmdEnabled}, transcriptEnabled=${cfg.transcriptEnabled}, hourlySummariesEnabled=${cfg.hourlySummariesEnabled}, localLlmEnabled=${cfg.localLlmEnabled})`
     );
     if (globalThis[ENGRAM_REGISTERED_GUARD] === true) {
-      log.warn("register called more than once; skipping duplicate hook/tool registration");
+      log.debug("register called more than once; skipping duplicate hook/tool registration");
       return;
     }
     globalThis[ENGRAM_REGISTERED_GUARD] = true;
@@ -15620,6 +15988,7 @@ Use this context naturally when relevant. Never quote or expose this memory cont
         const newJob = {
           id: jobId,
           agentId: "generalist",
+          model,
           name: "Engram Hourly Summary",
           enabled: true,
           createdAtMs: Date.now(),