@joshuaswarren/openclaw-engram 9.0.11 → 9.0.13

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

@@ -325,6 +325,11 @@ function parseConfig(raw) {
     localLlmRetryBackoffMs: typeof cfg.localLlmRetryBackoffMs === "number" ? cfg.localLlmRetryBackoffMs : 400,
     localLlm400TripThreshold: typeof cfg.localLlm400TripThreshold === "number" ? cfg.localLlm400TripThreshold : 5,
     localLlm400CooldownMs: typeof cfg.localLlm400CooldownMs === "number" ? cfg.localLlm400CooldownMs : 12e4,
+    // Local LLM fast tier (v9.1)
+    localLlmFastEnabled: cfg.localLlmFastEnabled === true,
+    localLlmFastModel: typeof cfg.localLlmFastModel === "string" && cfg.localLlmFastModel.length > 0 ? cfg.localLlmFastModel : "",
+    localLlmFastUrl: typeof cfg.localLlmFastUrl === "string" && cfg.localLlmFastUrl.length > 0 ? cfg.localLlmFastUrl : typeof cfg.localLlmUrl === "string" && cfg.localLlmUrl.length > 0 ? cfg.localLlmUrl : "http://localhost:1234/v1",
+    localLlmFastTimeoutMs: typeof cfg.localLlmFastTimeoutMs === "number" ? cfg.localLlmFastTimeoutMs : 15e3,
     // Gateway config (passed from index.ts for fallback AI)
     gatewayConfig: cfg.gatewayConfig,
     // v3.0 namespaces (default off)
@@ -2401,7 +2406,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 +2470,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 +3701,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 +3731,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 +3760,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 +3780,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 +3812,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 +3837,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 +3877,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 +3906,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) {
@@ -16348,6 +16393,7 @@ var Orchestrator = class _Orchestrator {
   sessionObserver;
   summarizer;
   localLlm;
+  fastLlm;
   modelRegistry;
   relevance;
   negatives;
@@ -16449,6 +16495,10 @@ var Orchestrator = class _Orchestrator {
     this.policyRuntime = new PolicyRuntimeManager(config.memoryDir, config);
     this.summarizer = new HourlySummarizer(config, config.gatewayConfig, this.modelRegistry, this.transcript);
     this.localLlm = new LocalLlmClient(config, this.modelRegistry);
+    this.fastLlm = config.localLlmFastEnabled ? new LocalLlmClient(
+      { ...config, localLlmModel: config.localLlmFastModel || config.localLlmModel, localLlmUrl: config.localLlmFastUrl, localLlmTimeoutMs: config.localLlmFastTimeoutMs },
+      this.modelRegistry
+    ) : this.localLlm;
     this.extraction = new ExtractionEngine(config, this.localLlm, config.gatewayConfig, this.modelRegistry);
     this.threading = new ThreadingManager(
       path30.join(config.memoryDir, "threads"),
@@ -17852,7 +17902,7 @@ ${tmtNode.summary}`);
             id: r.path,
             snippet: r.snippet || r.path
           })),
-          local: this.localLlm,
+          local: this.fastLlm,
           enabled: true,
           timeoutMs: this.config.rerankTimeoutMs,
           maxCandidates: this.config.rerankMaxCandidates,
@@ -19343,7 +19393,7 @@ _Context: ${topQuestion.context}_`
           try {
             const factsText = entity.facts.slice(0, 10).join("; ");
             const prompt = `Summarize this entity in one sentence. Entity: ${entity.name} (${entity.type}). Facts: ${factsText}`;
-            const response = await this.localLlm.chatCompletion(
+            const response = await this.fastLlm.chatCompletion(
               [
                 { role: "system", content: "Respond with a single concise sentence summarizing the entity. No JSON, just plain text." },
                 { role: "user", content: prompt }
@@ -19445,7 +19495,7 @@ _Context: ${topQuestion.context}_`
           const prompt = `You are a memory archivist. Summarize the following ${level}-level memories into 3\u20135 sentences, preserving key facts, decisions, and preferences.
 
 ${texts.map((t, i) => `[${i + 1}] ${t}`).join("\n\n")}`;
-          const response = await this.localLlm.chatCompletion(
+          const response = await this.fastLlm.chatCompletion(
             [
               { role: "system", content: "Respond with a 3\u20135 sentence narrative summary. No JSON, just plain prose." },
               { role: "user", content: prompt }
@@ -19502,7 +19552,7 @@ ${texts.map((t, i) => `[${i + 1}] ${t}`).join("\n\n")}`;
           "Input candidate:",
           JSON.stringify(baseline)
         ].join("\n");
-        const response = await this.localLlm.chatCompletion(
+        const response = await this.fastLlm.chatCompletion(
           [
             { role: "system", content: "Respond with strict JSON only. No markdown." },
             { role: "user", content: prompt }
@@ -20114,7 +20164,7 @@ ${lines.join("\n\n")}`;
           id: r.path,
           snippet: r.snippet || r.path
         })),
-        local: this.localLlm,
+        local: this.fastLlm,
         enabled: true,
         timeoutMs: this.config.rerankTimeoutMs,
         maxCandidates: this.config.rerankMaxCandidates,
@@ -27686,7 +27736,7 @@ var index_default = {
     });
     initLogger(api.logger, cfg.debug);
     log.info(
-      `initialized (debug=${cfg.debug}, qmdEnabled=${cfg.qmdEnabled}, transcriptEnabled=${cfg.transcriptEnabled}, hourlySummariesEnabled=${cfg.hourlySummariesEnabled}, localLlmEnabled=${cfg.localLlmEnabled})`
+      `initialized (debug=${cfg.debug}, qmdEnabled=${cfg.qmdEnabled}, transcriptEnabled=${cfg.transcriptEnabled}, hourlySummariesEnabled=${cfg.hourlySummariesEnabled}, localLlmEnabled=${cfg.localLlmEnabled}${cfg.localLlmFastEnabled ? `, fastLlm=${cfg.localLlmFastModel || "(primary)"}` : ""})`
     );
     const existing = globalThis.__openclawEngramOrchestrator;
     const orchestrator = existing?.recall ? existing : new Orchestrator(cfg);