openclaw-hybrid-memory 2026.5.310 → 2026.6.10

package/api/plugin-runtime.ts

@@ -49,6 +49,8 @@ import type { ToolRegistrationHandle } from "../setup/register-tools.js";
 export interface PluginRuntime {
   // --- Config & resolved paths ---
   cfg: HybridMemoryConfig;
+  /** Parse-time config snapshot for hot-reload reuse checks (bootstrap may mutate `cfg`). */
+  parsedCfgSnapshot: HybridMemoryConfig;
   resolvedLancePath: string;
   resolvedSqlitePath: string;
 

package/backends/facts-db/contradictions.ts

@@ -925,7 +925,7 @@ export async function resolveContradictionsAutonomously(
         if (applied) decisionsApplied++;
       }
       continue;
-    } else if (lww.eligible && isFactVerified(db, contradiction.factIdOld)) {
+    } else if (isFactVerified(db, contradiction.factIdOld)) {
       reviewItem.suggestedReason = "Older fact is verified; leaving for manual review.";
     }
 

package/cli/cmd-extract-directives.ts

@@ -15,11 +15,75 @@ import type { HandlerContext } from "./handlers.js";
 import { acquireScanSlot, clearScanLock } from "./shared.js";
 
 import { getSessionFilePathsSince, getMaxMtime } from "./cmd-extract-sessions.js";
