openclaw-hybrid-memory 2026.5.310 → 2026.6.10

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "openclaw-hybrid-memory",
   "kind": "memory",
-  "version": "2026.5.310",
+  "version": "2026.6.10",
   "contracts": {
     "tools": [
       "active_task_checkpoint",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-hybrid-memory",
-  "version": "2026.5.310",
+  "version": "2026.6.10",
   "type": "module",
   "description": "Give your OpenClaw agent lasting memory: structured facts, semantic search, auto-capture & recall, decay, optional credential vault. Part of Hybrid Memory v3.",
   "files": [
@@ -50,7 +50,7 @@
     "openclaw": ">=2026.5.0 <2027"
   },
   "dependencies": {
-    "@lancedb/lancedb": "^0.29.0",
+    "@lancedb/lancedb": "^0.30.0",
     "@types/node": "^25.2.3",
     "commander": "^13.1.0",
     "franc": "^6.2.0",

package/services/adaptive-catch-up-pacing.ts

@@ -0,0 +1,28 @@
+/**
+ * Adaptive catch-up pressure backoff: provider Retry-After is a hard floor and is not
+ * reduced by the normal adaptive max-delay cap (used only when no Retry-After hint).
+ */
+export function computeAdaptivePressureDelayMs(opts: {
+  currentDelayMs: number;
+  batchRetryAfterMs?: number;
+  maxAdaptiveDelayMs: number;
+  backoffMinDelayMs: number;
+}): number {
+  const retryAfterFloor = opts.batchRetryAfterMs ?? 0;
+  const retryAfterDelay = Math.max(retryAfterFloor, opts.currentDelayMs);
+  const scaledDelay = Math.ceil(retryAfterDelay * 1.5);
+  const computed = Math.max(opts.backoffMinDelayMs, scaledDelay, retryAfterFloor);
+  if (retryAfterFloor > 0) {
+    return computed;
+  }
+  return Math.min(opts.maxAdaptiveDelayMs, computed);
+}
+
+/** Cap inter-batch sleep so a configured time budget is not exceeded by pacing delay. */
+export function capDelayMsByDeadline(delayMs: number, deadlineMs: number | undefined, nowMs = Date.now()): number {
+  if (delayMs <= 0) return 0;
+  if (deadlineMs == null) return delayMs;
+  const remainingMs = deadlineMs - nowMs;
+  if (remainingMs <= 0) return 0;
+  return Math.min(delayMs, remainingMs);
+}

package/services/chat.ts

@@ -193,6 +193,13 @@ export function is429OrWrapped(err: Error): boolean {
   return false;
 }
 
+/** Returns true when the error is a ByteString serialization failure — direct or wrapped in LLMRetryError. */
+export function isByteStringOrWrapped(err: Error): boolean {
+  if (isByteStringSerializationError(err)) return true;
+  if (err instanceof LLMRetryError && isByteStringSerializationError(err.cause)) return true;
+  return false;
+}
+
 /**
  * Unified 5xx / internal server error detection helper.
  * Checks HTTP status code property first, then uses conservative message patterns.
@@ -347,6 +354,17 @@ function is400EmptyBodyGatewayError(err: unknown): boolean {
   return /\b400\b.*\bno body\b/i.test(err.message);
 }
 
+/**
+ * True when the error is a Node.js / browser-fetch ByteString serialization failure.
+ * Thrown by the HTTP layer when a header value contains a character with code point > 255
+ * (e.g. U+2026 HORIZONTAL ELLIPSIS in a copy-pasted API key, model name, or custom header).
+ * These errors are permanent — retrying the same request will always fail (#1776).
+ */
+export function isByteStringSerializationError(err: unknown): boolean {
+  if (!(err instanceof Error)) return false;
+  return /cannot convert argument to a bytestring/i.test(err.message);
+}
+
 /** Some Azure/Foundry deployments return 400 when chat params are not supported for the model (#1165). */
 function is400UnsupportedOperationError(err: unknown): boolean {
   if (!(err instanceof Error)) return false;
@@ -537,7 +555,8 @@ export async function chatComplete(opts: {
       is404Like(err) || // #303: model not found = wrong model name in config, not a bug
       is403Like(err) || // #394: country/region restriction = operator config issue, not a bug
       is401Like(err) || // #475: invalid API key = operator config issue, not a bug
-      isContextLengthError(err); // #488: input too long for model context window = wrong model choice, not a bug
+      isContextLengthError(err) || // #488: input too long for model context window = wrong model choice, not a bug
+      isByteStringSerializationError(err); // #1776: non-ASCII in HTTP header = config issue, not a bug
     if (!isTransient && !isConfigError) {
       capturePluginError(error, {
         subsystem: "chat",
@@ -649,6 +668,11 @@ export async function withLLMRetry<T>(
         );
         throw enrichLlmErrorMessage(lastError, opts?.llmContext);
       }
+      // Don't retry ByteString serialization errors — a non-ASCII character (e.g. U+2026 ELLIPSIS)
+      // in an HTTP header value (API key, model name, custom header) cannot be fixed by retrying (#1776).
+      if (isByteStringOrWrapped(lastError)) {
+        throw enrichLlmErrorMessage(lastError, opts?.llmContext);
+      }
       const isReasoningSequenceError = isResponsesReasoningSequenceError(lastError);
       // Azure/OpenAI Responses API intermittent malformed reasoning item sequence:
       // allow one retry, then fail fast so fallback model can run.
@@ -941,6 +965,7 @@ export async function chatCompleteWithRetryDetailed(opts: {
   const finalIsOOM = isOllamaOOM(finalError); // #387: OOM is expected when model too large for RAM
   const finalIs429 = is429OrWrapped(finalError); // #397
   const finalIsContextLength = isContextLengthError(finalError); // #488: input too long for model context window
+  const finalIsByteString = isByteStringOrWrapped(finalError); // #1776: non-ASCII in HTTP header = config issue
   const finalIsReasoningSequence = isResponsesReasoningSequenceError(finalError); // #1034
   /** Unwraps LLMRetryError so "Request was aborted" in the cause is detected (#935, #936). */
   const finalIsTransientLlm = isAbortOrTransientLlmError(finalError);
@@ -968,6 +993,7 @@ export async function chatCompleteWithRetryDetailed(opts: {
       !finalIs500 &&
       !finalIsOOM &&
       !finalIsContextLength && // #488: context window exceeded = config issue, not a bug
+      !finalIsByteString && // #1776: non-ASCII in HTTP header = config issue, not a bug
       !finalIsUnconfigured &&
       !finalIsTransientLlm &&
       !finalIs403 &&
@@ -996,6 +1022,13 @@ export async function chatCompleteWithRetryDetailed(opts: {
         "Consider using a model with a larger context window or reducing input size. " +
         "Run: openclaw hybrid-mem verify --test-llm",
     );
+  } else if (finalIsByteString) {
+    // #1776: ByteString serialization error (non-ASCII in HTTP header) — config issue, not a code bug
+    pendingWarnings?.add(
+      "⚠️ Memory plugin: LLM request contains non-ASCII characters in HTTP headers (API key, model name, or custom header). " +
+        "Check your provider configuration for invalid characters (e.g. copy-pasted ellipsis U+2026). " +
+        "Run: openclaw hybrid-mem verify --test-llm",
+    );
   } else if (finalIs500) {
     // #302: 500 server errors are transient — don't report to GlitchTip; request will be retried naturally
   } else if (finalIs404) {

package/services/cron-job-bash-harness.ts

@@ -144,18 +144,65 @@ export function buildHybridMemCronBashBody(
     '    return "$original_ec"',
     "  fi",
     "  HM_VALIDATED=1",
+    '  local signal_during_validate=""',
+    "  trap 'signal_during_validate=143' TERM INT",
+    "  trap 'signal_during_validate=129' HUP",
+    "  trap 'signal_during_validate=131' QUIT",
     "  set +e",
     '  echo "--- validate-cron-exit ---" | tee -a "$HM_LOG"',
-    '  openclaw hybrid-mem validate-cron-exit --exit-path "$HM_EXIT" --log-path "$HM_LOG" --required-steps "${HM_REQUIRED_STEPS[@]}" --allow-skip --json 2>&1 | tee -a "$HM_LOG"',
+    "  local validate_output",
+    '  validate_output="$(mktemp "${TMPDIR:-/tmp}/hm-validate-XXXXXX")"',
+    '  openclaw hybrid-mem validate-cron-exit --exit-path "$HM_EXIT" --log-path "$HM_LOG" --required-steps "${HM_REQUIRED_STEPS[@]}" --allow-skip --json 2>&1 | tee -a "$HM_LOG" "$validate_output"',
     '  local validation_ec="${PIPESTATUS[0]}"',
-    "  set -e",
+    '  local maintenance_status=""',
+    "  # Parse maintenanceStatus without jq to keep cron harness dependencies minimal/portable.",
+    '  maintenance_status="$(grep -Eo \'"maintenanceStatus"[[:space:]]*:[[:space:]]*"(success|skipped|partial|failed)"\' "$validate_output" | tail -n1 | sed -E \'s/.*"(success|skipped|partial|failed)"/\\1/\' || true)"',
+    '  rm -f "$validate_output"',
+    '  local final_ec="$validation_ec"',
+    "  # Preserve original non-zero (step/signal) failure code; validation is supplemental diagnostics.",
     '  if [ "$original_ec" -ne 0 ]; then',
-    '    return "$original_ec"',
+    '    if [ "$validation_ec" -ne 0 ] && [ "$validation_ec" -ne "$original_ec" ]; then',
+    '      echo "WARNING: validate-cron-exit failed with different exit code than original failure: validation_exit=${validation_ec} original_exit=${original_ec}" | tee -a "$HM_LOG"',
+    "    fi",
+    '    final_ec="$original_ec"',
+    "  fi",
+    '  if [ "$original_ec" -eq 0 ] && [ -n "$signal_during_validate" ]; then',
+    '    final_ec="$signal_during_validate"',
+    "  fi",
+    '  local final_label="FAILED"',
+    '  if [ -n "$maintenance_status" ]; then',
+    '    case "$maintenance_status" in',
+    '      success) final_label="SUCCESS" ;;',
+    '      skipped) final_label="SKIPPED" ;;',
+    '      partial) final_label="PARTIAL" ;;',
+    "    esac",
+    '  elif [ "$final_ec" -eq 0 ]; then',
+    '    final_label="SUCCESS"',
     "  fi",
-    '  return "$validation_ec"',
+    '  local ledger_status=""',
+    '  if [ -n "$maintenance_status" ]; then',
+    '    case "$maintenance_status" in',
+    '      success) ledger_status="ok" ;;',
+    '      failed) ledger_status="failed" ;;',
+    '      skipped) ledger_status="skipped" ;;',
+    '      partial) ledger_status="failed" ;;',
+    "    esac",
+    "  fi",
+    '  local status_suffix=""',
+    '  if [ -n "$ledger_status" ]; then',
+    '    status_suffix=" status=${ledger_status} reason=maintenance_${maintenance_status}"',
+    "  fi",
+    "  # HM_VALIDATED guard ensures this final validation row is written at most once per run.",
+    '  echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) validate-cron-exit exit=${validation_ec}${status_suffix}" >>"$HM_EXIT"',
+    '  echo "${final_label}: ${HM_JOB}" | tee -a "$HM_LOG"',
+    '  echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) ${HM_JOB} exit=${final_ec}" | tee -a "$HM_LOG"',
+    "  set -e",
+    '  return "$final_ec"',
     "}",
     "trap 'ec=$?; trap - EXIT; hm_validate \"$ec\"; exit $?' EXIT",
-    "trap 'trap - TERM INT; hm_validate 143; exit $?' TERM INT",
+    "trap 'trap - TERM INT HUP QUIT; hm_validate 143; exit $?' TERM INT",
+    "trap 'trap - TERM INT HUP QUIT; hm_validate 129; exit $?' HUP",
+    "trap 'trap - TERM INT HUP QUIT; hm_validate 131; exit $?' QUIT",
     "",
     ...lines,
   ].join("\n");

package/services/embeddings/shared.ts

@@ -10,6 +10,7 @@ import {
   is404Like,
   is429OrWrapped,
   is500OrWrapped,
+  isByteStringSerializationError,
   isContextLengthError,
 } from "../chat.js";
 import { capturePluginError } from "../error-reporter.js";
@@ -195,7 +196,8 @@ export function shouldSuppressEmbeddingError(err: unknown): boolean {
     is500OrWrapped(err) ||
     isOllamaCircuitBreakerOpen(err) ||
     isOllamaConnectionFailure(err) ||
-    isContextLengthError(err)
+    isContextLengthError(err) ||
+    isByteStringSerializationError(err)
   ) {
     return true;
   }
@@ -209,7 +211,8 @@ export function shouldSuppressEmbeddingError(err: unknown): boolean {
         is500OrWrapped(c) ||
         isOllamaCircuitBreakerOpen(c) ||
         isOllamaConnectionFailure(c) ||
-        isContextLengthError(c),
+        isContextLengthError(c) ||
+        isByteStringSerializationError(c),
     );
   }
   return false;

package/services/entity-enrichment-adaptive.ts

@@ -0,0 +1,245 @@
+/** Adaptive enrich-entities catch-up: budgets, summaries, and vectorless SLO repair hints. */
+
+export const VECTORLESS_SLO_TARGET_RATIO = 0.02;
+
+export type EntityEnrichmentStopReason = "completed" | "time_budget" | "provider_budget" | "exhausted";
+
+/** Issue #1791 suggested telemetry field names. */
+export type Issue1791AdaptiveTelemetry = {
+  mode: "adaptive-catchup";
+  processed: number;
+  enriched: number;
+  remaining: number;
+  durationSec: number;
+  avgSecPerFact: number;
+  provider429s: number;
+  timeouts: number;
+  batchSizeStart: number;
+  batchSizeEnd: number;
+  delayMsStart: number;
+  delayMsEnd: number;
+  concurrencyStart: number;
+  concurrencyEnd: number;
+  stopReason: EntityEnrichmentStopReason;
+  nextRecommendedLimit: number;
+  nextRecommendedTimeoutSec?: number;
+  estimatedRunsRemaining: number;
+  etaSeconds?: number;
+};
+
+export type EntityEnrichmentAdaptiveSummary = {
+  enabled: true;
+  durationMs: number;
+  avgSecondsPerFact: number;
+  processed: number;
+  remainingTotal: number;
+  rateLimitCount: number;
+  transientFailureCount: number;
+  timeoutFailureCount: number;
+  llmFailureCount: number;
+  startBatchSize: number;
+  endBatchSize: number;
+  startDelayMs: number;
+  endDelayMs: number;
+  startConcurrency: number;
+  endConcurrency: number;
+  stopReason: EntityEnrichmentStopReason;
+  timeBudgetSec?: number;
+  estimatedRunsRemaining: number;
+  etaSecondsAtCurrentLimit?: number;
+  nextRecommendedLimit: number;
+  nextRecommendedTimeoutSec?: number;
+};
+
+export type VectorlessSloRepairRecommendation = {
+  /** SLO ratio uses global vectorless counts (audit-health target is store-wide). */
+  sloScope: "global";
+  targetVectorlessRatio: number;
+  activeFacts: number;
+  vectorlessBefore: number;
+  vectorlessAfter: number;
+  /** When a run used --source, these reflect that filter only (not used for sloMetAfterRun). */
+  scopedSource?: string;
+  scopedVectorlessBefore?: number;
+  scopedVectorlessAfter?: number;
+  vectorlessRatioBefore: number;
+  vectorlessRatioAfter: number;
+  maxVectorlessAtTarget: number;
+  vectorlessToClearForSlo: number;
+  embeddedThisRun: number;
+  recommendedLimitNextRun: number;
+  recommendedBatchSizeNextRun: number;
+  estimatedRunsToReachSlo: number;
+  sloMetAfterRun: boolean;
+};
+
+export function sanitizeTimeBudgetSec(n: number | undefined): number | undefined {
+  if (n === undefined) return undefined;
+  const x = Math.floor(Number(n));
+  if (!Number.isFinite(x) || x < 1) return undefined;
+  return Math.min(86_400, x);
+}
+
+export function sanitizeMaxConcurrency(n: number | undefined, adaptiveCatchUp: boolean): number {
+  const x = Math.floor(Number(n ?? (adaptiveCatchUp ? 3 : 1)));
+  if (!Number.isFinite(x) || x < 1) return adaptiveCatchUp ? 3 : 1;
+  return Math.min(adaptiveCatchUp ? 16 : 1, x);
+}
+
+export function isLlmTimeoutLike(message: string): boolean {
+  const msg = message.toLowerCase();
+  return /timed out|llm request timeout|request was aborted/.test(msg);
+}
+
+/** Walk LLMRetryError `.cause` chains so wrapped timeouts still count toward pressure budgets. */
+export function errorIndicatesLlmTimeout(err: unknown): boolean {
+  let e: unknown = err;
+  while (e instanceof Error) {
+    if (isLlmTimeoutLike(e.message)) return true;
+    if (e.name === "LLMRetryError" && "cause" in e) {
+      e = (e as { cause: unknown }).cause;
+      continue;
+    }
+    break;
+  }
+  return false;
+}
+
+export function buildEntityEnrichmentAdaptiveSummary(input: {
+  startedAtMs: number;
+  processed: number;
+  remainingTotal: number;
+  limit: number;
+  mode: "bounded" | "all";
+  rateLimitCount: number;
+  transientFailureCount: number;
+  timeoutFailureCount: number;
+  llmFailureCount: number;
+  startBatchSize: number;
+  endBatchSize: number;
+  startDelayMs: number;
+  endDelayMs: number;
+  startConcurrency: number;
+  endConcurrency: number;
+  stopReason: EntityEnrichmentStopReason;
+  timeBudgetSec?: number;
+}): EntityEnrichmentAdaptiveSummary {
+  const durationMs = Math.max(0, Date.now() - input.startedAtMs);
+  const avgSecondsPerFact = input.processed > 0 ? Number((durationMs / 1000 / input.processed).toFixed(3)) : 0;
+  const estimatedRunsRemaining = input.mode === "all" ? 0 : Math.ceil(input.remainingTotal / Math.max(1, input.limit));
+  const factsPerRun = Math.max(1, input.processed);
+  const nextRecommendedLimit = Math.max(
+    input.limit,
+    Math.min(100_000, Math.ceil(input.remainingTotal / Math.max(1, estimatedRunsRemaining || 1))),
+  );
+  const etaSecondsAtCurrentLimit =
+    input.processed > 0 && input.remainingTotal > 0
+      ? Math.ceil((durationMs / 1000 / input.processed) * input.remainingTotal)
+      : undefined;
+  const nextRecommendedTimeoutSec =
+    input.timeoutFailureCount > 0
+      ? Math.min(600, Math.max(60, Math.ceil(Math.max(avgSecondsPerFact, 1) * 3)))
+      : undefined;
+
+  return {
+    enabled: true,
+    durationMs,
+    avgSecondsPerFact,
+    processed: input.processed,
+    remainingTotal: input.remainingTotal,
+    rateLimitCount: input.rateLimitCount,
+    transientFailureCount: input.transientFailureCount,
+    timeoutFailureCount: input.timeoutFailureCount,
+    llmFailureCount: input.llmFailureCount,
+    startBatchSize: input.startBatchSize,
+    endBatchSize: input.endBatchSize,
+    startDelayMs: input.startDelayMs,
+    endDelayMs: input.endDelayMs,
+    startConcurrency: input.startConcurrency,
+    endConcurrency: input.endConcurrency,
+    stopReason: input.stopReason,
+    timeBudgetSec: input.timeBudgetSec,
+    estimatedRunsRemaining,
+    etaSecondsAtCurrentLimit,
+    nextRecommendedLimit,
+    nextRecommendedTimeoutSec,
+  };
+}
+
+export function buildIssue1791AdaptiveTelemetry(
+  summary: EntityEnrichmentAdaptiveSummary,
+  factsEnriched: number,
+): Issue1791AdaptiveTelemetry {
+  return {
+    mode: "adaptive-catchup",
+    processed: summary.processed,
+    enriched: factsEnriched,
+    remaining: summary.remainingTotal,
+    durationSec: Number((summary.durationMs / 1000).toFixed(1)),
+    avgSecPerFact: summary.avgSecondsPerFact,
+    provider429s: summary.rateLimitCount,
+    timeouts: summary.timeoutFailureCount,
+    batchSizeStart: summary.startBatchSize,
+    batchSizeEnd: summary.endBatchSize,
+    delayMsStart: summary.startDelayMs,
+    delayMsEnd: summary.endDelayMs,
+    concurrencyStart: summary.startConcurrency,
+    concurrencyEnd: summary.endConcurrency,
+    stopReason: summary.stopReason,
+    nextRecommendedLimit: summary.nextRecommendedLimit,
+    nextRecommendedTimeoutSec: summary.nextRecommendedTimeoutSec,
+    estimatedRunsRemaining: summary.estimatedRunsRemaining,
+    etaSeconds: summary.etaSecondsAtCurrentLimit,
+  };
+}
+
+export function buildVectorlessSloRepairRecommendation(input: {
+  activeFacts: number;
+  vectorlessBefore: number;
+  vectorlessAfter: number;
+  embeddedThisRun: number;
+  runLimit: number;
+  effectiveBatchSize?: number;
+  scopedSource?: string;
+  scopedVectorlessBefore?: number;
+  scopedVectorlessAfter?: number;
+}): VectorlessSloRepairRecommendation {
+  const activeFacts = Math.max(0, input.activeFacts);
+  const vectorlessBefore = Math.max(0, input.vectorlessBefore);
+  const vectorlessAfter = Math.max(0, input.vectorlessAfter);
+  const vectorlessRatioBefore = activeFacts > 0 ? vectorlessBefore / activeFacts : 0;
+  const vectorlessRatioAfter = activeFacts > 0 ? vectorlessAfter / activeFacts : 0;
+  const maxVectorlessAtTarget = Math.floor(activeFacts * VECTORLESS_SLO_TARGET_RATIO);
+  const vectorlessToClearForSlo = Math.max(0, vectorlessAfter - maxVectorlessAtTarget);
+  const embeddedPerRun = Math.max(1, input.embeddedThisRun);
+  const recommendedLimitNextRun = Math.max(input.runLimit, embeddedPerRun);
+  const recommendedBatchSizeNextRun = Math.max(1, input.effectiveBatchSize ?? embeddedPerRun);
+  const estimatedRunsToReachSlo = Math.ceil(vectorlessToClearForSlo / embeddedPerRun);
+
+  return {
+    sloScope: "global",
+    targetVectorlessRatio: VECTORLESS_SLO_TARGET_RATIO,
+    activeFacts,
+    vectorlessBefore,
+    vectorlessAfter,
+    vectorlessRatioBefore: Number(vectorlessRatioBefore.toFixed(4)),
+    vectorlessRatioAfter: Number(vectorlessRatioAfter.toFixed(4)),
+    maxVectorlessAtTarget,
+    vectorlessToClearForSlo,
+    embeddedThisRun: input.embeddedThisRun,
+    recommendedLimitNextRun,
+    recommendedBatchSizeNextRun,
+    estimatedRunsToReachSlo,
+    sloMetAfterRun: vectorlessRatioAfter <= VECTORLESS_SLO_TARGET_RATIO,
+    scopedSource: input.scopedSource,
+    scopedVectorlessBefore: input.scopedVectorlessBefore,
+    scopedVectorlessAfter: input.scopedVectorlessAfter,
+  };
+}
+
+export function sanitizeProviderPressureBudget(n: number | undefined): number | undefined {
+  if (n === undefined) return undefined;
+  const x = Math.floor(Number(n));
+  if (!Number.isFinite(x) || x < 1) return undefined;
+  return Math.min(10_000, x);
+}