@joshuaswarren/openclaw-engram 9.0.11 → 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

@@ -2401,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);
@@ -2465,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;
@@ -3650,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}
@@ -3684,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: [
@@ -3693,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})`
         );
@@ -3729,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: [] };
     }
@@ -3765,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: [
@@ -3774,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");
@@ -3835,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: [
@@ -3846,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) {