@echomem/echo-memory-cloud-openclaw-plugin 0.2.0 → 0.2.1

package/README.md

@@ -59,8 +59,11 @@ Path resolution order for `memoryDir`:
 Supported runtime `.env` locations:
 
 - `~/.openclaw/.env`
-- `~/.moltbot/.env`
-- `~/.clawdbot/.env`
+
+Legacy one-release migration bridge:
+
+- if `~/.openclaw/.env` is missing, EchoMemory can still read `~/.moltbot/.env` or `~/.clawdbot/.env`
+- new saves and updated setup should go to `~/.openclaw/.env`
 
 Supported environment variables:
 
@@ -132,6 +135,11 @@ Older configs may still include `baseUrl` or `webBaseUrl`. Those keys are deprec
 
 ### Install from a local path
 
+Version note:
+
+- on OpenClaw `2026.3.22+`, avoid bare plugin names during install because plugin source precedence changed
+- use an exact local path, `--link`, or the exact scoped npm package
+
 On Windows, quote the path if your username or folders contain spaces:
 
 ```powershell
@@ -229,6 +237,7 @@ The plugin starts a localhost workspace UI during gateway startup and can auto-o
 
 - first run can automatically trigger `npm install` and `npm run build` under `lib/local-ui`
 - browser auto-open is skipped automatically for SSH, CI, and headless Linux sessions
+- when the gateway restarts, an already-open local UI tab reconnects and refreshes itself instead of spawning a redundant new tab
 - `/echo-memory view` returns the current localhost URL for the local markdown workspace UI and also tries to open the browser
 - natural-language requests can use the `echo_memory_local_ui` tool to get the exact live URL instead of guessing the port
 - the local markdown archive stays fully browsable even when no Echo Cloud API key is configured

package/clawdbot.plugin.json

@@ -2,7 +2,7 @@
   "id": "echo-memory-cloud-openclaw-plugin",
   "name": "Echo Memory Cloud OpenClaw Plugin",
   "description": "Sync OpenClaw local markdown memory files to Echo cloud",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "kind": "lifecycle",
   "main": "./index.js",
   "configSchema": {
@@ -22,7 +22,7 @@
       },
       "memoryDir": {
         "type": "string",
-        "description": "Absolute path to the markdown memory directory. Falls back to ECHOMEM_MEMORY_DIR, then ~/.clawdbot/workspace/memory."
+        "description": "Absolute path to the markdown memory directory. Falls back to ECHOMEM_MEMORY_DIR, then ~/.openclaw/workspace/memory."
       },
       "localOnlyMode": {
         "type": "boolean",

package/index.js

@@ -15,7 +15,14 @@ import {
 import { buildOnboardingText } from "./lib/onboarding.js";
 import { createSyncRunner, formatStatusText } from "./lib/sync.js";
 import { readLastSyncState } from "./lib/state.js";
-import { openUrlInDefaultBrowser, startLocalServer, stopLocalServer } from "./lib/local-server.js";
+import {
+  openUrlInDefaultBrowser,
+  startLocalServer,
+  stopLocalServer,
+  waitForLocalUiClient,
+} from "./lib/local-server.js";
+
+const LOCAL_UI_RECONNECT_GRACE_MS = 1500;
 
 function resolveCommandLabel(channel) {
   return channel === "discord" ? "/echomemory" : "/echo-memory";
@@ -75,10 +82,15 @@ export default {
       let openedInBrowser = false;
       let openReason = "not_requested";
       if (openInBrowser) {
-        const openResult = await openUrlInDefaultBrowser(url, {
-          logger: api.logger,
-          force: trigger !== "gateway-start",
-        });
+        const existingClientDetected = trigger === "gateway-start"
+          ? await waitForLocalUiClient({ timeoutMs: LOCAL_UI_RECONNECT_GRACE_MS })
+          : false;
+        const openResult = existingClientDetected
+          ? { opened: false, reason: "existing_client_reconnected" }
+          : await openUrlInDefaultBrowser(url, {
+              logger: api.logger,
+              force: trigger !== "gateway-start",
+            });
         openedInBrowser = openResult.opened;
         openReason = openResult.reason;
       }
@@ -130,7 +142,18 @@ export default {
       });
     }
 
-    const envStatus = getEnvFileStatus();
+    const envStatus = getEnvFileStatus();
+    if (envStatus.usingLegacyBridge) {
+      api.logger?.warn?.(
+        `[echo-memory] Legacy env file detected (${envStatus.legacyPaths.join(", ")}). ` +
+        `EchoMemory is using a one-release migration bridge and will write future changes to ${envStatus.primaryPath}.`,
+      );
+    } else if (envStatus.legacyPaths.length > 0) {
+      api.logger?.info?.(
+        `[echo-memory] Legacy env file still present (${envStatus.legacyPaths.join(", ")}). ` +
+        `Current settings should be kept in ${envStatus.primaryPath}.`,
+      );
+    }
     if (!envStatus.found) {
       api.logger?.warn?.(
         `[echo-memory] No .env file found in ${envStatus.searchPaths.join(", ")}. Using plugin config or process env.`,

package/lib/config.js

@@ -4,12 +4,25 @@ import { dirname, join } from "node:path";
 
 const DEFAULT_BASE_URL = "https://echo-mem-chrome.vercel.app";
 const DEFAULT_WEB_BASE_URL = "https://www.iditor.com";
-const DEFAULT_CONFIG_PATH = process.env.OPENCLAW_CONFIG_PATH || join(homedir(), ".openclaw", "openclaw.json");
-const ENV_SOURCES = [
-  join(homedir(), ".openclaw", ".env"),
+function resolveOpenClawHome() {
+  const configPath = process.env.OPENCLAW_CONFIG_PATH?.trim();
+  if (configPath) {
+    return dirname(configPath);
+  }
+  return join(homedir(), ".openclaw");
+}
+
+const OPENCLAW_HOME = resolveOpenClawHome();
+const PRIMARY_ENV_PATH = join(OPENCLAW_HOME, ".env");
+const LEGACY_ENV_SOURCES = [
   join(homedir(), ".moltbot", ".env"),
   join(homedir(), ".clawdbot", ".env"),
 ];
+const DEFAULT_CONFIG_PATH = process.env.OPENCLAW_CONFIG_PATH || join(OPENCLAW_HOME, "openclaw.json");
+const ENV_SOURCES = [
+  PRIMARY_ENV_PATH,
+  ...LEGACY_ENV_SOURCES,
+];
 
 let cachedEnv = null;
 
@@ -97,10 +110,15 @@ function parseInteger(value, fallback, { min = Number.NEGATIVE_INFINITY, max = N
 
 export function getEnvFileStatus() {
   const env = loadEnvFiles();
+  const legacyPaths = env.foundPaths.filter((envPath) => LEGACY_ENV_SOURCES.includes(envPath));
   return {
     found: env.foundPaths.length > 0,
     paths: env.foundPaths,
     searchPaths: env.searchPaths,
+    primaryPath: PRIMARY_ENV_PATH,
+    foundPrimary: env.foundPaths.includes(PRIMARY_ENV_PATH),
+    legacyPaths,
+    usingLegacyBridge: !env.foundPaths.includes(PRIMARY_ENV_PATH) && legacyPaths.length > 0,
   };
 }
 
@@ -142,7 +160,6 @@ function maskValue(value, { keepStart = 2, keepEnd = 2 } = {}) {
 export function getLocalUiSetupState(pluginConfig = {}, cfg = null) {
   const runtimeCfg = cfg ?? buildConfig(pluginConfig);
   const envStatus = getEnvFileStatus();
-  const targetEnvPath = envStatus.paths[0] || envStatus.searchPaths[0];
   const localOnlyMode = resolveConfigValue(
     pluginConfig,
     "localOnlyMode",
@@ -162,9 +179,12 @@ export function getLocalUiSetupState(pluginConfig = {}, cfg = null) {
       targetPath: DEFAULT_CONFIG_PATH,
     },
     envFile: {
-      targetPath: targetEnvPath,
+      targetPath: envStatus.primaryPath,
+      activePath: envStatus.paths[0] || null,
       foundPaths: envStatus.paths,
       searchPaths: envStatus.searchPaths,
+      legacyPaths: envStatus.legacyPaths,
+      usingLegacyBridge: envStatus.usingLegacyBridge,
     },
     localOnlyMode: {
       enabled: Boolean(runtimeCfg.localOnlyMode),
@@ -190,12 +210,13 @@ export function getLocalUiSetupState(pluginConfig = {}, cfg = null) {
 
 export function saveLocalUiSetup(values = {}) {
   const envStatus = getEnvFileStatus();
-  const targetPath = envStatus.paths[0] || envStatus.searchPaths[0];
+  const targetPath = envStatus.primaryPath;
+  const sourcePath = envStatus.foundPrimary ? envStatus.primaryPath : (envStatus.paths[0] || envStatus.primaryPath);
   mkdirSync(dirname(targetPath), { recursive: true });
 
   let lines = [];
   try {
-    lines = readFileSync(targetPath, "utf8").split(/\r?\n/);
+    lines = readFileSync(sourcePath, "utf8").split(/\r?\n/);
   } catch {
     lines = [];
   }
@@ -237,6 +258,8 @@ export function saveLocalUiSetup(values = {}) {
   invalidateEnvCache();
   return {
     targetPath,
+    sourcePath,
+    migratedFrom: sourcePath !== targetPath ? sourcePath : null,
     savedKeys: [...managedKeys],
   };
 }
@@ -275,7 +298,7 @@ export function buildConfig(pluginConfig = {}) {
     memoryDir: String(
       cfg.memoryDir
       || loadEnvVar("ECHOMEM_MEMORY_DIR")
-      || join(homedir(), ".openclaw", "workspace", "memory"),
+      || join(OPENCLAW_HOME, "workspace", "memory"),
     ).trim(),
   };
 }

package/lib/local-server.js

@@ -24,11 +24,18 @@ let _lastOpenedUrl = null;
 const SKIP_DIRS = new Set(["node_modules", ".git", ".next", "dist", "build", "__pycache__", "logs", "completions", "delivery-queue", "browser", "canvas", "cron", "media"]);
 
 /** Debounced file-change broadcaster */
-function createFileWatcher(workspaceDir) {
-  const sseClients = new Set();
-  const watchers = [];
-  let debounceTimer = null;
-  const DEBOUNCE_MS = 500;
+function createFileWatcher(workspaceDir) {
+  const sseClients = new Set();
+  const clientWaiters = new Set();
+  const watchers = [];
+  let debounceTimer = null;
+  const DEBOUNCE_MS = 500;
+
+  function settleClientWaiters(didConnect) {
+    for (const finish of [...clientWaiters]) {
+      finish(didConnect);
+    }
+  }
 
   function broadcast(eventData) {
     const payload = `data: ${JSON.stringify(eventData)}\n\n`;
@@ -66,18 +73,48 @@ function createFileWatcher(workspaceDir) {
   // Start watching
   watchRecursive(workspaceDir);
 
-  return {
-    sseClients,
-    broadcast,
-    close() {
-      if (debounceTimer) clearTimeout(debounceTimer);
-      for (const w of watchers) { try { w.close(); } catch {} }
-      watchers.length = 0;
-      for (const res of sseClients) { try { res.end(); } catch {} }
-      sseClients.clear();
-    },
-  };
-}
+  return {
+    sseClients,
+    addSseClient(res) {
+      sseClients.add(res);
+      settleClientWaiters(true);
+    },
+    removeSseClient(res) {
+      sseClients.delete(res);
+    },
+    waitForClient(timeoutMs = 0) {
+      if (sseClients.size > 0) {
+        return Promise.resolve(true);
+      }
+      return new Promise((resolve) => {
+        let timer = null;
+        const finish = (didConnect) => {
+          if (!clientWaiters.delete(finish)) {
+            return;
+          }
+          if (timer) {
+            clearTimeout(timer);
+            timer = null;
+          }
+          resolve(didConnect);
+        };
+        clientWaiters.add(finish);
+        if (timeoutMs > 0) {
+          timer = setTimeout(() => finish(false), timeoutMs);
+        }
+      });
+    },
+    broadcast,
+    close() {
+      if (debounceTimer) clearTimeout(debounceTimer);
+      for (const w of watchers) { try { w.close(); } catch {} }
+      watchers.length = 0;
+      for (const res of sseClients) { try { res.end(); } catch {} }
+      sseClients.clear();
+      settleClientWaiters(false);
+    },
+  };
+}
 
 function tryListen(server, port) {
   return new Promise((resolve) => {
@@ -388,10 +425,10 @@ async function buildWorkspaceSyncView({ workspaceDir, syncMemoryDir, statePath }
   };
 }
 
-function createRequestHandler(workspaceDir, htmlContent, opts = {}) {
-  const normalizedBase = path.resolve(workspaceDir) + path.sep;
-  const { apiClient, syncRunner, cfg, fileWatcher, logger } = opts;
-  const syncMemoryDir = cfg?.memoryDir ? path.resolve(cfg.memoryDir) : null;
+function createRequestHandler(workspaceDir, htmlContent, opts = {}) {
+  const normalizedBase = path.resolve(workspaceDir) + path.sep;
+  const { apiClient, syncRunner, cfg, fileWatcher, logger, serverInstanceId } = opts;
+  const syncMemoryDir = cfg?.memoryDir ? path.resolve(cfg.memoryDir) : null;
 
   return async function handler(req, res) {
     setCorsHeaders(res);
@@ -415,19 +452,24 @@ function createRequestHandler(workspaceDir, htmlContent, opts = {}) {
     }
 
     // SSE endpoint — push file-change events to the frontend
-    if (url.pathname === "/api/events") {
-      res.writeHead(200, {
-        "Content-Type": "text/event-stream",
-        "Cache-Control": "no-cache",
-        "Connection": "keep-alive",
-      });
-      res.write(": connected\n\n");
-      if (fileWatcher) {
-        fileWatcher.sseClients.add(res);
-        req.on("close", () => fileWatcher.sseClients.delete(res));
-      }
-      return;
-    }
+    if (url.pathname === "/api/events") {
+      res.writeHead(200, {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache",
+        "Connection": "keep-alive",
+      });
+      res.write("retry: 1000\n");
+      res.write(`data: ${JSON.stringify({
+        type: "server-connected",
+        serverInstanceId,
+        connectedAt: new Date().toISOString(),
+      })}\n\n`);
+      if (fileWatcher) {
+        fileWatcher.addSseClient(res);
+        req.on("close", () => fileWatcher.removeSseClient(res));
+      }
+      return;
+    }
 
     if (url.pathname === "/") {
       // Always serve the built React app from dist/
@@ -576,11 +618,16 @@ function createRequestHandler(workspaceDir, htmlContent, opts = {}) {
             typeof body.apiKey === "string" && body.apiKey.trim()
               ? "false"
               : "true",
-        };
-        const saveResult = saveLocalUiSetup(payload);
-        if (cfg) {
-          cfg.apiKey = payload.ECHOMEM_API_KEY.trim();
-          cfg.localOnlyMode = payload.ECHOMEM_LOCAL_ONLY_MODE === "true";
+        };
+        const saveResult = saveLocalUiSetup(payload);
+        if (saveResult.migratedFrom) {
+          logger?.info?.(
+            `[echo-memory] Migrated local UI setup from ${saveResult.migratedFrom} to ${saveResult.targetPath}`,
+          );
+        }
+        if (cfg) {
+          cfg.apiKey = payload.ECHOMEM_API_KEY.trim();
+          cfg.localOnlyMode = payload.ECHOMEM_LOCAL_ONLY_MODE === "true";
           cfg.memoryDir = payload.ECHOMEM_MEMORY_DIR.trim() || cfg.memoryDir;
         }
         sendJson(res, {
@@ -794,15 +841,16 @@ function createRequestHandler(workspaceDir, htmlContent, opts = {}) {
   };
 }
 
-export async function startLocalServer(workspaceDir, opts = {}) {
-  if (_instance) {
-    return _instance.url;
-  }
-
-  await ensureLocalUiReady(opts.cfg, opts.logger);
-  const htmlContent = await fs.readFile(UI_HTML_PATH, "utf8");
-  const fileWatcher = createFileWatcher(workspaceDir);
-  const unsubscribeSyncProgress = typeof opts.syncRunner?.onProgress === "function"
+export async function startLocalServer(workspaceDir, opts = {}) {
+  if (_instance) {
+    return _instance.url;
+  }
+
+  await ensureLocalUiReady(opts.cfg, opts.logger);
+  const htmlContent = await fs.readFile(UI_HTML_PATH, "utf8");
+  const fileWatcher = createFileWatcher(workspaceDir);
+  const serverInstanceId = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+  const unsubscribeSyncProgress = typeof opts.syncRunner?.onProgress === "function"
     ? opts.syncRunner.onProgress((event) => {
         const mapPath = (targetPath) => {
           if (!targetPath) return null;
@@ -832,8 +880,8 @@ export async function startLocalServer(workspaceDir, opts = {}) {
         });
       })
     : null;
-  const handler = createRequestHandler(workspaceDir, htmlContent, { ...opts, fileWatcher });
-  const server = http.createServer(handler);
+  const handler = createRequestHandler(workspaceDir, htmlContent, { ...opts, fileWatcher, serverInstanceId });
+  const server = http.createServer(handler);
 
   let port = null;
   for (let attempt = 0; attempt < 3; attempt++) {
@@ -849,11 +897,15 @@ export async function startLocalServer(workspaceDir, opts = {}) {
     fileWatcher.close();
     throw new Error(`Could not bind to ports ${BASE_PORT}–${BASE_PORT + 2}. All in use.`);
   }
-
-  const url = `http://127.0.0.1:${port}`;
-  _instance = { server, url, fileWatcher, unsubscribeSyncProgress };
-  return url;
-}
+
+  const url = `http://127.0.0.1:${port}`;
+  _instance = { server, url, fileWatcher, unsubscribeSyncProgress, serverInstanceId };
+  return url;
+}
+
+export async function waitForLocalUiClient({ timeoutMs = 0 } = {}) {
+  return _instance?.fileWatcher?.waitForClient(timeoutMs) ?? false;
+}
 
 export function stopLocalServer() {
   if (_instance) {