memory-lancedb-pro 1.0.24 → 1.0.26

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "memory-lancedb-pro",
   "name": "Memory (LanceDB Pro)",
   "description": "Enhanced LanceDB-backed long-term memory with hybrid retrieval, multi-scope isolation, long-context chunking, and management CLI",
-  "version": "1.0.23",
+  "version": "1.0.26",
   "kind": "memory",
   "configSchema": {
     "type": "object",
@@ -18,8 +18,18 @@
           },
           "apiKey": {
             "oneOf": [
-              { "type": "string" },
-              { "type": "array", "items": { "type": "string" }, "minItems": 1 }
+              {
+                "type": "string",
+                "minLength": 1
+              },
+              {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "minItems": 1
+              }
             ],
             "description": "Single API key or array of keys for round-robin rotation"
           },
@@ -189,6 +199,20 @@
             "maximum": 365,
             "default": 60,
             "description": "Time decay half-life in days. Old entries lose score gradually. Floor at 0.5x. Set 0 to disable."
+          },
+          "reinforcementFactor": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 2,
+            "default": 0.5,
+            "description": "Access reinforcement factor for time decay. Frequently recalled memories decay slower. 0 to disable."
+          },
+          "maxHalfLifeMultiplier": {
+            "type": "number",
+            "minimum": 1,
+            "maximum": 10,
+            "default": 3,
+            "description": "Maximum half-life multiplier from access reinforcement. Prevents frequently accessed memories from becoming immortal."
           }
         }
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memory-lancedb-pro",
-  "version": "1.0.24",
+  "version": "1.0.26",
   "description": "OpenClaw enhanced LanceDB memory plugin with hybrid retrieval (Vector + BM25), cross-encoder rerank, multi-scope isolation, long-context chunking, and management CLI",
   "type": "module",
   "main": "index.ts",

package/src/access-tracker.ts

