@joshuaswarren/openclaw-engram 9.0.38 → 9.0.40

package/README.md

@@ -40,6 +40,8 @@ AI agents forget everything between conversations. Engram fixes that.
 - **Red-team benchmark packs** — Engram's eval harness can now validate and count typed `memory-red-team` benchmark packs so poisoning-defense regression suites stay explicit and reviewable instead of hiding inside generic benchmark metadata.
 - **Cue-anchor index foundation** — Engram can now, when `harmonicRetrievalEnabled` and `abstractionAnchorsEnabled` are enabled, persist typed cue anchors for entities, files, tools, outcomes, constraints, and dates, inspect them with `openclaw engram cue-anchor-status`, and keep harmonic retrieval grounded in explicit abstraction-to-cue links before blending logic lands.
 - **Harmonic retrieval diagnostics** — Engram can now, when `harmonicRetrievalEnabled` is enabled, blend abstraction-node evidence with cue-anchor matches into a dedicated `Harmonic Retrieval` recall section and inspect those blended results with `openclaw engram harmonic-search`.
+- **Verified episodic recall** — Engram can now, when `verifiedRecallEnabled` is enabled, inject a dedicated `Verified Episodes` recall section that reuses memory boxes but only surfaces boxes whose cited source memories still verify as non-archived episodes.
+- **Semantic rule promotion** — Engram can now, when `semanticRulePromotionEnabled` is enabled, promote explicit `IF ... THEN ...` rules from verified episodic memories into durable `rule` memories with lineage, source-memory provenance, duplicate suppression, and the operator-facing `openclaw engram semantic-rule-promote` CLI.
 - **Zero-config start** — Install, add an API key, restart. Engram works out of the box with sensible defaults and progressively unlocks advanced features as you enable them.
 
 ## Quick Start
@@ -167,6 +169,8 @@ openclaw engram objective-state-status       # Objective-state snapshot counts a
 openclaw engram causal-trajectory-status    # Causal-trajectory record counts and latest stored chain
 openclaw engram trust-zone-status           # Trust-zone record counts and latest stored record
 openclaw engram trust-zone-promote          # Dry-run or apply a trust-zone promotion with provenance/corroboration enforcement
+openclaw engram harmonic-search <query>     # Preview blended harmonic retrieval matches
+openclaw engram verified-recall-search <query> # Preview verified episodic recall matches
 openclaw engram conversation-index-health    # Conversation index status
 openclaw engram graph-health                 # Entity graph status
 openclaw engram tier-status                  # Hot/cold tier metrics
@@ -203,6 +207,10 @@ Key settings:
 | `trustZoneRecallEnabled` | `false` | Inject prompt-relevant working and trusted trust-zone records into recall context |
 | `memoryPoisoningDefenseEnabled` | `false` | Enable deterministic provenance trust scoring and corroboration requirements for risky trusted promotions |
 | `memoryRedTeamBenchEnabled` | `false` | Enable typed memory red-team benchmark pack support and status accounting for poisoning-defense suites |
+| `harmonicRetrievalEnabled` | `false` | Enable harmonic retrieval blending over abstraction nodes and cue anchors, including the dedicated recall section and `harmonic-search` diagnostics |
+| `abstractionAnchorsEnabled` | `false` | Enable typed cue-anchor indexing for abstraction nodes and expose the anchor store through status tooling |
+| `verifiedRecallEnabled` | `false` | Inject prompt-relevant memory boxes only when their cited source memories verify as non-archived episodes |
+| `semanticRulePromotionEnabled` | `false` | Enable deterministic promotion of explicit `IF ... THEN ...` rules from verified episodic memories via `openclaw engram semantic-rule-promote` |
 
 Full reference: [Config Reference](docs/config-reference.md)
 

package/dist/index.js

