memory-lancedb-pro 1.0.25 → 1.0.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memory-lancedb-pro",
-  "version": "1.0.25",
+  "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;
+    }
+  }
+}