@remnic/plugin-openclaw 1.0.10 → 1.0.12

package/dist/first-start-migration-I24M2JEE.js

@@ -0,0 +1,258 @@
+import {
+  TierMigrationExecutor
+} from "./chunk-BU5KJVWF.js";
+import {
+  applyUtilityPromotionRuntimePolicy,
+  decideTierTransition,
+  loadUtilityRuntimeValues
+} from "./chunk-7OQEPGQF.js";
+import "./chunk-4G2XCSD2.js";
+import "./chunk-3G7FAF6S.js";
+import "./chunk-5LE4HTVL.js";
+import "./chunk-MLKGABMK.js";
+
+// ../remnic-core/src/maintenance/first-start-migration.ts
+import path from "path";
+import { access, mkdir, readFile, unlink, writeFile } from "fs/promises";
+var FIRST_START_DEMOTION_CAP = 50;
+var LIFECYCLE_INIT_DONE_MARKER = ".lifecycle-init-done";
+var LIFECYCLE_QMD_REFRESH_PENDING_MARKER = ".lifecycle-qmd-refresh-pending";
+function markerPath(memoryDir) {
+  return path.join(memoryDir, "state", LIFECYCLE_INIT_DONE_MARKER);
+}
+function qmdRefreshPendingPath(memoryDir) {
+  return path.join(memoryDir, "state", LIFECYCLE_QMD_REFRESH_PENDING_MARKER);
+}
+async function markerExists(memoryDir) {
+  try {
+    await access(markerPath(memoryDir));
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function writeMarker(memoryDir, now) {
+  const p = markerPath(memoryDir);
+  await mkdir(path.dirname(p), { recursive: true });
+  await writeFile(p, JSON.stringify({ createdAt: now.toISOString() }), "utf-8");
+}
+async function readQmdRefreshPending(memoryDir) {
+  try {
+    const raw = await readFile(qmdRefreshPendingPath(memoryDir), "utf-8");
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object" && typeof parsed.createdAt === "string" && typeof parsed.collection === "string" && parsed.collection.length > 0) {
+      return parsed;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+async function pathExists(p) {
+  try {
+    await access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function writeQmdRefreshPending(memoryDir, now, collection) {
+  const p = qmdRefreshPendingPath(memoryDir);
+  await mkdir(path.dirname(p), { recursive: true });
+  await writeFile(p, JSON.stringify({ createdAt: now.toISOString(), collection }), "utf-8");
+}
+async function clearQmdRefreshPending(memoryDir) {
+  await unlink(qmdRefreshPendingPath(memoryDir)).catch(() => {
+  });
+}
+async function buildTierRoutingPolicy(config) {
+  const basePolicy = {
+    enabled: config.qmdTierMigrationEnabled,
+    demotionMinAgeDays: config.qmdTierDemotionMinAgeDays,
+    demotionValueThreshold: config.qmdTierDemotionValueThreshold,
+    promotionValueThreshold: config.qmdTierPromotionValueThreshold
+  };
+  const runtime = await loadUtilityRuntimeValues({
+    memoryDir: config.memoryDir,
+    memoryUtilityLearningEnabled: config.memoryUtilityLearningEnabled,
+    promotionByOutcomeEnabled: config.promotionByOutcomeEnabled
+  });
+  return applyUtilityPromotionRuntimePolicy(basePolicy, runtime);
+}
+async function refreshQmdCollection(qmd, collection, signal) {
+  if (typeof qmd.updateCollectionStrict === "function") {
+    await qmd.updateCollectionStrict(collection, { signal });
+    return;
+  }
+  await qmd.updateCollection(collection, { signal });
+}
+async function runFirstStartMigration(options) {
+  const {
+    storage,
+    config,
+    demotionCap = FIRST_START_DEMOTION_CAP,
+    dryRun = false,
+    qmd,
+    signal
+  } = options;
+  const now = (options.now ?? (() => /* @__PURE__ */ new Date()))();
+  const abortedResult = (candidateCount2 = 0, demotedCount2 = 0, failureCount2 = 0) => ({
+    skipped: candidateCount2 === 0 && demotedCount2 === 0 && failureCount2 === 0,
+    skipReason: candidateCount2 === 0 && demotedCount2 === 0 && failureCount2 === 0 ? "aborted" : void 0,
+    dryRun,
+    candidateCount: candidateCount2,
+    demotedCount: demotedCount2,
+    failureCount: failureCount2,
+    cappedAt: demotionCap
+  });
+  if (signal?.aborted) {
+    return abortedResult();
+  }
+  if (!config.lifecyclePolicyEnabled) {
+    return {
+      skipped: true,
+      skipReason: "lifecyclePolicyEnabled is false",
+      dryRun,
+      candidateCount: 0,
+      demotedCount: 0,
+      failureCount: 0,
+      cappedAt: demotionCap
+    };
+  }
+  if (!config.qmdTierMigrationEnabled) {
+    return {
+      skipped: true,
+      skipReason: "qmdTierMigrationEnabled is false",
+      dryRun,
+      candidateCount: 0,
+      demotedCount: 0,
+      failureCount: 0,
+      cappedAt: demotionCap
+    };
+  }
+  if (await markerExists(config.memoryDir)) {
+    return {
+      skipped: true,
+      skipReason: "lifecycle-init-done marker already present",
+      dryRun,
+      candidateCount: 0,
+      demotedCount: 0,
+      failureCount: 0,
+      cappedAt: demotionCap
+    };
+  }
+  if (signal?.aborted) {
+    return abortedResult();
+  }
+  const policy = await buildTierRoutingPolicy(config);
+  if (signal?.aborted) {
+    return abortedResult();
+  }
+  const hotMemories = await storage.readAllMemories();
+  if (signal?.aborted) {
+    return abortedResult();
+  }
+  const demotionCandidates = hotMemories.filter((m) => {
+    const decision = decideTierTransition(m, "hot", policy, now);
+    return decision.changed && decision.nextTier === "cold";
+  });
+  const candidateCount = demotionCandidates.length;
+  const batch = demotionCandidates.slice(0, demotionCap);
+  if (dryRun) {
+    return {
+      skipped: false,
+      dryRun: true,
+      candidateCount,
+      demotedCount: 0,
+      failureCount: 0,
+      cappedAt: demotionCap
+    };
+  }
+  let demotedCount = 0;
+  let failureCount = 0;
+  let qmdRefreshPendingForRun = false;
+  const executor = qmd ? new TierMigrationExecutor({
+    storage,
+    qmd,
+    hotCollection: options.hotCollection ?? config.qmdCollection ?? "openclaw-engram",
+    coldCollection: options.coldCollection ?? config.qmdColdCollection ?? "openclaw-engram-cold"
+  }) : null;
+  const coldCollection = options.coldCollection ?? config.qmdColdCollection ?? "openclaw-engram-cold";
+  for (const memory of batch) {
+    if (signal?.aborted) {
+      return abortedResult(candidateCount, demotedCount, failureCount);
+    }
+    try {
+      if (executor) {
+        await executor.migrateMemory({
+          memory,
+          fromTier: "hot",
+          toTier: "cold",
+          reason: "first-start-lifecycle-migration"
+        });
+      } else {
+        await storage.migrateMemoryToTier(memory, "cold");
+      }
+      demotedCount += 1;
+    } catch {
+      const targetPath = storage.buildTierMemoryPath(memory, "cold");
+      const [targetExists, sourceExists] = await Promise.all([
+        pathExists(targetPath),
+        pathExists(memory.path)
+      ]);
+      const movedToCold = targetExists && !sourceExists;
+      if (movedToCold) {
+        if (!qmd) {
+          demotedCount += 1;
+          continue;
+        }
+        try {
+          await refreshQmdCollection(qmd, coldCollection, signal);
+          demotedCount += 1;
+          continue;
+        } catch {
+          qmdRefreshPendingForRun = true;
+          try {
+            await writeQmdRefreshPending(config.memoryDir, now, coldCollection);
+          } catch {
+          }
+          demotedCount += 1;
+          continue;
+        }
+      }
+      failureCount += 1;
+    }
+  }
+  if (signal?.aborted) {
+    return abortedResult(candidateCount, demotedCount, failureCount);
+  }
+  const persistedQmdRefreshPending = qmd ? await readQmdRefreshPending(config.memoryDir) : null;
+  const hasPersistedQmdRefreshPending = persistedQmdRefreshPending?.collection === coldCollection;
+  if (qmd && persistedQmdRefreshPending && persistedQmdRefreshPending.collection !== coldCollection) {
+    failureCount += 1;
+  }
+  if (qmd && (qmdRefreshPendingForRun || hasPersistedQmdRefreshPending)) {
+    try {
+      await refreshQmdCollection(qmd, coldCollection, signal);
+      await clearQmdRefreshPending(config.memoryDir);
+    } catch {
+      failureCount += 1;
+    }
+  }
+  if (failureCount === 0) {
+    await writeMarker(config.memoryDir, now);
+  }
+  return {
+    skipped: false,
+    dryRun: false,
+    candidateCount,
+    demotedCount,
+    failureCount,
+    cappedAt: demotionCap
+  };
+}
+export {
+  FIRST_START_DEMOTION_CAP,
+  LIFECYCLE_INIT_DONE_MARKER,
+  runFirstStartMigration
+};

package/dist/forget-NI4RBDPB.js

@@ -0,0 +1,68 @@
+import "./chunk-MLKGABMK.js";
+
+// ../remnic-core/src/maintenance/forget.ts
+var ForgetMemoryNotFoundError = class extends Error {
+  code = "memory_not_found";
+  constructor(id) {
+    super(`memory not found: ${id}`);
+    this.name = "ForgetMemoryNotFoundError";
+  }
+};
+var ForgetMemoryAlreadyForgottenError = class extends Error {
+  code = "already_forgotten";
+  constructor(id, forgottenAt) {
+    super(`memory ${id} was already forgotten at ${forgottenAt}`);
+    this.name = "ForgetMemoryAlreadyForgottenError";
+  }
+};
+async function forgetMemory(storage, request) {
+  const id = typeof request.id === "string" ? request.id.trim() : "";
+  if (id.length === 0) {
+    throw new Error("forget: memory id is required and must be non-empty");
+  }
+  const memory = await findMemoryById(storage, id);
+  if (!memory) {
+    throw new ForgetMemoryNotFoundError(id);
+  }
+  if (memory.frontmatter.status === "forgotten") {
+    throw new ForgetMemoryAlreadyForgottenError(
+      id,
+      memory.frontmatter.forgottenAt ?? "(unknown)"
+    );
+  }
+  const priorStatus = typeof memory.frontmatter.status === "string" ? memory.frontmatter.status : "active";
+  const now = (request.now ?? (() => /* @__PURE__ */ new Date()))();
+  const forgottenAt = now.toISOString();
+  const reason = typeof request.reason === "string" ? request.reason.trim() : "";
+  await storage.writeMemoryFrontmatter(memory, {
+    status: "forgotten",
+    forgottenAt,
+    forgottenReason: reason.length > 0 ? reason : void 0,
+    updated: forgottenAt
+  }, {
+    actor: "remnic-forget",
+    reasonCode: "operator_forget"
+  });
+  return {
+    id,
+    path: memory.path,
+    priorStatus,
+    forgottenAt,
+    reason
+  };
+}
+async function findMemoryById(storage, id) {
+  const hot = await storage.readAllMemories();
+  const hotMatch = hot.find((m) => m.frontmatter.id === id);
+  if (hotMatch) return hotMatch;
+  const archived = await storage.readArchivedMemories();
+  const archivedMatch = archived.find((m) => m.frontmatter.id === id);
+  if (archivedMatch) return archivedMatch;
+  const cold = await storage.readAllColdMemories();
+  return cold.find((m) => m.frontmatter.id === id) ?? null;
+}
+export {
+  ForgetMemoryAlreadyForgottenError,
+  ForgetMemoryNotFoundError,
+  forgetMemory
+};

package/dist/fs-utils-PZRI2HDZ.js

@@ -0,0 +1,29 @@
+import {
+  assertIsDirectoryNotSymlink,
+  assertRealpathInsideRoot,
+  ensureDirExists,
+  fileExists,
+  fromPosixRelPath,
+  isPathInsideRoot,
+  listFilesRecursive,
+  readJsonFile,
+  sha256File,
+  sha256String,
+  toPosixRelPath,
+  writeJsonFile
+} from "./chunk-NKVIN6RD.js";
+import "./chunk-MLKGABMK.js";
+export {
+  assertIsDirectoryNotSymlink,
+  assertRealpathInsideRoot,
+  ensureDirExists,
+  fileExists,
+  fromPosixRelPath,
+  isPathInsideRoot,
+  listFilesRecursive,
+  readJsonFile,
+  sha256File,
+  sha256String,
+  toPosixRelPath,
+  writeJsonFile
+};

package/dist/graph-edge-decay-5CVKWBYH.js

@@ -0,0 +1,203 @@
+import {
+  isSafeRouteNamespace
+} from "./chunk-FQRSVYY4.js";
+import {
+  DEFAULT_DECAY_FLOOR,
+  DEFAULT_DECAY_PER_WINDOW,
+  DEFAULT_DECAY_WINDOW_MS,
+  decayEdgeConfidence,
+  graphFilePath,
+  graphsDir,
+  readEdgeConfidence,
+  readEdgesStrict,
+  withGraphWriteLock
+} from "./chunk-3GUF7RQI.js";
+import "./chunk-MLKGABMK.js";
+
+// ../remnic-core/src/maintenance/graph-edge-decay.ts
+import {
+  mkdir,
+  readdir,
+  readFile,
+  rename,
+  writeFile
+} from "fs/promises";
+import path from "path";
+var DEFAULT_VISIBILITY_THRESHOLD = 0.2;
+var GRAPH_TYPES = ["entity", "time", "causal"];
+function graphEdgeDecayStatusPath(memoryDir) {
+  return path.join(memoryDir, "state", "graph-edge-decay-status.json");
+}
+async function writeJsonlAtomic(filePath, edges) {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  const body = edges.length === 0 ? "" : edges.map((e) => JSON.stringify(e)).join("\n") + "\n";
+  const tempPath = `${filePath}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;
+  await writeFile(tempPath, body, "utf-8");
+  await rename(tempPath, filePath);
+}
+async function runGraphEdgeDecayMaintenance(memoryDir, options = {}) {
+  const startedAt = Date.now();
+  const ranAt = options.now ?? (/* @__PURE__ */ new Date()).toISOString();
+  const windowMs = options.windowMs ?? DEFAULT_DECAY_WINDOW_MS;
+  const perWindow = options.perWindow ?? DEFAULT_DECAY_PER_WINDOW;
+  const floor = options.floor ?? DEFAULT_DECAY_FLOOR;
+  const visibilityThreshold = typeof options.visibilityThreshold === "number" && Number.isFinite(options.visibilityThreshold) ? Math.max(0, Math.min(1, options.visibilityThreshold)) : DEFAULT_VISIBILITY_THRESHOLD;
+  const dryRun = options.dryRun === true;
+  await mkdir(graphsDir(memoryDir), { recursive: true });
+  const perType = [];
+  const dropByLabel = /* @__PURE__ */ new Map();
+  let edgesTotal = 0;
+  let edgesDecayed = 0;
+  let edgesBelowVisibilityThreshold = 0;
+  for (const type of GRAPH_TYPES) {
+    const filePath = graphFilePath(memoryDir, type);
+    const {
+      typeDecayed,
+      typeBelow,
+      typeTotal
+    } = await withGraphWriteLock(filePath, async () => {
+      const edges = await readEdgesStrict(memoryDir, type);
+      const updated = new Array(edges.length);
+      let localDecayed = 0;
+      let localBelow = 0;
+      let localChangedAny = false;
+      for (let i = 0; i < edges.length; i += 1) {
+        const edge = edges[i];
+        const before = readEdgeConfidence(edge);
+        const decayed = decayEdgeConfidence(edge, ranAt, { windowMs, perWindow, floor });
+        const after = readEdgeConfidence(decayed);
+        if (after < before) {
+          localDecayed += 1;
+          const drop = before - after;
+          const label = typeof edge.label === "string" ? edge.label : "";
+          if (label.length > 0) {
+            const prev = dropByLabel.get(label);
+            if (prev) {
+              prev.totalDrop += drop;
+              prev.edgeCount += 1;
+            } else {
+              dropByLabel.set(label, { totalDrop: drop, edgeCount: 1 });
+            }
+          }
+        }
+        if (after < visibilityThreshold) {
+          localBelow += 1;
+        }
+        updated[i] = decayed;
+        if (decayed.confidence !== edge.confidence || decayed.lastReinforcedAt !== edge.lastReinforcedAt) {
+          localChangedAny = true;
+        }
+      }
+      if (!dryRun && localChangedAny && edges.length > 0) {
+        await writeJsonlAtomic(filePath, updated);
+      }
+      return {
+        typeDecayed: localDecayed,
+        typeBelow: localBelow,
+        typeTotal: edges.length
+      };
+    });
+    edgesDecayed += typeDecayed;
+    edgesBelowVisibilityThreshold += typeBelow;
+    edgesTotal += typeTotal;
+    perType.push({
+      type,
+      edgesTotal: typeTotal,
+      edgesDecayed: typeDecayed,
+      edgesBelowVisibilityThreshold: typeBelow
+    });
+  }
+  const topDecayedEntities = [...dropByLabel.entries()].map(([label, agg]) => ({ label, totalDrop: agg.totalDrop, edgeCount: agg.edgeCount })).sort((a, b) => {
+    if (b.totalDrop !== a.totalDrop) return b.totalDrop - a.totalDrop;
+    return a.label.localeCompare(b.label);
+  }).slice(0, 5);
+  const telemetry = {
+    ranAt,
+    durationMs: Date.now() - startedAt,
+    edgesTotal,
+    edgesDecayed,
+    edgesBelowVisibilityThreshold,
+    topDecayedEntities,
+    perType,
+    windowMs,
+    perWindow,
+    floor,
+    visibilityThreshold
+  };
+  if (!dryRun) {
+    await persistTelemetry(memoryDir, telemetry);
+  }
+  return telemetry;
+}
+async function persistTelemetry(memoryDir, telemetry) {
+  const statusPath = graphEdgeDecayStatusPath(memoryDir);
+  await mkdir(path.dirname(statusPath), { recursive: true });
+  const tempPath = `${statusPath}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;
+  try {
+    await writeFile(tempPath, JSON.stringify(telemetry, null, 2) + "\n", "utf-8");
+    await rename(tempPath, statusPath);
+  } catch {
+  }
+}
+async function readGraphEdgeDecayStatus(memoryDir) {
+  try {
+    const raw = await readFile(graphEdgeDecayStatusPath(memoryDir), "utf-8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+async function discoverGraphNamespaceRoots(memoryDir, options) {
+  const seen = /* @__PURE__ */ new Map();
+  seen.set(options.defaultNamespace, memoryDir);
+  if (!options.namespacesEnabled) {
+    return [...seen.entries()].map(([namespace, storageRoot]) => ({ namespace, storageRoot }));
+  }
+  const namespacesDir = path.join(memoryDir, "namespaces");
+  let entries;
+  try {
+    entries = await readdir(namespacesDir, { withFileTypes: true });
+  } catch {
+    return [...seen.entries()].map(([namespace, storageRoot]) => ({ namespace, storageRoot }));
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (!isSafeRouteNamespace(entry.name)) continue;
+    const root = path.join(namespacesDir, entry.name);
+    seen.set(entry.name, root);
+  }
+  return [...seen.entries()].map(([namespace, storageRoot]) => ({ namespace, storageRoot }));
+}
+async function runGraphEdgeDecayMaintenanceAcrossNamespaces(memoryDir, options) {
+  const { namespacesEnabled, defaultNamespace, ...decayOptions } = options;
+  const roots = await discoverGraphNamespaceRoots(memoryDir, {
+    namespacesEnabled,
+    defaultNamespace
+  });
+  const results = [];
+  for (const { namespace, storageRoot } of roots) {
+    try {
+      const telemetry = await runGraphEdgeDecayMaintenance(storageRoot, decayOptions);
+      results.push({ namespace, storageRoot, telemetry });
+    } catch (err) {
+      results.push({
+        namespace,
+        storageRoot,
+        error: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
+  return results;
+}
+export {
+  DEFAULT_VISIBILITY_THRESHOLD,
+  discoverGraphNamespaceRoots,
+  graphEdgeDecayStatusPath,
+  readGraphEdgeDecayStatus,
+  runGraphEdgeDecayMaintenance,
+  runGraphEdgeDecayMaintenanceAcrossNamespaces
+};