@joshuaswarren/openclaw-engram 8.3.12 → 8.3.14

package/dist/index.js

@@ -120,6 +120,9 @@ function parseConfig(raw) {
     qmdEnabled: cfg.qmdEnabled !== false,
     qmdCollection: typeof cfg.qmdCollection === "string" ? cfg.qmdCollection : "openclaw-engram",
     qmdMaxResults: typeof cfg.qmdMaxResults === "number" ? cfg.qmdMaxResults : 8,
+    qmdColdTierEnabled: cfg.qmdColdTierEnabled === true,
+    qmdColdCollection: typeof cfg.qmdColdCollection === "string" && cfg.qmdColdCollection.length > 0 ? cfg.qmdColdCollection : "openclaw-engram-cold",
+    qmdColdMaxResults: typeof cfg.qmdColdMaxResults === "number" ? cfg.qmdColdMaxResults : 8,
     embeddingFallbackEnabled: cfg.embeddingFallbackEnabled !== false,
     embeddingFallbackProvider: cfg.embeddingFallbackProvider === "openai" ? "openai" : cfg.embeddingFallbackProvider === "local" ? "local" : "auto",
     qmdPath: typeof cfg.qmdPath === "string" && cfg.qmdPath.length > 0 ? cfg.qmdPath : void 0,
@@ -257,6 +260,7 @@ function parseConfig(raw) {
     qmdAutoEmbedEnabled: cfg.qmdAutoEmbedEnabled === true,
     qmdEmbedMinIntervalMs: typeof cfg.qmdEmbedMinIntervalMs === "number" ? cfg.qmdEmbedMinIntervalMs : 60 * 6e4,
     qmdUpdateTimeoutMs: typeof cfg.qmdUpdateTimeoutMs === "number" ? cfg.qmdUpdateTimeoutMs : 9e4,
+    qmdUpdateMinIntervalMs: typeof cfg.qmdUpdateMinIntervalMs === "number" ? cfg.qmdUpdateMinIntervalMs : 15 * 6e4,
     // Local LLM resilience
     localLlmRetry5xxCount: typeof cfg.localLlmRetry5xxCount === "number" ? cfg.localLlmRetry5xxCount : 1,
     localLlmRetryBackoffMs: typeof cfg.localLlmRetryBackoffMs === "number" ? cfg.localLlmRetryBackoffMs : 400,
@@ -277,6 +281,12 @@ function parseConfig(raw) {
       includeInRecallByDefault: p?.includeInRecallByDefault === true
     })).filter((p) => p.name.length > 0) : [],
     defaultRecallNamespaces: Array.isArray(cfg.defaultRecallNamespaces) ? ["self", "shared"].filter((x) => cfg.defaultRecallNamespaces.includes(x)) : ["self", "shared"],
+    cronRecallMode: cfg.cronRecallMode === "none" ? "none" : cfg.cronRecallMode === "allowlist" ? "allowlist" : "all",
+    cronRecallAllowlist: Array.isArray(cfg.cronRecallAllowlist) ? cfg.cronRecallAllowlist.filter((v) => typeof v === "string" && v.length > 0) : [],
+    cronRecallPolicyEnabled: cfg.cronRecallPolicyEnabled !== false,
+    cronRecallNormalizedQueryMaxChars: typeof cfg.cronRecallNormalizedQueryMaxChars === "number" ? cfg.cronRecallNormalizedQueryMaxChars : 480,
+    cronRecallInstructionHeavyTokenCap: typeof cfg.cronRecallInstructionHeavyTokenCap === "number" ? cfg.cronRecallInstructionHeavyTokenCap : 36,
+    cronConversationRecallMode: cfg.cronConversationRecallMode === "always" ? "always" : cfg.cronConversationRecallMode === "never" ? "never" : "auto",
     autoPromoteToSharedEnabled: cfg.autoPromoteToSharedEnabled === true,
     autoPromoteToSharedCategories: Array.isArray(cfg.autoPromoteToSharedCategories) ? cfg.autoPromoteToSharedCategories.filter((c) => c === "correction" || c === "decision" || c === "preference") : ["correction", "decision", "preference"],
     autoPromoteMinConfidenceTier: cfg.autoPromoteMinConfidenceTier === "explicit" ? "explicit" : cfg.autoPromoteMinConfidenceTier === "implied" ? "implied" : "explicit",