@@ -304,6 +304,8 @@ function parseConfig(raw) {
     memoryRedTeamBenchEnabled: cfg.memoryRedTeamBenchEnabled === true,
     harmonicRetrievalEnabled: cfg.harmonicRetrievalEnabled === true,
     abstractionAnchorsEnabled: cfg.abstractionAnchorsEnabled === true,
+    verifiedRecallEnabled: cfg.verifiedRecallEnabled === true,
+    semanticRulePromotionEnabled: cfg.semanticRulePromotionEnabled === true,
     abstractionNodeStoreDir: typeof cfg.abstractionNodeStoreDir === "string" && cfg.abstractionNodeStoreDir.trim().length > 0 ? cfg.abstractionNodeStoreDir.trim() : path.join(memoryDir, "state", "abstraction-nodes"),
     // Local LLM Provider (v2.1)
     localLlmEnabled: cfg.localLlmEnabled === true || cfg.localLlmEnabled === "true",
@@ -587,6 +589,12 @@ function buildDefaultRecallPipeline(cfg) {
       maxResults: 3,
       maxChars: 2200
     },
+    {
+      id: "verified-episodes",
+      enabled: cfg.verifiedRecallEnabled === true,
+      maxResults: 3,
+      maxChars: 1800
+    },
     {
       id: "memories",
       enabled: true,
@@ -15336,6 +15344,92 @@ async function searchHarmonicRetrieval(options) {
   ).slice(0, options.maxResults);
 }
 
+// src/verified-recall.ts
+function createReadOnlyBoxBuilder(memoryDir) {
+  return new BoxBuilder(memoryDir, {
+    memoryBoxesEnabled: true,
+    traceWeaverEnabled: false,
+    boxTopicShiftThreshold: 0.35,
+    boxTimeGapMs: 30 * 60 * 1e3,
+    boxMaxMemories: 50,
+    traceWeaverLookbackDays: 7,
+    traceWeaverOverlapThreshold: 0.4
+  });
+}
+function scoreVerifiedEpisodeCandidate(box, verifiedMemories, queryTokens) {
+  const matchedFields = /* @__PURE__ */ new Set();
+  let score = 0;
+  const topicMatches = countRecallTokenOverlap(queryTokens, box.topics.join(" "));
+  if (topicMatches > 0) {
+    score += topicMatches * 3;
+    matchedFields.add("topics");
+  }
+  const goalMatches = countRecallTokenOverlap(queryTokens, box.goal);
+  if (goalMatches > 0) {
+    score += goalMatches * 4;
+    matchedFields.add("goal");
+  }
+  const toolMatches = countRecallTokenOverlap(queryTokens, box.toolsUsed?.join(" "));
+  if (toolMatches > 0) {
+    score += toolMatches * 2;
+    matchedFields.add("toolsUsed");
+  }
+  let episodeContentMatches = 0;
+  for (const memory of verifiedMemories) {
+    episodeContentMatches += countRecallTokenOverlap(queryTokens, memory.content);
+  }
+  if (episodeContentMatches > 0) {
+    score += episodeContentMatches * 4;
+    matchedFields.add("episodeContent");
+  }
+  return { score, matchedFields };
+}
+function resolveVerifiedEpisodeMemoriesFromMap(memoryById, memoryIds) {
+  const verified = [];
+  for (const memoryId of memoryIds) {
+    try {
+      const memory = memoryById.get(memoryId);
+      if (!memory) continue;
+      if (memory.frontmatter.status === "archived") continue;
+      if (memory.frontmatter.memoryKind !== "episode") continue;
+      verified.push(memory);
+    } catch {
+    }
+  }
+  return verified;
+}
+async function searchVerifiedEpisodes(options) {
+  const queryTokens = new Set(normalizeRecallTokens(options.query, ["what", "which"]));
+  if (queryTokens.size === 0 || options.maxResults <= 0) return [];
+  const storage = new StorageManager(options.memoryDir);
+  const verifiedMemoryById = new Map(
+    (await storage.readAllMemories()).filter((memory) => memory.frontmatter.status !== "archived").filter((memory) => memory.frontmatter.memoryKind === "episode").map((memory) => [memory.frontmatter.id, memory])
+  );
+  const boxes = await createReadOnlyBoxBuilder(options.memoryDir).readRecentBoxes(Math.max(1, Math.floor(options.boxRecallDays ?? 3))).catch(() => []);
+  const candidates = [];
+  for (const box of boxes) {
+    const verifiedMemories = resolveVerifiedEpisodeMemoriesFromMap(verifiedMemoryById, box.memoryIds);
+    if (verifiedMemories.length === 0) continue;
+    const { score, matchedFields } = scoreVerifiedEpisodeCandidate(box, verifiedMemories, queryTokens);
+    if (score <= 0) continue;
+    candidates.push({
+      box,
+      score,
+      matchedFields,
+      verifiedMemories
+    });
+  }
+  return candidates.map((candidate) => ({
+    box: candidate.box,
+    score: candidate.score,
+    verifiedEpisodeCount: candidate.verifiedMemories.length,
+    verifiedMemoryIds: candidate.verifiedMemories.map((memory) => memory.frontmatter.id),
+    matchedFields: [...candidate.matchedFields].sort()
+  })).sort(
+    (left, right) => right.score - left.score || right.verifiedEpisodeCount - left.verifiedEpisodeCount || right.box.sealedAt.localeCompare(left.box.sealedAt)
+  ).slice(0, options.maxResults);
+}
+
 // src/replay/types.ts
 var VALID_SOURCES = /* @__PURE__ */ new Set(["openclaw", "claude", "chatgpt"]);
 var VALID_ROLES = /* @__PURE__ */ new Set(["user", "assistant"]);
@@ -19120,6 +19214,26 @@ ${r.snippet.trim()}
       timings.harmonicRetrieval = `${Date.now() - t0}ms`;
       return results.length > 0 ? this.formatHarmonicRetrievalResults(results) : null;
     })();
