@joshuaswarren/openclaw-engram 9.0.40 → 9.0.41

package/README.md

@@ -42,6 +42,7 @@ AI agents forget everything between conversations. Engram fixes that.
 - **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.
+- **Verified rule recall** — Engram can now, when `semanticRuleVerificationEnabled` is enabled, inject a dedicated `Verified Rules` recall section that re-checks promoted rule memories against their cited source episodes at recall time and downgrades stale provenance before the rule can surface.
 - **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
@@ -211,6 +212,7 @@ Key settings:
 | `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` |
+| `semanticRuleVerificationEnabled` | `false` | Verify promoted semantic rules against their cited source episodes at recall time and inject a dedicated `Verified Rules` section via `openclaw engram semantic-rule-verify` |
 
 Full reference: [Config Reference](docs/config-reference.md)
 

package/dist/index.js

@@ -306,6 +306,7 @@ function parseConfig(raw) {
     abstractionAnchorsEnabled: cfg.abstractionAnchorsEnabled === true,
     verifiedRecallEnabled: cfg.verifiedRecallEnabled === true,
     semanticRulePromotionEnabled: cfg.semanticRulePromotionEnabled === true,
+    semanticRuleVerificationEnabled: cfg.semanticRuleVerificationEnabled === 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",
@@ -595,6 +596,12 @@ function buildDefaultRecallPipeline(cfg) {
       maxResults: 3,
       maxChars: 1800
     },
+    {
+      id: "verified-rules",
+      enabled: cfg.semanticRuleVerificationEnabled === true,
+      maxResults: 3,
+      maxChars: 1800
+    },
     {
       id: "memories",
       enabled: true,
@@ -15430,6 +15437,100 @@ async function searchVerifiedEpisodes(options) {
   ).slice(0, options.maxResults);
 }
 
+// src/semantic-rule-verifier.ts
+var DEFAULT_MIN_EFFECTIVE_CONFIDENCE = 0.45;
+function verificationConfidenceMultiplier(status) {
+  switch (status) {
+    case "verified":
+      return 1;
+    case "source-memory-not-episode":
+      return 0.45;
+    case "source-memory-archived":
+      return 0.4;
+    case "source-memory-missing":
+      return 0.35;
+    default:
+      return 0.35;
+  }
+}
+function resolveVerificationStatus(sourceMemory) {
+  if (!sourceMemory) return "source-memory-missing";
+  if (sourceMemory.frontmatter.status === "archived") return "source-memory-archived";
+  if (sourceMemory.frontmatter.memoryKind !== "episode") return "source-memory-not-episode";
+  return "verified";
+}
+function resolveEffectiveConfidence(rule, sourceMemory) {
+  const status = resolveVerificationStatus(sourceMemory);
+  const ruleConfidence = Number.isFinite(rule.frontmatter.confidence) ? rule.frontmatter.confidence : 0.8;
+  const sourceConfidence = Number.isFinite(sourceMemory?.frontmatter.confidence) ? sourceMemory.frontmatter.confidence : ruleConfidence;
+  const anchoredConfidence = Math.min(ruleConfidence, sourceConfidence);
+  const effectiveConfidence = Math.max(
+    0,
+    Math.min(1, anchoredConfidence * verificationConfidenceMultiplier(status))
+  );
+  return { status, effectiveConfidence };
+}
+function scoreVerifiedSemanticRuleCandidate(rule, sourceMemory, queryTokens, effectiveConfidence) {
+  const matchedFields = /* @__PURE__ */ new Set();
+  let score = 0;
+  const ruleContentMatches = countRecallTokenOverlap(queryTokens, rule.content);
+  if (ruleContentMatches > 0) {
+    score += ruleContentMatches * 5;
+    matchedFields.add("ruleContent");
+  }
+  const tagMatches = countRecallTokenOverlap(queryTokens, rule.frontmatter.tags?.join(" "));
+  if (tagMatches > 0) {
+    score += tagMatches * 2;
+    matchedFields.add("tags");
+  }
+  const sourceContentMatches = countRecallTokenOverlap(queryTokens, sourceMemory?.content);
+  if (sourceContentMatches > 0) {
+    score += sourceContentMatches * 2;
+    matchedFields.add("sourceContent");
+  }
+  if (score > 0) {
+    score += effectiveConfidence;
+  }
+  return { score, matchedFields };
+}
+async function searchVerifiedSemanticRules(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 allMemories = await storage.readAllMemories();
+  const memoryById = new Map(allMemories.map((memory) => [memory.frontmatter.id, memory]));
+  const minEffectiveConfidence = options.minEffectiveConfidence ?? DEFAULT_MIN_EFFECTIVE_CONFIDENCE;
+  const candidates = [];
+  for (const memory of allMemories) {
+    if (memory.frontmatter.category !== "rule") continue;
+    if (memory.frontmatter.status === "archived") continue;
+    if (memory.frontmatter.source !== "semantic-rule-promotion") continue;
+    const sourceMemoryId = memory.frontmatter.sourceMemoryId;
+    if (!sourceMemoryId) continue;
+    const sourceMemory = memoryById.get(sourceMemoryId);
+    const { status, effectiveConfidence } = resolveEffectiveConfidence(memory, sourceMemory);
+    if (effectiveConfidence < minEffectiveConfidence) continue;
+    const { score, matchedFields } = scoreVerifiedSemanticRuleCandidate(
+      memory,
+      sourceMemory,
+      queryTokens,
+      effectiveConfidence
+    );
+    if (score <= 0) continue;
+    candidates.push({
+      rule: memory,
+      score,
+      sourceMemoryId,
+      verificationStatus: status,
+      effectiveConfidence,
+      matchedFields: [...matchedFields].sort()
+    });
+  }
+  return candidates.sort(
+    (left, right) => right.score - left.score || right.effectiveConfidence - left.effectiveConfidence || right.rule.frontmatter.updated.localeCompare(left.rule.frontmatter.updated)
+  ).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"]);
@@ -19234,6 +19335,25 @@ ${r.snippet.trim()}
       timings.verifiedRecall = `${Date.now() - t0}ms`;
       return results.length > 0 ? this.formatVerifiedEpisodeResults(results) : null;
     })();