+
+const VECTOR_CANDIDATE_LIMIT = 10;
+const VECTOR_CANDIDATE_OVERFETCH_LIMIT = 50;
+const VECTOR_CANDIDATE_MIN_SCORE = 0;
+
+/**
+ * Identifies transient/retryable store errors (SQLite busy, network issues) vs permanent errors.
+ * Permanent errors (TypeError, schema bugs, etc.) should not block cursor advancement.
+ */
+function isRetryableStoreError(err: unknown): boolean {
+  const message = err instanceof Error ? err.message : String(err);
+  const code =
+    typeof err === "object" && err !== null && "code" in err ? String((err as { code?: unknown }).code ?? "") : "";
+
+  // SQLite busy/lock errors are retryable
+  if (/SQLITE_BUSY|database is locked/i.test(message) || /SQLITE_BUSY/i.test(code)) {
+    return true;
+  }
+
+  // Transient network errors are retryable
+  if (
+    /ECONNREFUSED|ECONNRESET|ETIMEDOUT|ENOTFOUND|EAI_AGAIN|EHOSTUNREACH|socket hang up|fetch failed|network timeout|connect\s+ETIMEDOUT/i.test(
+      message,
+    ) ||
+    /ECONNREFUSED|ECONNRESET|ETIMEDOUT|ENOTFOUND|EHOSTUNREACH/i.test(code)
+  ) {
+    return true;
+  }
+
+  // All other errors (TypeError, schema bugs, programming errors) are permanent
+  return false;
+}
+
+function getVectorSearchFailReason(vectorDb: unknown): string | null {
+  const getter = (vectorDb as { getLastSearchFailReason?: unknown }).getLastSearchFailReason;
+  if (typeof getter !== "function") return null;
+  try {
+    const reason = getter.call(vectorDb);
+    return typeof reason === "string" && reason.length > 0 ? reason : null;
+  } catch {
+    return null;
+  }
+}
+
+function isLiveFact(candidate: { supersededAt?: number | null; expiresAt?: number | null }): boolean {
+  const nowSec = Math.floor(Date.now() / 1000);
+  return candidate.supersededAt == null && (candidate.expiresAt == null || candidate.expiresAt > nowSec);
+}
+
 export async function runExtractDirectivesForCli(
   ctx: HandlerContext,
   opts: { days?: number; verbose?: boolean; dryRun?: boolean; full?: boolean },
-): Promise<DirectiveExtractResult & { stored?: number; partial?: boolean; dedupeDegraded?: boolean }> {
-  const { factsDb, vectorDb, cfg, logger } = ctx;
+): Promise<
+  DirectiveExtractResult & {
+    stored?: number;
+    partial?: boolean;
+    dedupeDegraded?: boolean;
+    directiveDedupeMode?: "vector" | "lexical-only" | "mixed";
+    directiveRejected?: {
+      permanent: number;
+      retryable: number;
+      parserOrModelFailure: number;
+      boundedPartialRetry: number;
+    };
+    cursorAdvanced?: boolean;
+    cursorBlockedReason?: "retryable_rejections" | "parser_or_model_failure" | "bounded_partial_retry";
+  }
+> {
+  const { factsDb, vectorDb, embeddings, cfg, logger } = ctx;
   const SCAN_TYPE = "extract-directives";
   logger.info?.("memory-hybrid: extract-directives — regex extraction (no LLM model selection)");
   const sessionDir = cfg.procedures.sessionsDir;
@@ -87,6 +151,11 @@ export async function runExtractDirectivesForCli(
     // Store directives as facts if not dry-run
     let stored = 0;
     let storeDedupeVectorFallbackSuppressed = 0;
+    let vectorDedupeStores = 0;
+    let lexicalOnlyDedupeStores = 0;
+    let retryableRejected = 0;
+    let parserOrModelRejected = 0;
+    let boundedPartialRetryRejected = 0;
     if (!opts.dryRun) {
       for (const incident of result.incidents) {
         try {
@@ -111,10 +180,59 @@ export async function runExtractDirectivesForCli(
                             ? "fact"
                             : "other";
           const source = `directive:${incident.sessionFile}`;
-          const shouldCountVectorFallback = shouldReportVectorDedupeFallback({
+          let vector: number[] | undefined;
+          let vectorCandidates: Array<{ id: string; score: number }> | undefined;
+          try {
+            vector = await embeddings.embed(incident.extractedRule);
+            if (cfg.store?.fuzzyDedupe ?? true) {
+              const sourceScope = "global";
+              const sourceScopeTarget = null;
+              const embeddingModelName =
+                typeof embeddings.modelName === "string" && embeddings.modelName.trim().length > 0
+                  ? embeddings.modelName
+                  : null;
+              const neighbors = await vectorDb.search(
+                vector,
+                VECTOR_CANDIDATE_OVERFETCH_LIMIT,
+                VECTOR_CANDIDATE_MIN_SCORE,
+              );
+              if (!getVectorSearchFailReason(vectorDb)) {
+                vectorCandidates = neighbors
+                  .map((candidate) => ({
+                    id: candidate.entry.id,
+                    score: candidate.score,
+                  }))
+                  .filter(
+                    (candidate) =>
+                      typeof candidate.id === "string" && candidate.id.length > 0 && Number.isFinite(candidate.score),
+                  )
+                  .filter((candidate) => {
+                    const fact = factsDb.getById(candidate.id);
+                    return (
+                      fact != null &&
+                      isLiveFact(fact) &&
+                      fact.source.startsWith("directive:") &&
+                      (fact.scope ?? "global") === sourceScope &&
+                      (fact.scope === "global" ? null : (fact.scopeTarget ?? null)) === sourceScopeTarget &&
+                      (embeddingModelName == null ||
+                        fact.embeddingModel == null ||
+                        fact.embeddingModel === embeddingModelName)
+                    );
+                  })
+                  .slice(0, VECTOR_CANDIDATE_LIMIT);
+              }
+            }
+          } catch (err) {
+            capturePluginError(err instanceof Error ? err : new Error(String(err)), {
+              subsystem: "cli",
+              operation: "runExtractDirectivesForCli:vector-candidates",
+            });
+          }
+          const usedLexicalOnlyFallback = shouldReportVectorDedupeFallback({
             source,
             fuzzyDedupe: cfg.store?.fuzzyDedupe ?? true,
             storeConfig: cfg.store,
+            vectorCandidates,
           });
           const storeResult = factsDb.storeWithResult(
             {
@@ -131,13 +249,24 @@ export async function runExtractDirectivesForCli(
               tags: ["directive-extract", ...incident.categories.map((c) => `directive:${c}`)],
             },
             {
+              vectorCandidates,
               warnContext: "extract-directives",
               suppressVectorFallbackWarning: true,
             },
           );
+          const usedVectorCandidates = Boolean(vectorCandidates && vectorCandidates.length > 0);
+          if (usedLexicalOnlyFallback) {
+            storeDedupeVectorFallbackSuppressed++;
+            lexicalOnlyDedupeStores++;
+          } else if (usedVectorCandidates) {
+            vectorDedupeStores++;
+          } else {
+            lexicalOnlyDedupeStores++;
+          }
           if (storeResult.skipped) {
             continue;
           }
+          const entry = storeResult.entry;
           // CRITICAL FIX (#2): Delete vector for evicted fact to prevent orphaned vectors
           await cleanupEvictedVector({
             vectorDb,
@@ -145,9 +274,57 @@ export async function runExtractDirectivesForCli(
             logger: logger,
             context: "extract-directives",
           });
-          if (shouldCountVectorFallback) storeDedupeVectorFallbackSuppressed++;
-          stored++;
+          if (storeResult.embeddingStale) {
+            try {
+              const mergedVector = await embeddings.embed(entry.text);
+              // Avoid pre-delete so transient store failures do not leave merged facts without any vector.
+              await vectorDb.store({
+                text: entry.text,
+                vector: mergedVector,
+                importance: entry.importance,
+                category: entry.category as MemoryCategory,
+                id: entry.id,
+              });
+              factsDb.setEmbeddingModel(entry.id, embeddings.modelName);
+            } catch (err) {
+              logger.warn?.(`memory-hybrid: extract-directives merged vector refresh failed: ${err}`);
+              capturePluginError(err instanceof Error ? err : new Error(String(err)), {
+                subsystem: "cli",
+                operation: "runExtractDirectivesForCli:merged-vector-refresh",
+              });
+            }
+            continue;
+          }
+          if (!storeResult.newlyStored) {
+            continue;
+          }
+          if (!vector) {
+            stored++;
+            continue;
+          }
+          try {
+            await vectorDb.store({
+              text: incident.extractedRule,
+              vector,
+              importance: 0.8,
+              category: category as MemoryCategory,
+              id: entry.id,
+            });
+            factsDb.setEmbeddingModel(entry.id, embeddings.modelName);
+            stored++;
+          } catch (err) {
+            logger.warn?.(`memory-hybrid: extract-directives vector store failed: ${err}`);
+            capturePluginError(err instanceof Error ? err : new Error(String(err)), {
+              subsystem: "cli",
+              operation: "runExtractDirectivesForCli:vector-store",
+            });
+            stored++;
+          }
         } catch (err) {
+          const isRetryable = isRetryableStoreError(err);
+          if (isRetryable) {
+            retryableRejected++;
+          }
           capturePluginError(err as Error, {
             subsystem: "cli",
             operation: "runExtractDirectivesForCli:store",
@@ -158,19 +335,56 @@ export async function runExtractDirectivesForCli(
 
     if (storeDedupeVectorFallbackSuppressed > 0) {
       logger.warn?.(
-        `memory-hybrid: extract-directives DEGRADED — store dedupe used lexical-only for ${storeDedupeVectorFallbackSuppressed} store(s) (vectorCandidates not wired for this CLI path yet)`,
+        `memory-hybrid: extract-directives DEGRADED — store dedupe used lexical-only for ${storeDedupeVectorFallbackSuppressed} store(s) (embedding or vector search failed)`,
       );
     }
-    const partial = (result.rejected ?? 0) > 0;
+    const directiveRejected = {
+      permanent: result.rejected ?? 0,
+      retryable: retryableRejected,
+      parserOrModelFailure: parserOrModelRejected,
+      boundedPartialRetry: boundedPartialRetryRejected,
+    };
+    const blockedRejections =
+      directiveRejected.retryable + directiveRejected.parserOrModelFailure + directiveRejected.boundedPartialRetry;
+    const partial = blockedRejections > 0;
     const dedupeDegraded = storeDedupeVectorFallbackSuppressed > 0;
-    const returnVal = { ...result, stored, partial, dedupeDegraded };
-    if (!opts.dryRun && !partial) {
+    const totalDedupeStores = vectorDedupeStores + lexicalOnlyDedupeStores;
+    let directiveDedupeMode: "vector" | "lexical-only" | "mixed" | undefined;
+    if (vectorDedupeStores === totalDedupeStores && totalDedupeStores > 0) {
+      directiveDedupeMode = "vector";
+    } else if (lexicalOnlyDedupeStores === totalDedupeStores && totalDedupeStores > 0) {
+      directiveDedupeMode = "lexical-only";
+    } else if (totalDedupeStores > 0) {
+      directiveDedupeMode = "mixed";
+    }
+    let cursorAdvanced: boolean | undefined;
+    let cursorBlockedReason: "retryable_rejections" | "parser_or_model_failure" | "bounded_partial_retry" | undefined;
+    if (directiveRejected.parserOrModelFailure > 0) {
+      cursorBlockedReason = "parser_or_model_failure";
+    } else if (directiveRejected.boundedPartialRetry > 0) {
+      cursorBlockedReason = "bounded_partial_retry";
+    } else if (directiveRejected.retryable > 0) {
+      cursorBlockedReason = "retryable_rejections";
+    }
+    const returnVal = {
+      ...result,
+      stored,
+      partial,
+      dedupeDegraded,
+      directiveDedupeMode,
+      directiveRejected,
+      cursorAdvanced,
+      cursorBlockedReason,
+    };
+    if (!opts.dryRun && !cursorBlockedReason) {
       const lastSessionTs = getMaxMtime(filePaths);
       factsDb.updateScanCursor(SCAN_TYPE, lastSessionTs ?? 0, result.sessionsScanned);
+      returnVal.cursorAdvanced = true;
     }
-    if (!opts.dryRun && partial) {
+    if (!opts.dryRun && cursorBlockedReason) {
+      returnVal.cursorAdvanced = false;
       logger.info?.(
-        `memory-hybrid: extract-directives — ${result.rejected ?? 0} directive candidate(s) rejected, cursor not advanced`,
+        `memory-hybrid: extract-directives — cursor blocked (${cursorBlockedReason}); rejected={permanent:${directiveRejected.permanent},retryable:${directiveRejected.retryable},parserOrModelFailure:${directiveRejected.parserOrModelFailure},boundedPartialRetry:${directiveRejected.boundedPartialRetry}}`,
       );
     }
     return returnVal;

package/cli/cmd-extract-proposals.ts

@@ -177,16 +177,15 @@ export async function runGenerateProposalsForCli(
     rawResponse = detail.content;
   } catch (err) {
     const errMsg = err instanceof Error ? err.message : String(err);
-    console.error(
-      `memory-hybrid: generate-proposals LLM call failed (model=${model}, fallbacks=${JSON.stringify(
-        fallbackModels,
-      )}): ${errMsg}`,
-    );
+    const failureMessage = `memory-hybrid: generate-proposals LLM call failed (model=${model}, fallbacks=${JSON.stringify(
+      fallbackModels,
+    )}): ${errMsg}`;
+    console.error(failureMessage);
     capturePluginError(err instanceof Error ? err : new Error(String(err)), {
       subsystem: "cli",
       operation: "runGenerateProposalsForCli:llm",
     });
-    return { created: 0 };
+    throw new Error(failureMessage);
   }
   let items: Array<{
     targetFile: string;

package/cli/cmd-extract-reinforcement.ts

@@ -16,6 +16,7 @@ import { CostFeature } from "../services/cost-feature-labels.js";
 import { capturePluginError } from "../services/error-reporter.js";
 import {
   type AnnotationReasons,
+  type ReinforcementAnnotationDiagnostic,
   type ReinforcementAnnotationStatus,
   type ReinforcementExtractResult,
   runReinforcementExtract,
@@ -456,6 +457,7 @@ export async function runExtractReinforcementForCli(
 
     // Derive annotation status for the incidentsFound > 0 && annotated == 0 case
     let annotationStatus: ReinforcementAnnotationStatus | undefined;
+    let annotationDiagnostic: ReinforcementAnnotationDiagnostic | undefined;
     if (!opts.dryRun && result.incidents.length > 0 && annotated === 0) {
       if (llmAnalysisFailed && annotationReasons.noRecalledIds === result.incidents.length) {
         annotationStatus = "degraded_model_or_parser";
@@ -474,10 +476,79 @@ export async function runExtractReinforcementForCli(
       // Do not override a successful annotation with a failure status — leave undefined.
     }
 
+    if (!opts.dryRun && result.incidents.length > 0 && annotated === 0 && annotationStatus) {
+      const noIdsAfterRecall = result.incidents.filter(
+        (incident) =>
+          incident.recalledMemoryIds.length === 0 &&
+          incident.toolCallSequence.some((tool) => tool.toLowerCase() === "memory_recall"),
+      ).length;
+      if (annotationStatus === "partial_no_matches") {
+        if (noIdsAfterRecall > 0) {
+          annotationDiagnostic = {
+            kind: "missing_recall_metadata",
+            summary: `${noIdsAfterRecall}/${result.incidents.length} incident(s) invoked memory_recall but yielded no parseable memory IDs.`,
+            recommendedActions: [
+              "Inspect memory_recall tool_result payload format and ensure IDs remain visible in session logs.",
+              "Run a targeted replay to confirm retrieval output includes canonical UUID IDs.",
+            ],
+          };
+        } else {
+          annotationDiagnostic = {
+            kind: "expected_sparse_data",
+            summary:
+              "No incidents included recalled memory IDs; this is expected for sessions without explicit memory recall usage.",
+            recommendedActions: [
+              "Treat as informational unless recall-heavy sessions also show partial_no_matches.",
+              "If recall should have happened, inspect retrieval prompting and memory_recall tool usage in those sessions.",
+            ],
+          };
+        }
+      } else if (annotationStatus === "degraded_model_or_parser") {
+        annotationDiagnostic = {
+          kind: "model_or_parser_degraded",
+          summary:
+            "LLM analysis failed or returned unparseable output while incidents lacked reinforceable recalled IDs.",
+          recommendedActions: [
+            "Retry extract-reinforcement after confirming LLM/provider health and parser logs.",
+            "If this persists, run with --verbose and inspect reinforcement analysis prompt/response shape.",
+          ],
+        };
+      } else if (annotationReasons.errors > 0) {
+        annotationDiagnostic = {
+          kind: "annotation_errors",
+          summary: `${annotationReasons.errors} incident(s) hit runtime annotation errors.`,
+          recommendedActions: [
+            "Inspect captured plugin errors for runExtractReinforcementForCli.",
+            "Address procedure/fact reinforce exceptions before rerunning extract-reinforcement.",
+          ],
+        };
+      } else if (annotationReasons.recalledIdsNoMatch === result.incidents.length) {
+        annotationDiagnostic = {
+          kind: "stale_recalled_ids",
+          summary: "All recalled memory IDs failed to match active reinforceable facts.",
+          recommendedActions: [
+            "Audit stale/superseded IDs referenced by memory_recall outputs.",
+            "Re-run retrieval against current fact IDs and repair stale recall references.",
+          ],
+        };
+      } else if (annotationStatus === "failed_annotation") {
+        annotationDiagnostic = {
+          kind: "mixed_failure",
+          summary: `Mixed failure: ${annotationReasons.noRecalledIds} incident(s) had no recalled IDs, ${annotationReasons.recalledIdsNoMatch} had stale IDs.`,
+          recommendedActions: [
+            "Address both missing recall metadata and stale ID issues.",
+            "Inspect sessions without recalled IDs for memory_recall usage gaps.",
+            "Audit stale/superseded IDs in the remaining sessions.",
+          ],
+        };
+      }
+    }
+
     // Attach annotation results to the returned value
     result.annotated = annotated;
     result.annotationReasons = annotationReasons;
     if (annotationStatus !== undefined) result.annotationStatus = annotationStatus;
+    if (annotationDiagnostic) result.annotationDiagnostic = annotationDiagnostic;
 
     if (!opts.dryRun) {
       const lastSessionTs = getMaxMtime(filePaths);

package/cli/cmd-feedback.ts

@@ -11,8 +11,7 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, join } from "node:path";
-
-import type { ReinforcementContext } from "../backends/facts-db.js";
+import type { FactsDB, ReinforcementContext } from "../backends/facts-db.js";
 import { getCronModelConfig, getDefaultCronModel, getLLMModelPreference, isCompactVerbosity } from "../config.js";
 import { chatCompleteWithRetry } from "../services/chat.js";
 import { CostFeature } from "../services/cost-feature-labels.js";
@@ -22,18 +21,17 @@ import { getEffectivenessReport, runClosedLoopAnalysis } from "../services/feedb
 import { extractImplicitSignals, parseSessionTurns } from "../services/implicit-feedback-extract.js";
 import { getModeCostEstimates } from "../services/model-pricing.js";
 import {
-  ToolEffectivenessStore,
   computeToolEffectiveness,
   formatToolEffectivenessReport,
   generateMonthlyReport,
+  ToolEffectivenessStore,
 } from "../services/tool-effectiveness.js";
 import { analyzeTrajectoriesWithLLM, buildTrajectories, serializeTrajectory } from "../services/trajectory-tracker.js";
-import type { FactsDB } from "../backends/facts-db.js";
+import { cleanupEvictedVector } from "../services/vector-maintenance.js";
 import { loadPrompt } from "../utils/prompt-loader.js";
+import { createTransaction } from "../utils/sqlite-transaction.js";
 import { getSessionFilePathsSince } from "./cmd-extract.js";
 import type { HandlerContext } from "./handlers.js";
-import { cleanupEvictedVector } from "../services/vector-maintenance.js";
-import { createTransaction } from "../utils/sqlite-transaction.js";
 
 const IMPLICIT_FEEDBACK_LESSON_TAGS = ["implicit-feedback", "trajectory", "feedback"];
 
@@ -184,6 +182,16 @@ function buildImplicitFeedbackCleanupFilter(includeLegacy: boolean): string {
   return SQL_IMPLICIT_TRAJECTORY_LESSON_FILTER;
 }
 
+export type ImplicitFeedbackCollapseStatus = "no_candidates" | "no_changes" | "partial" | "collapsed";
+
+/** Operator-facing collapse outcome for `reflect-meta --collapse-implicit-feedback` (#1736). */
+export function implicitFeedbackCollapseStatus(scanned: number, collapsed: number): ImplicitFeedbackCollapseStatus {
+  if (scanned === 0) return "no_candidates";
+  if (collapsed === 0) return "no_changes";
+  if (collapsed < scanned) return "partial";
+  return "collapsed";
+}
+
 export function cleanupImplicitFeedbackDuplicates(
   factsDb: FactsDB,
   opts: {
@@ -1418,9 +1426,7 @@ function hasValidWorkflowTraces(dbPath: string): boolean {
             (tool): tool is string => typeof tool === "string" && tool.trim().length > 0,
           );
           if (nonEmptyTools.length > 0) return true;
-        } catch {
-          continue;
-        }
+        } catch {}
       }
       return false;
     } finally {