+    const verifiedRecallPromise = (async () => {
+      const t0 = Date.now();
+      if (!this.config.verifiedRecallEnabled || !this.isRecallSectionEnabled("verified-episodes", this.config.verifiedRecallEnabled === true)) {
+        timings.verifiedRecall = "skip";
+        return null;
+      }
+      const maxResults = this.getRecallSectionNumber("verified-episodes", "maxResults") ?? 3;
+      if (maxResults <= 0) {
+        timings.verifiedRecall = "skip(limit=0)";
+        return null;
+      }
+      const results = await searchVerifiedEpisodes({
+        memoryDir: this.config.memoryDir,
+        query: retrievalQuery,
+        maxResults,
+        boxRecallDays: this.config.boxRecallDays
+      });
+      timings.verifiedRecall = `${Date.now() - t0}ms`;
+      return results.length > 0 ? this.formatVerifiedEpisodeResults(results) : null;
+    })();
     const qmdPromise = (async () => {
       if (recallResultLimit <= 0) {
         timings.qmd = "skip(limit=0)";
@@ -19327,6 +19441,7 @@ ${formatted}`;
       causalTrajectorySection,
       trustZoneSection,
       harmonicRetrievalSection,
+      verifiedRecallSection,
       qmdResult,
       transcriptSection,
       compactionSection,
@@ -19343,6 +19458,7 @@ ${formatted}`;
       causalTrajectoryPromise,
       trustZonePromise,
       harmonicRetrievalPromise,
+      verifiedRecallPromise,
       qmdPromise,
       transcriptPromise,
       compactionPromise,
@@ -19409,6 +19525,9 @@ ${tmtNode.summary}`);
     if (harmonicRetrievalSection) {
       this.appendRecallSection(sectionBuckets, "harmonic-retrieval", harmonicRetrievalSection);
     }
+    if (verifiedRecallSection) {
+      this.appendRecallSection(sectionBuckets, "verified-episodes", verifiedRecallSection);
+    }
     if (qmdResult) {
       const t0 = Date.now();
       const { memoryResultsLists, globalResults } = qmdResult;
@@ -21609,6 +21728,29 @@ ${details.join("\n")}`;
     });
     return `## Harmonic Retrieval
 
+${lines.join("\n\n")}`;
+  }
+  formatVerifiedEpisodeResults(results) {
+    const lines = results.map(({ box, verifiedEpisodeCount, matchedFields }, index) => {
+      const header = [
+        `[${index + 1}] ${box.sealedAt.replace("T", " ").slice(0, 16)}`,
+        box.traceId ? `trace:${box.traceId.slice(0, 12)}` : "trace:none"
+      ].join(" | ");
+      const details = [
+        box.goal ?? `topics: ${box.topics.join(", ")}`,
+        `verified episodes: ${verifiedEpisodeCount}`
+      ];
+      if (box.toolsUsed && box.toolsUsed.length > 0) {
+        details.push(`tools: ${box.toolsUsed.join(", ")}`);
+      }
+      if (matchedFields.length > 0) {
+        details.push(`matched: ${matchedFields.join(", ")}`);
+      }
+      return `${header}
+${details.join("\n")}`;
+    });
+    return `## Verified Episodes
+
 ${lines.join("\n\n")}`;
   }
   summarizeIdentityText(raw, maxLines, maxChars) {
@@ -27106,6 +27248,126 @@ async function runCompatChecks(options) {
   };
 }
 
