memory-braid 0.3.1 → 0.3.4

package/README.md

@@ -20,23 +20,35 @@ On the target machine:
 1. Install from npm:
 
 ```bash
-openclaw plugins install memory-braid@0.3.0
+openclaw plugins install memory-braid@0.3.4
 ```
 
-2. Enable and set as active memory slot:
+2. Rebuild native dependencies inside the installed extension:
+
+```bash
+cd ~/.openclaw/extensions/memory-braid
+npm rebuild sqlite3 sharp
+```
+
+Why this step exists:
+- OpenClaw plugin installs run `npm install --omit=dev --ignore-scripts` for safety.
+- This behavior is currently not user-overridable from `openclaw plugins install`.
+- `memory-braid` needs native artifacts for `sqlite3` (required by Mem0 OSS) and `sharp` (used by `@xenova/transformers`).
+
+3. Enable and set as active memory slot:
 
 ```bash
 openclaw plugins enable memory-braid
 openclaw config set plugins.slots.memory memory-braid
 ```
 
-3. Restart gateway:
+4. Restart gateway:
 
 ```bash
 openclaw gateway restart
 ```
 
-4. Confirm plugin is loaded:
+5. Confirm plugin is loaded:
 
 ```bash
 openclaw plugins info memory-braid
@@ -56,6 +68,19 @@ openclaw config set plugins.slots.memory memory-braid
 openclaw gateway restart
 ```
 
+If you install from npm and see native module errors like:
+
+- `Could not locate the bindings file` (sqlite3)
+- `Cannot find module ... sharp-*.node`
+
+run:
+
+```bash
+cd ~/.openclaw/extensions/memory-braid
+npm rebuild sqlite3 sharp
+openclaw gateway restart
+```
+
 ## Quick start: hybrid capture + multilingual NER
 
 Add this under `plugins.entries["memory-braid"].config` in your OpenClaw config:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memory-braid",
-  "version": "0.3.1",
+  "version": "0.3.4",
   "description": "OpenClaw memory plugin that augments local memory with Mem0, bootstrap import, reconcile, and capture.",
   "type": "module",
   "main": "./src/index.ts",

package/src/index.ts

@@ -593,6 +593,11 @@ const memoryBraidPlugin = {
           log,
           targets,
           runId,
+        }).catch((err) => {
+          log.warn("memory_braid.bootstrap.error", {
+            runId,
+            error: err instanceof Error ? err.message : String(err),
+          });
         });
 
         // One startup reconcile pass (non-blocking).
