memory-braid 0.2.0 → 0.3.3

package/src/index.ts

@@ -5,6 +5,7 @@ import type {
 } from "openclaw/plugin-sdk";
 import { parseConfig, pluginConfigSchema } from "./config.js";
 import { stagedDedupe } from "./dedupe.js";
+import { EntityExtractionManager } from "./entities.js";
 import { extractCandidates } from "./extract.js";
 import { MemoryBraidLogger } from "./logger.js";
 import { resolveLocalTools, runLocalGet, runLocalSearch } from "./local-memory.js";
@@ -75,6 +76,25 @@ function formatRelevantMemories(results: MemoryBraidResult[], maxChars = 600): s
   ].join("\n");
 }
 
+function formatEntityExtractionStatus(params: {
+  enabled: boolean;
+  provider: string;
+  model: string;
+  minScore: number;
+  maxEntitiesPerMemory: number;
+  cacheDir: string;
+}): string {
+  return [
+    "Memory Braid entity extraction:",
+    `- enabled: ${params.enabled}`,
+    `- provider: ${params.provider}`,
+    `- model: ${params.model}`,
+    `- minScore: ${params.minScore}`,
+    `- maxEntitiesPerMemory: ${params.maxEntitiesPerMemory}`,
+    `- cacheDir: ${params.cacheDir}`,
+  ].join("\n");
+}
+
 async function runHybridRecall(params: {
   api: OpenClawPluginApi;
   cfg: ReturnType<typeof parseConfig>;
@@ -94,6 +114,13 @@ async function runHybridRecall(params: {
 }> {
   const local = resolveLocalTools(params.api, params.ctx);
   if (!local.searchTool) {
+    params.log.warn("memory_braid.search.skip", {
+      runId: params.runId,
+      reason: "local_search_tool_unavailable",
+      agentId: params.ctx.agentId,
+      sessionKey: params.ctx.sessionKey,
+      workspaceHash: workspaceHashFromDir(params.ctx.workspaceDir),
+    });
     return { local: [], mem0: [], merged: [] };
   }
 
@@ -190,6 +217,9 @@ const memoryBraidPlugin = {
     const log = new MemoryBraidLogger(api.logger, cfg.debug);
     const initialStateDir = api.runtime.state.resolveStateDir();
     const mem0 = new Mem0Adapter(cfg, log, { stateDir: initialStateDir });
+    const entityExtraction = new EntityExtractionManager(cfg.entityExtraction, log, {
+      stateDir: initialStateDir,
+    });
 
     let serviceTimer: NodeJS.Timeout | null = null;
     let statePaths: StatePaths | null = null;
@@ -288,6 +318,61 @@ const memoryBraidPlugin = {
       { names: ["memory_search", "memory_get"] },
     );
 
+    api.registerCommand({
+      name: "memorybraid",
+      description: "Memory Braid status and entity extraction warmup.",
+      acceptsArgs: true,
+      handler: async (ctx) => {
+        const args = ctx.args?.trim() ?? "";
+        const tokens = args.split(/\s+/).filter(Boolean);
+        const action = (tokens[0] ?? "status").toLowerCase();
+
+        if (action === "status") {
+          return {
+            text: [
+              `capture.mode: ${cfg.capture.mode}`,
+              formatEntityExtractionStatus(entityExtraction.getStatus()),
+            ].join("\n\n"),
+          };
+        }
+
+        if (action === "warmup") {
+          const runId = log.newRunId();
+          const forceReload = tokens.some((token) => token === "--force");
+          const result = await entityExtraction.warmup({
+            runId,
+            reason: "command",
+            forceReload,
+          });
+          if (!result.ok) {
+            return {
+              text: [
+                "Entity extraction warmup failed.",
+                `- model: ${result.model}`,
+                `- cacheDir: ${result.cacheDir}`,
+                `- durMs: ${result.durMs}`,
+                `- error: ${result.error ?? "unknown"}`,
+              ].join("\n"),
+              isError: true,
+            };
+          }
+          return {
+            text: [
+              "Entity extraction warmup complete.",
+              `- model: ${result.model}`,
+              `- cacheDir: ${result.cacheDir}`,
+              `- entities: ${result.entities}`,
+              `- durMs: ${result.durMs}`,
+            ].join("\n"),
+          };
+        }
+
+        return {
+          text: "Usage: /memorybraid [status|warmup [--force]]",
+        };
+      },
+    });
+
     api.on("before_agent_start", async (event, ctx) => {
       const runId = log.newRunId();
       const toolCtx: OpenClawPluginToolContext = {
@@ -375,14 +460,21 @@ const memoryBraidPlugin = {
       }
 
       let persisted = 0;
+      let dedupeSkipped = 0;
+      let entityAnnotatedCandidates = 0;
+      let totalEntitiesAttached = 0;
+      let mem0AddAttempts = 0;
+      let mem0AddWithId = 0;
+      let mem0AddWithoutId = 0;
       for (const candidate of candidates) {
         const hash = sha256(normalizeForHash(candidate.text));
         if (dedupe.seen[hash]) {
+          dedupeSkipped += 1;
           continue;
         }
         dedupe.seen[hash] = now;
 
-        const metadata = {
+        const metadata: Record<string, unknown> = {
           sourceType: "capture",
           workspaceHash: scope.workspaceHash,
           agentId: scope.agentId,
@@ -394,23 +486,59 @@ const memoryBraidPlugin = {
           indexedAt: new Date().toISOString(),
         };
 
-        await mem0.addMemory({
+        if (cfg.entityExtraction.enabled) {
+          const entities = await entityExtraction.extract({
+            text: candidate.text,
+            runId,
+          });
+          if (entities.length > 0) {
+            entityAnnotatedCandidates += 1;
+            totalEntitiesAttached += entities.length;
+            metadata.entityUris = entities.map((entity) => entity.canonicalUri);
+            metadata.entities = entities;
+          }
+        }
+
+        mem0AddAttempts += 1;
+        const addResult = await mem0.addMemory({
           text: candidate.text,
           scope,
           metadata,
           runId,
         });
+        if (addResult.id) {
+          mem0AddWithId += 1;
+        } else {
+          mem0AddWithoutId += 1;
+          log.warn("memory_braid.capture.persist", {
+            runId,
+            reason: "mem0_add_missing_id",
+            workspaceHash: scope.workspaceHash,
+            agentId: scope.agentId,
+            sessionKey: scope.sessionKey,
+            contentHashPrefix: hash.slice(0, 12),
+            category: candidate.category,
+          });
+        }
         persisted += 1;
       }
 
       await writeCaptureDedupeState(statePaths, dedupe);
       log.debug("memory_braid.capture.persist", {
         runId,
+        mode: cfg.capture.mode,
         workspaceHash: scope.workspaceHash,
         agentId: scope.agentId,
         sessionKey: scope.sessionKey,
         candidates: candidates.length,
+        dedupeSkipped,
         persisted,
+        mem0AddAttempts,
+        mem0AddWithId,
+        mem0AddWithoutId,
+        entityExtractionEnabled: cfg.entityExtraction.enabled,
+        entityAnnotatedCandidates,
+        totalEntitiesAttached,
       }, true);
     });
 
@@ -418,6 +546,7 @@ const memoryBraidPlugin = {
       id: "memory-braid-service",
       start: async (ctx) => {
         mem0.setStateDir(ctx.stateDir);
+        entityExtraction.setStateDir(ctx.stateDir);
         statePaths = createStatePaths(ctx.stateDir);
         await ensureStateDir(statePaths);
         targets = await resolveTargets({
@@ -437,6 +566,24 @@ const memoryBraidPlugin = {
           stateDir: ctx.stateDir,
           targets: targets.length,
         });
+        log.info("memory_braid.config", {
+          runId,
+          mem0Mode: cfg.mem0.mode,
+          captureEnabled: cfg.capture.enabled,
+          captureMode: cfg.capture.mode,
+          captureMaxItemsPerRun: cfg.capture.maxItemsPerRun,
+          captureMlProvider: cfg.capture.ml.provider ?? "unset",
+          captureMlModel: cfg.capture.ml.model ?? "unset",
+          entityExtractionEnabled: cfg.entityExtraction.enabled,
+          entityProvider: cfg.entityExtraction.provider,
+          entityModel: cfg.entityExtraction.model,
+          entityMinScore: cfg.entityExtraction.minScore,
+          entityMaxPerMemory: cfg.entityExtraction.maxEntitiesPerMemory,
+          entityWarmupOnStartup: cfg.entityExtraction.startup.downloadOnStartup,
+          debugEnabled: cfg.debug.enabled,
+          debugIncludePayloads: cfg.debug.includePayloads,
+          debugSamplingRate: cfg.debug.logSamplingRate,
+        });
 
         // Bootstrap is async by design so tool availability is not blocked.
         void runBootstrapIfNeeded({
@@ -446,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).
@@ -456,8 +608,30 @@ 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) {
+          void entityExtraction
+            .warmup({
+              runId,
+              reason: "startup",
+            })
+            .catch((err) => {
+              log.warn("memory_braid.entity.warmup", {
+                runId,
+                reason: "startup",
+                error: err instanceof Error ? err.message : String(err),
+              });
+            });
+        }
+
         if (cfg.reconcile.enabled) {
           const intervalMs = cfg.reconcile.intervalMinutes * 60 * 1000;
           serviceTimer = setInterval(() => {

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,30 @@ 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;
+}
+
+export function resolveOssMemoryCtor(moduleValue: unknown): OssMemoryCtor | undefined {
+  if (!moduleValue) {
+    return undefined;
+  }
+
+  const mod = asRecord(moduleValue);
+  const defaultMod = asRecord(mod.default);
+
+  return (
+    asOssMemoryCtor(mod.Memory) ??
+    asOssMemoryCtor(mod.MemoryClient) ??
+    asOssMemoryCtor(defaultMod.Memory) ??
+    asOssMemoryCtor(defaultMod.MemoryClient) ??
+    asOssMemoryCtor(mod.default)
+  );
+}
+
 function resolveStateDir(explicitStateDir?: string): string {
   const resolved =
     explicitStateDir?.trim() ||
@@ -319,10 +345,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;
+}