@@ -3490,6 +3500,7 @@ import os2 from "os";
 import path2 from "path";
 var QMD_TIMEOUT_MS = 3e4;
 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_FALLBACK_PATHS = [
@@ -3702,6 +3713,7 @@ var QmdClient = class {
     this.maxResults = maxResults;
     this.slowLog = opts?.slowLog;
     this.updateTimeoutMs = opts?.updateTimeoutMs ?? 12e4;
+    this.updateMinIntervalMs = Math.max(0, opts?.updateMinIntervalMs ?? 15 * 6e4);
     this.configuredQmdPath = opts?.qmdPath?.trim() ? opts.qmdPath.trim() : void 0;
     this.daemonRecheckIntervalMs = opts?.daemonRecheckIntervalMs ?? 6e4;
     if (opts?.daemonUrl) {
@@ -3711,7 +3723,10 @@ var QmdClient = class {
   available = null;
   lastUpdateFailAtMs = null;
   lastEmbedFailAtMs = null;
+  lastUpdateRunAtMs = null;
+  warnedGlobalUpdateBehavior = false;
   updateTimeoutMs;
+  updateMinIntervalMs;
   slowLog;
   configuredQmdPath;
   qmdPathSource = "auto-path";
@@ -3770,7 +3785,7 @@ ${stderr}`.trim();
     };
     if (this.configuredQmdPath) {
       try {
-        const result = await runQmd(["--version"], 3e3, this.configuredQmdPath);
+        const result = await runQmd(["--version"], QMD_PROBE_TIMEOUT_MS, this.configuredQmdPath);
         this.available = true;
         this.qmdPath = this.configuredQmdPath;
         this.qmdPathSource = "configured";
@@ -3785,7 +3800,7 @@ ${stderr}`.trim();
       }
     }
     try {
-      const result = await runQmd(["--version"], 3e3, "qmd");
+      const result = await runQmd(["--version"], QMD_PROBE_TIMEOUT_MS, "qmd");
       this.available = true;
       this.qmdPath = "qmd";
       this.qmdPathSource = "auto-path";
@@ -3796,7 +3811,7 @@ ${stderr}`.trim();
       markProbeFailure(err);
       for (const fallbackPath of QMD_FALLBACK_PATHS) {
         try {
-          const result = await runQmd(["--version"], 3e3, fallbackPath);
+          const result = await runQmd(["--version"], QMD_PROBE_TIMEOUT_MS, fallbackPath);
           this.available = true;
           this.qmdPath = fallbackPath;
           this.qmdPathSource = "auto-fallback";
@@ -3842,7 +3857,10 @@ ${stderr}`.trim();
     await this.maybeProbeDaemon();
     if (this.daemonAvailable) {
       const results = await this.searchViaDaemon(trimmed, col, n);
-      if (results !== null) return results;
+      if (results !== null) {
+        if (results.length > 0) return results;
+        log.debug("QMD daemon search returned 0 results; falling back to subprocess query");
+      }
     }
     return this.searchViaSubprocess(trimmed, col, n);
   }
@@ -3854,7 +3872,10 @@ ${stderr}`.trim();
     await this.maybeProbeDaemon();
     if (this.daemonAvailable) {
       const results = await this.searchViaDaemon(trimmed, void 0, n);
-      if (results !== null) return results;
+      if (results !== null) {
+        if (results.length > 0) return results;
+        log.debug("QMD daemon global search returned 0 results; falling back to subprocess query");
+      }
     }
     return this.searchGlobalViaSubprocess(trimmed, n);
   }
@@ -4076,17 +4097,28 @@ ${stderr}`.trim();
   }
   async update() {
     if (this.available === false) return;
+    if (this.lastUpdateRunAtMs && Date.now() - this.lastUpdateRunAtMs < this.updateMinIntervalMs) {
+      log.debug("QMD update: suppressed due to min-interval gate");
+      return;
+    }
     if (this.lastUpdateFailAtMs && Date.now() - this.lastUpdateFailAtMs < QMD_UPDATE_BACKOFF_MS) {
       log.debug("QMD update: suppressed due to recent failures (backoff)");
       return;
     }
     try {
+      if (!this.warnedGlobalUpdateBehavior) {
+        this.warnedGlobalUpdateBehavior = true;
+        log.warn(
+          "QMD update runs globally across collections in current CLI versions; Engram now rate-limits update calls to reduce gateway load."
+        );
+      }
       const startedAtMs = Date.now();
       await runQmd(["update", "-c", this.collection], this.updateTimeoutMs, this.qmdPath);
       const durationMs = Date.now() - startedAtMs;
       if (this.slowLog?.enabled && durationMs >= this.slowLog.thresholdMs) {
         log.warn(`SLOW QMD update: durationMs=${durationMs}`);
       }
+      this.lastUpdateRunAtMs = Date.now();
       log.debug("QMD update completed");
     } catch (err) {
       this.lastUpdateFailAtMs = Date.now();
@@ -5030,6 +5062,41 @@ ${sanitized.text}
     await readDir(this.correctionsDir);
     return memories;
   }
+  /**
+   * Read archived memory markdown files under archive/.
+   * Used by long-term recall fallback when hot recall has no hits.
+   */
+  async readArchivedMemories() {
+    const memories = [];
+    const root = this.archiveDir;
+    const readDir = async (dir) => {
+      try {
+        const entries = await readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+          const fullPath = path4.join(dir, entry.name);
+          if (entry.isDirectory()) {
+            await readDir(fullPath);
+          } else if (entry.name.endsWith(".md")) {
+            try {
+              const raw = await readFile2(fullPath, "utf-8");
+              const parsed = parseFrontmatter(raw);
+              if (parsed) {
+                memories.push({
+                  path: fullPath,
+                  frontmatter: parsed.frontmatter,
+                  content: parsed.content
+                });
+              }
+            } catch {
+            }
+          }
+        }
+      } catch {
+      }
+    };
+    await readDir(root);
+    return memories;
+  }
   /** Read a single memory file by its absolute path. Returns null if unreadable. */
   async readMemoryByPath(filePath) {
     try {
@@ -8275,6 +8342,160 @@ function planRecallMode(prompt) {
   return "full";
 }
 
+// src/recall-query-policy.ts
+var DEFAULT_STOPWORDS = /* @__PURE__ */ new Set([
+  "the",
+  "and",
+  "for",
+  "with",
+  "from",
+  "that",
+  "this",
+  "your",
+  "you",
+  "are",
+  "was",
+  "were",
+  "have",
+  "has",
+  "had",
+  "not",
+  "but",
+  "its",
+  "into",
+  "only",
+  "use",
+  "run",
+  "then",
+  "when",
+  "what",
+  "where",
+  "which",
+  "will",
+  "would",
+  "should",
+  "could",
+  "goal",
+  "output",
+  "format",
+  "rules",
+  "section",
+  "sections",
+  "skip",
+  "today",
+  "yesterday",
+  "return",
+  "summary",
+  "plain",
+  "text",
+  "before",
+  "after",
+  "time",
+  "date",
+  "daily",
+  "cron",
+  "agent",
+  "mode",
+  "data",
+  "gathering",
+  "context"
+]);
+function collapseWhitespace(text) {
+  return text.replace(/\s+/g, " ").trim();
+}
+function stripFilesystemLikePaths(text) {
+  return text.replace(/(?:^|\s)(~\/[^\s)]+)(?=\s|$)/g, " ").replace(/(?:^|\s)(\/[A-Za-z0-9._\-\/]+)(?=\s|$)/g, " ").replace(/(?:^|\s)([A-Za-z]:\\[^\s)]+)(?=\s|$)/g, " ");
+}
+function isBulletOrNumberedLine(line) {
+  if (line.startsWith("-") || line.startsWith("*")) {
+    return true;
+  }
+  let i = 0;
+  while (i < line.length) {
+    const code = line.charCodeAt(i);
+    if (code < 48 || code > 57) {
+      break;
+    }
+    i += 1;
+  }
+  return i > 0 && i < line.length && line.charAt(i) === ".";
+}
+function scoreInstructionHeavyShape(prompt) {
+  const lines = prompt.split(/\r?\n/).map((line) => line.trim()).filter((line) => line.length > 0);
+  const lineCount = lines.length;
+  if (lineCount === 0) return 0;
+  const headingLineCount = lines.filter(
+    (line) => /^(goal|output format|tone rules|grounding rules|data gathering|date computation|crm context|follow-up|social|current time|return)\b/i.test(
+      line
+    ) || /^[A-Z][A-Z\s/-]{4,}:$/.test(line)
+  ).length;
+  const bulletLineCount = lines.filter((line) => isBulletOrNumberedLine(line)).length;
+  const longLineCount = lines.filter((line) => line.length >= 180).length;
+  const hasPathDensity = (prompt.match(/(?:~\/|\/Users\/|[A-Za-z]:\\)/g)?.length ?? 0) >= 2;
+  const hasImperativeDensity = (prompt.match(/\b(run|extract|read|parse|determine|include|omit|skip)\b/gi)?.length ?? 0) >= 8;
+  let score = 0;
+  if (lineCount >= 24) score += 2;
+  if (headingLineCount >= 4) score += 2;
+  if (bulletLineCount >= 8) score += 1;
+  if (longLineCount >= 3) score += 1;
+  if (hasPathDensity) score += 1;
+  if (hasImperativeDensity) score += 1;
+  return score;
+}
+function classifyRecallPromptShape(prompt) {
+  const score = scoreInstructionHeavyShape(prompt);
+  return score >= 5 ? "instruction_heavy" : "standard";
+}
+function tokenizeForCompactQuery(text) {
+  const raw = text.toLowerCase().replace(/[^a-z0-9\s:_-]+/g, " ").split(/\s+/).filter((token) => token.length >= 3);
+  const deduped = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const token of raw) {
+    if (DEFAULT_STOPWORDS.has(token)) continue;
+    if (seen.has(token)) continue;
+    seen.add(token);
+    deduped.push(token);
+  }
+  return deduped;
+}
+function buildInstructionHeavyQuery(prompt, tokenCap, maxChars) {
+  const cleaned = stripFilesystemLikePaths(prompt);
+  const tokens = tokenizeForCompactQuery(cleaned).slice(0, Math.max(8, tokenCap));
+  const joined = tokens.join(" ");
+  const compact = collapseWhitespace(joined);
+  if (compact.length <= maxChars) return compact;
+  return compact.slice(0, maxChars).trim();
+}
+function buildStandardQuery(prompt, maxChars) {
+  const trimmed = collapseWhitespace(prompt);
+  if (trimmed.length <= maxChars) return trimmed;
+  return trimmed.slice(0, maxChars).trim();
+}
+function buildRecallQueryPolicy(prompt, sessionKey, cfg) {
+  const normalizedPrompt = collapseWhitespace(prompt);
+  const isCron = (sessionKey ?? "").includes(":cron:");
+  if (!cfg.cronRecallPolicyEnabled || !isCron) {
+    return {
+      promptShape: "standard",
+      retrievalQuery: prompt,
+      skipConversationRecall: false,
+      retrievalBudgetMode: "full"
+    };
+  }
+  const promptShape = classifyRecallPromptShape(prompt);
+  const maxChars = Math.max(120, cfg.cronRecallNormalizedQueryMaxChars);
+  const tokenCap = Math.max(8, cfg.cronRecallInstructionHeavyTokenCap);
+  const retrievalQuery = promptShape === "instruction_heavy" ? buildInstructionHeavyQuery(prompt, tokenCap, maxChars) : buildStandardQuery(prompt, maxChars);
+  const skipConversationRecall = cfg.cronConversationRecallMode === "never" ? true : cfg.cronConversationRecallMode === "always" ? false : promptShape === "instruction_heavy";
+  const retrievalBudgetMode = promptShape === "instruction_heavy" ? "minimal" : "full";
+  return {
+    promptShape,
+    retrievalQuery: retrievalQuery.length > 0 ? retrievalQuery : normalizedPrompt.slice(0, maxChars),
+    skipConversationRecall,
+    retrievalBudgetMode
+  };
+}
+
 // src/boxes.ts
 import { mkdir as mkdir10, writeFile as writeFile10, readFile as readFile11, readdir as readdir6 } from "fs/promises";
 import path13 from "path";
