@joshuaswarren/openclaw-engram 8.3.75 → 8.3.76

package/dist/index.js

@@ -8805,6 +8805,18 @@ function clampGraphRecallExpandedEntries(entries, maxEntries = 64) {
     };
   }).filter((item) => item.path.length > 0 && item.namespace.length > 0).slice(0, limit);
 }
+var DEFAULT_TIER_MIGRATION_STATUS = {
+  updatedAt: (/* @__PURE__ */ new Date(0)).toISOString(),
+  lastCycle: null,
+  totals: {
+    cycles: 0,
+    scanned: 0,
+    migrated: 0,
+    promoted: 0,
+    demoted: 0,
+    errors: 0
+  }
+};
 var LastRecallStore = class {
   statePath;
   impressionsPath;
@@ -8870,6 +8882,70 @@ var LastRecallStore = class {
     }
   }
 };
+var TierMigrationStatusStore = class {
+  statePath;
+  state = structuredClone(DEFAULT_TIER_MIGRATION_STATUS);
+  constructor(memoryDir) {
+    this.statePath = path10.join(memoryDir, "state", "tier-migration-status.json");
+  }
+  async load() {
+    try {
+      const raw = await readFile8(this.statePath, "utf-8");
+      const parsed = JSON.parse(raw);
+      if (!parsed || typeof parsed !== "object") {
+        this.state = structuredClone(DEFAULT_TIER_MIGRATION_STATUS);
+        return;
+      }
+      const totals = parsed.totals && typeof parsed.totals === "object" ? parsed.totals : DEFAULT_TIER_MIGRATION_STATUS.totals;
+      this.state = {
+        updatedAt: typeof parsed.updatedAt === "string" && parsed.updatedAt.length > 0 ? parsed.updatedAt : DEFAULT_TIER_MIGRATION_STATUS.updatedAt,
+        lastCycle: parsed.lastCycle && typeof parsed.lastCycle === "object" ? parsed.lastCycle : null,
+        totals: {
+          cycles: typeof totals.cycles === "number" && Number.isFinite(totals.cycles) ? totals.cycles : 0,
+          scanned: typeof totals.scanned === "number" && Number.isFinite(totals.scanned) ? totals.scanned : 0,
+          migrated: typeof totals.migrated === "number" && Number.isFinite(totals.migrated) ? totals.migrated : 0,
+          promoted: typeof totals.promoted === "number" && Number.isFinite(totals.promoted) ? totals.promoted : 0,
+          demoted: typeof totals.demoted === "number" && Number.isFinite(totals.demoted) ? totals.demoted : 0,
+          errors: typeof totals.errors === "number" && Number.isFinite(totals.errors) ? totals.errors : 0
+        }
+      };
+    } catch {
+      this.state = structuredClone(DEFAULT_TIER_MIGRATION_STATUS);
+    }
+  }
+  get() {
+    return {
+      updatedAt: this.state.updatedAt,
+      lastCycle: this.state.lastCycle ? { ...this.state.lastCycle } : null,
+      totals: { ...this.state.totals }
+    };
+  }
+  async recordCycle(summary) {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const migratedDelta = summary.dryRun ? 0 : Math.max(0, summary.migrated);
+    const promotedDelta = summary.dryRun ? 0 : Math.max(0, summary.promoted);
+    const demotedDelta = summary.dryRun ? 0 : Math.max(0, summary.demoted);
+    const next = {
+      updatedAt: now,
+      lastCycle: { ...summary },
+      totals: {
+        cycles: this.state.totals.cycles + 1,
+        scanned: this.state.totals.scanned + Math.max(0, summary.scanned),
+        migrated: this.state.totals.migrated + migratedDelta,
+        promoted: this.state.totals.promoted + promotedDelta,
+        demoted: this.state.totals.demoted + demotedDelta,
+        errors: this.state.totals.errors + Math.max(0, summary.errorCount ?? 0)
+      }
+    };
+    this.state = next;
+    try {
+      await mkdir8(path10.dirname(this.statePath), { recursive: true });
+      await writeFile8(this.statePath, JSON.stringify(next, null, 2), "utf-8");
+    } catch (err) {
+      log.debug(`tier migration status write failed: ${err}`);
+    }
+  }
+};
 
 // src/session-observer-state.ts
 import path11 from "path";
