@joshuaswarren/openclaw-engram 9.0.10 → 9.0.12

package/README.md

@@ -138,13 +138,13 @@ openclaw engram policy-status                # Lifecycle policy snapshot
 
 ## Configuration
 
-All settings live in `openclaw.json` under `plugins.entries.openclaw-engram.config`. Only `openaiApiKey` is required — everything else has sensible defaults.
+All settings live in `openclaw.json` under `plugins.entries.openclaw-engram.config`. `openaiApiKey` is optional when local LLM or gateway fallback paths are available.
 
 Key settings:
 
 | Setting | Default | Description |
 |---------|---------|-------------|
-| `openaiApiKey` | `(env fallback)` | OpenAI API key or `${ENV_VAR}` reference |
+| `openaiApiKey` | `(env fallback)` | Optional OpenAI API key or `${ENV_VAR}` reference for direct-client paths |
 | `model` | `gpt-5.2` | LLM model for extraction |
 | `searchBackend` | `"qmd"` | Search engine: `qmd`, `orama`, `lancedb`, `meilisearch`, `remote`, `noop` |
 | `qmdEnabled` | `true` | Enable QMD hybrid search |

package/dist/index.js

@@ -474,6 +474,8 @@ function parseConfig(raw) {
     recallConfidenceGateEnabled: cfg.recallConfidenceGateEnabled === true,
     recallConfidenceGateThreshold: typeof cfg.recallConfidenceGateThreshold === "number" ? Math.max(0, Math.min(1, cfg.recallConfidenceGateThreshold)) : 0.12,
     causalRuleExtractionEnabled: cfg.causalRuleExtractionEnabled === true,
+    memoryReconstructionEnabled: cfg.memoryReconstructionEnabled === true,
+    memoryReconstructionMaxExpansions: typeof cfg.memoryReconstructionMaxExpansions === "number" ? Math.max(0, Math.round(cfg.memoryReconstructionMaxExpansions)) : 3,
     graphLateralInhibitionEnabled: cfg.graphLateralInhibitionEnabled !== false,
     graphLateralInhibitionBeta: typeof cfg.graphLateralInhibitionBeta === "number" ? Math.max(0, Math.min(1, cfg.graphLateralInhibitionBeta)) : 0.15,
     graphLateralInhibitionTopM: typeof cfg.graphLateralInhibitionTopM === "number" ? Math.max(0, Math.round(cfg.graphLateralInhibitionTopM)) : 7,
@@ -2399,7 +2401,7 @@ var ExtractionEngine = class {
       });
     } else {
       this.client = null;
-      log.warn("no OpenAI API key \u2014 extraction/consolidation disabled (retrieval still works)");
+      log.warn("no OpenAI API key \u2014 direct OpenAI client disabled; local and gateway fallback paths remain available");
     }
     this.localLlm = localLlm ?? new LocalLlmClient(config, modelRegistry);
     this.fallbackLlm = new FallbackLlmClient(gatewayConfig);
@@ -2463,6 +2465,52 @@ var ExtractionEngine = class {
       ) : void 0
     };
   }