@@ -10214,6 +10435,9 @@ function filterRecallCandidates(candidates, options) {
   const scopedByNamespace = options.namespacesEnabled ? candidates.filter((r) => options.recallNamespaces.includes(options.resolveNamespace(r.path))) : candidates;
   return scopedByNamespace.filter((r) => !isArtifactMemoryPath(r.path)).slice(0, Math.max(0, options.limit));
 }
+function tokenizeRecallQuery(prompt) {
+  return prompt.toLowerCase().split(/[^a-z0-9]+/i).map((t) => t.trim()).filter((t) => t.length >= 3);
+}
 function hasLifecycleMetadata(frontmatter) {
   return frontmatter.lifecycleState !== void 0 || frontmatter.verificationState !== void 0 || frontmatter.policyClass !== void 0 || frontmatter.lastValidatedAt !== void 0 || frontmatter.decayScore !== void 0 || frontmatter.heatScore !== void 0;
 }
@@ -10441,6 +10665,7 @@ var Orchestrator = class _Orchestrator {
         thresholdMs: config.slowLogThresholdMs
       },
       updateTimeoutMs: config.qmdUpdateTimeoutMs,
+      updateMinIntervalMs: config.qmdUpdateMinIntervalMs,
       qmdPath: config.qmdPath,
       daemonUrl: config.qmdDaemonEnabled ? config.qmdDaemonUrl : void 0,
       daemonRecheckIntervalMs: config.qmdDaemonRecheckIntervalMs