+    const verifiedRulesPromise = (async () => {
+      const t0 = Date.now();
+      if (!this.config.semanticRuleVerificationEnabled || !this.isRecallSectionEnabled("verified-rules", this.config.semanticRuleVerificationEnabled === true)) {
+        timings.verifiedRules = "skip";
+        return null;
+      }
+      const maxResults = this.getRecallSectionNumber("verified-rules", "maxResults") ?? 3;
+      if (maxResults <= 0) {
+        timings.verifiedRules = "skip(limit=0)";
+        return null;
+      }
+      const results = await searchVerifiedSemanticRules({
+        memoryDir: this.config.memoryDir,
+        query: retrievalQuery,
+        maxResults
+      });
+      timings.verifiedRules = `${Date.now() - t0}ms`;
+      return results.length > 0 ? this.formatVerifiedSemanticRuleResults(results) : null;
+    })();
     const qmdPromise = (async () => {
       if (recallResultLimit <= 0) {
         timings.qmd = "skip(limit=0)";
@@ -19442,6 +19562,7 @@ ${formatted}`;
       trustZoneSection,
       harmonicRetrievalSection,
       verifiedRecallSection,
+      verifiedRulesSection,
       qmdResult,
       transcriptSection,
       compactionSection,
@@ -19459,6 +19580,7 @@ ${formatted}`;
       trustZonePromise,
       harmonicRetrievalPromise,
       verifiedRecallPromise,
+      verifiedRulesPromise,
       qmdPromise,
       transcriptPromise,
       compactionPromise,
@@ -19528,6 +19650,9 @@ ${tmtNode.summary}`);
     if (verifiedRecallSection) {
       this.appendRecallSection(sectionBuckets, "verified-episodes", verifiedRecallSection);
     }
+    if (verifiedRulesSection) {
+      this.appendRecallSection(sectionBuckets, "verified-rules", verifiedRulesSection);
+    }
     if (qmdResult) {
       const t0 = Date.now();
       const { memoryResultsLists, globalResults } = qmdResult;
@@ -21751,6 +21876,27 @@ ${details.join("\n")}`;
     });
     return `## Verified Episodes
 
+${lines.join("\n\n")}`;
+  }
+  formatVerifiedSemanticRuleResults(results) {
+    const lines = results.map(({ rule, sourceMemoryId, verificationStatus, effectiveConfidence, matchedFields }, index) => {
+      const header = [
+        `[${index + 1}] ${rule.frontmatter.updated.replace("T", " ").slice(0, 16)}`,
+        verificationStatus,
+        `confidence:${effectiveConfidence.toFixed(2)}`
+      ].join(" | ");
+      const details = [
+        rule.content,
+        `source memory: ${sourceMemoryId}`
+      ];
+      if (matchedFields.length > 0) {
+        details.push(`matched: ${matchedFields.join(", ")}`);
+      }
+      return `${header}
+${details.join("\n")}`;
+    });
+    return `## Verified Rules
+
 ${lines.join("\n\n")}`;
   }
   summarizeIdentityText(raw, maxLines, maxChars) {
@@ -27621,6 +27767,14 @@ async function runSemanticRulePromoteCliCommand(options) {
     dryRun: options.dryRun
   });
 }
+async function runSemanticRuleVerifyCliCommand(options) {
+  if (!options.semanticRuleVerificationEnabled) return [];
+  return searchVerifiedSemanticRules({
+    memoryDir: options.memoryDir,
+    query: options.query,
+    maxResults: Math.max(1, Math.floor(options.maxResults ?? 3))
+  });
+}
 async function runTrustZonePromoteCliCommand(options) {
   const result = await promoteTrustZoneRecord({
     memoryDir: options.memoryDir,
@@ -28891,6 +29045,19 @@ function registerCli(api, orchestrator) {
         console.log(JSON.stringify(result, null, 2));
         console.log("OK");
       });
+      cmd.command("semantic-rule-verify").description("Preview verified semantic-rule recall with provenance-aware confidence downgrades").argument("<query>", "Prompt-like query to evaluate against verified semantic-rule recall").option("--max-results <count>", "Maximum number of verified semantic rules 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 runSemanticRuleVerifyCliCommand({
+          memoryDir: orchestrator.config.memoryDir,
+          semanticRuleVerificationEnabled: orchestrator.config.semanticRuleVerificationEnabled,
+          query,
+          maxResults: Number.isFinite(maxResults) ? maxResults : 3
+        });
+        console.log(JSON.stringify(results, 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));