@@ -13218,6 +13294,7 @@ var Orchestrator = class _Orchestrator {
   relevance;
   negatives;
   lastRecall;
+  tierMigrationStatus;
   embeddingFallback;
   conversationIndexDir;
   extraction;
@@ -13311,6 +13388,7 @@ var Orchestrator = class _Orchestrator {
     this.relevance = new RelevanceStore(config.memoryDir);
     this.negatives = new NegativeExampleStore(config.memoryDir);
     this.lastRecall = new LastRecallStore(config.memoryDir);
+    this.tierMigrationStatus = new TierMigrationStatusStore(config.memoryDir);
     this.sessionObserver = new SessionObserverState({
       memoryDir: config.memoryDir,
       debounceMs: config.sessionObserverDebounceMs ?? 12e4,
@@ -13455,6 +13533,7 @@ var Orchestrator = class _Orchestrator {
     await this.relevance.load();
     await this.negatives.load();
     await this.lastRecall.load();
+    await this.tierMigrationStatus.load();
     await this.sessionObserver.load();
     if (this.config.factDeduplicationEnabled) {
       const stateDir2 = path26.join(this.config.memoryDir, "state");
@@ -15047,13 +15126,69 @@ _Context: ${topQuestion.context}_`);
     this.requestQmdMaintenance();
     await this.runTierMigrationCycle(storage, "extraction");
   }
-  async runTierMigrationCycle(storage, trigger) {
-    if (!this.config.qmdTierMigrationEnabled) return;
-    if (trigger === "maintenance" && !this.config.qmdTierAutoBackfillEnabled) return;
-    if (this.tierMigrationInFlight) return;
-    const budget = this.compounding?.tierMigrationCycleBudget(trigger) ?? defaultTierMigrationCycleBudget(this.config, trigger);
+  async runTierMigrationCycle(storage, trigger, options) {
+    const dryRun = options?.dryRun === true;
+    const persistSkipped = options?.force === true || trigger === "manual";
+    if (!this.config.qmdTierMigrationEnabled && options?.force !== true) {
+      const skipped = {
+        trigger,
+        scanned: 0,
+        migrated: 0,
+        promoted: 0,
+        demoted: 0,
+        limit: 0,
+        dryRun,
+        skipped: "tier_migration_disabled"
+      };
+      if (persistSkipped) await this.tierMigrationStatus.recordCycle(skipped);
+      return skipped;
+    }
+    if (trigger === "maintenance" && !this.config.qmdTierAutoBackfillEnabled && options?.force !== true) {
+      const skipped = {
+        trigger,
+        scanned: 0,
+        migrated: 0,
+        promoted: 0,
+        demoted: 0,
+        limit: 0,
+        dryRun,
+        skipped: "maintenance_backfill_disabled"
+      };
+      if (persistSkipped) await this.tierMigrationStatus.recordCycle(skipped);
+      return skipped;
+    }
+    if (this.tierMigrationInFlight) {
+      const skipped = {
+        trigger,
+        scanned: 0,
+        migrated: 0,
+        promoted: 0,
+        demoted: 0,
+        limit: 0,
+        dryRun,
+        skipped: "migration_in_flight"
+      };
+      if (persistSkipped) await this.tierMigrationStatus.recordCycle(skipped);
+      return skipped;
+    }
+    const budgetTrigger = trigger === "manual" ? "maintenance" : trigger;
+    const budget = this.compounding?.tierMigrationCycleBudget(budgetTrigger) ?? defaultTierMigrationCycleBudget(this.config, budgetTrigger);
+    const limit = options?.limitOverride !== void 0 ? Math.max(0, Math.floor(options.limitOverride)) : budget.limit;
     const nowMs = Date.now();
-    if (nowMs - this.lastTierMigrationRunAtMs < budget.minIntervalMs) return;
+    if (options?.force !== true && nowMs - this.lastTierMigrationRunAtMs < budget.minIntervalMs) {
+      const skipped = {
+        trigger,
+        scanned: 0,
+        migrated: 0,
+        promoted: 0,
+        demoted: 0,
+        limit,
+        dryRun,
+        skipped: "min_interval"
+      };
+      if (persistSkipped) await this.tierMigrationStatus.recordCycle(skipped);
+      return skipped;
+    }
     const policy = {
       enabled: this.config.qmdTierMigrationEnabled,
       demotionMinAgeDays: this.config.qmdTierDemotionMinAgeDays,
@@ -15083,29 +15218,70 @@ _Context: ${topQuestion.context}_`);
         autoEmbed: this.config.qmdAutoEmbedEnabled
       });
       let migrated = 0;
+      let promoted = 0;
+      let demoted = 0;
       for (const candidate of candidates) {
-        if (migrated >= budget.limit) break;
+        if (migrated >= limit) break;
         const decision = decideTierTransition(candidate.memory, candidate.tier, policy, now);
         if (!decision.changed) continue;
-        const res = await migration.migrateMemory({
-          memory: candidate.memory,
-          fromTier: candidate.tier,
-          toTier: decision.nextTier,
-          reason: `${trigger}:${decision.reason}`
-        });
-        if (res.changed) migrated += 1;
+        if (!dryRun) {
+          const res = await migration.migrateMemory({
+            memory: candidate.memory,
+            fromTier: candidate.tier,
+            toTier: decision.nextTier,
+            reason: `${trigger}:${decision.reason}`
+          });
+          if (!res.changed) continue;
+        }
+        migrated += 1;
+        if (decision.nextTier === "cold") demoted += 1;
+        if (decision.nextTier === "hot") promoted += 1;
       }
-      this.lastTierMigrationRunAtMs = Date.now();
+      if (!dryRun) this.lastTierMigrationRunAtMs = Date.now();
       log.debug(
-        `tier migration cycle completed: trigger=${trigger} scanned=${candidates.length} migrated=${migrated} limit=${budget.limit}`
+        `tier migration cycle completed: trigger=${trigger} scanned=${candidates.length} migrated=${migrated} limit=${limit}${dryRun ? " dryRun=true" : ""}`
       );
+      const summary = {
+        trigger,
+        scanned: candidates.length,
+        migrated,
+        promoted,
+        demoted,
+        limit,
+        dryRun
+      };
+      const shouldPersistCycle = trigger === "manual" || migrated > 0;
+      if (shouldPersistCycle) await this.tierMigrationStatus.recordCycle(summary);
+      return summary;
     } catch (err) {
       this.lastTierMigrationRunAtMs = Date.now();
       log.warn(`tier migration cycle failed (${trigger}, fail-open): ${err}`);
+      const failed = {
+        trigger,
+        scanned: 0,
+        migrated: 0,
+        promoted: 0,
+        demoted: 0,
+        limit,
+        dryRun,
+        errorCount: 1
+      };
+      await this.tierMigrationStatus.recordCycle(failed);
+      return failed;
     } finally {
       this.tierMigrationInFlight = false;
     }
   }
+  async getTierMigrationStatus() {
+    return this.tierMigrationStatus.get();
+  }
+  async runTierMigrationNow(options) {
+    return this.runTierMigrationCycle(this.storage, "manual", {
+      dryRun: options?.dryRun === true,
+      limitOverride: options?.limit,
+      force: false
+    });
+  }
   maybeScheduleConsolidation(nonZeroExtraction) {
     if (this.config.consolidationRequireNonZeroExtraction && !nonZeroExtraction) return;
     if (this.nonZeroExtractionsSinceConsolidation < this.config.consolidateEveryN) return;
@@ -21523,6 +21699,15 @@ async function runGraphHealthCliCommand(options) {
     includeRepairGuidance: options.includeRepairGuidance
   });
 }