@@ -10454,6 +10679,7 @@ var Orchestrator = class _Orchestrator {
           thresholdMs: config.slowLogThresholdMs
         },
         updateTimeoutMs: config.qmdUpdateTimeoutMs,
+        updateMinIntervalMs: config.qmdUpdateMinIntervalMs,
         qmdPath: config.qmdPath,
         daemonUrl: config.qmdDaemonEnabled ? config.qmdDaemonUrl : void 0,
         daemonRecheckIntervalMs: config.qmdDaemonRecheckIntervalMs
@@ -10967,10 +11193,28 @@ var Orchestrator = class _Orchestrator {
     const maxFetchLimit = Math.min(800, Math.max(fetchLimit, qmdFetchLimit * 8));
     const MAX_ATTEMPTS = 4;
     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(
         prompt,
-        void 0,
+        options.collection,
         fetchLimit
       );
       const filteredResults = filterRecallCandidates(memoryResults, {
@@ -10986,17 +11230,27 @@ var Orchestrator = class _Orchestrator {
         bestFiltered = filteredResults;
       }
       if (memoryResults.length === 0) {
+        const queryFallback = await runQueryFallback();
+        if (queryFallback.length > 0) {
+          return queryFallback.slice(0, qmdFetchLimit);
+        }
         return filteredResults;
       }
       if (memoryResults.length < fetchLimit && filteredResults.length > 0) {
         return filteredResults;
       }
       if (fetchLimit >= maxFetchLimit) {
-        return filteredResults;
+        break;
       }
       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;
   }
   async expandResultsViaGraph(options) {
@@ -11080,6 +11334,14 @@ var Orchestrator = class _Orchestrator {
     const recallStart = Date.now();
     const timings = {};
     const sections = [];
+    const queryPolicy = buildRecallQueryPolicy(prompt, sessionKey, {
+      cronRecallPolicyEnabled: this.config.cronRecallPolicyEnabled,
+      cronRecallNormalizedQueryMaxChars: this.config.cronRecallNormalizedQueryMaxChars,
+      cronRecallInstructionHeavyTokenCap: this.config.cronRecallInstructionHeavyTokenCap,
+      cronConversationRecallMode: this.config.cronConversationRecallMode
+    });
+    const retrievalQuery = queryPolicy.retrievalQuery || prompt;
+    timings.queryPolicy = `${queryPolicy.promptShape}/${queryPolicy.retrievalBudgetMode}${queryPolicy.skipConversationRecall ? "/skip-conv" : ""}`;
     const recallMode = resolveEffectiveRecallMode({
       plannerEnabled: this.config.recallPlannerEnabled,
       graphRecallEnabled: this.config.graphRecallEnabled,
@@ -11087,7 +11349,12 @@ var Orchestrator = class _Orchestrator {
       prompt
     });
     timings.recallPlan = recallMode;
-    const recallResultLimit = recallMode === "no_recall" ? 0 : recallMode === "minimal" ? Math.max(0, Math.min(this.config.qmdMaxResults, this.config.recallPlannerMaxQmdResultsMinimal)) : this.config.qmdMaxResults;
+    const plannerRecallResultLimit = recallMode === "no_recall" ? 0 : recallMode === "minimal" ? Math.max(0, Math.min(this.config.qmdMaxResults, this.config.recallPlannerMaxQmdResultsMinimal)) : this.config.qmdMaxResults;
+    const policyMinimalLimit = Math.max(
+      0,
+      Math.min(this.config.qmdMaxResults, this.config.recallPlannerMaxQmdResultsMinimal)
+    );
+    const recallResultLimit = recallMode !== "no_recall" && queryPolicy.retrievalBudgetMode === "minimal" ? Math.min(plannerRecallResultLimit, policyMinimalLimit) : plannerRecallResultLimit;
     const recallHeadroom = this.config.verbatimArtifactsEnabled ? Math.max(12, this.config.verbatimArtifactsMaxRecall * 4) : 12;
     const computedFetchLimit = recallResultLimit === 0 ? 0 : Math.max(recallResultLimit, Math.min(200, recallResultLimit + recallHeadroom));
     const qmdFetchLimit = computedFetchLimit;
@@ -11154,7 +11421,11 @@ var Orchestrator = class _Orchestrator {
         timings.artifacts = "skip(limit=0)";
         return [];
       }
-      const results = await this.recallArtifactsAcrossNamespaces(prompt, recallNamespaces, targetCount);
+      const results = await this.recallArtifactsAcrossNamespaces(
+        retrievalQuery,
+        recallNamespaces,
+        targetCount
+      );
       timings.artifacts = `${Date.now() - t0}ms`;
       return results;
     })();
@@ -11170,7 +11441,7 @@ var Orchestrator = class _Orchestrator {
       }
       const t0 = Date.now();
       const filteredResults = await this.fetchQmdMemoryResultsWithArtifactTopUp(
-        prompt,
+        retrievalQuery,
         qmdFetchLimit,
         qmdHybridFetchLimit,
         {
@@ -11254,17 +11525,17 @@ ${tmtNode.summary}`);
         memoryResults = merged;
         await this.recordLastGraphRecallSnapshot({
           storage: profileStorage,
-          prompt,
+          prompt: retrievalQuery,
           recallMode,
           recallNamespaces,
           seedPaths,
           expandedPaths
         });
       }
-      memoryResults = await this.boostSearchResults(memoryResults, recallNamespaces, prompt);
+      memoryResults = await this.boostSearchResults(memoryResults, recallNamespaces, retrievalQuery);
       if (this.config.rerankEnabled && this.config.rerankProvider === "local") {
         const ranked = await rerankLocalOrNoop({
-          query: prompt,
+          query: retrievalQuery,
           candidates: memoryResults.slice(0, this.config.rerankMaxCandidates).map((r) => ({
             id: r.path,
             snippet: r.snippet || r.path
@@ -11296,33 +11567,48 @@ ${tmtNode.summary}`);
       }
       memoryResults = memoryResults.slice(0, recallResultLimit);
       if (memoryResults.length > 0) {
-        const memoryIds = this.extractMemoryIdsFromResults(memoryResults);
-        this.trackMemoryAccess(memoryIds);
-        if (sessionKey) {
-          const unique = Array.from(new Set(memoryIds)).slice(0, 40);
-          this.lastRecall.record({ sessionKey, query: prompt, memoryIds: unique }).catch((err) => log.debug(`last recall record failed: ${err}`));
-        }
-        sections.push(this.formatQmdResults("Relevant Memories", memoryResults));
+        this.publishRecallResults({
+          title: "Relevant Memories",
+          results: memoryResults,
+          sections,
+          retrievalQuery,
+          sessionKey
+        });
       } else {
-        const embeddingResults = await this.searchEmbeddingFallback(prompt, embeddingFetchLimit);
+        const embeddingResults = await this.searchEmbeddingFallback(retrievalQuery, embeddingFetchLimit);
         const scopedCandidates = filterRecallCandidates(embeddingResults, {
           namespacesEnabled: this.config.namespacesEnabled,
           recallNamespaces,
           resolveNamespace: (p) => this.namespaceFromPath(p),
           limit: embeddingFetchLimit
         });
-        const scoped = (await this.boostSearchResults(scopedCandidates, recallNamespaces, prompt)).slice(
+        const scoped = (await this.boostSearchResults(scopedCandidates, recallNamespaces, retrievalQuery)).slice(
           0,
           recallResultLimit
         );
         if (scoped.length > 0) {
-          const memoryIds = this.extractMemoryIdsFromResults(scoped);
-          this.trackMemoryAccess(memoryIds);
-          if (sessionKey) {
-            const unique = Array.from(new Set(memoryIds)).slice(0, 40);
-            this.lastRecall.record({ sessionKey, query: prompt, memoryIds: unique }).catch((err) => log.debug(`last recall record failed: ${err}`));
+          this.publishRecallResults({
+            title: "Relevant Memories",
+            results: scoped,
+            sections,
+            retrievalQuery,
+            sessionKey
+          });
+        } else {
+          const longTerm = await this.applyColdFallbackPipeline({
+            prompt: retrievalQuery,
+            recallNamespaces,
+            recallResultLimit
+          });
+          if (longTerm.length > 0) {
+            this.publishRecallResults({
+              title: "Long-Term Memories (Fallback)",
+              results: longTerm,
+              sections,
+              retrievalQuery,
+              sessionKey
+            });
           }
-          sections.push(this.formatQmdResults("Relevant Memories", scoped));
         }
       }
       if (globalResults.length > 0) {
@@ -11345,25 +11631,26 @@ ${tmtNode.summary}`);
         );
       }
     } else if (recallResultLimit > 0 && (!this.config.qmdEnabled || !this.qmd.isAvailable())) {
-      const embeddingResults = await this.searchEmbeddingFallback(prompt, embeddingFetchLimit);
+      const embeddingResults = await this.searchEmbeddingFallback(retrievalQuery, embeddingFetchLimit);
       const scopedCandidates = filterRecallCandidates(embeddingResults, {
         namespacesEnabled: this.config.namespacesEnabled,
         recallNamespaces,
         resolveNamespace: (p) => this.namespaceFromPath(p),
         limit: embeddingFetchLimit
       });
-      const scoped = (await this.boostSearchResults(scopedCandidates, recallNamespaces, prompt)).slice(
-        0,
-        recallResultLimit
-      );
+      const scoped = (await this.boostSearchResults(
+        scopedCandidates,
+        recallNamespaces,
+        retrievalQuery
+      )).slice(0, recallResultLimit);
       if (scoped.length > 0) {
-        const memoryIds = this.extractMemoryIdsFromResults(scoped);
-        this.trackMemoryAccess(memoryIds);
-        if (sessionKey) {
-          const unique = Array.from(new Set(memoryIds)).slice(0, 40);
-          this.lastRecall.record({ sessionKey, query: prompt, memoryIds: unique }).catch((err) => log.debug(`last recall record failed: ${err}`));
-        }
-        sections.push(this.formatQmdResults("Relevant Memories", scoped));
+        this.publishRecallResults({
+          title: "Relevant Memories",
+          results: scoped,
+          sections,
+          retrievalQuery,
+          sessionKey
+        });
       } else {
         const memories = await this.readAllMemoriesForNamespaces(recallNamespaces);
         if (memories.length > 0) {
@@ -11382,14 +11669,51 @@ ${tmtNode.summary}`);
             snippet: m.content,
             score: 1 - i / Math.max(recentSorted.length, 1)
           }));
-          const recent = (await this.boostSearchResults(recentAsResults, recallNamespaces, prompt, preloadedMap)).sort((a, b) => b.score - a.score).slice(0, recallResultLimit);
-          const memoryIds = recent.map((r) => r.docid).filter(Boolean);
-          this.trackMemoryAccess(memoryIds);
-          if (sessionKey) {
-            const unique = Array.from(new Set(memoryIds)).slice(0, 40);
-            this.lastRecall.record({ sessionKey, query: prompt, memoryIds: unique }).catch((err) => log.debug(`last recall record failed: ${err}`));
+          const recent = (await this.boostSearchResults(
+            recentAsResults,
+            recallNamespaces,
+            retrievalQuery,
+            preloadedMap
+          )).sort((a, b) => b.score - a.score).slice(0, recallResultLimit);
+          if (recent.length > 0) {
+            this.publishRecallResults({
+              title: "Recent Memories",
+              results: recent,
+              sections,
+              retrievalQuery,
+              sessionKey
+            });
+          } else {
+            const longTerm = await this.applyColdFallbackPipeline({
+              prompt: retrievalQuery,
+              recallNamespaces,
+              recallResultLimit
+            });
+            if (longTerm.length > 0) {
+              this.publishRecallResults({
+                title: "Long-Term Memories (Fallback)",
+                results: longTerm,
+                sections,
+                retrievalQuery,
+                sessionKey
+              });
+            }
+          }
+        } else {
+          const longTerm = await this.applyColdFallbackPipeline({
+            prompt: retrievalQuery,
+            recallNamespaces,
+            recallResultLimit
+          });
+          if (longTerm.length > 0) {
+            this.publishRecallResults({
+              title: "Long-Term Memories (Fallback)",
+              results: longTerm,
+              sections,
+              retrievalQuery,
+              sessionKey
+            });
           }
-          sections.push(this.formatQmdResults("Recent Memories", recent));
         }
       }
       if (isDisagreementPrompt(prompt)) {
@@ -11465,13 +11789,13 @@ ${formatted}`);
     }
     timings.summaries = `${Date.now() - summariesT0}ms`;
     const convT0 = Date.now();
-    if (this.config.conversationIndexEnabled && this.conversationQmd && this.conversationQmd.isAvailable()) {
+    if (this.config.conversationIndexEnabled && !queryPolicy.skipConversationRecall && this.conversationQmd && this.conversationQmd.isAvailable()) {
       const startedAtMs = Date.now();
       const timeoutMs = Math.max(200, this.config.conversationRecallTimeoutMs);
       const topK = Math.max(1, this.config.conversationRecallTopK);
       const maxChars = Math.max(400, this.config.conversationRecallMaxChars);
       const results = await Promise.race([
-        this.conversationQmd.search(prompt, void 0, topK),
+        this.conversationQmd.search(retrievalQuery, void 0, topK),
         new Promise((resolve) => setTimeout(() => resolve([]), timeoutMs))
       ]).catch(() => []);
       const durationMs = Date.now() - startedAtMs;
@@ -12614,6 +12938,15 @@ ${snippet}`;
 
 ${lines.join("\n\n")}`;
   }
+  publishRecallResults(options) {
+    const memoryIds = this.extractMemoryIdsFromResults(options.results);
+    this.trackMemoryAccess(memoryIds);
+    if (options.sessionKey) {
+      const unique = Array.from(new Set(memoryIds)).slice(0, 40);
+      this.lastRecall.record({ sessionKey: options.sessionKey, query: options.retrievalQuery, memoryIds: unique }).catch((err) => log.debug(`last recall record failed: ${err}`));
+    }
+    options.sections.push(this.formatQmdResults(options.title, options.results));
+  }
   async searchEmbeddingFallback(query, limit) {
     if (!this.config.embeddingFallbackEnabled) return [];
     if (!await this.embeddingFallback.isAvailable()) return [];
@@ -12633,6 +12966,123 @@ ${lines.join("\n\n")}`;
     }
     return results;
   }
