@joshuaswarren/openclaw-engram 9.0.4 → 9.0.6

package/dist/index.js

@@ -246,6 +246,8 @@ function parseConfig(raw) {
     checkpointEnabled: cfg.checkpointEnabled !== false,
     // default: true
     checkpointTurns: typeof cfg.checkpointTurns === "number" ? cfg.checkpointTurns : 15,
+    // Compaction reset (opt-in, default: false)
+    compactionResetEnabled: cfg.compactionResetEnabled === true,
     // Hourly summaries
     hourlySummariesEnabled: cfg.hourlySummariesEnabled !== false,
     // default: true
@@ -467,6 +469,9 @@ function parseConfig(raw) {
     graphExpansionBlendMin: typeof cfg.graphExpansionBlendMin === "number" ? Math.min(1, Math.max(0, cfg.graphExpansionBlendMin)) : 0.05,
     graphExpansionBlendMax: typeof cfg.graphExpansionBlendMax === "number" ? Math.min(1, Math.max(0, cfg.graphExpansionBlendMax)) : 0.95,
     maxEntityGraphEdgesPerMemory: typeof cfg.maxEntityGraphEdgesPerMemory === "number" ? Math.max(0, cfg.maxEntityGraphEdgesPerMemory) : 10,
+    graphLateralInhibitionEnabled: cfg.graphLateralInhibitionEnabled !== false,
+    graphLateralInhibitionBeta: typeof cfg.graphLateralInhibitionBeta === "number" ? Math.max(0, Math.min(1, cfg.graphLateralInhibitionBeta)) : 0.15,
+    graphLateralInhibitionTopM: typeof cfg.graphLateralInhibitionTopM === "number" ? Math.max(0, Math.round(cfg.graphLateralInhibitionTopM)) : 7,
     // v8.2: Temporal Memory Tree
     temporalMemoryTreeEnabled: cfg.temporalMemoryTreeEnabled === true,
     tmtHourlyMinMemories: typeof cfg.tmtHourlyMinMemories === "number" ? cfg.tmtHourlyMinMemories : 3,
@@ -570,8 +575,9 @@ function buildRecallPipelineConfig(cfg) {
 
 // src/orchestrator.ts
 import path30 from "path";
+import os5 from "os";
 import { createHash as createHash6 } from "crypto";
-import { mkdir as mkdir21, readdir as readdir14, readFile as readFile22, writeFile as writeFile20 } from "fs/promises";
+import { mkdir as mkdir21, readdir as readdir14, readFile as readFile22, stat as stat6, unlink as unlink5, writeFile as writeFile20 } from "fs/promises";
 
 // src/signal.ts
 var BUILTIN_HIGH_PATTERNS = [
@@ -13634,6 +13640,15 @@ var GraphIndex = class {
           }
         }
       }
+      if (this.cfg.graphLateralInhibitionEnabled && scores.size > 1) {
+        const inhibited = applyLateralInhibition(scores, {
+          beta: this.cfg.graphLateralInhibitionBeta,
+          topM: this.cfg.graphLateralInhibitionTopM
+        });
+        for (const [k, v] of inhibited) {
+          scores.set(k, v);
+        }
+      }
       return Array.from(scores.entries()).map(([p, score]) => ({
         path: p,
         score,
@@ -13649,6 +13664,23 @@ var GraphIndex = class {
     }
   }
 };
+function applyLateralInhibition(scores, opts) {
+  const { beta, topM } = opts;
+  if (beta === 0 || topM === 0) return new Map(scores);
+  const sorted = Array.from(scores.entries()).sort((a, b) => b[1] - a[1]);
+  const topCompetitors = sorted.slice(0, topM);
+  const result = /* @__PURE__ */ new Map();
+  for (const [node, u] of scores) {
+    let inhibition = 0;
+    for (const [, uK] of topCompetitors) {
+      if (uK > u) {
+        inhibition += uK - u;
+      }
+    }
+    result.set(node, Math.max(0, u - beta * inhibition));
+  }
+  return result;
+}
 
 // src/replay/types.ts
 var VALID_SOURCES = /* @__PURE__ */ new Set(["openclaw", "claude", "chatgpt"]);
@@ -15851,6 +15883,15 @@ function dedupeBehaviorSignalsByMemoryAndHash(signals) {
 }
 
 // src/orchestrator.ts
+var COMPACTION_SIGNAL_MAX_AGE_MS = 60 * 60 * 1e3;
+function defaultWorkspaceDir() {
+  return path30.join(os5.homedir(), ".openclaw", "workspace");
+}
+function sanitizeSessionKeyForFilename(sessionKey) {
+  const readable = sessionKey.replace(/[^a-zA-Z0-9._-]/g, "_");
+  const hash = createHash6("sha256").update(sessionKey).digest("hex").slice(0, 12);
+  return `${readable}-${hash}`;
+}
 function isArtifactMemoryPath(filePath) {
   return /(?:^|[\\/])artifacts(?:[\\/]|$)/i.test(filePath);
 }
@@ -16131,6 +16172,13 @@ var Orchestrator = class _Orchestrator {
   /** Temporal Memory Tree builder — builds hour/day/week/persona summary nodes. */
   tmtBuilder;
   rerankCache = new RerankCache();
+  /**
+   * Per-session workspace overrides keyed by sessionKey.
+   * Set by the before_agent_start hook so recall() uses the correct
+   * agent workspace for BOOT.md injection. Cleared after each recall.
+   * Using a Map prevents concurrent sessions from overwriting each other.
+   */
+  _recallWorkspaceOverrides = /* @__PURE__ */ new Map();
   routingRulesStore = null;
   contentHashIndex = null;
   artifactSourceStatusCache = /* @__PURE__ */ new WeakMap();
@@ -16163,6 +16211,14 @@ var Orchestrator = class _Orchestrator {
   // Initialization gate: recall() awaits this before proceeding
   initPromise = null;
   resolveInit = null;
+  /** Set per-session workspace for the next recall() call (compaction reset). @internal */
+  setRecallWorkspaceOverride(sessionKey, dir) {
+    this._recallWorkspaceOverrides.set(sessionKey, dir);
+  }
+  /** Remove a per-session workspace override (cleanup on error or early return). @internal */
+  clearRecallWorkspaceOverride(sessionKey) {
+    this._recallWorkspaceOverrides.delete(sessionKey);
+  }
   constructor(config) {
     this.config = config;
     this.storageRouter = new NamespaceStorageRouter(config);
@@ -16440,6 +16496,24 @@ var Orchestrator = class _Orchestrator {
     if (this.config.localLlmEnabled) {
       await this.validateLocalLlmModel();
     }
+    if (this.config.compactionResetEnabled) {
+      try {
+        const wsDir = this.config.workspaceDir || defaultWorkspaceDir();
+        const files = await readdir14(wsDir).catch(() => []);
+        for (const f of files) {
+          if (!f.startsWith(".compaction-reset-signal-")) continue;
+          const fp = path30.join(wsDir, f);
+          const s = await stat6(fp).catch(() => null);
+          if (s && Date.now() - s.mtimeMs >= COMPACTION_SIGNAL_MAX_AGE_MS) {
+            await unlink5(fp).catch(() => {
+            });
+            log.debug(`initialize: removed stale compaction signal ${f}`);
+          }
+        }
+      } catch (err) {
+        log.debug("initialize: stale signal sweep failed:", err);
+      }
+    }
     log.info("orchestrator initialized");
     if (this.resolveInit) {
       this.resolveInit();
@@ -17156,6 +17230,8 @@ ${r.snippet.trim()}
     );
     const embeddingFetchLimit = computedFetchLimit;
     if (recallMode === "no_recall") {
+      const earlySessionKey = sessionKey ?? "default";
+      this._recallWorkspaceOverrides.delete(earlySessionKey);
       timings.total = `${Date.now() - recallStart}ms`;
       this.emitTrace({
         kind: "recall_summary",
@@ -17329,6 +17405,58 @@ ${formatted}`;
       timings.transcript = `${Date.now() - t0}ms`;
       return section;
     })();
+    const compactionPromise = (async () => {
+      const effectiveSessionKey = sessionKey ?? "default";
+      const compactionWorkspaceDir = this._recallWorkspaceOverrides.get(effectiveSessionKey);
+      this._recallWorkspaceOverrides.delete(effectiveSessionKey);
+      if (!this.config.compactionResetEnabled) return null;
+      const workspaceDir = compactionWorkspaceDir || this.config.workspaceDir || defaultWorkspaceDir();
+      const safeSessionKey = sanitizeSessionKeyForFilename(effectiveSessionKey);
+      const signalPath = path30.join(workspaceDir, `.compaction-reset-signal-${safeSessionKey}`);
+      const bootPath = path30.join(workspaceDir, "BOOT.md");
+      try {
+        const signalStat = await stat6(signalPath).catch(() => null);
+        if (!signalStat) return null;
+        const signalAge = Date.now() - signalStat.mtimeMs;
+        const signalData = JSON.parse(await readFile22(signalPath, "utf-8"));
+        if (signalData.sessionKey !== effectiveSessionKey) {
+          log.debug(
+            `recall: compaction signal is for ${signalData.sessionKey}, not ${effectiveSessionKey} \u2014 skipping`
+          );
+          return null;
+        }
+        if (signalAge >= COMPACTION_SIGNAL_MAX_AGE_MS) {
+          log.debug(
+            `recall: stale compaction signal (${Math.round(signalAge / 1e3)}s old), skipping`
+          );
+          await unlink5(signalPath).catch(() => {
+          });
+          return null;
+        }
+        let section = "\n\n## Session Recovery (Post-Compaction)\n\n";
+        section += `\u26A0\uFE0F A compaction occurred at ${signalData.compactedAt} and this is a fresh session.
+
+`;
+        try {
+          const bootContent = await readFile22(bootPath, "utf-8");
+          section += "### BOOT.md (working state before compaction)\n\n";
+          section += bootContent + "\n";
+        } catch {
+          section += "### \u26A0\uFE0F BOOT.md is MISSING\n\n";
+          section += "The memory flush may not have written BOOT.md before compaction. ";
+          section += "Ask the user what you were working on \u2014 do not guess.\n";
+        }
+        log.info(`recall: injected compaction reset context for ${effectiveSessionKey}`);
+        await unlink5(signalPath).catch(() => {
+        });
+        return section;
+      } catch (err) {
+        log.debug("recall: compaction signal check failed:", err);
+        await unlink5(signalPath).catch(() => {
+        });
+        return null;
+      }
+    })();
     const summariesPromise = (async () => {
       const t0 = Date.now();
       if (!this.config.hourlySummariesEnabled || !sessionKey || !this.isRecallSectionEnabled("summaries", true)) {
@@ -17416,6 +17544,7 @@ ${formatted}`;
       artifacts,
       qmdResult,
       transcriptSection,
+      compactionSection,
       summariesSection,
       conversationRecallSection,
       compoundingSection
@@ -17427,6 +17556,7 @@ ${formatted}`;
       artifactsPromise,
       qmdPromise,
       transcriptPromise,
+      compactionPromise,
       summariesPromise,
       conversationRecallPromise,
       compoundingPromise
@@ -17794,6 +17924,9 @@ ${tmtNode.summary}`);
     if (transcriptSection) {
       this.appendRecallSection(sectionBuckets, "transcript", transcriptSection);
     }
+    if (compactionSection) {
+      this.appendRecallSection(sectionBuckets, "compaction-reset", compactionSection);
+    }
     if (summariesSection) {
       this.appendRecallSection(sectionBuckets, "summaries", summariesSection);
     }
@@ -22477,7 +22610,7 @@ promotionCandidates: ${res.promotionCandidateCount}`
 
 // src/cli.ts
 import path50 from "path";
-import { access as access3, readFile as readFile36, readdir as readdir22, unlink as unlink6 } from "fs/promises";
+import { access as access3, readFile as readFile36, readdir as readdir22, unlink as unlink7 } from "fs/promises";
 import { createHash as createHash10 } from "crypto";
 
 // src/transfer/export-json.ts
@@ -22490,7 +22623,7 @@ var EXPORT_SCHEMA_VERSION = 1;
 
 // src/transfer/fs-utils.ts
 import { createHash as createHash8 } from "crypto";
-import { mkdir as mkdir23, readdir as readdir16, readFile as readFile24, stat as stat6, writeFile as writeFile22 } from "fs/promises";
+import { mkdir as mkdir23, readdir as readdir16, readFile as readFile24, stat as stat7, writeFile as writeFile22 } from "fs/promises";
 import path33 from "path";
 async function sha256File(filePath) {
   const buf = await readFile24(filePath);
@@ -22528,7 +22661,7 @@ async function listFilesRecursive(rootDir) {
 }
 async function fileExists(filePath) {
   try {
-    await stat6(filePath);
+    await stat7(filePath);
     return true;
   } catch {
     return false;
@@ -22927,12 +23060,12 @@ async function importMarkdownBundle(opts) {
 
 // src/transfer/autodetect.ts
 import path41 from "path";
-import { stat as stat7 } from "fs/promises";
+import { stat as stat8 } from "fs/promises";
 async function detectImportFormat(fromPath) {
   const abs = path41.resolve(fromPath);
   let st;
   try {
-    st = await stat7(abs);
+    st = await stat8(abs);
   } catch {
     return null;
   }
@@ -23415,7 +23548,7 @@ var openclawReplayNormalizer = {
 
 // src/maintenance/archive-observations.ts
 import path42 from "path";
-import { mkdir as mkdir30, readdir as readdir18, readFile as readFile29, unlink as unlink5, writeFile as writeFile27 } from "fs/promises";
+import { mkdir as mkdir30, readdir as readdir18, readFile as readFile29, unlink as unlink6, writeFile as writeFile27 } from "fs/promises";
 var DATE_FILE_PATTERN = /^(\d{4})-(\d{2})-(\d{2})\.(jsonl|md)$/;
 function normalizeRetentionDays(value) {
   if (!Number.isFinite(value)) return 30;
@@ -23495,7 +23628,7 @@ async function archiveObservations(options) {
       await mkdir30(archiveDir, { recursive: true });
       const raw = await readFile29(candidate.absolutePath);
       await writeFile27(archivePath, raw);
-      await unlink5(candidate.absolutePath);
+      await unlink6(candidate.absolutePath);
       archivedFiles += 1;
       archivedBytes += raw.byteLength;
       archivedRelativePaths.push(candidate.relativePath);
@@ -23827,7 +23960,7 @@ async function migrateObservations(options) {
 }
 
 // src/network/tailscale.ts
-import { stat as stat8 } from "fs/promises";
+import { stat as stat9 } from "fs/promises";
 import { spawn as spawn3 } from "child_process";
 var TailscaleHelper = class {
   tailscaleBinary;
@@ -23892,7 +24025,7 @@ var TailscaleHelper = class {
   }
 };
 async function assertReadableDirectory(dir) {
-  const info = await stat8(dir);
+  const info = await stat9(dir);
   if (!info.isDirectory()) {
     throw new Error(`sourceDir must be a directory: ${dir}`);
   }
@@ -23939,7 +24072,7 @@ var defaultCommandRunner = (command, args, options) => {
 
 // src/network/webdav.ts
 import { createReadStream } from "fs";
-import { mkdir as mkdir32, readdir as readdir21, realpath as realpath2, stat as stat9 } from "fs/promises";
+import { mkdir as mkdir32, readdir as readdir21, realpath as realpath2, stat as stat10 } from "fs/promises";
 import { createServer } from "http";
 import { timingSafeEqual } from "crypto";
 import path46 from "path";
@@ -24175,7 +24308,7 @@ var WebDavServer = class _WebDavServer {
   async handleRead(method, absolutePath, res) {
     let info;
     try {
-      info = await stat9(absolutePath);
+      info = await stat10(absolutePath);
     } catch {
       res.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
       res.end("not found");
@@ -24199,7 +24332,7 @@ var WebDavServer = class _WebDavServer {
   async handlePropfind(absolutePath, displayPath, res) {
     let info;
     try {
-      info = await stat9(absolutePath);
+      info = await stat10(absolutePath);
     } catch {
       res.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
       res.end("not found");
@@ -26656,7 +26789,7 @@ function registerCli(api, orchestrator) {
         let deleted = 0;
         for (const filePath of plan.deletePaths) {
           try {
-            await unlink6(filePath);
+            await unlink7(filePath);
             deleted += 1;
           } catch (err) {
             console.log(`  failed to delete ${filePath}: ${String(err)}`);
@@ -26704,7 +26837,7 @@ function registerCli(api, orchestrator) {
         let deleted = 0;
         for (const filePath of plan.deletePaths) {
           try {
-            await unlink6(filePath);
+            await unlink7(filePath);
             deleted += 1;
           } catch (err) {
             console.log(`  failed to delete ${filePath}: ${String(err)}`);
@@ -27268,12 +27401,13 @@ function parseDuration(duration) {
 import { readFile as readFile37, writeFile as writeFile29 } from "fs/promises";
 import { readFileSync as readFileSync4 } from "fs";
 import path51 from "path";
-import os5 from "os";
+import os6 from "os";
 var ENGRAM_REGISTERED_GUARD = "__openclawEngramRegistered";
+var ENGRAM_HOOK_APIS = "__openclawEngramHookApis";
 function loadPluginConfigFromFile() {
   try {
     const explicitConfigPath = process.env.OPENCLAW_ENGRAM_CONFIG_PATH || process.env.OPENCLAW_CONFIG_PATH;
-    const homeDir = process.env.HOME ?? os5.homedir();
+    const homeDir = process.env.HOME ?? os6.homedir();
     const configPath = explicitConfigPath && explicitConfigPath.length > 0 ? explicitConfigPath : path51.join(homeDir, ".openclaw", "openclaw.json");
     const content = readFileSync4(configPath, "utf-8");
     const config = JSON.parse(content);
@@ -27321,13 +27455,19 @@ var index_default = {
     log.info(
       `initialized (debug=${cfg.debug}, qmdEnabled=${cfg.qmdEnabled}, transcriptEnabled=${cfg.transcriptEnabled}, hourlySummariesEnabled=${cfg.hourlySummariesEnabled}, localLlmEnabled=${cfg.localLlmEnabled})`
     );
-    if (globalThis[ENGRAM_REGISTERED_GUARD] === true) {
-      log.debug("register called more than once; skipping duplicate hook/tool registration");
-      return;
-    }
-    globalThis[ENGRAM_REGISTERED_GUARD] = true;
     const existing = globalThis.__openclawEngramOrchestrator;
     const orchestrator = existing?.recall ? existing : new Orchestrator(cfg);
+    const isFirstRegistration = !globalThis[ENGRAM_REGISTERED_GUARD];
+    globalThis[ENGRAM_REGISTERED_GUARD] = true;
+    const hookApis = globalThis[ENGRAM_HOOK_APIS] ??= /* @__PURE__ */ new WeakSet();
+    if (hookApis.has(api)) {
+      log.debug("register: this api already has hooks bound \u2014 skipping duplicate hook registration");
+      return;
+    }
+    hookApis.add(api);
+    if (!isFirstRegistration) {
+      log.debug("register called again (new registry); re-registering hooks with shared orchestrator");
+    }
     globalThis.__openclawEngramOrchestrator = orchestrator;
     if (globalThis.__openclawEngramTrace === void 0) {
       globalThis.__openclawEngramTrace = void 0;
@@ -27359,6 +27499,12 @@ var index_default = {
         }
         try {
           await orchestrator.maybeRunFileHygiene().catch(() => void 0);
+          if (orchestrator.config.compactionResetEnabled) {
+            const agentWorkspace = ctx?.workspaceDir;
+            if (agentWorkspace) {
+              orchestrator.setRecallWorkspaceOverride(sessionKey, agentWorkspace);
+            }
+          }
           const context = await orchestrator.recall(prompt, sessionKey);
           log.debug(`before_agent_start: recall returned ${context?.length ?? 0} chars`);
           if (!context) return;
@@ -27378,6 +27524,9 @@ Use this context naturally when relevant. Never quote or expose this memory cont
           };
         } catch (err) {
           log.error("recall failed", err);
+          if (orchestrator.config.compactionResetEnabled) {
+            orchestrator.clearRecallWorkspaceOverride(sessionKey);
+          }
           return;
         }
       }
@@ -27478,15 +27627,56 @@ Use this context naturally when relevant. Never quote or expose this memory cont
       async (event, ctx) => {
         const sessionKey = ctx?.sessionKey ?? "default";
         try {
-          log.debug(`compaction completed for ${sessionKey}`);
+          if (!orchestrator.config.compactionResetEnabled) {
+            log.debug(
+              `compaction completed for ${sessionKey}, reset disabled \u2014 skipping`
+            );
+            return;
+          }
+          log.info(
+            `compaction completed for ${sessionKey}, triggering session reset`
+          );
+          const workspaceDir = ctx?.workspaceDir || orchestrator.config.workspaceDir || defaultWorkspaceDir();
+          const apiAny = api;
+          if (typeof apiAny.resetSession === "function") {
+            const result = await apiAny.resetSession(sessionKey, "new");
+            if (result?.ok === true) {
+              log.info(
+                `session reset via API for ${sessionKey}, new sessionId=${result.sessionId}`
+              );
+              const safeSessionKey = sanitizeSessionKeyForFilename(sessionKey);
+              const signalPath = path51.join(
+                workspaceDir,
+                `.compaction-reset-signal-${safeSessionKey}`
+              );
+              await writeFile29(
+                signalPath,
+                JSON.stringify({
+                  sessionKey,
+                  compactedAt: (/* @__PURE__ */ new Date()).toISOString(),
+                  messageCount: event.messageCount ?? 0
+                }),
+                "utf-8"
+              );
+            } else {
+              const errorDetail = result && typeof result === "object" && "error" in result ? String(result.error ?? "unknown error") : `invalid result: ${JSON.stringify(result)}`;
+              log.error(
+                `api.resetSession failed for ${sessionKey}: ${errorDetail}`
+              );
+            }
+          } else {
+            log.error(
+              `api.resetSession not available \u2014 compaction reset requires OC fork with PR #29985. Session ${sessionKey} will continue without reset.`
+            );
+          }
         } catch (err) {
-          log.error("after_compaction hook failed", err);
+          log.error("after_compaction reset failed", err);
         }
       }
     );
     async function ensureHourlySummaryCron(api2) {
       const jobId = "engram-hourly-summary";
-      const cronFilePath = path51.join(os5.homedir(), ".openclaw", "cron", "jobs.json");
+      const cronFilePath = path51.join(os6.homedir(), ".openclaw", "cron", "jobs.json");
       try {
         let jobsData = { version: 1, jobs: [] };
         try {
@@ -27533,9 +27723,11 @@ Use this context naturally when relevant. Never quote or expose this memory cont
         log.error("failed to auto-register hourly summary cron job:", err);
       }
     }
-    registerTools(api, orchestrator);
-    registerCli(api, orchestrator);
-    api.registerService({
+    if (isFirstRegistration) {
+      registerTools(api, orchestrator);
+      registerCli(api, orchestrator);
+    }
+    if (isFirstRegistration) api.registerService({
       id: "openclaw-engram",
       start: async () => {
         log.info("initializing engram memory system...");
@@ -27554,6 +27746,7 @@ Use this context naturally when relevant. Never quote or expose this memory cont
       },
       stop: () => {
         globalThis[ENGRAM_REGISTERED_GUARD] = false;
+        globalThis[ENGRAM_HOOK_APIS] = /* @__PURE__ */ new WeakSet();
         log.info("stopped");
       }
     });