@joshuaswarren/openclaw-engram 8.3.6 → 8.3.8

package/dist/index.js

@@ -312,6 +312,16 @@ function parseConfig(raw) {
     factArchivalMaxImportance: typeof cfg.factArchivalMaxImportance === "number" ? cfg.factArchivalMaxImportance : 0.3,
     factArchivalMaxAccessCount: typeof cfg.factArchivalMaxAccessCount === "number" ? cfg.factArchivalMaxAccessCount : 2,
     factArchivalProtectedCategories: Array.isArray(cfg.factArchivalProtectedCategories) ? cfg.factArchivalProtectedCategories.filter((c) => typeof c === "string") : ["commitment", "preference", "decision", "principle"],
+    // v8.3 lifecycle policy engine (default off)
+    lifecyclePolicyEnabled: cfg.lifecyclePolicyEnabled === true,
+    lifecycleFilterStaleEnabled: cfg.lifecycleFilterStaleEnabled === true,
+    lifecyclePromoteHeatThreshold: typeof cfg.lifecyclePromoteHeatThreshold === "number" ? Math.min(1, Math.max(0, cfg.lifecyclePromoteHeatThreshold)) : 0.55,
+    lifecycleStaleDecayThreshold: typeof cfg.lifecycleStaleDecayThreshold === "number" ? Math.min(1, Math.max(0, cfg.lifecycleStaleDecayThreshold)) : 0.65,
+    lifecycleArchiveDecayThreshold: typeof cfg.lifecycleArchiveDecayThreshold === "number" ? Math.min(1, Math.max(0, cfg.lifecycleArchiveDecayThreshold)) : 0.85,
+    lifecycleProtectedCategories: Array.isArray(cfg.lifecycleProtectedCategories) ? cfg.lifecycleProtectedCategories.filter(
+      (c) => typeof c === "string" && VALID_MEMORY_CATEGORIES.has(c)
+    ) : ["decision", "principle", "commitment", "preference"],
+    lifecycleMetricsEnabled: typeof cfg.lifecycleMetricsEnabled === "boolean" ? cfg.lifecycleMetricsEnabled : cfg.lifecyclePolicyEnabled === true,
     // v8.0 phase 1
     recallPlannerEnabled: cfg.recallPlannerEnabled !== false,
     recallPlannerMaxQmdResultsMinimal: typeof cfg.recallPlannerMaxQmdResultsMinimal === "number" ? cfg.recallPlannerMaxQmdResultsMinimal : 4,
@@ -4989,6 +4999,37 @@ ${sanitized.text}
     log.debug(`updated memory ${id}`);
     return true;
   }