+  /**
+   * Long-term fallback retrieval.
+   * Searches archived memories only, and is invoked only when hot recall returns zero hits.
+   */
+  async searchLongTermArchiveFallback(prompt, recallNamespaces, limit) {
+    const cappedLimit = Math.max(0, limit);
+    if (cappedLimit === 0) return [];
+    const tokens = Array.from(new Set(tokenizeRecallQuery(prompt)));
+    if (tokens.length === 0) return [];
+    const archivedMemories = await this.readArchivedMemoriesForNamespaces(recallNamespaces);
+    if (archivedMemories.length === 0) return [];
+    const scored = [];
+    for (const memory of archivedMemories) {
+      const haystack = [
+        memory.content,
+        memory.frontmatter.category,
+        ...memory.frontmatter.tags ?? []
+      ].join(" ").toLowerCase();
+      let hits = 0;
+      for (const token of tokens) {
+        if (haystack.includes(token)) hits += 1;
+      }
+      if (hits === 0) continue;
+      const normalized = hits / tokens.length;
+      scored.push({
+        docid: memory.frontmatter.id,
+        path: memory.path,
+        score: normalized,
+        snippet: memory.content.slice(0, 400).replace(/\n/g, " ")
+      });
+    }
+    return scored.sort((a, b) => b.score - a.score).slice(0, cappedLimit);
+  }
+  async applyColdFallbackPipeline(options) {
+    const coldQmdEnabled = this.config.qmdColdTierEnabled === true;
+    const coldCollection = this.config.qmdColdCollection ?? "openclaw-engram-cold";
+    const coldMaxResults = this.config.qmdColdMaxResults ?? this.config.qmdMaxResults;
+    let longTerm = [];
+    if (coldQmdEnabled && this.config.qmdEnabled && this.qmd.isAvailable()) {
+      const coldFetchLimit = Math.max(
+        0,
+        Math.min(options.recallResultLimit, Math.max(0, coldMaxResults))
+      );
+      if (coldFetchLimit > 0) {
+        const coldHybridLimit = computeQmdHybridFetchLimit(
+          coldFetchLimit,
+          false,
+          0
+        );
+        longTerm = await this.fetchQmdMemoryResultsWithArtifactTopUp(
+          options.prompt,
+          coldFetchLimit,
+          coldHybridLimit,
+          {
+            namespacesEnabled: this.config.namespacesEnabled,
+            recallNamespaces: options.recallNamespaces,
+            resolveNamespace: (p) => this.namespaceFromPath(p),
+            collection: coldCollection
+          }
+        );
+        if (longTerm.length > 0) {
+          log.debug(`cold-tier recall source=cold-qmd collection=${coldCollection} hits=${longTerm.length}`);
+        }
+      }
+    }
+    if (longTerm.length === 0) {
+      longTerm = await this.searchLongTermArchiveFallback(
+        options.prompt,
+        options.recallNamespaces,
+        options.recallResultLimit
+      );
+      if (longTerm.length > 0) {
+        log.debug("cold-tier recall source=archive-scan");
+      }
+    }
+    if (longTerm.length === 0) return [];
+    let results = await this.boostSearchResults(
+      longTerm,
+      options.recallNamespaces,
+      options.prompt,
+      void 0,
+      { allowLifecycleFiltered: true }
+    );
+    if (this.config.rerankEnabled && this.config.rerankProvider === "local") {
+      const ranked = await rerankLocalOrNoop({
+        query: options.prompt,
+        candidates: results.slice(0, this.config.rerankMaxCandidates).map((r) => ({
+          id: r.path,
+          snippet: r.snippet || r.path
+        })),
+        local: this.localLlm,
+        enabled: true,
+        timeoutMs: this.config.rerankTimeoutMs,
+        maxCandidates: this.config.rerankMaxCandidates,
+        cache: this.rerankCache,
+        cacheEnabled: this.config.rerankCacheEnabled,
+        cacheTtlMs: this.config.rerankCacheTtlMs
+      });
+      if (ranked && ranked.length > 0) {
+        const byPath = new Map(results.map((r) => [r.path, r]));
+        const reordered = [];
+        for (const p of ranked) {
+          const it = byPath.get(p);
+          if (it) reordered.push(it);
+        }
+        const rankedSet = new Set(ranked);
+        for (const r of results) {
+          if (!rankedSet.has(r.path)) reordered.push(r);
+        }
+        results = reordered;
+      }
+    }
+    if (this.config.rerankEnabled && this.config.rerankProvider === "cloud") {
+      log.debug("rerankProvider=cloud is reserved/experimental in v2.2.0; skipping rerank");
+    }
+    return results.slice(0, options.recallResultLimit);
+  }
   // ---------------------------------------------------------------------------
   // Access Tracking (Phase 1A)
   // ---------------------------------------------------------------------------