+async function runTierStatusCliCommand(orchestrator) {
+  return orchestrator.getTierMigrationStatus();
+}
+async function runTierMigrateCliCommand(orchestrator, options = {}) {
+  return orchestrator.runTierMigrationNow({
+    dryRun: options.dryRun === true,
+    limit: options.limit
+  });
+}
 function incrementCounter(target, key) {
   const normalized = key && key.length > 0 ? key : "unknown";
   target[normalized] = (target[normalized] ?? 0) + 1;
@@ -22226,6 +22411,22 @@ function registerCli(api, orchestrator) {
         console.log(JSON.stringify(report, null, 2));
         console.log("OK");
       });
+      cmd.command("tier-status").description("Show tier migration telemetry and last-cycle summary").action(async () => {
+        const status = await runTierStatusCliCommand(orchestrator);
+        console.log(JSON.stringify(status, null, 2));
+        console.log("OK");
+      });
+      cmd.command("tier-migrate").description("Run one tier migration pass (dry-run by default)").option("--dry-run", "Evaluate and report moves without writing").option("--write", "Apply migration writes (default: dry-run)").option("--limit <n>", "Override migration move limit for this run").action(async (...args) => {
+        const options = args[0] ?? {};
+        const limitRaw = parseInt(String(options.limit ?? ""), 10);
+        const explicitDryRun = options.dryRun === true;
+        const summary = await runTierMigrateCliCommand(orchestrator, {
+          dryRun: explicitDryRun || options.write !== true,
+          limit: Number.isFinite(limitRaw) ? Math.max(0, limitRaw) : void 0
+        });
+        console.log(JSON.stringify(summary, null, 2));
+        console.log("OK");
+      });
       cmd.command("action-audit").description("Show namespace-aware memory action policy outcomes").option("--namespace <name>", "Filter to a single namespace").option("--limit <n>", "Max events to read per namespace", "200").action(async (...args) => {
         const options = args[0] ?? {};
         const limitRaw = parseInt(String(options.limit ?? "200"), 10);