@@ -0,0 +1,330 @@
+/**
+ * Access Tracker
+ *
+ * Tracks memory access patterns to support reinforcement-based decay.
+ * Frequently accessed memories decay more slowly (longer effective half-life).
+ *
+ * Key exports:
+ * - parseAccessMetadata   — extract accessCount/lastAccessedAt from metadata JSON
+ * - buildUpdatedMetadata  — merge access fields into existing metadata JSON
+ * - computeEffectiveHalfLife — compute reinforced half-life from access history
+ * - AccessTracker         — debounced write-back tracker for batch metadata updates
+ */
+
+import type { MemoryStore } from "./store.js";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface AccessMetadata {
+  readonly accessCount: number;
+  readonly lastAccessedAt: number;
+}
+
+export interface AccessTrackerOptions {
+  readonly store: MemoryStore;
+  readonly logger: {
+    warn: (...args: unknown[]) => void;
+    info?: (...args: unknown[]) => void;
+  };
+  readonly debounceMs?: number;
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const MIN_ACCESS_COUNT = 0;
+const MAX_ACCESS_COUNT = 10_000;
+
+/** Access count itself decays with a 30-day half-life */
+const ACCESS_DECAY_HALF_LIFE_DAYS = 30;
+
+// ============================================================================
+// Utility
+// ============================================================================
+
+function clampAccessCount(value: number): number {
+  if (!Number.isFinite(value)) return MIN_ACCESS_COUNT;
+  return Math.min(
+    MAX_ACCESS_COUNT,
+    Math.max(MIN_ACCESS_COUNT, Math.floor(value)),
+  );
+}
+
+// ============================================================================
+// Metadata Parsing
+// ============================================================================
+
+/**
+ * Parse access-related fields from a metadata JSON string.
+ *
+ * Handles: undefined, empty string, malformed JSON, negative numbers,
+ * numbers exceeding 10000. Always returns a valid AccessMetadata.
+ */
+export function parseAccessMetadata(
+  metadata: string | undefined,
+): AccessMetadata {
+  if (metadata === undefined || metadata === "") {
+    return { accessCount: 0, lastAccessedAt: 0 };
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(metadata);
+  } catch {
+    return { accessCount: 0, lastAccessedAt: 0 };
+  }
+
+  if (typeof parsed !== "object" || parsed === null) {
+    return { accessCount: 0, lastAccessedAt: 0 };
+  }
+
+  const obj = parsed as Record<string, unknown>;
+
+  const rawCount = typeof obj.accessCount === "number" ? obj.accessCount : 0;
+  const rawLastAccessed =
+    typeof obj.lastAccessedAt === "number" ? obj.lastAccessedAt : 0;
+
+  return {
+    accessCount: clampAccessCount(rawCount),
+    lastAccessedAt:
+      Number.isFinite(rawLastAccessed) && rawLastAccessed >= 0
+        ? rawLastAccessed
+        : 0,
+  };
+}
+
+// ============================================================================
+// Metadata Building
+// ============================================================================
+
+/**
+ * Merge an access-count increment into existing metadata JSON.
+ *
+ * Preserves ALL existing fields in the metadata object — only overwrites
+ * `accessCount` and `lastAccessedAt`. Returns a new JSON string.
+ */
+export function buildUpdatedMetadata(
+  existingMetadata: string | undefined,
+  accessDelta: number,
+): string {
+  let existing: Record<string, unknown> = {};
+
+  if (existingMetadata !== undefined && existingMetadata !== "") {
+    try {
+      const parsed = JSON.parse(existingMetadata);
+      if (typeof parsed === "object" && parsed !== null) {
+        existing = { ...parsed };
+      }
+    } catch {
+      // malformed JSON — start fresh but preserve nothing
+    }
+  }
+
+  const prev = parseAccessMetadata(existingMetadata);
+  const newCount = clampAccessCount(prev.accessCount + accessDelta);
+
+  return JSON.stringify({
+    ...existing,
+    accessCount: newCount,
+    lastAccessedAt: Date.now(),
+  });
+}
+
+// ============================================================================
+// Effective Half-Life Computation
+// ============================================================================
+
+/**
+ * Compute the effective half-life for a memory based on its access history.
+ *
+ * The access count itself decays over time (30-day half-life for access
+ * freshness), so stale accesses contribute less reinforcement. The extension
+ * uses a logarithmic curve (`Math.log1p`) to provide diminishing returns.
+ *
+ * @param baseHalfLife        - Base half-life in days (e.g. 30)
+ * @param accessCount         - Raw number of times the memory was accessed
+ * @param lastAccessedAt      - Timestamp (ms) of last access
+ * @param reinforcementFactor - Scaling factor for reinforcement (0 = disabled)
+ * @param maxMultiplier       - Hard cap: result <= baseHalfLife * maxMultiplier
+ * @returns Effective half-life in days
+ */
+export function computeEffectiveHalfLife(
+  baseHalfLife: number,
+  accessCount: number,
+  lastAccessedAt: number,
+  reinforcementFactor: number,
+  maxMultiplier: number,
+): number {
+  // Short-circuit: no reinforcement or no accesses
+  if (reinforcementFactor === 0 || accessCount <= 0) {
+    return baseHalfLife;
+  }
+
+  const now = Date.now();
+  const daysSinceLastAccess = Math.max(
+    0,
+    (now - lastAccessedAt) / (1000 * 60 * 60 * 24),
+  );
+
+  // Access freshness decays exponentially with 30-day half-life
+  const accessFreshness = Math.exp(
+    -daysSinceLastAccess * (Math.LN2 / ACCESS_DECAY_HALF_LIFE_DAYS),
+  );
+
+  // Effective access count after freshness decay
+  const effectiveAccessCount = accessCount * accessFreshness;
+
+  // Logarithmic extension for diminishing returns
+  const extension =
+    baseHalfLife * reinforcementFactor * Math.log1p(effectiveAccessCount);
+
+  const result = baseHalfLife + extension;
+
+  // Hard cap
+  const cap = baseHalfLife * maxMultiplier;
+  return Math.min(result, cap);
+}
+
+// ============================================================================
+// AccessTracker Class
+// ============================================================================
+
+/**
+ * Debounced write-back tracker for memory access events.
+ *
+ * `recordAccess()` is synchronous (Map update only, no I/O). Pending deltas
+ * accumulate until `flush()` is called (or by a future scheduled callback).
+ * On flush, each pending entry is read via `store.getById()`, its metadata
+ * is merged with the accumulated access delta, and written back via
+ * `store.update()`.
+ */
+export class AccessTracker {
+  private readonly pending: Map<string, number> = new Map();
+  private debounceTimer: ReturnType<typeof setTimeout> | null = null;
+  private flushPromise: Promise<void> | null = null;
+  private readonly debounceMs: number;
+  private readonly store: MemoryStore;
+  private readonly logger: {
+    warn: (...args: unknown[]) => void;
+    info?: (...args: unknown[]) => void;
+  };
+
+  constructor(options: AccessTrackerOptions) {
+    this.store = options.store;
+    this.logger = options.logger;
+    this.debounceMs = options.debounceMs ?? 5_000;
+  }
+
+  /**
+   * Record one access for each of the given memory IDs.
+   * Synchronous — only updates the in-memory pending map.
+   */
+  recordAccess(ids: readonly string[]): void {
+    for (const id of ids) {
+      const current = this.pending.get(id) ?? 0;
+      this.pending.set(id, current + 1);
+    }
+
+    // Reset debounce timer
+    this.resetTimer();
+  }
+
+  /**
+   * Return a snapshot of all pending (id -> delta) entries.
+   */
+  getPendingUpdates(): Map<string, number> {
+    return new Map(this.pending);
+  }
+
+  /**
+   * Flush pending access deltas to the store.
+   *
+   * If a flush is already in progress, awaits the current flush to complete.
+   * If new pending data accumulated during the in-flight flush, a follow-up
+   * flush is automatically triggered.
+   */
+  async flush(): Promise<void> {
+    this.clearTimer();
+
+    // If a flush is in progress, wait for it to finish
+    if (this.flushPromise) {
+      await this.flushPromise;
+      // After the in-flight flush completes, check if new data accumulated
+      if (this.pending.size > 0) {
+        return this.flush();
+      }
+      return;
+    }
+
+    if (this.pending.size === 0) return;
+
+    this.flushPromise = this.doFlush();
+    try {
+      await this.flushPromise;
+    } finally {
+      this.flushPromise = null;
+    }
+
+    // If new data accumulated during flush, schedule a follow-up
+    if (this.pending.size > 0) {
+      this.resetTimer();
+    }
+  }
+
+  /**
+   * Tear down the tracker — cancel timers and clear pending state.
+   */
+  destroy(): void {
+    this.clearTimer();
+    if (this.pending.size > 0) {
+      this.logger.warn(
+        `access-tracker: destroying with ${this.pending.size} pending writes`,
+      );
+    }
+    this.pending.clear();
+  }
+
+  // --------------------------------------------------------------------------
+  // Internal helpers
+  // --------------------------------------------------------------------------
+
+  private async doFlush(): Promise<void> {
+    const batch = new Map(this.pending);
+    this.pending.clear();
+
+    for (const [id, delta] of batch) {
+      try {
+        const current = await this.store.getById(id);
+        if (!current) continue;
+
+        const updatedMeta = buildUpdatedMetadata(current.metadata, delta);
+        await this.store.update(id, { metadata: updatedMeta });
+      } catch (err) {
+        // Requeue failed delta for retry on next flush
+        const existing = this.pending.get(id) ?? 0;
+        this.pending.set(id, existing + delta);
+        this.logger.warn(
+          `access-tracker: write-back failed for ${id.slice(0, 8)}:`,
+          err,
+        );
+      }
+    }
+  }
+
+  private resetTimer(): void {
+    this.clearTimer();
+    this.debounceTimer = setTimeout(() => {
+      void this.flush();
+    }, this.debounceMs);
+  }
+
+  private clearTimer(): void {
+    if (this.debounceTimer !== null) {
+      clearTimeout(this.debounceTimer);
+      this.debounceTimer = null;
+    }
+  }
+}

package/src/embedder.ts

@@ -208,14 +208,28 @@ export class Embedder {
     return client;
   }
 
-  /** Check whether an error is a rate-limit / quota-exceeded error. */
+  /** Check whether an error is a rate-limit / quota-exceeded / overload error. */
   private isRateLimitError(error: unknown): boolean {
-    // OpenAI SDK typed error
-    if (error && typeof error === "object" && "status" in error && (error as any).status === 429) {
-      return true;
+    if (!error || typeof error !== "object") return false;
+
+    const err = error as Record<string, any>;
+
+    // HTTP status: 429 (rate limit) or 503 (service overload)
+    if (err.status === 429 || err.status === 503) return true;
+
+    // OpenAI SDK structured error code
+    if (err.code === "rate_limit_exceeded" || err.code === "insufficient_quota") return true;
+
+    // Nested error object (some providers)
+    const nested = err.error;
+    if (nested && typeof nested === "object") {
+      if (nested.type === "rate_limit_exceeded" || nested.type === "insufficient_quota") return true;
+      if (nested.code === "rate_limit_exceeded" || nested.code === "insufficient_quota") return true;
     }
+
+    // Fallback: message text matching
     const msg = error instanceof Error ? error.message : String(error);
-    return /rate.limit|quota|too many requests|insufficient.*credit|429/i.test(msg);
+    return /rate.limit|quota|too many requests|insufficient.*credit|429|503.*overload/i.test(msg);
   }
 
   /**
@@ -231,19 +245,27 @@ export class Embedder {
       try {
         return await client.embeddings.create(payload);
       } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+
         if (this.isRateLimitError(error) && attempt < maxAttempts - 1) {
           console.log(
-            `[memory-lancedb-pro] API key ${attempt + 1}/${maxAttempts} hit rate limit, rotating to next key...`
+            `[memory-lancedb-pro] Attempt ${attempt + 1}/${maxAttempts} hit rate limit, rotating to next key...`
           );
-          lastError = error instanceof Error ? error : new Error(String(error));
           continue;
         }
-        // Non-rate-limit error or last attempt — let caller handle
-        throw error;
+
+        // Non-rate-limit error → don't retry, let caller handle (e.g. chunking)
+        if (!this.isRateLimitError(error)) {
+          throw error;
+        }
       }
     }
 
-    throw lastError || new Error("All API keys exhausted (rate limited)");
+    // All keys exhausted with rate-limit errors
+    throw new Error(
+      `All ${maxAttempts} API keys exhausted (rate limited). Last error: ${lastError?.message || "unknown"}`,
+      { cause: lastError }
+    );
   }
 
   /** Number of API keys in the rotation pool. */