@echomem/echo-memory-cloud-openclaw-plugin 0.1.0 → 0.1.1

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.1.0",
+  "version": "0.1.1",
   "kind": "lifecycle",
   "main": "./index.js",
   "configSchema": {

package/index.js

@@ -1,6 +1,6 @@
-#!/usr/bin/env node
-import path from "node:path";
-import { buildConfig, getEnvFileStatus } from "./lib/config.js";
+#!/usr/bin/env node
+import path from "node:path";
+import { buildConfig, getEnvFileStatus } from "./lib/config.js";
 import { createApiClient } from "./lib/api-client.js";
 import { formatSearchResultsText } from "./lib/echo-memory-search.js";
 import {
@@ -46,13 +46,22 @@ export default {
   register(api) {
     const cfg = buildConfig(api.pluginConfig);
     const client = createApiClient(cfg);
+    const workspaceDir = path.resolve(path.dirname(cfg.memoryDir), "..");
+    const openclawHome = path.resolve(workspaceDir, "..");
+    const fallbackStateDir = path.join(openclawHome, "state", "plugins", "echo-memory-cloud-openclaw-plugin");
     const syncRunner = createSyncRunner({
       api,
       cfg,
       client,
+      fallbackStateDir,
     });
-    const workspaceDir = path.resolve(path.dirname(cfg.memoryDir), "..");
     let startupBrowserOpenAttempted = false;
+    let backgroundStarted = false;
+    let serviceStartObserved = false;
+
+    if (!workspaceDir || workspaceDir === "." || workspaceDir === path.sep) {
+      api.logger?.warn?.("[echo-memory] workspace resolution looks unusual; compatibility fallback may be limited");
+    }
 
     async function ensureLocalUi({ openInBrowser = false, trigger = "manual" } = {}) {
       const url = await startLocalServer(workspaceDir, {
@@ -77,223 +86,252 @@ export default {
       return { url, openedInBrowser, openReason };
     }
 
-    api.registerTool(createEchoMemorySearchTool(client));
-    api.registerTool(createEchoMemoryOnboardTool(cfg, resolveCommandLabel("slack")));
-    api.registerTool(createEchoMemoryGraphTool(client, cfg));
-    api.registerTool(createEchoMemoryLocalUiTool({
-      getLocalUiUrl: ensureLocalUi,
-      commandLabel: resolveCommandLabel("slack"),
-    }));
-    api.registerTool(createEchoMemoryStatusTool(client, syncRunner));
-    api.registerTool(createEchoMemorySyncTool(client, syncRunner));
-    api.on("before_prompt_build", (_event, _ctx) => {
-      return {
-        appendSystemContext: [
-          "EchoMem cloud retrieval is available through the `echo_memory_search` tool.",
-          "Echo Memory setup and usage guidance is available through the `echo_memory_onboard` tool.",
-          "Echo memory graph links are available through the `echo_memory_graph_link` tool.",
-          "Echo memory local workspace UI links are available through the `echo_memory_local_ui` tool.",
-          "Echo sync inspection is available through the `echo_memory_status` tool.",
-          "Echo markdown-to-cloud sync is available through the `echo_memory_sync` tool.",
-          "Use it when the conversation asks about prior facts, plans, decisions, dates, preferences, people, or when memory context would improve accuracy.",
-          "Prefer it before answering memory-dependent questions instead of guessing.",
-          "Use `echo_memory_onboard` when the user asks how to install, set up, configure, authenticate, or use the plugin, or asks about signup, API keys, commands, graph access, or troubleshooting.",
-          "Treat any question about becoming a new EchoMemory user, signing up, creating an account, receiving OTP, referral code, API key creation, or configuring the plugin as an onboarding question for `echo_memory_onboard`.",
-          "Do not answer Echo Memory signup, account setup, or plugin setup from generic prior knowledge. Call `echo_memory_onboard` so the OpenClaw-specific signup URL, OTP step, referral code, API key flow, command names, and config details stay exact.",
-          "There is only one onboarding path. Do not try to choose between signup/setup onboarding variants; call `echo_memory_onboard` and return the full authoritative guide.",
-          "Use `echo_memory_graph_link` when the user explicitly asks for the memory graph, cloud graph, graph view, public memories page, or an iditor.com page.",
-          "Use `echo_memory_local_ui` when the user asks to open, view, browse, launch, or get the URL for local memories, markdown files, the workspace viewer, the local UI, or the localhost view.",
-          "Treat `/echo-memory view` as the local localhost markdown viewer command.",
-          "Do not confuse the localhost local workspace UI with the cloud memory graph. The local UI shows local markdown files directly, while graph links open iditor.com pages.",
-          "If the user says 'view my memories' or similar without saying graph/iditor/public, prefer the local workspace UI.",
-          "If the user asks to open the local workspace UI, request `openInBrowser: true` and include the returned localhost URL directly in the reply.",
-          "Use `visibility: private` for the user's personal memory graph login page and `visibility: public` for the shared public memories page at iditor.com/memories.",
-          "Private graph access from OpenClaw intentionally requires a fresh login at iditor.com/login?next=/memory-graph instead of an auto-login bridge link.",
-          "When providing a graph link, include the returned URL directly in the Slack reply.",
-          "Use `echo_memory_status` when the user asks about sync health, import progress, last sync, recent imports, or whether Echo memory is working.",
-          "Use `echo_memory_sync` when the user explicitly asks to sync, refresh, import, upload, or push local markdown memories into Echo cloud.",
-          "If the user reports permission, privacy, authorization, or tool-access restrictions while using Echo Memory in OpenClaw, tell them to set `tools.profile` to `full` in `~/.openclaw/openclaw.json` and restart the gateway.",
-        ].join("\n"),
-      };
-    });
+    if (typeof api.registerTool === "function") {
+      api.registerTool(createEchoMemorySearchTool(client));
+      api.registerTool(createEchoMemoryOnboardTool(cfg, resolveCommandLabel("slack")));
+      api.registerTool(createEchoMemoryGraphTool(client, cfg));
+      api.registerTool(createEchoMemoryLocalUiTool({
+        getLocalUiUrl: ensureLocalUi,
+        commandLabel: resolveCommandLabel("slack"),
+      }));
+      api.registerTool(createEchoMemoryStatusTool(client, syncRunner));
+      api.registerTool(createEchoMemorySyncTool(client, syncRunner));
+    }
+    if (typeof api.on === "function") {
+      api.on("before_prompt_build", (_event, _ctx) => {
+        return {
+          appendSystemContext: [
+            "EchoMem cloud retrieval is available through the `echo_memory_search` tool.",
+            "Echo Memory setup and usage guidance is available through the `echo_memory_onboard` tool.",
+            "Echo memory graph links are available through the `echo_memory_graph_link` tool.",
+            "Echo memory local workspace UI links are available through the `echo_memory_local_ui` tool.",
+            "Echo sync inspection is available through the `echo_memory_status` tool.",
+            "Echo markdown-to-cloud sync is available through the `echo_memory_sync` tool.",
+            "Use it when the conversation asks about prior facts, plans, decisions, dates, preferences, people, or when memory context would improve accuracy.",
+            "Prefer it before answering memory-dependent questions instead of guessing.",
+            "Use `echo_memory_onboard` when the user asks how to install, set up, configure, authenticate, or use the plugin, or asks about signup, API keys, commands, graph access, or troubleshooting.",
+            "Treat any question about becoming a new EchoMemory user, signing up, creating an account, receiving OTP, referral code, API key creation, or configuring the plugin as an onboarding question for `echo_memory_onboard`.",
+            "Do not answer Echo Memory signup, account setup, or plugin setup from generic prior knowledge. Call `echo_memory_onboard` so the OpenClaw-specific signup URL, OTP step, referral code, API key flow, command names, and config details stay exact.",
+            "There is only one onboarding path. Do not try to choose between signup/setup onboarding variants; call `echo_memory_onboard` and return the full authoritative guide.",
+            "Use `echo_memory_graph_link` when the user explicitly asks for the memory graph, cloud graph, graph view, public memories page, or an iditor.com page.",
+            "Use `echo_memory_local_ui` when the user asks to open, view, browse, launch, or get the URL for local memories, markdown files, the workspace viewer, the local UI, or the localhost view.",
+            "Treat `/echo-memory view` as the local localhost markdown viewer command.",
+            "Do not confuse the localhost local workspace UI with the cloud memory graph. The local UI shows local markdown files directly, while graph links open iditor.com pages.",
+            "If the user says 'view my memories' or similar without saying graph/iditor/public, prefer the local workspace UI.",
+            "If the user asks to open the local workspace UI, request `openInBrowser: true` and include the returned localhost URL directly in the reply.",
+            "Use `visibility: private` for the user's personal memory graph login page and `visibility: public` for the shared public memories page at iditor.com/memories.",
+            "Private graph access from OpenClaw intentionally requires a fresh login at iditor.com/login?next=/memory-graph instead of an auto-login bridge link.",
+            "When providing a graph link, include the returned URL directly in the Slack reply.",
+            "Use `echo_memory_status` when the user asks about sync health, import progress, last sync, recent imports, or whether Echo memory is working.",
+            "Use `echo_memory_sync` when the user explicitly asks to sync, refresh, import, upload, or push local markdown memories into Echo cloud.",
+            "If the user reports permission, privacy, authorization, or tool-access restrictions while using Echo Memory in OpenClaw, tell them to set `tools.profile` to `full` in `~/.openclaw/openclaw.json` and restart the gateway.",
+          ].join("\n"),
+        };
+      });
+    }
 
     const envStatus = getEnvFileStatus();
-    if (!envStatus.found) {
-      api.logger?.warn?.(
-        `[echo-memory] No .env file found in ${envStatus.searchPaths.join(", ")}. Using plugin config or process env.`,
-      );
-    }
-
-    api.registerService({
-      id: "echo-memory-cloud-openclaw-sync",
-      start: async (ctx) => {
-        await syncRunner.initialize(ctx.stateDir);
+    if (!envStatus.found) {
+      api.logger?.warn?.(
+        `[echo-memory] No .env file found in ${envStatus.searchPaths.join(", ")}. Using plugin config or process env.`,
+      );
+    }
 
-        try {
-          const shouldOpenBrowser = cfg.localUiAutoOpenOnGatewayStart && !startupBrowserOpenAttempted;
-          const { url, openedInBrowser, openReason } = await ensureLocalUi({
-            openInBrowser: shouldOpenBrowser,
-            trigger: "gateway-start",
-          });
-          api.logger?.info?.(`[echo-memory] Local workspace viewer: ${url}`);
-          if (shouldOpenBrowser) {
-            startupBrowserOpenAttempted = true;
-            if (openedInBrowser) {
-              api.logger?.info?.("[echo-memory] Opened local workspace viewer in the default browser");
-            } else {
-              api.logger?.info?.(`[echo-memory] Skipped browser auto-open (${openReason})`);
-            }
+    async function startBackgroundFeatures({ stateDir = null, trigger = "service" } = {}) {
+      if (backgroundStarted) {
+        return;
+      }
+      backgroundStarted = true;
+      await syncRunner.initialize(stateDir || fallbackStateDir);
+
+      try {
+        const shouldOpenBrowser = cfg.localUiAutoOpenOnGatewayStart && !startupBrowserOpenAttempted;
+        const { url, openedInBrowser, openReason } = await ensureLocalUi({
+          openInBrowser: shouldOpenBrowser,
+          trigger: trigger === "service" ? "gateway-start" : trigger,
+        });
+        api.logger?.info?.(`[echo-memory] Local workspace viewer: ${url}`);
+        if (shouldOpenBrowser) {
+          startupBrowserOpenAttempted = true;
+          if (openedInBrowser) {
+            api.logger?.info?.("[echo-memory] Opened local workspace viewer in the default browser");
+          } else {
+            api.logger?.info?.(`[echo-memory] Skipped browser auto-open (${openReason})`);
           }
-        } catch (error) {
-          api.logger?.warn?.(`[echo-memory] local server failed: ${String(error?.message ?? error)}`);
         }
-
-        if (!cfg.autoSync) {
-          api.logger?.info?.("[echo-memory] autoSync disabled");
-          return;
-        }
-
-        await syncRunner.runSync("startup").catch((error) => {
-          api.logger?.warn?.(`[echo-memory] startup sync failed: ${String(error?.message ?? error)}`);
-        });
-
-        syncRunner.startInterval();
-      },
-      stop: async () => {
-        syncRunner.stopInterval();
-        stopLocalServer();
-      },
-    });
-
-    api.registerCommand({
-      name: "echo-memory",
-      description: "Sync and search OpenClaw markdown memories through Echo cloud.",
-      acceptsArgs: true,
-      handler: async (ctx) => {
-        const { action, actionArgs } = parseCommandArgs(ctx.args);
-        const commandLabel = resolveCommandLabel(ctx.channel);
+      } catch (error) {
+        api.logger?.warn?.(`[echo-memory] local server failed: ${String(error?.message ?? error)}`);
+      }
+
+      if (!cfg.autoSync) {
+        api.logger?.info?.("[echo-memory] autoSync disabled");
+        return;
+      }
+
+      await syncRunner.runSync(trigger === "service" ? "startup" : trigger).catch((error) => {
+        api.logger?.warn?.(`[echo-memory] startup sync failed: ${String(error?.message ?? error)}`);
+      });
+
+      syncRunner.startInterval();
+    }
+
+    if (typeof api.registerService === "function") {
+      api.registerService({
+        id: "echo-memory-cloud-openclaw-sync",
+        start: async (ctx) => {
+          serviceStartObserved = true;
+          await startBackgroundFeatures({ stateDir: ctx?.stateDir || null, trigger: "service" });
+        },
+        stop: async () => {
+          syncRunner.stopInterval();
+          stopLocalServer();
+          backgroundStarted = false;
+        },
+      });
+    }
+
+    // Compatibility fallback for older hosts that discover the plugin but do not
+    // reliably auto-start registered background services.
+    queueMicrotask(() => {
+      if (serviceStartObserved) {
+        return;
+      }
+      startBackgroundFeatures({ stateDir: fallbackStateDir, trigger: "compat-startup" }).catch((error) => {
+        api.logger?.warn?.(`[echo-memory] compatibility startup failed: ${String(error?.message ?? error)}`);
+      });
+    });
+
+    if (typeof api.registerCommand === "function") {
+      api.registerCommand({
+        name: "echo-memory",
+        description: "Sync and search OpenClaw markdown memories through Echo cloud.",
+        acceptsArgs: true,
+        handler: async (ctx) => {
+          const { action, actionArgs } = parseCommandArgs(ctx.args);
+          const commandLabel = resolveCommandLabel(ctx.channel);
+
+          if (action === "view") {
+            const { url, openedInBrowser } = await ensureLocalUi({
+              openInBrowser: true,
+              trigger: "command",
+            });
+            return {
+              text: [
+                `Open your workspace: ${url}`,
+                openedInBrowser
+                  ? "The default browser was opened on this machine."
+                  : "Open the URL manually if the browser did not launch automatically.",
+                "",
+                "This local UI reads your markdown files directly on localhost. All files stay local until you choose to sync.",
+                `For EchoMemory account signup or plugin onboarding, run ${commandLabel} onboard.`,
+              ].join("\n"),
+            };
+          }
+
+          if (action === "help") {
+            return {
+              text: [
+                "Echo Memory commands:",
+                "",
+                `${commandLabel} onboard`,
+                `${commandLabel} view`,
+                `${commandLabel} status`,
+                `${commandLabel} search <query>`,
+                `${commandLabel} graph`,
+                `${commandLabel} graph public`,
+                `${commandLabel} sync`,
+                `${commandLabel} whoami`,
+                `${commandLabel} help`,
+              ].join("\n"),
+            };
+          }
+
+          if (action === "whoami") {
+            const whoami = await client.whoami();
+            return {
+              text: [
+                "Echo identity:",
+                `- user_id: ${whoami.user_id}`,
+                `- token_type: ${whoami.token_type}`,
+                `- scopes: ${Array.isArray(whoami.scopes) ? whoami.scopes.join(", ") : "(none)"}`,
+              ].join("\n"),
+            };
+          }
+
+          if (action === "onboard") {
+            const guide = buildOnboardingText({
+              commandLabel,
+              cfg,
+            });
+            return { text: guide.text };
+          }
+
+          if (action === "sync") {
+            const result = await syncRunner.runSync("manual");
+            return { text: formatStatusText(result) };
+          }
+
+          if (action === "search") {
+            if (!actionArgs) {
+              return {
+                text: [
+                  "Missing search query.",
+                  `Usage: ${commandLabel} search <query>`,
+                ].join("\n"),
+              };
+            }
+
+            const payload = await client.searchMemories({
+              query: actionArgs,
+              similarityThreshold: 0.3,
+            });
+            return {
+              text: formatSearchResultsText(actionArgs, payload),
+            };
+          }
+
+          if (action === "graph") {
+            const graphMode = String(actionArgs || "").trim().toLowerCase();
+
+            if (!graphMode || graphMode === "private") {
+              const url = buildPrivateGraphLoginUrl(cfg);
+              return {
+                text: [
+                  "Log in again to open your private memory graph:",
+                  url,
+                  "This intentionally requires a fresh web login for security.",
+                ].filter(Boolean).join("\n"),
+              };
+            }
+
+            if (graphMode === "public") {
+              return {
+                text: [
+                  "Open the public memory page:",
+                  `${cfg.webBaseUrl}/memories`,
+                ].join("\n"),
+              };
+            }
+
+            return {
+              text: [
+                "Unknown graph mode.",
+                `Usage: ${commandLabel} graph`,
+                `Usage: ${commandLabel} graph public`,
+              ].join("\n"),
+            };
+          }
+
+          const [localState, remoteStatus] = await Promise.all([
+            readLastSyncState(syncRunner.getStatePath()),
+            client.getImportStatus().catch(() => null),
+          ]);
 
-        if (action === "view") {
-          const { url, openedInBrowser } = await ensureLocalUi({
-            openInBrowser: true,
-            trigger: "command",
-          });
           return {
-            text: [
-              `Open your workspace: ${url}`,
-              openedInBrowser
-                ? "The default browser was opened on this machine."
-                : "Open the URL manually if the browser did not launch automatically.",
-              "",
-              "This local UI reads your markdown files directly on localhost. All files stay local until you choose to sync.",
-              `For EchoMemory account signup or plugin onboarding, run ${commandLabel} onboard.`,
-            ].join("\n"),
-          };
-        }
-
-        if (action === "help") {
-          return {
-            text: [
-              "Echo Memory commands:",
-              "",
-              `${commandLabel} onboard`,
-              `${commandLabel} view`,
-              `${commandLabel} status`,
-              `${commandLabel} search <query>`,
-              `${commandLabel} graph`,
-              `${commandLabel} graph public`,
-              `${commandLabel} sync`,
-              `${commandLabel} whoami`,
-              `${commandLabel} help`,
-            ].join("\n"),
-          };
-        }
-
-        if (action === "whoami") {
-          const whoami = await client.whoami();
-          return {
-            text: [
-              "Echo identity:",
-              `- user_id: ${whoami.user_id}`,
-              `- token_type: ${whoami.token_type}`,
-              `- scopes: ${Array.isArray(whoami.scopes) ? whoami.scopes.join(", ") : "(none)"}`,
-            ].join("\n"),
-          };
-        }
-
-        if (action === "onboard") {
-          const guide = buildOnboardingText({
-            commandLabel,
-            cfg,
-          });
-          return { text: guide.text };
-        }
-
-        if (action === "sync") {
-          const result = await syncRunner.runSync("manual");
-          return { text: formatStatusText(result) };
-        }
-
-        if (action === "search") {
-          if (!actionArgs) {
-            return {
-              text: [
-                "Missing search query.",
-                `Usage: ${commandLabel} search <query>`,
-              ].join("\n"),
-            };
-          }
-
-          const payload = await client.searchMemories({
-            query: actionArgs,
-            similarityThreshold: 0.3,
-          });
-          return {
-            text: formatSearchResultsText(actionArgs, payload),
-          };
-        }
-
-        if (action === "graph") {
-          const graphMode = String(actionArgs || "").trim().toLowerCase();
-
-          if (!graphMode || graphMode === "private") {
-            const url = buildPrivateGraphLoginUrl(cfg);
-            return {
-              text: [
-                "Log in again to open your private memory graph:",
-                url,
-                "This intentionally requires a fresh web login for security.",
-              ].filter(Boolean).join("\n"),
-            };
-          }
-
-          if (graphMode === "public") {
-            return {
-              text: [
-                "Open the public memory page:",
-                `${cfg.webBaseUrl}/memories`,
-              ].join("\n"),
-            };
-          }
-
-          return {
-            text: [
-              "Unknown graph mode.",
-              `Usage: ${commandLabel} graph`,
-              `Usage: ${commandLabel} graph public`,
-            ].join("\n"),
+            text: formatStatusText(localState, remoteStatus),
           };
-        }
-
-        const [localState, remoteStatus] = await Promise.all([
-          readLastSyncState(syncRunner.getStatePath()),
-          client.getImportStatus().catch(() => null),
-        ]);
-
-        return {
-          text: formatStatusText(localState, remoteStatus),
-        };
-      },
-    });
-  },
-};
+        },
+      });
+    }
+  },
+};

package/lib/local-server.js

@@ -255,21 +255,44 @@ export async function openUrlInDefaultBrowser(url, opts = {}) {
   }
 }
 
-function readBody(req) {
-  return new Promise((resolve, reject) => {
-    const chunks = [];
-    req.on("data", (c) => chunks.push(c));
-    req.on("end", () => {
-      try { resolve(JSON.parse(Buffer.concat(chunks).toString("utf8"))); }
-      catch { resolve({}); }
-    });
-    req.on("error", reject);
-  });
-}
-
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on("data", (c) => chunks.push(c));
+    req.on("end", () => {
+      const rawText = Buffer.concat(chunks).toString("utf8");
+      if (!rawText.trim()) {
+        resolve({
+          ok: true,
+          body: {},
+          rawText,
+          parseError: null,
+        });
+        return;
+      }
+      try {
+        resolve({
+          ok: true,
+          body: JSON.parse(rawText),
+          rawText,
+          parseError: null,
+        });
+      } catch (error) {
+        resolve({
+          ok: false,
+          body: null,
+          rawText,
+          parseError: String(error?.message ?? error),
+        });
+      }
+    });
+    req.on("error", reject);
+  });
+}
+
 function createRequestHandler(workspaceDir, htmlContent, opts = {}) {
   const normalizedBase = path.resolve(workspaceDir) + path.sep;
-  const { apiClient, syncRunner, cfg, fileWatcher } = opts;
+  const { apiClient, syncRunner, cfg, fileWatcher, logger } = opts;
   const syncMemoryDir = cfg?.memoryDir ? path.resolve(cfg.memoryDir) : null;
 
   return async function handler(req, res) {
@@ -420,7 +443,20 @@ function createRequestHandler(workspaceDir, htmlContent, opts = {}) {
 
     if (url.pathname === "/api/setup-config" && req.method === "POST") {
       try {
-        const body = await readBody(req);
+        const bodyResult = await readBody(req);
+        if (!bodyResult.ok) {
+          logger?.warn?.(
+            `[echo-memory] invalid JSON for ${url.pathname}: ${bodyResult.parseError}; body=${JSON.stringify(bodyResult.rawText.slice(0, 400))}`,
+          );
+          res.writeHead(400, { "Content-Type": "application/json; charset=utf-8" });
+          res.end(JSON.stringify({
+            ok: false,
+            error: "Invalid JSON body",
+            details: bodyResult.parseError,
+          }));
+          return;
+        }
+        const body = bodyResult.body;
         const payload = {
           ECHOMEM_API_KEY: typeof body.apiKey === "string" ? body.apiKey : "",
           ECHOMEM_MEMORY_DIR: typeof body.memoryDir === "string" ? body.memoryDir : "",
@@ -591,30 +627,68 @@ function createRequestHandler(workspaceDir, htmlContent, opts = {}) {
       return;
     }
 
-    if (url.pathname === "/api/sync-selected" && req.method === "POST") {
+    if (url.pathname === "/api/sync-selected" && req.method === "POST") {
       if (!syncRunner) {
         res.writeHead(400, { "Content-Type": "application/json" });
         res.end(JSON.stringify({ error: "Sync not available" }));
         return;
       }
       try {
-        const body = await readBody(req);
+        const bodyResult = await readBody(req);
+        if (!bodyResult.ok) {
+          logger?.warn?.(
+            `[echo-memory] invalid JSON for ${url.pathname}: ${bodyResult.parseError}; body=${JSON.stringify(bodyResult.rawText.slice(0, 400))}`,
+          );
+          res.writeHead(400, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({
+            error: "Invalid JSON body for sync-selected",
+            details: bodyResult.parseError,
+            receivedBodyPreview: bodyResult.rawText.slice(0, 400),
+          }));
+          return;
+        }
+
+        const body = bodyResult.body;
         const relativePaths = body.paths;
-        if (!Array.isArray(relativePaths) || relativePaths.length === 0) {
-          res.writeHead(400, { "Content-Type": "application/json" });
-          res.end(JSON.stringify({ error: "paths array required" }));
-          return;
-        }
-
+        if (!Array.isArray(relativePaths) || relativePaths.length === 0) {
+          logger?.warn?.(
+            `[echo-memory] invalid sync-selected payload: expected non-empty paths array; body=${JSON.stringify(body).slice(0, 400)}`,
+          );
+          res.writeHead(400, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({
+            error: "paths array required",
+            details: "Expected request body like {\"paths\":[\"memory/2026-03-17.md\"]}",
+            receivedBody: body,
+          }));
+          return;
+        }
+
         const filterPaths = new Set();
+        const invalidPaths = [];
         for (const rp of relativePaths) {
+          if (typeof rp !== "string" || !rp.trim()) {
+            invalidPaths.push(rp);
+            continue;
+          }
           const absPath = path.resolve(workspaceDir, rp);
-          if (!absPath.startsWith(path.resolve(workspaceDir) + path.sep) || !absPath.endsWith(".md")) continue;
+          if (!absPath.startsWith(path.resolve(workspaceDir) + path.sep) || !absPath.endsWith(".md")) {
+            invalidPaths.push(rp);
+            continue;
+          }
           filterPaths.add(absPath);
         }
 
         if (filterPaths.size === 0) {
-          sendJson(res, { trigger: "local-ui-selected", summary: { file_count: 0 }, results: [] });
+          logger?.warn?.(
+            `[echo-memory] sync-selected contained no valid markdown paths; requested=${JSON.stringify(relativePaths).slice(0, 400)}`,
+          );
+          res.writeHead(400, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({
+            error: "No valid markdown paths to sync",
+            details: "All provided paths were outside the workspace or did not end with .md",
+            invalidPaths,
+            requestedPaths: relativePaths,
+          }));
           return;
         }
         const result = await syncRunner.runSync("local-ui-selected", filterPaths);

package/lib/local-ui/src/App.jsx

@@ -335,8 +335,8 @@ export default function App() {
       setSyncResult({ ok: true, msg: parts.join(' | ') || 'Sync complete' });
       loadSyncStatus();
       loadBackendSources();
-    } catch {
-      setSyncResult({ ok: false, msg: 'Sync failed' });
+    } catch (error) {
+      setSyncResult({ ok: false, msg: String(error?.message || 'Sync failed') });
     } finally {
       setSyncing(false);
     }

package/lib/local-ui/src/sync/api.js

@@ -68,15 +68,16 @@ export async function fetchBackendSources() {
   }
 }
 
-export async function triggerSyncSelected(paths) {
-  const res = await fetch('/api/sync-selected', {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ paths }),
-  });
-  if (!res.ok) throw new Error(`Sync failed: HTTP ${res.status}`);
-  return await res.json();
-}
+export async function triggerSyncSelected(paths) {
+  const res = await fetch('/api/sync-selected', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ paths }),
+  });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(data?.details || data?.error || `Sync failed: HTTP ${res.status}`);
+  return data;
+}
 
 /**
  * Fetch content of a single markdown file.

package/lib/sync.js

@@ -1,5 +1,13 @@
-import { scanOpenClawMemoryDir } from "./openclaw-memory-scan.js";
-import { resolveStatePath, readLastSyncState, writeLastSyncState } from "./state.js";
+import { scanOpenClawMemoryDir } from "./openclaw-memory-scan.js";
+import { resolveStatePath, readLastSyncState, writeLastSyncState } from "./state.js";
+
+function resolveRuntimeStateDir(api, fallbackStateDir = null) {
+  const runtimeStateDir = api?.runtime?.state?.resolveStateDir?.();
+  if (runtimeStateDir) {
+    return runtimeStateDir;
+  }
+  return fallbackStateDir;
+}
 
 function chunk(items, size) {
   const batches = [];
@@ -101,18 +109,29 @@ export function formatStatusText(localState, remoteStatus = null) {
   return lines.join("\n");
 }
 
-export function createSyncRunner({ api, cfg, client }) {
+export function createSyncRunner({ api, cfg, client, fallbackStateDir = null }) {
   let intervalHandle = null;
   let statePath = null;
   let activeRun = null;
   const progressListeners = new Set();
 
-  async function initialize(stateDir) {
-    statePath = resolveStatePath(stateDir || api.runtime.state.resolveStateDir());
-  }
-
+  async function initialize(stateDir) {
+    const resolvedStateDir = stateDir || resolveRuntimeStateDir(api, fallbackStateDir);
+    if (!resolvedStateDir) {
+      throw new Error("Echo memory state directory is unavailable");
+    }
+    statePath = resolveStatePath(resolvedStateDir);
+  }
+
   function getStatePath() {
-    return statePath || resolveStatePath(api.runtime.state.resolveStateDir());
+    if (statePath) {
+      return statePath;
+    }
+    const resolvedStateDir = resolveRuntimeStateDir(api, fallbackStateDir);
+    if (!resolvedStateDir) {
+      throw new Error("Echo memory state directory is unavailable");
+    }
+    return resolveStatePath(resolvedStateDir);
   }
 
   function emitProgress(event) {

package/moltbot.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.1.0",
+  "version": "0.1.1",
   "kind": "lifecycle",
   "main": "./index.js",
   "configSchema": {

package/openclaw.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.1.0",
+  "version": "0.1.1",
   "kind": "lifecycle",
   "main": "./index.js",
   "configSchema": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@echomem/echo-memory-cloud-openclaw-plugin",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "OpenClaw plugin for syncing local markdown memory files to Echo cloud",
   "type": "module",
   "main": "./index.js",