+  /**
+   * Update frontmatter fields without changing memory content.
+   * Returns false when the memory is not found.
+   */
+  async writeMemoryFrontmatter(memory, patch) {
+    const beforeStatus = memory.frontmatter.status ?? "active";
+    const updated = {
+      ...memory.frontmatter,
+      ...patch
+    };
+    const afterStatus = updated.status ?? "active";
+    const fileContent = `${serializeFrontmatter(updated)}
+
+${memory.content}
+`;
+    await writeFile2(memory.path, fileContent, "utf-8");
+    if (beforeStatus !== afterStatus) {
+      this.bumpMemoryStatusVersion();
+    }
+    return true;
+  }
+  /**
+   * Update frontmatter by memory ID.
+   * Prefer writeMemoryFrontmatter(memory, patch) in batch loops to avoid full-corpus rescans.
+   */
+  async updateMemoryFrontmatter(id, patch) {
+    const memories = await this.readAllMemories();
+    const memory = memories.find((m) => m.frontmatter.id === id);
+    if (!memory) return false;
+    return this.writeMemoryFrontmatter(memory, patch);
+  }
   /** Remove memories past their TTL expiresAt date */
   async cleanExpiredTTL() {
     const memories = await this.readAllMemories();
@@ -5325,8 +5366,8 @@ ${reflection}
    */
   static scoreEntity(entity, now) {
     const updated = entity.updated ? new Date(entity.updated).getTime() : 0;
-    const daysSince = Math.max(0, (now.getTime() - updated) / (1e3 * 60 * 60 * 24));
-    const recency = 1 / (1 + daysSince / 7);
+    const daysSince2 = Math.max(0, (now.getTime() - updated) / (1e3 * 60 * 60 * 24));
+    const recency = 1 / (1 + daysSince2 / 7);
     const frequency = Math.min(entity.facts.length / 20, 1);
     const activityScore = Math.min(entity.activity.length / 10, 1);
     const TYPE_PRIORITY = {
@@ -8752,6 +8793,167 @@ var TmtBuilder = class {
   }
 };
 
+// src/lifecycle.ts
+var DEFAULT_POLICY = {
+  promoteHeatThreshold: 0.55,
+  staleDecayThreshold: 0.65,
+  archiveDecayThreshold: 0.85,
+  protectedCategories: ["decision", "principle", "commitment", "preference"]
+};
+function clamp01(value) {
+  if (!Number.isFinite(value)) return 0;
+  if (value < 0) return 0;
+  if (value > 1) return 1;
+  return value;
+}
+function parseIsoMs(value) {
+  if (!value) return null;
+  const ms = Date.parse(value);
+  return Number.isFinite(ms) ? ms : null;
+}
+function daysSince(value, nowMs) {
+  const ts = parseIsoMs(value);
+  if (ts === null) return 365;
+  return Math.max(0, (nowMs - ts) / 864e5);
+}
+function confidenceTierWeight(frontmatter) {
+  switch (frontmatter.confidenceTier) {
+    case "explicit":
+      return 1;
+    case "implied":
+      return 0.8;
+    case "inferred":
+      return 0.6;
+    case "speculative":
+      return 0.35;
+    default:
+      return clamp01(frontmatter.confidence ?? 0.5);
+  }
+}
+function accessWeight(accessCount) {
+  const raw = accessCount ?? 0;
+  if (raw <= 0) return 0;
+  return clamp01(Math.log1p(raw) / Math.log1p(20));
+}
+function recencyWeight(frontmatter, nowMs) {
+  const lastTouch = frontmatter.lastAccessed ?? frontmatter.updated ?? frontmatter.created;
+  const ageDays = daysSince(lastTouch, nowMs);
+  return clamp01(1 - ageDays / 90);
+}
+function feedbackWeight(signals) {
+  const raw = signals?.feedbackScore ?? 0;
+  return clamp01((raw + 1) / 2);
+}
+function isProtectedMemory(frontmatter, policy) {
+  return frontmatter.policyClass === "protected" || policy.protectedCategories.includes(frontmatter.category);
+}
+function resolveLifecycleState(frontmatter) {
+  if (frontmatter.status === "archived") return "archived";
+  return frontmatter.lifecycleState ?? "candidate";
+}
+function computeHeat(memory, now, signals) {
+  const frontmatter = memory.frontmatter;
+  if (frontmatter.status === "archived") return 0;
+  const nowMs = now.getTime();
+  const confidence = confidenceTierWeight(frontmatter);
+  const access3 = accessWeight(frontmatter.accessCount);
+  const recency = recencyWeight(frontmatter, nowMs);
+  const importance = clamp01(frontmatter.importance?.score ?? 0.5);
+  const feedback = feedbackWeight(signals);
+  const disputedPenalty = frontmatter.verificationState === "disputed" ? 0.2 : 0;
+  const score = confidence * 0.25 + access3 * 0.3 + recency * 0.2 + importance * 0.15 + feedback * 0.1 - disputedPenalty;
+  return clamp01(score);
+}
+function computeDecay(memory, now, signals) {
+  const frontmatter = memory.frontmatter;
+  if (frontmatter.status === "archived") return 1;
+  const nowMs = now.getTime();
+  const ageDays = daysSince(frontmatter.updated ?? frontmatter.created, nowMs);
+  const staleAccessDays = daysSince(frontmatter.lastAccessed, nowMs);
+  const ageRisk = clamp01(ageDays / 180);
+  const staleAccessRisk = clamp01(staleAccessDays / 120);
+  const confidenceRisk = 1 - confidenceTierWeight(frontmatter);
+  const feedbackRisk = clamp01(((signals?.feedbackScore ?? 0) * -1 + 1) / 2);
+  const heat = computeHeat(memory, now, signals);
+  const score = ageRisk * 0.3 + staleAccessRisk * 0.25 + confidenceRisk * 0.2 + feedbackRisk * 0.1 + (1 - heat) * 0.15;
+  return clamp01(score);
+}
+function toTerminalDisputedState(currentState) {
+  if (currentState === "archived") return "archived";
+  return "stale";
+}
+function isActiveEligible(verificationState) {
+  return verificationState === "user_confirmed" || verificationState === "system_inferred";
+}
+function decideLifecycleTransition(memory, policy, now, signals) {
+  const mergedPolicy = { ...DEFAULT_POLICY, ...policy };
+  const frontmatter = memory.frontmatter;
+  const currentState = resolveLifecycleState(frontmatter);
+  const heatScore = computeHeat(memory, now, signals);
+  const decayScore = computeDecay(memory, now, signals);
+  const protectedMemory = isProtectedMemory(frontmatter, mergedPolicy);
+  if (currentState === "archived") {
+    return {
+      currentState,
+      nextState: "archived",
+      heatScore,
+      decayScore,
+      changed: false,
+      reason: "archived_is_terminal"
+    };
+  }
+  if (frontmatter.verificationState === "disputed") {
+    const nextState = toTerminalDisputedState(currentState);
+    return {
+      currentState,
+      nextState,
+      heatScore,
+      decayScore,
+      changed: nextState !== currentState,
+      reason: "disputed_memories_do_not_promote_to_active"
+    };
+  }
+  if (decayScore >= mergedPolicy.archiveDecayThreshold && !protectedMemory) {
+    return {
+      currentState,
+      nextState: "archived",
+      heatScore,
+      decayScore,
+      changed: true,
+      reason: "decay_exceeded_archive_threshold"
+    };
+  }
+  if (decayScore >= mergedPolicy.staleDecayThreshold) {
+    return {
+      currentState,
+      nextState: "stale",
+      heatScore,
+      decayScore,
+      changed: currentState !== "stale",
+      reason: "decay_exceeded_stale_threshold"
+    };
+  }
+  if (heatScore >= mergedPolicy.promoteHeatThreshold) {
+    const nextState = isActiveEligible(frontmatter.verificationState) ? "active" : "validated";
+    return {
+      currentState,
+      nextState,
+      heatScore,
+      decayScore,
+      changed: currentState !== nextState,
+      reason: "heat_exceeded_promote_threshold"
+    };
+  }
+  return {
+    currentState,
+    nextState: currentState,
+    heatScore,
+    decayScore,
+    changed: false,
+    reason: "no_transition"
+  };
+}
+
 // src/temporal-index.ts
 import * as fs2 from "fs";
 import * as path15 from "path";
@@ -9735,6 +9937,42 @@ function filterRecallCandidates(candidates, options) {
   const scopedByNamespace = options.namespacesEnabled ? candidates.filter((r) => options.recallNamespaces.includes(options.resolveNamespace(r.path))) : candidates;
   return scopedByNamespace.filter((r) => !isArtifactMemoryPath(r.path)).slice(0, Math.max(0, options.limit));
 }
+function hasLifecycleMetadata(frontmatter) {
+  return frontmatter.lifecycleState !== void 0 || frontmatter.verificationState !== void 0 || frontmatter.policyClass !== void 0 || frontmatter.lastValidatedAt !== void 0 || frontmatter.decayScore !== void 0 || frontmatter.heatScore !== void 0;
+}
+function shouldFilterLifecycleRecallCandidate(frontmatter, options) {
+  if (!options.lifecyclePolicyEnabled || !options.lifecycleFilterStaleEnabled) return false;
+  if (!hasLifecycleMetadata(frontmatter)) return false;
+  const lifecycleState = resolveLifecycleState(frontmatter);
+  return lifecycleState === "stale" || lifecycleState === "archived";
+}
+function lifecycleRecallScoreAdjustment(frontmatter, options) {
+  if (!options.lifecyclePolicyEnabled) return 0;
+  if (!hasLifecycleMetadata(frontmatter)) return 0;
+  let delta = 0;
+  const lifecycleState = resolveLifecycleState(frontmatter);
+  switch (lifecycleState) {
+    case "active":
+      delta += 0.05;
+      break;
+    case "validated":
+      delta += 0.03;
+      break;
+    case "candidate":
+      delta -= 0.01;
+      break;
+    case "stale":
+      delta -= 0.06;
+      break;
+    case "archived":
+      delta -= 0.08;
+      break;
+  }
+  if (frontmatter.verificationState === "disputed") {
+    delta -= 0.12;
+  }
+  return delta;
+}
 function computeArtifactRecallLimit(recallMode, recallResultLimit, verbatimArtifactsMaxRecall) {
   if (recallMode === "no_recall") return 0;
   if (Math.max(0, recallResultLimit) === 0) return 0;
@@ -11777,6 +12015,14 @@ _Context: ${topQuestion.context}_`);
         }
       }
     }
+    if (this.config.lifecyclePolicyEnabled) {
+      try {
+        const lifecycleCorpus = await this.storage.readAllMemories();
+        await this.runLifecyclePolicyPass(lifecycleCorpus);
+      } catch (err) {
+        log.warn(`lifecycle policy pass failed (ignored): ${err}`);
+      }
+    }
     if (this.config.factArchivalEnabled) {
       const archived = await this.runFactArchival(allMemories);
       if (archived > 0) {
@@ -11838,6 +12084,76 @@ ${texts.map((t, i) => `[${i + 1}] ${t}`).join("\n\n")}`;
     log.info("consolidation complete");
     return { memoriesProcessed: allMemories.length, merged, invalidated };
   }
+  async runLifecyclePolicyPass(allMemories) {
+    const now = /* @__PURE__ */ new Date();
+    const nowIso = now.toISOString();
+    const countsByState = {
+      candidate: 0,
+      validated: 0,
+      active: 0,
+      stale: 0,
+      archived: 0
+    };
+    const transitionCounts = {};
+    let updatedCount = 0;
+    let disputedCount = 0;
+    let evaluatedCount = 0;
+    const policy = {
+      promoteHeatThreshold: this.config.lifecyclePromoteHeatThreshold,
+      staleDecayThreshold: this.config.lifecycleStaleDecayThreshold,
+      archiveDecayThreshold: this.config.lifecycleArchiveDecayThreshold,
+      protectedCategories: this.config.lifecycleProtectedCategories
+    };
+    for (const memory of allMemories) {
+      if (memory.frontmatter.status === "superseded") {
+        continue;
+      }
+      evaluatedCount += 1;
+      const currentState = resolveLifecycleState(memory.frontmatter);
+      const decision = decideLifecycleTransition(memory, policy, now);
+      const nextState = memory.frontmatter.status === "archived" ? "archived" : decision.nextState;
+      countsByState[nextState] += 1;
+      if (memory.frontmatter.verificationState === "disputed") {
+        disputedCount += 1;
+      }
+      if (nextState !== currentState) {
+        const key = `${currentState}->${nextState}`;
+        transitionCounts[key] = (transitionCounts[key] ?? 0) + 1;
+      }
+      const prevHeat = memory.frontmatter.heatScore;
+      const prevDecay = memory.frontmatter.decayScore;
+      const scoreDelta = Math.abs((prevHeat ?? -1) - decision.heatScore) + Math.abs((prevDecay ?? -1) - decision.decayScore);
+      const shouldPersist = memory.frontmatter.lifecycleState !== nextState || memory.frontmatter.heatScore === void 0 || memory.frontmatter.decayScore === void 0 || memory.frontmatter.lastValidatedAt === void 0 || scoreDelta >= 0.01;
+      if (!shouldPersist) continue;
+      const wrote = await this.storage.writeMemoryFrontmatter(memory, {
+        lifecycleState: nextState,
+        heatScore: decision.heatScore,
+        decayScore: decision.decayScore,
+        lastValidatedAt: nowIso
+      });
+      if (wrote) updatedCount += 1;
+    }
+    if (!this.config.lifecycleMetricsEnabled) return;
+    const total = evaluatedCount;
+    const metrics = {
+      generatedAt: nowIso,
+      memoriesEvaluated: total,
+      memoriesUpdated: updatedCount,
+      countsByLifecycleState: countsByState,
+      transitionCounts,
+      staleRatio: total > 0 ? countsByState.stale / total : 0,
+      disputedRatio: total > 0 ? disputedCount / total : 0,
+      policy: {
+        promoteHeatThreshold: this.config.lifecyclePromoteHeatThreshold,
+        staleDecayThreshold: this.config.lifecycleStaleDecayThreshold,
+        archiveDecayThreshold: this.config.lifecycleArchiveDecayThreshold,
+        protectedCategories: this.config.lifecycleProtectedCategories
+      }
+    };
+    const metricsPath = path22.join(this.storage.dir, "state", "lifecycle-metrics.json");
+    await mkdir16(path22.dirname(metricsPath), { recursive: true });
+    await writeFile15(metricsPath, JSON.stringify(metrics, null, 2), "utf-8");
+  }
   /**
    * Archive old, low-importance, rarely-accessed facts (v6.0).
    * Moves eligible facts from facts/ to archive/YYYY-MM-DD/.
@@ -12122,10 +12438,19 @@ ${lines.join("\n\n")}`;
         tagCandidates = capSet(rawTags);
       }
     }
-    const boosted = results.map((r) => {
+    let lifecycleFilteredCount = 0;
+    const boosted = [];
+    for (const r of results) {
       const memory = memoryByPath.get(r.path);
       let score = r.score;
       if (memory) {
+        if (shouldFilterLifecycleRecallCandidate(memory.frontmatter, {
+          lifecyclePolicyEnabled: this.config.lifecyclePolicyEnabled,
+          lifecycleFilterStaleEnabled: this.config.lifecycleFilterStaleEnabled
+        })) {
+          lifecycleFilteredCount += 1;
+          continue;
+        }
         if (this.config.recencyWeight > 0) {
           const createdAt = new Date(memory.frontmatter.created).getTime();
           const ageMs = now - createdAt;
@@ -12176,9 +12501,15 @@ ${lines.join("\n\n")}`;
             score += 0.06;
           }
         }
+        score += lifecycleRecallScoreAdjustment(memory.frontmatter, {
+          lifecyclePolicyEnabled: this.config.lifecyclePolicyEnabled
+        });
       }
-      return { ...r, score };
-    });
+      boosted.push({ ...r, score });
+    }
+    if (lifecycleFilteredCount > 0) {
+      log.debug(`lifecycle retrieval filter removed ${lifecycleFilteredCount} stale/archived candidates`);
+    }
     return boosted.sort((a, b) => b.score - a.score);
   }
   /**