+// src/semantic-rule-promotion.ts
+function normalizeRuleWhitespace(value) {
+  return value.replace(/\s+/g, " ").trim();
+}
+function stripTrailingClausePunctuation(value) {
+  return value.replace(/[,:;]+$/g, "").trim();
+}
+function canonicalizeRuleContent(value) {
+  return extractExplicitIfThenRule(value) ?? normalizeRuleWhitespace(value);
+}
+function canonicalizeRuleKey(value) {
+  return canonicalizeRuleContent(value).toLowerCase();
+}
+function extractExplicitIfThenRule(content) {
+  const match = content.match(/\bif\b([\s\S]+?)\bthen\b([\s\S]+?)(?:[.!?](?:\s|$)|$)/i);
+  if (!match) return null;
+  const condition = stripTrailingClausePunctuation(normalizeRuleWhitespace(match[1] ?? ""));
+  const outcome = stripTrailingClausePunctuation(normalizeRuleWhitespace(match[2] ?? ""));
+  if (condition.length === 0 || outcome.length === 0) return null;
+  return `IF ${condition} THEN ${outcome}.`;
+}
+function promotionConfidence(memory) {
+  const base = Number.isFinite(memory.frontmatter.confidence) ? memory.frontmatter.confidence : 0.8;
+  return Math.max(0.6, Math.min(0.98, base));
+}
+function promotionTags(memory) {
+  return Array.from(/* @__PURE__ */ new Set([...memory.frontmatter.tags ?? [], "semantic-rule", "promoted-rule"]));
+}
+function buildSupportLinks(sourceMemoryId, confidence) {
+  return [
+    {
+      targetId: sourceMemoryId,
+      linkType: "supports",
+      strength: confidence,
+      reason: "Promoted from verified episodic memory"
+    }
+  ];
+}
+async function promoteSemanticRuleFromMemory(options) {
+  const report = {
+    enabled: options.enabled,
+    dryRun: options.dryRun === true,
+    promoted: [],
+    skipped: []
+  };
+  if (!options.enabled) {
+    report.skipped.push({
+      sourceMemoryId: options.sourceMemoryId,
+      reason: "disabled"
+    });
+    return report;
+  }
+  const storage = new StorageManager(options.memoryDir);
+  const sourceMemory = await storage.getMemoryById(options.sourceMemoryId);
+  if (!sourceMemory) {
+    report.skipped.push({
+      sourceMemoryId: options.sourceMemoryId,
+      reason: "source-memory-missing"
+    });
+    return report;
+  }
+  if (sourceMemory.frontmatter.status === "archived" || sourceMemory.frontmatter.memoryKind !== "episode") {
+    report.skipped.push({
+      sourceMemoryId: options.sourceMemoryId,
+      reason: "source-memory-not-episode"
+    });
+    return report;
+  }
+  const content = extractExplicitIfThenRule(sourceMemory.content);
+  if (!content) {
+    report.skipped.push({
+      sourceMemoryId: options.sourceMemoryId,
+      reason: "no-explicit-rule"
+    });
+    return report;
+  }
+  const ruleKey = canonicalizeRuleKey(content);
+  const existingRule = (await storage.readAllMemories()).find(
+    (memory) => memory.frontmatter.category === "rule" && memory.frontmatter.status !== "archived" && canonicalizeRuleKey(memory.content) === ruleKey
+  );
+  if (existingRule) {
+    report.skipped.push({
+      sourceMemoryId: options.sourceMemoryId,
+      reason: "duplicate-rule",
+      existingRuleId: existingRule.frontmatter.id
+    });
+    return report;
+  }
+  const confidence = promotionConfidence(sourceMemory);
+  const candidateBase = {
+    sourceMemoryId: options.sourceMemoryId,
+    content,
+    confidence,
+    tags: promotionTags(sourceMemory),
+    memoryKind: "note",
+    lineage: [options.sourceMemoryId]
+  };
+  if (options.dryRun === true) {
+    report.promoted.push({
+      id: `dry-run:${options.sourceMemoryId}`,
+      ...candidateBase
+    });
+    return report;
+  }
+  const id = await storage.writeMemory("rule", content, {
+    confidence,
+    tags: candidateBase.tags,
+    source: "semantic-rule-promotion",
+    lineage: candidateBase.lineage,
+    sourceMemoryId: options.sourceMemoryId,
+    memoryKind: "note",
+    links: buildSupportLinks(options.sourceMemoryId, confidence)
+  });
+  report.promoted.push({
+    id,
+    ...candidateBase
+  });
+  return report;
+}
+
 // src/cli.ts
 function rankCandidateForKeep(a, b) {
   const aConfidence = typeof a.frontmatter.confidence === "number" ? a.frontmatter.confidence : 0;
@@ -27342,6 +27604,23 @@ async function runHarmonicSearchCliCommand(options) {
     anchorsEnabled: options.abstractionAnchorsEnabled
   });
 }