@@ -603,6 +608,13 @@ const memoryBraidPlugin = {
           log,
           targets,
           reason: "startup",
+          runId,
+        }).catch((err) => {
+          log.warn("memory_braid.reconcile.error", {
+            runId,
+            reason: "startup",
+            error: err instanceof Error ? err.message : String(err),
+          });
         });
 
         if (cfg.entityExtraction.enabled && cfg.entityExtraction.startup.downloadOnStartup) {

package/src/mem0-client.ts

@@ -44,6 +44,8 @@ type OssClientLike = {
   delete: (memoryId: string) => Promise<{ message: string }>;
 };
 
+type OssMemoryCtor = new (config?: Record<string, unknown>) => OssClientLike;
+
 function extractCloudText(memory: CloudRecord): string {
   const byData = memory.data?.memory;
   if (typeof byData === "string" && byData.trim()) {
@@ -102,6 +104,48 @@ function asNonEmptyString(value: unknown): string | undefined {
   return trimmed ? trimmed : undefined;
 }
 
+function asOssMemoryCtor(value: unknown): OssMemoryCtor | undefined {
+  if (typeof value !== "function") {
+    return undefined;
+  }
+  return value as OssMemoryCtor;
+}
+
+function isObjectLike(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function resolveCtorFromCandidate(candidate: unknown, depth = 0): OssMemoryCtor | undefined {
+  if (depth > 6 || !candidate) {
+    return undefined;
+  }
+
+  const direct = asOssMemoryCtor(candidate);
+  if (direct) {
+    return direct;
+  }
+
+  if (!isObjectLike(candidate)) {
+    return undefined;
+  }
+
+  const record = candidate as Record<string, unknown>;
+  return (
+    resolveCtorFromCandidate(record.Memory, depth + 1) ??
+    resolveCtorFromCandidate(record.MemoryClient, depth + 1) ??
+    resolveCtorFromCandidate(record.default, depth + 1)
+  );
+}
+
+export function resolveOssMemoryCtor(moduleValue: unknown): OssMemoryCtor | undefined {
+  return (
+    resolveCtorFromCandidate(moduleValue) ??
+    resolveCtorFromCandidate(asRecord(moduleValue).Memory) ??
+    resolveCtorFromCandidate(asRecord(moduleValue).MemoryClient) ??
+    resolveCtorFromCandidate(asRecord(moduleValue).default)
+  );
+}
+
 function resolveStateDir(explicitStateDir?: string): string {
   const resolved =
     explicitStateDir?.trim() ||
@@ -319,10 +363,13 @@ export class Mem0Adapter {
 
     try {
       const mod = await import("mem0ai/oss");
-      const Memory = (mod as { Memory?: new (config?: Record<string, unknown>) => OssClientLike })
-        .Memory;
+      const Memory = resolveOssMemoryCtor(mod);
       if (!Memory) {
-        throw new Error("mem0ai/oss Memory export not found");
+        const exportKeys = Object.keys(asRecord(mod));
+        const defaultKeys = Object.keys(asRecord(asRecord(mod).default));
+        throw new Error(
+          `mem0ai/oss Memory export not found (exports=${exportKeys.join(",") || "none"}; default=${defaultKeys.join(",") || "none"})`,
+        );
       }
 
       const providedConfig = this.cfg.mem0.ossConfig;

package/src/state.ts

@@ -97,22 +97,38 @@ export async function writeCaptureDedupeState(
 export async function withStateLock<T>(
   lockFilePath: string,
   fn: () => Promise<T>,
-  options?: { retries?: number; retryDelayMs?: number },
+  options?: { retries?: number; retryDelayMs?: number; staleLockMs?: number },
 ): Promise<T> {
   const retries = options?.retries ?? 12;
   const retryDelayMs = options?.retryDelayMs ?? 150;
+  const staleLockMs = options?.staleLockMs ?? 30_000;
   await fs.mkdir(path.dirname(lockFilePath), { recursive: true });
 
   let handle: fs.FileHandle | null = null;
   for (let attempt = 0; attempt <= retries; attempt += 1) {
     try {
       handle = await fs.open(lockFilePath, "wx");
+      await handle.writeFile(
+        `${JSON.stringify({
+          pid: process.pid,
+          startedAt: new Date().toISOString(),
+        })}\n`,
+        "utf8",
+      );
       break;
     } catch (err) {
       const code = (err as { code?: string }).code;
-      if (code !== "EEXIST" || attempt >= retries) {
+      if (code !== "EEXIST") {
         throw err;
       }
+      const recovered = await recoverStaleLock(lockFilePath, staleLockMs);
+      if (recovered) {
+        attempt -= 1;
+        continue;
+      }
+      if (attempt >= retries) {
+        throw new Error(`Failed to acquire lock for ${lockFilePath}: lock file already exists`);
+      }
       await new Promise((resolve) => setTimeout(resolve, retryDelayMs));
     }
   }
@@ -128,3 +144,56 @@ export async function withStateLock<T>(
     await fs.unlink(lockFilePath).catch(() => undefined);
   }
 }
+
+function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    const code = (err as { code?: string }).code;
+    if (code === "ESRCH") {
+      return false;
+    }
+    return true;
+  }
+}
+
+async function recoverStaleLock(lockFilePath: string, staleLockMs: number): Promise<boolean> {
+  let stat: Awaited<ReturnType<typeof fs.stat>>;
+  try {
+    stat = await fs.stat(lockFilePath);
+  } catch {
+    return false;
+  }
+
+  const ageMs = Date.now() - stat.mtimeMs;
+
+  let raw: string | null = null;
+  try {
+    raw = await fs.readFile(lockFilePath, "utf8");
+  } catch {
+    raw = null;
+  }
+
+  if (raw) {
+    try {
+      const parsed = JSON.parse(raw) as { pid?: unknown };
+      if (typeof parsed.pid === "number" && Number.isFinite(parsed.pid)) {
+        if (isProcessAlive(parsed.pid)) {
+          return false;
+        }
+        await fs.unlink(lockFilePath).catch(() => undefined);
+        return true;
+      }
+    } catch {
+      // Legacy lock file format, handled by age-based fallback below.
+    }
+  }
+
+  if (ageMs < staleLockMs) {
+    return false;
+  }
+
+  await fs.unlink(lockFilePath).catch(() => undefined);
+  return true;
+}