+  parseJsonObject(content) {
+    const trimmed = content?.trim();
+    if (!trimmed) return null;
+    for (const candidate of extractJsonCandidates(trimmed)) {
+      try {
+        return JSON.parse(candidate);
+      } catch {
+      }
+    }
+    return null;
+  }
+  normalizeContradictionVerificationResult(parsed) {
+    if (!parsed || typeof parsed.isContradiction !== "boolean") return null;
+    const rawWhich = parsed.whichIsNewer ?? parsed.winner;
+    const normalizedWhich = rawWhich === "first" || rawWhich === "existing" ? "first" : rawWhich === "second" || rawWhich === "new" ? "second" : "unclear";
+    return {
+      isContradiction: Boolean(parsed.isContradiction),
+      confidence: typeof parsed.confidence === "number" ? parsed.confidence : 0.5,
+      reasoning: typeof parsed.reasoning === "string" ? parsed.reasoning : typeof parsed.explanation === "string" ? parsed.explanation : "",
+      whichIsNewer: normalizedWhich
+    };
+  }
+  normalizeSuggestedLinksResult(parsed) {
+    if (!parsed || !Array.isArray(parsed.links)) {
+      return null;
+    }
+    const normalizedLinks = parsed.links.map((link) => {
+      const rawLinkType = link?.linkType ?? link?.type;
+      return {
+        targetId: typeof link?.targetId === "string" ? link.targetId : "",
+        linkType: rawLinkType === "follows" || rawLinkType === "references" || rawLinkType === "contradicts" || rawLinkType === "supports" || rawLinkType === "related" ? rawLinkType : "related",
+        strength: typeof link?.strength === "number" ? Math.max(0, Math.min(1, link.strength)) : 0.5,
+        reason: typeof link?.reason === "string" ? link.reason : void 0
+      };
+    }).filter((link) => link.targetId.length > 0);
+    return { links: normalizedLinks };
+  }
+  normalizeMemorySummaryResult(parsed) {
+    if (!parsed) return null;
+    const normalized = {
+      summaryText: typeof parsed.summaryText === "string" ? parsed.summaryText : typeof parsed.summary === "string" ? parsed.summary : "",
+      keyFacts: Array.isArray(parsed.keyFacts) ? parsed.keyFacts.filter((f) => typeof f === "string") : [],
+      keyEntities: Array.isArray(parsed.keyEntities) ? parsed.keyEntities.filter((e) => typeof e === "string") : Array.isArray(parsed.entities) ? parsed.entities.filter((e) => typeof e === "string") : []
+    };
+    return normalized.summaryText.length > 0 ? normalized : null;
+  }
   sanitizeConsolidationResult(result) {
     const items = result.items.map((item) => {
       if (!item.updatedContent) return item;
@@ -3648,10 +3696,6 @@ Respond with valid JSON matching this schema:
    * Called when QMD finds semantically similar memories (Phase 2B).
    */
   async verifyContradiction(newMemory, existingMemory) {
-    if (!this.client) {
-      log.warn("contradiction verification skipped \u2014 no OpenAI API key");
-      return null;
-    }
     const input = `Memory 1 (existing, created ${existingMemory.created}):
 Category: ${existingMemory.category}
 Content: ${existingMemory.content}
@@ -3682,6 +3726,26 @@ Respond with valid JSON matching this schema:
   "reasoning": "why they contradict or don't",
   "whichIsNewer": "first"
 }`;
+      if (!this.client) {
+        const fallbackResponse = await this.fallbackLlm.chatCompletion(
+          [
+            { role: "system", content: systemPrompt },
+            { role: "user", content: input }
+          ],
+          { temperature: 0.3, maxTokens: 2048 }
+        );
+        const normalized2 = this.normalizeContradictionVerificationResult(
+          this.parseJsonObject(fallbackResponse?.content)
+        );
+        if (normalized2) {
+          log.debug(
+            `contradiction check via fallback: ${normalized2.isContradiction ? "YES" : "NO"} (confidence: ${normalized2.confidence})`
+          );
+          return normalized2;
+        }
+        log.warn("contradiction verification skipped \u2014 no OpenAI API key and fallback unavailable");
+        return null;
+      }
       const response = await this.client.chat.completions.create({
         model: this.config.model,
         messages: [
@@ -3691,26 +3755,10 @@ Respond with valid JSON matching this schema:
         temperature: 0.3,
         max_tokens: 2048
       });
-      const rawContent = response.choices?.[0]?.message?.content?.trim();
-      let parsed = null;
-      if (rawContent) {
-        for (const candidate of extractJsonCandidates(rawContent)) {
-          try {
-            parsed = JSON.parse(candidate);
-            break;
-          } catch {
-          }
-        }
-      }
-      if (parsed && typeof parsed.isContradiction === "boolean") {
-        const rawWhich = parsed.whichIsNewer ?? parsed.winner;
-        const normalizedWhich = rawWhich === "first" || rawWhich === "existing" ? "first" : rawWhich === "second" || rawWhich === "new" ? "second" : "unclear";
-        const normalized = {
-          isContradiction: Boolean(parsed.isContradiction),
-          confidence: typeof parsed.confidence === "number" ? parsed.confidence : 0.5,
-          reasoning: typeof parsed.reasoning === "string" ? parsed.reasoning : typeof parsed.explanation === "string" ? parsed.explanation : "",
-          whichIsNewer: normalizedWhich
-        };
+      const normalized = this.normalizeContradictionVerificationResult(
+        this.parseJsonObject(response.choices?.[0]?.message?.content)
+      );
+      if (normalized) {
         log.debug(
           `contradiction check: ${normalized.isContradiction ? "YES" : "NO"} (confidence: ${normalized.confidence})`
         );
@@ -3727,10 +3775,6 @@ Respond with valid JSON matching this schema:
    * Called during extraction to build the knowledge graph.
    */
   async suggestLinks(newMemory, candidateMemories) {
-    if (!this.client) {
-      log.warn("link suggestion skipped \u2014 no OpenAI API key");
-      return null;
-    }
     if (candidateMemories.length === 0) {
       return { links: [] };
     }
@@ -3763,6 +3807,22 @@ Respond with valid JSON matching this schema:
 {
   "links": [{"targetId": "memory-id", "linkType": "follows|references|contradicts|supports|related", "strength": 0.8, "reason": "why"}]
 }`;
+      if (!this.client) {
+        const fallbackResponse = await this.fallbackLlm.chatCompletion(
+          [
+            { role: "system", content: systemPrompt },
+            { role: "user", content: input }
+          ],
+          { temperature: 0.3, maxTokens: 2048 }
+        );
+        const normalized2 = this.normalizeSuggestedLinksResult(this.parseJsonObject(fallbackResponse?.content));
+        if (normalized2) {
+          log.debug(`suggested ${normalized2.links.length} links via fallback`);
+          return normalized2;
+        }
+        log.warn("link suggestion skipped \u2014 no OpenAI API key and fallback unavailable");
+        return null;
+      }
       const response = await this.client.chat.completions.create({
         model: this.config.model,
         messages: [
@@ -3772,44 +3832,23 @@ Respond with valid JSON matching this schema:
         temperature: 0.3,
         max_tokens: 2048
       });
-      const rawContent = response.choices?.[0]?.message?.content?.trim();
-      let parsed = null;
-      if (rawContent) {
-        for (const candidate of extractJsonCandidates(rawContent)) {
-          try {
-            parsed = JSON.parse(candidate);
-            break;
-          } catch {
-          }
-        }
-      }
-      if (parsed && Array.isArray(parsed.links)) {
-        const normalizedLinks = parsed.links.map((link) => {
-          const rawLinkType = link?.linkType ?? link?.type;
-          return {
-            targetId: typeof link?.targetId === "string" ? link.targetId : "",
-            linkType: rawLinkType === "follows" || rawLinkType === "references" || rawLinkType === "contradicts" || rawLinkType === "supports" || rawLinkType === "related" ? rawLinkType : "related",
-            strength: typeof link?.strength === "number" ? Math.max(0, Math.min(1, link.strength)) : 0.5,
-            reason: typeof link?.reason === "string" ? link.reason : void 0
-          };
-        }).filter((link) => link.targetId.length > 0);
-        log.debug(`suggested ${normalizedLinks.length} links`);
-        return { links: normalizedLinks };
+      const normalized = this.normalizeSuggestedLinksResult(
+        this.parseJsonObject(response.choices?.[0]?.message?.content)
+      );
+      if (normalized) {
+        log.debug(`suggested ${normalized.links.length} links`);
+        return normalized;
       }
-      return { links: [] };
+      return null;
     } catch (err) {
       log.error("link suggestion failed", err);
-      return { links: [] };
+      return null;
     }
   }
   /**
    * Summarize a batch of old memories into a compact summary (Phase 4A).
    */
   async summarizeMemories(memories) {
-    if (!this.client) {
-      log.warn("summarization skipped \u2014 no OpenAI API key");
-      return null;
-    }
     if (memories.length === 0) return null;
     const memoryList = memories.map((m) => `[${m.id}] (${m.category}, ${m.created.slice(0, 10)})
 ${m.content}`).join("\n\n");
@@ -3833,6 +3872,24 @@ Respond with valid JSON matching this schema:
   "keyFacts": ["fact 1", "fact 2"],
   "keyEntities": ["entity-1", "entity-2"]
 }`;
+      if (!this.client) {
+        const fallbackResponse = await this.fallbackLlm.chatCompletion(
+          [
+            { role: "system", content: systemPrompt },
+            { role: "user", content: `Summarize these ${memories.length} memories:
+
+${memoryList}` }
+          ],
+          { temperature: 0.3, maxTokens: 4096 }
+        );
+        const normalized2 = this.normalizeMemorySummaryResult(this.parseJsonObject(fallbackResponse?.content));
+        if (normalized2) {
+          log.debug(`summarized ${memories.length} memories into ${normalized2.keyFacts.length} key facts via fallback`);
+          return normalized2;
+        }
+        log.warn("summarization skipped \u2014 no OpenAI API key and fallback unavailable");
+        return null;
+      }
       const response = await this.client.chat.completions.create({
         model: this.config.model,
         messages: [
@@ -3844,27 +3901,12 @@ ${memoryList}` }
         temperature: 0.3,
         max_tokens: 4096
       });
-      const rawContent = response.choices?.[0]?.message?.content?.trim();
-      let parsed = null;
-      if (rawContent) {
-        for (const candidate of extractJsonCandidates(rawContent)) {
-          try {
-            parsed = JSON.parse(candidate);
-            break;
-          } catch {
-          }
-        }
-      }
-      if (parsed) {
-        const normalized = {
-          summaryText: typeof parsed.summaryText === "string" ? parsed.summaryText : typeof parsed.summary === "string" ? parsed.summary : "",
-          keyFacts: Array.isArray(parsed.keyFacts) ? parsed.keyFacts.filter((f) => typeof f === "string") : [],
-          keyEntities: Array.isArray(parsed.keyEntities) ? parsed.keyEntities.filter((e) => typeof e === "string") : Array.isArray(parsed.entities) ? parsed.entities.filter((e) => typeof e === "string") : []
-        };
-        if (normalized.summaryText.length > 0) {
-          log.debug(`summarized ${memories.length} memories into ${normalized.keyFacts.length} key facts`);
-          return normalized;
-        }
+      const normalized = this.normalizeMemorySummaryResult(
+        this.parseJsonObject(response.choices?.[0]?.message?.content)
+      );
+      if (normalized) {
+        log.debug(`summarized ${memories.length} memories into ${normalized.keyFacts.length} key facts`);
+        return normalized;
       }
       return null;
     } catch (err) {
@@ -4179,6 +4221,26 @@ function rescoreMemoryImportance(memory) {
   return scoreImportance(memory.content, memory.frontmatter.category, memory.frontmatter.tags ?? []);
 }
 
+// src/reconstruct.ts
+function findUnresolvedEntityRefs(recalledSnippets, recalledEntityRefs, knownEntities) {
+  const refSet = new Set(recalledEntityRefs.map((r) => r.toLowerCase()));
+  const combinedText = recalledSnippets.join(" ").toLowerCase();
+  const sorted = [...knownEntities].sort((a, b) => b.length - a.length);
+  const matched = /* @__PURE__ */ new Set();
+  const unresolved = [];
+  for (const entity of sorted) {
+    const lower = entity.toLowerCase();
+    if (refSet.has(lower)) continue;
+    const escaped = lower.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const pattern = new RegExp(`(?:^|[\\s,;:'"(\\[])${escaped}(?:$|[\\s,;:'".)\\]])`, "i");
+    if (pattern.test(combinedText) && !matched.has(lower)) {
+      unresolved.push(entity);
+      matched.add(lower);
+    }
+  }
+  return unresolved;
+}
+
 // src/search/noop-backend.ts
 var NoopSearchBackend = class {
   async probe() {
@@ -17862,6 +17924,37 @@ ${tmtNode.summary}`);
         confidenceGateRejected = true;
       }
       memoryResults = memoryResults.slice(0, recallResultLimit);
+      if (this.config.memoryReconstructionEnabled && memoryResults.length > 0) {
+        try {
+          const snippets = memoryResults.map((r) => r.snippet);
+          const coveredRefs = memoryResults.map((r) => r.path).filter((p) => p.startsWith("entities/")).map((p) => p.replace(/^entities\//, "").replace(/\.md$/, ""));
+          const knownEntities = await profileStorage.listEntityNames();
+          const missing = findUnresolvedEntityRefs(snippets, coveredRefs, knownEntities);
+          if (missing.length > 0) {
+            const budget = this.config.memoryReconstructionMaxExpansions;
+            let expanded = 0;
+            for (const entityName of missing) {
+              if (expanded >= budget) break;
+              const raw = await profileStorage.readEntity(entityName);
+              if (raw && raw.length > 0) {
+                const snippet = raw.length > 300 ? raw.slice(0, 300) + "\u2026" : raw;
+                memoryResults.push({
+                  docid: `entity:${entityName}`,
+                  path: `entities/${entityName}.md`,
+                  snippet: `[Entity: ${entityName}] ${snippet}`,
+                  score: 0.1
+                });
+                expanded++;
+              }
+            }
+            if (expanded > 0) {
+              log.debug(`recall: reconstructed ${expanded} entity contexts`);
+            }
+          }
+        } catch (err) {
+          log.warn("recall: memory reconstruction failed (non-fatal)", err);
+        }
+      }
       if (memoryResults.length > 0) {
         recallSource = "hot_qmd";
         recalledMemoryCount = memoryResults.length;