+async function runVerifiedRecallSearchCliCommand(options) {
+  if (!options.verifiedRecallEnabled) return [];
+  return searchVerifiedEpisodes({
+    memoryDir: options.memoryDir,
+    query: options.query,
+    maxResults: Math.max(1, Math.floor(options.maxResults ?? 3)),
+    boxRecallDays: options.boxRecallDays
+  });
+}
+async function runSemanticRulePromoteCliCommand(options) {
+  return promoteSemanticRuleFromMemory({
+    memoryDir: options.memoryDir,
+    enabled: options.semanticRulePromotionEnabled,
+    sourceMemoryId: options.sourceMemoryId,
+    dryRun: options.dryRun
+  });
+}
 async function runTrustZonePromoteCliCommand(options) {
   const result = await promoteTrustZoneRecord({
     memoryDir: options.memoryDir,
@@ -28587,6 +28866,31 @@ function registerCli(api, orchestrator) {
         console.log(JSON.stringify(result, null, 2));
         console.log("OK");
       });
+      cmd.command("verified-recall-search").description("Preview verified episodic recall over recent memory boxes").argument("<query>", "Prompt-like query to evaluate against verified episodic recall").option("--max-results <count>", "Maximum number of verified episodic results to return", "3").action(async (...args) => {
+        const query = typeof args[0] === "string" ? args[0] : "";
+        const options = args[1] ?? {};
+        const maxResults = typeof options.maxResults === "string" ? Number.parseInt(options.maxResults, 10) : 3;
+        const results = await runVerifiedRecallSearchCliCommand({
+          memoryDir: orchestrator.config.memoryDir,
+          verifiedRecallEnabled: orchestrator.config.verifiedRecallEnabled,
+          query,
+          maxResults: Number.isFinite(maxResults) ? maxResults : 3,
+          boxRecallDays: orchestrator.config.boxRecallDays
+        });
+        console.log(JSON.stringify(results, null, 2));
+        console.log("OK");
+      });
+      cmd.command("semantic-rule-promote").description("Promote an explicit IF/THEN rule from a verified episodic memory").requiredOption("--memory-id <memoryId>", "Verified episodic memory id to promote from").option("--dry-run", "Preview the promoted semantic rule without writing it").action(async (...args) => {
+        const options = args[0] ?? {};
+        const result = await runSemanticRulePromoteCliCommand({
+          memoryDir: orchestrator.config.memoryDir,
+          semanticRulePromotionEnabled: orchestrator.config.semanticRulePromotionEnabled,
+          sourceMemoryId: String(options.memoryId ?? ""),
+          dryRun: options.dryRun === true
+        });
+        console.log(JSON.stringify(result, null, 2));
+        console.log("OK");
+      });
       cmd.command("conversation-index-health").description("Show conversation index backend health and index stats").action(async () => {
         const health = await runConversationIndexHealthCliCommand(orchestrator);
         console.log(JSON.stringify(health, null, 2));