@@ -12701,7 +13151,7 @@ ${lines.join("\n\n")}`;
    * Apply recency, access count, and importance boosting to QMD search results.
    * Returns re-ranked results.
    */
-  async boostSearchResults(results, _recallNamespaces, prompt, preloadedMemoryMap) {
+  async boostSearchResults(results, _recallNamespaces, prompt, preloadedMemoryMap, options) {
     if (results.length === 0) return results;
     const now = Date.now();
     const memoryByPath = preloadedMemoryMap ? new Map(preloadedMemoryMap) : /* @__PURE__ */ new Map();
@@ -12749,7 +13199,7 @@ ${lines.join("\n\n")}`;
       const memory = memoryByPath.get(r.path);
       let score = r.score;
       if (memory) {
-        if (shouldFilterLifecycleRecallCandidate(memory.frontmatter, {
+        if (options?.allowLifecycleFiltered !== true && shouldFilterLifecycleRecallCandidate(memory.frontmatter, {
           lifecyclePolicyEnabled: this.config.lifecyclePolicyEnabled,
           lifecycleFilterStaleEnabled: this.config.lifecycleFilterStaleEnabled
         })) {
@@ -12945,6 +13395,16 @@ ${lines.join("\n\n")}`;
     );
     return lists.flat();
   }
+  async readArchivedMemoriesForNamespaces(namespaces) {
+    const uniq = Array.from(new Set(namespaces.filter(Boolean)));
+    const lists = await Promise.all(
+      uniq.map(async (ns) => {
+        const sm = await this.storageRouter.storageFor(ns);
+        return sm.readArchivedMemories();
+      })
+    );
+    return lists.flat();
+  }
 };
 
 // src/tools.ts
@@ -14483,6 +14943,7 @@ function registerCli(api, orchestrator) {
           console.log("Missing query. Usage: openclaw engram search <query>");
           return;
         }
+        await orchestrator.qmd.probe();
         if (orchestrator.qmd.isAvailable()) {
           const results = await orchestrator.qmd.search(
             query,
@@ -14511,12 +14972,18 @@ function registerCli(api, orchestrator) {
           const matches = memories.filter(
             (m) => m.content.toLowerCase().includes(lowerQuery) || m.frontmatter.tags.some((t) => t.includes(lowerQuery))
           );
+          const qmdStatus = orchestrator.qmd.debugStatus();
           if (matches.length === 0) {
-            console.log(`No results for: "${query}" (QMD not available, using text search)`);
+            console.log(
+              `No results for: "${query}" (QMD unavailable in this CLI process; text search fallback).`
+            );
+            console.log(`QMD status: ${qmdStatus}`);
             return;
           }
           console.log(`
-=== Text Search: "${query}" (${matches.length} results) ===
+=== Text Search Fallback: "${query}" (${matches.length} results) ===
+`);
+          console.log(`QMD status: ${qmdStatus}
 `);
           for (const m of matches.slice(0, maxResults)) {
             console.log(`  [${m.frontmatter.category}] ${m.content.slice(0, 120)}`);
@@ -14932,6 +15399,7 @@ import { readFile as readFile23, writeFile as writeFile21 } from "fs/promises";
 import { readFileSync as readFileSync4 } from "fs";
 import path34 from "path";
 import os5 from "os";
+var ENGRAM_REGISTERED_GUARD = "__openclawEngramRegistered";
 function loadPluginConfigFromFile() {
   try {
     const explicitConfigPath = process.env.OPENCLAW_ENGRAM_CONFIG_PATH || process.env.OPENCLAW_CONFIG_PATH;
@@ -14946,6 +15414,24 @@ function loadPluginConfigFromFile() {
     return void 0;
   }
 }
+function wildcardToRegExp(pattern) {
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`^${escaped.replace(/\*/g, ".*")}$`);
+}
+function shouldSkipRecallForSession(sessionKey, cfg) {
+  const isCron = sessionKey.includes(":cron:");
+  if (!isCron) return false;
+  if (cfg.cronRecallMode === "none") return true;
+  if (cfg.cronRecallMode === "all") return false;
+  if (cfg.cronRecallAllowlist.length === 0) return true;
+  return !cfg.cronRecallAllowlist.some((pattern) => {
+    try {
+      return wildcardToRegExp(pattern).test(sessionKey);
+    } catch {
+      return false;
+    }
+  });
+}
 var index_default = {
   id: "openclaw-engram",
   name: "Engram (Local Memory)",
@@ -14965,6 +15451,11 @@ var index_default = {
     log.info(
       `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");
+      return;
+    }
+    globalThis[ENGRAM_REGISTERED_GUARD] = true;
     const existing = globalThis.__openclawEngramOrchestrator;
     const orchestrator = existing?.recall ? existing : new Orchestrator(cfg);
     globalThis.__openclawEngramOrchestrator = orchestrator;
@@ -14978,6 +15469,24 @@ var index_default = {
         if (!prompt || prompt.length < 5) return;
         const sessionKey = ctx?.sessionKey ?? "default";
         log.debug(`before_agent_start: sessionKey=${sessionKey}, promptLen=${prompt.length}`);
+        log.debug(
+          `before_agent_start: cronRecallMode=${cfg.cronRecallMode}, allowlistCount=${cfg.cronRecallAllowlist.length}`
+        );
+        if (sessionKey.includes(":cron:") && cfg.cronRecallMode === "allowlist") {
+          const matchedPattern = cfg.cronRecallAllowlist.find((pattern) => {
+            const re = wildcardToRegExp(pattern);
+            return re.test(sessionKey);
+          });
+          log.debug(
+            `before_agent_start: cron allowlist match=${matchedPattern ? "yes" : "no"} pattern=${matchedPattern ?? "none"}`
+          );
+        }
+        if (shouldSkipRecallForSession(sessionKey, cfg)) {
+          log.debug(
+            `before_agent_start: skip recall for cron session ${sessionKey} (mode=${cfg.cronRecallMode})`
+          );
+          return;
+        }
         try {
           await orchestrator.maybeRunFileHygiene().catch(() => void 0);
           const context = await orchestrator.recall(prompt, sessionKey);
@@ -15159,6 +15668,7 @@ Use this context naturally when relevant. Never quote or expose this memory cont
         log.info("engram memory system ready");
       },
       stop: () => {
+        globalThis[ENGRAM_REGISTERED_GUARD] = false;
         log.info("stopped");
       }
     });