@joshuaswarren/openclaw-engram 9.0.39 → 9.0.41

package/README.md

@@ -41,6 +41,8 @@ AI agents forget everything between conversations. Engram fixes that.
 - **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.
+- **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
@@ -209,7 +211,8 @@ Key settings:
 | `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` | Reserve semantic-rule promotion surfaces until verified episodic recall has been benchmarked in follow-on slices |
+| `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) {
@@ -27248,6 +27394,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;
@@ -27493,6 +27759,22 @@ async function runVerifiedRecallSearchCliCommand(options) {
     boxRecallDays: options.boxRecallDays
   });
 }
+async function runSemanticRulePromoteCliCommand(options) {
+  return promoteSemanticRuleFromMemory({
+    memoryDir: options.memoryDir,
+    enabled: options.semanticRulePromotionEnabled,
+    sourceMemoryId: options.sourceMemoryId,
+    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,
@@ -28752,6 +29034,30 @@ function registerCli(api, orchestrator) {
         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("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));