memory-braid 0.2.0 → 0.3.1

package/README.md

@@ -7,12 +7,157 @@ Memory Braid is an OpenClaw `kind: "memory"` plugin that augments local memory s
 - Hybrid recall: local memory + Mem0, merged with weighted RRF.
 - Install-time bootstrap import: indexes existing `MEMORY.md`, `memory.md`, `memory/**/*.md`, and recent sessions.
 - Periodic reconcile: keeps remote Mem0 chunks updated and deletes stale remote chunks.
-- Capture pipeline: heuristic extraction with optional ML enrichment mode.
+- Capture pipeline modes: `local`, `hybrid`, `ml`.
+- Optional entity extraction: multilingual NER with canonical `entity://...` URIs in memory metadata.
 - Structured debug logs for troubleshooting and tuning.
 
 ## Install
 
-Add this plugin to your OpenClaw plugin load path, then enable it as the active memory plugin.
+### Install from npm (recommended)
+
+On the target machine:
+
+1. Install from npm:
+
+```bash
+openclaw plugins install memory-braid@0.3.0
+```
+
+2. Enable and set as active memory slot:
+
+```bash
+openclaw plugins enable memory-braid
+openclaw config set plugins.slots.memory memory-braid
+```
+
+3. Restart gateway:
+
+```bash
+openclaw gateway restart
+```
+
+4. Confirm plugin is loaded:
+
+```bash
+openclaw plugins info memory-braid
+```
+
+Expected:
+- `Status: loaded`
+- `Tools: memory_search, memory_get`
+- `Services: memory-braid-service`
+
+### Install from local path (development)
+
+```bash
+openclaw plugins install --link /absolute/path/to/memory-braid
+openclaw plugins enable memory-braid
+openclaw config set plugins.slots.memory memory-braid
+openclaw gateway restart
+```
+
+## Quick start: hybrid capture + multilingual NER
+
+Add this under `plugins.entries["memory-braid"].config` in your OpenClaw config:
+
+```json
+{
+  "mem0": {
+    "mode": "oss",
+    "ossConfig": {
+      "version": "v1.1",
+      "embedder": {
+        "provider": "openai",
+        "config": {
+          "apiKey": "${OPENAI_API_KEY}",
+          "model": "text-embedding-3-small"
+        }
+      },
+      "vectorStore": {
+        "provider": "memory",
+        "config": {
+          "collectionName": "memories",
+          "dimension": 1536
+        }
+      },
+      "llm": {
+        "provider": "openai",
+        "config": {
+          "apiKey": "${OPENAI_API_KEY}",
+          "model": "gpt-4o-mini"
+        }
+      },
+      "enableGraph": false
+    }
+  },
+  "capture": {
+    "enabled": true,
+    "mode": "hybrid",
+    "maxItemsPerRun": 6,
+    "ml": {
+      "provider": "openai",
+      "model": "gpt-4o-mini",
+      "timeoutMs": 2500
+    }
+  },
+  "entityExtraction": {
+    "enabled": true,
+    "provider": "multilingual_ner",
+    "model": "Xenova/bert-base-multilingual-cased-ner-hrl",
+    "minScore": 0.65,
+    "maxEntitiesPerMemory": 8,
+    "startup": {
+      "downloadOnStartup": true,
+      "warmupText": "John works at Acme in Berlin."
+    }
+  },
+  "debug": {
+    "enabled": true
+  }
+}
+```
+
+Then restart:
+
+```bash
+openclaw gateway restart
+```
+
+## Verification checklist
+
+1. Check runtime status:
+
+```bash
+openclaw plugins info memory-braid
+openclaw gateway status
+```
+
+2. Trigger/inspect NER warmup:
+
+```bash
+openclaw agent --agent main --message "/memorybraid warmup" --json
+```
+
+3. Send a message that should be captured:
+
+```bash
+openclaw agent --agent main --message "Remember that Ana works at OpenClaw and likes ramen." --json
+```
+
+4. Inspect logs for capture + NER:
+
+```bash
+rg -n "memory_braid\\.startup|memory_braid\\.capture|memory_braid\\.entity|memory_braid\\.mem0" ~/.openclaw/logs/gateway.log | tail -n 80
+```
+
+Expected events:
+- `memory_braid.startup`
+- `memory_braid.entity.model_load`
+- `memory_braid.entity.warmup`
+- `memory_braid.capture.extract`
+- `memory_braid.capture.ml` (for `capture.mode=hybrid|ml`)
+- `memory_braid.entity.extract`
+- `memory_braid.capture.persist`
 
 ## Self-hosting quick guide
 
@@ -241,14 +386,23 @@ Use this preset when:
       },
       "capture": {
         "enabled": true,
-        "extraction": {
-          "mode": "heuristic"
-        },
+        "mode": "hybrid",
+        "maxItemsPerRun": 6,
         "ml": {
           "provider": "openai",
           "model": "gpt-4o-mini",
-          "timeoutMs": 2500,
-          "maxItemsPerRun": 6
+          "timeoutMs": 2500
+        }
+      },
+      "entityExtraction": {
+        "enabled": true,
+        "provider": "multilingual_ner",
+        "model": "Xenova/bert-base-multilingual-cased-ner-hrl",
+        "minScore": 0.65,
+        "maxEntitiesPerMemory": 8,
+        "startup": {
+          "downloadOnStartup": true,
+          "warmupText": "John works at Acme in Berlin."
         }
       },
       "dedupe": {
@@ -266,6 +420,48 @@ Use this preset when:
 }
 ```
 
+## Capture defaults
+
+Capture defaults are:
+
+- `capture.enabled`: `true`
+- `capture.mode`: `"local"`
+- `capture.maxItemsPerRun`: `6`
+- `capture.ml.provider`: unset
+- `capture.ml.model`: unset
+- `capture.ml.timeoutMs`: `2500`
+
+Important behavior:
+
+- `capture.mode = "local"`: heuristic-only extraction.
+- `capture.mode = "hybrid"`: heuristic extraction + ML enrichment when ML config is set.
+- `capture.mode = "ml"`: ML-first extraction; falls back to heuristic if ML config/call is unavailable.
+- ML calls run only when both `capture.ml.provider` and `capture.ml.model` are set.
+
+## Entity extraction defaults
+
+Entity extraction defaults are:
+
+- `entityExtraction.enabled`: `false`
+- `entityExtraction.provider`: `"multilingual_ner"`
+- `entityExtraction.model`: `"Xenova/bert-base-multilingual-cased-ner-hrl"`
+- `entityExtraction.minScore`: `0.65`
+- `entityExtraction.maxEntitiesPerMemory`: `8`
+- `entityExtraction.startup.downloadOnStartup`: `true`
+- `entityExtraction.startup.warmupText`: `"John works at Acme in Berlin."`
+
+When enabled:
+
+- Model cache/download path is `<OPENCLAW_STATE_DIR>/memory-braid/models/entity-extraction` (typically `~/.openclaw/memory-braid/models/entity-extraction`).
+- Captured memories get `metadata.entities` and `metadata.entityUris` (canonical IDs like `entity://person/john-doe`).
+- Startup can pre-download/warm the model (`downloadOnStartup: true`).
+
+Warmup command:
+
+- `/memorybraid status`
+- `/memorybraid warmup`
+- `/memorybraid warmup --force`
+
 ## Debugging
 
 Set:
@@ -285,14 +481,35 @@ Set:
 Key events:
 
 - `memory_braid.startup`
+- `memory_braid.config`
 - `memory_braid.bootstrap.begin|complete|error`
 - `memory_braid.reconcile.begin|progress|complete|error`
-- `memory_braid.search.local|mem0|merge|inject`
+- `memory_braid.search.local|mem0|merge|inject|skip`
 - `memory_braid.capture.extract|ml|persist|skip`
+- `memory_braid.entity.model_load|warmup|extract`
 - `memory_braid.mem0.request|response|error`
 
 `debug.includePayloads=true` includes payload fields; otherwise sensitive text fields are omitted.
 
+Traceability tips:
+
+- Use `runId` to follow one execution end-to-end across capture/search/entity/mem0 events.
+- `memory_braid.capture.persist` includes high-signal counters:
+  - `dedupeSkipped`
+  - `mem0AddAttempts`
+  - `mem0AddWithId`
+  - `mem0AddWithoutId`
+  - `entityAnnotatedCandidates`
+  - `totalEntitiesAttached`
+- `memory_braid.capture.ml` includes `fallbackUsed` and fallback reasons when ML is unavailable.
+- `memory_braid.entity.extract` includes `entityTypes` and `sampleEntityUris`.
+
+Example:
+
+```bash
+rg -n "memory_braid\\.|runId\":\"<RUN_ID>\"" ~/.openclaw/logs/gateway.log | tail -n 120
+```
+
 ## Tests
 
 ```bash

package/openclaw.plugin.json

@@ -47,25 +47,48 @@
         "additionalProperties": false,
         "properties": {
           "enabled": { "type": "boolean", "default": true },
-          "extraction": {
+          "mode": {
+            "type": "string",
+            "enum": ["local", "hybrid", "ml"],
+            "default": "local"
+          },
+          "maxItemsPerRun": { "type": "integer", "minimum": 1, "maximum": 50, "default": 6 },
+          "ml": {
             "type": "object",
             "additionalProperties": false,
             "properties": {
-              "mode": {
-                "type": "string",
-                "enum": ["heuristic", "heuristic_plus_ml"],
-                "default": "heuristic"
-              }
+              "provider": { "type": "string", "enum": ["openai", "anthropic", "gemini"] },
+              "model": { "type": "string" },
+              "timeoutMs": { "type": "integer", "minimum": 250, "maximum": 30000, "default": 2500 }
             }
+          }
+        }
+      },
+      "entityExtraction": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "enabled": { "type": "boolean", "default": false },
+          "provider": {
+            "type": "string",
+            "enum": ["multilingual_ner"],
+            "default": "multilingual_ner"
           },
-          "ml": {
+          "model": {
+            "type": "string",
+            "default": "Xenova/bert-base-multilingual-cased-ner-hrl"
+          },
+          "minScore": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.65 },
+          "maxEntitiesPerMemory": { "type": "integer", "minimum": 1, "maximum": 50, "default": 8 },
+          "startup": {
             "type": "object",
             "additionalProperties": false,
             "properties": {
-              "provider": { "type": "string", "enum": ["openai", "anthropic", "gemini"] },
-              "model": { "type": "string" },
-              "timeoutMs": { "type": "integer", "minimum": 250, "maximum": 30000, "default": 2500 },
-              "maxItemsPerRun": { "type": "integer", "minimum": 1, "maximum": 50, "default": 6 }
+              "downloadOnStartup": { "type": "boolean", "default": true },
+              "warmupText": {
+                "type": "string",
+                "default": "John works at Acme in Berlin."
+              }
             }
           }
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memory-braid",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "OpenClaw memory plugin that augments local memory with Mem0, bootstrap import, reconcile, and capture.",
   "type": "module",
   "main": "./src/index.ts",
@@ -31,6 +31,7 @@
     "openclaw": ">=2026.2.18"
   },
   "dependencies": {
+    "@xenova/transformers": "^2.17.2",
     "mem0ai": "^2.2.3"
   },
   "devDependencies": {

package/src/config.ts

@@ -20,14 +20,23 @@ export type MemoryBraidConfig = {
   };
   capture: {
     enabled: boolean;
-    extraction: {
-      mode: "heuristic" | "heuristic_plus_ml";
-    };
+    mode: "local" | "hybrid" | "ml";
+    maxItemsPerRun: number;
     ml: {
       provider?: "openai" | "anthropic" | "gemini";
       model?: string;
       timeoutMs: number;
-      maxItemsPerRun: number;
+    };
+  };
+  entityExtraction: {
+    enabled: boolean;
+    provider: "multilingual_ner";
+    model: string;
+    minScore: number;
+    maxEntitiesPerMemory: number;
+    startup: {
+      downloadOnStartup: boolean;
+      warmupText: string;
     };
   };
   bootstrap: {
@@ -84,14 +93,23 @@ const DEFAULTS: MemoryBraidConfig = {
   },
   capture: {
     enabled: true,
-    extraction: {
-      mode: "heuristic",
-    },
+    mode: "local",
+    maxItemsPerRun: 6,
     ml: {
       provider: undefined,
       model: undefined,
       timeoutMs: 2500,
-      maxItemsPerRun: 6,
+    },
+  },
+  entityExtraction: {
+    enabled: false,
+    provider: "multilingual_ner",
+    model: "Xenova/bert-base-multilingual-cased-ner-hrl",
+    minScore: 0.65,
+    maxEntitiesPerMemory: 8,
+    startup: {
+      downloadOnStartup: true,
+      warmupText: "John works at Acme in Berlin.",
     },
   },
   bootstrap: {
@@ -160,7 +178,8 @@ export function parseConfig(raw: unknown): MemoryBraidConfig {
   const recall = asRecord(root.recall);
   const merge = asRecord(recall.merge);
   const capture = asRecord(root.capture);
-  const extraction = asRecord(capture.extraction);
+  const entityExtraction = asRecord(root.entityExtraction);
+  const entityStartup = asRecord(entityExtraction.startup);
   const ml = asRecord(capture.ml);
   const bootstrap = asRecord(root.bootstrap);
   const reconcile = asRecord(root.reconcile);
@@ -170,8 +189,11 @@ export function parseConfig(raw: unknown): MemoryBraidConfig {
   const debug = asRecord(root.debug);
 
   const mode = mem0.mode === "oss" ? "oss" : "cloud";
-  const extractionMode =
-    extraction.mode === "heuristic_plus_ml" ? "heuristic_plus_ml" : "heuristic";
+  const rawCaptureMode = asString(capture.mode)?.toLowerCase();
+  const captureMode =
+    rawCaptureMode === "local" || rawCaptureMode === "hybrid" || rawCaptureMode === "ml"
+      ? rawCaptureMode
+      : DEFAULTS.capture.mode;
 
   return {
     enabled: asBoolean(root.enabled, DEFAULTS.enabled),
@@ -195,9 +217,8 @@ export function parseConfig(raw: unknown): MemoryBraidConfig {
     },
     capture: {
       enabled: asBoolean(capture.enabled, DEFAULTS.capture.enabled),
-      extraction: {
-        mode: extractionMode,
-      },
+      mode: captureMode,
+      maxItemsPerRun: asInt(capture.maxItemsPerRun, DEFAULTS.capture.maxItemsPerRun, 1, 50),
       ml: {
         provider:
           ml.provider === "openai" || ml.provider === "anthropic" || ml.provider === "gemini"
@@ -205,7 +226,29 @@ export function parseConfig(raw: unknown): MemoryBraidConfig {
             : DEFAULTS.capture.ml.provider,
         model: asString(ml.model),
         timeoutMs: asInt(ml.timeoutMs, DEFAULTS.capture.ml.timeoutMs, 250, 30_000),
-        maxItemsPerRun: asInt(ml.maxItemsPerRun, DEFAULTS.capture.ml.maxItemsPerRun, 1, 50),
+      },
+    },
+    entityExtraction: {
+      enabled: asBoolean(entityExtraction.enabled, DEFAULTS.entityExtraction.enabled),
+      provider:
+        entityExtraction.provider === "multilingual_ner"
+          ? "multilingual_ner"
+          : DEFAULTS.entityExtraction.provider,
+      model: asString(entityExtraction.model) ?? DEFAULTS.entityExtraction.model,
+      minScore: asNumber(entityExtraction.minScore, DEFAULTS.entityExtraction.minScore, 0, 1),
+      maxEntitiesPerMemory: asInt(
+        entityExtraction.maxEntitiesPerMemory,
+        DEFAULTS.entityExtraction.maxEntitiesPerMemory,
+        1,
+        50,
+      ),
+      startup: {
+        downloadOnStartup: asBoolean(
+          entityStartup.downloadOnStartup,
+          DEFAULTS.entityExtraction.startup.downloadOnStartup,
+        ),
+        warmupText:
+          asString(entityStartup.warmupText) ?? DEFAULTS.entityExtraction.startup.warmupText,
       },
     },
     bootstrap: {

package/src/entities.ts

@@ -0,0 +1,354 @@
+import os from "node:os";
+import path from "node:path";
+import { normalizeWhitespace } from "./chunking.js";
+import type { MemoryBraidConfig } from "./config.js";
+import { MemoryBraidLogger } from "./logger.js";
+
+type NerPipeline = (text: string, options?: Record<string, unknown>) => Promise<unknown>;
+
+type NerRecord = {
+  word?: unknown;
+  entity_group?: unknown;
+  entity?: unknown;
+  score?: unknown;
+};
+
+export type ExtractedEntity = {
+  text: string;
+  type: "person" | "organization" | "location" | "misc";
+  score: number;
+  canonicalUri: string;
+};
+
+function summarizeEntityTypes(entities: ExtractedEntity[]): Record<string, number> {
+  const summary: Record<string, number> = {};
+  for (const entity of entities) {
+    summary[entity.type] = (summary[entity.type] ?? 0) + 1;
+  }
+  return summary;
+}
+
+function resolveStateDir(explicitStateDir?: string): string {
+  const resolved =
+    explicitStateDir?.trim() ||
+    process.env.OPENCLAW_STATE_DIR?.trim() ||
+    path.join(os.homedir(), ".openclaw");
+  return path.resolve(resolved);
+}
+
+export function resolveEntityModelCacheDir(stateDir?: string): string {
+  return path.join(resolveStateDir(stateDir), "memory-braid", "models", "entity-extraction");
+}
+
+function slugify(value: string): string {
+  const ascii = value
+    .normalize("NFKD")
+    .replace(/[\u0300-\u036f]/g, "");
+  const slug = ascii
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return slug || "unknown";
+}
+
+export function buildCanonicalEntityUri(
+  type: ExtractedEntity["type"],
+  text: string,
+): string {
+  return `entity://${type}/${slugify(text)}`;
+}
+
+function normalizeEntityType(raw: unknown): ExtractedEntity["type"] {
+  const label = typeof raw === "string" ? raw.toUpperCase() : "";
+  if (label.includes("PER")) {
+    return "person";
+  }
+  if (label.includes("ORG")) {
+    return "organization";
+  }
+  if (label.includes("LOC") || label.includes("GPE")) {
+    return "location";
+  }
+  return "misc";
+}
+
+function normalizeEntityText(raw: unknown): string {
+  if (typeof raw !== "string") {
+    return "";
+  }
+  return normalizeWhitespace(raw.replace(/^##/, "").replace(/^▁/, ""));
+}
+
+type EntityExtractionOptions = {
+  stateDir?: string;
+};
+
+export class EntityExtractionManager {
+  private readonly cfg: MemoryBraidConfig["entityExtraction"];
+  private readonly log: MemoryBraidLogger;
+  private stateDir?: string;
+  private pipelinePromise: Promise<NerPipeline | null> | null = null;
+
+  constructor(
+    cfg: MemoryBraidConfig["entityExtraction"],
+    log: MemoryBraidLogger,
+    options?: EntityExtractionOptions,
+  ) {
+    this.cfg = cfg;
+    this.log = log;
+    this.stateDir = options?.stateDir;
+  }
+
+  setStateDir(stateDir?: string): void {
+    const next = stateDir?.trim();
+    if (!next || next === this.stateDir) {
+      return;
+    }
+    this.stateDir = next;
+    this.pipelinePromise = null;
+  }
+
+  getStatus(): {
+    enabled: boolean;
+    provider: MemoryBraidConfig["entityExtraction"]["provider"];
+    model: string;
+    minScore: number;
+    maxEntitiesPerMemory: number;
+    cacheDir: string;
+  } {
+    return {
+      enabled: this.cfg.enabled,
+      provider: this.cfg.provider,
+      model: this.cfg.model,
+      minScore: this.cfg.minScore,
+      maxEntitiesPerMemory: this.cfg.maxEntitiesPerMemory,
+      cacheDir: resolveEntityModelCacheDir(this.stateDir),
+    };
+  }
+
+  async warmup(params?: {
+    runId?: string;
+    reason?: string;
+    forceReload?: boolean;
+    text?: string;
+  }): Promise<{
+    ok: boolean;
+    cacheDir: string;
+    model: string;
+    entities: number;
+    durMs: number;
+    error?: string;
+  }> {
+    const startedAt = Date.now();
+    if (!this.cfg.enabled) {
+      return {
+        ok: false,
+        cacheDir: resolveEntityModelCacheDir(this.stateDir),
+        model: this.cfg.model,
+        entities: 0,
+        durMs: Date.now() - startedAt,
+        error: "entity_extraction_disabled",
+      };
+    }
+
+    const pipeline = await this.ensurePipeline(params?.forceReload);
+    if (!pipeline) {
+      return {
+        ok: false,
+        cacheDir: resolveEntityModelCacheDir(this.stateDir),
+        model: this.cfg.model,
+        entities: 0,
+        durMs: Date.now() - startedAt,
+        error: "model_load_failed",
+      };
+    }
+
+    try {
+      const entities = await this.extractWithPipeline({
+        pipeline,
+        text: params?.text ?? this.cfg.startup.warmupText,
+      });
+      this.log.info("memory_braid.entity.warmup", {
+        runId: params?.runId,
+        reason: params?.reason ?? "manual",
+        provider: this.cfg.provider,
+        model: this.cfg.model,
+        cacheDir: resolveEntityModelCacheDir(this.stateDir),
+        entities: entities.length,
+        entityTypes: summarizeEntityTypes(entities),
+        sampleEntityUris: entities.slice(0, 5).map((entry) => entry.canonicalUri),
+        durMs: Date.now() - startedAt,
+      });
+      return {
+        ok: true,
+        cacheDir: resolveEntityModelCacheDir(this.stateDir),
+        model: this.cfg.model,
+        entities: entities.length,
+        durMs: Date.now() - startedAt,
+      };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      this.log.warn("memory_braid.entity.warmup", {
+        runId: params?.runId,
+        reason: params?.reason ?? "manual",
+        provider: this.cfg.provider,
+        model: this.cfg.model,
+        cacheDir: resolveEntityModelCacheDir(this.stateDir),
+        error: message,
+      });
+      return {
+        ok: false,
+        cacheDir: resolveEntityModelCacheDir(this.stateDir),
+        model: this.cfg.model,
+        entities: 0,
+        durMs: Date.now() - startedAt,
+        error: message,
+      };
+    }
+  }
+
+  async extract(params: { text: string; runId?: string }): Promise<ExtractedEntity[]> {
+    if (!this.cfg.enabled) {
+      return [];
+    }
+
+    const text = normalizeWhitespace(params.text);
+    if (!text) {
+      return [];
+    }
+
+    const pipeline = await this.ensurePipeline();
+    if (!pipeline) {
+      return [];
+    }
+
+    try {
+      const entities = await this.extractWithPipeline({ pipeline, text });
+      this.log.debug("memory_braid.entity.extract", {
+        runId: params.runId,
+        provider: this.cfg.provider,
+        model: this.cfg.model,
+        entities: entities.length,
+        entityTypes: summarizeEntityTypes(entities),
+        sampleEntityUris: entities.slice(0, 5).map((entry) => entry.canonicalUri),
+      });
+      return entities;
+    } catch (err) {
+      this.log.warn("memory_braid.entity.extract", {
+        runId: params.runId,
+        provider: this.cfg.provider,
+        model: this.cfg.model,
+        error: err instanceof Error ? err.message : String(err),
+      });
+      return [];
+    }
+  }
+
+  private async ensurePipeline(forceReload = false): Promise<NerPipeline | null> {
+    if (!this.cfg.enabled) {
+      return null;
+    }
+
+    if (forceReload) {
+      this.pipelinePromise = null;
+    }
+
+    if (this.pipelinePromise) {
+      return this.pipelinePromise;
+    }
+
+    this.pipelinePromise = this.loadPipeline();
+    return this.pipelinePromise;
+  }
+
+  private async loadPipeline(): Promise<NerPipeline | null> {
+    const cacheDir = resolveEntityModelCacheDir(this.stateDir);
+    this.log.info("memory_braid.entity.model_load", {
+      provider: this.cfg.provider,
+      model: this.cfg.model,
+      cacheDir,
+    });
+
+    try {
+      const mod = (await import("@xenova/transformers")) as {
+        env?: Record<string, unknown>;
+        pipeline?: (
+          task: string,
+          model: string,
+          options?: Record<string, unknown>,
+        ) => Promise<unknown>;
+      };
+
+      if (!mod.pipeline) {
+        throw new Error("@xenova/transformers pipeline export not found");
+      }
+
+      if (mod.env) {
+        mod.env.cacheDir = cacheDir;
+        mod.env.allowRemoteModels = true;
+        mod.env.allowLocalModels = true;
+        mod.env.useFS = true;
+      }
+
+      const classifier = await mod.pipeline("token-classification", this.cfg.model, {
+        quantized: true,
+      });
+
+      if (typeof classifier !== "function") {
+        throw new Error("token-classification pipeline is not callable");
+      }
+
+      return classifier as NerPipeline;
+    } catch (err) {
+      this.log.error("memory_braid.entity.model_load", {
+        provider: this.cfg.provider,
+        model: this.cfg.model,
+        cacheDir,
+        error: err instanceof Error ? err.message : String(err),
+      });
+      return null;
+    }
+  }
+
+  private async extractWithPipeline(params: {
+    pipeline: NerPipeline;
+    text: string;
+  }): Promise<ExtractedEntity[]> {
+    const raw = await params.pipeline(params.text, {
+      aggregation_strategy: "simple",
+    });
+    const rows = Array.isArray(raw) ? raw : [];
+
+    const deduped = new Map<string, ExtractedEntity>();
+    for (const row of rows) {
+      if (!row || typeof row !== "object") {
+        continue;
+      }
+      const record = row as NerRecord;
+      const entityText = normalizeEntityText(record.word);
+      if (!entityText) {
+        continue;
+      }
+      const score = typeof record.score === "number" ? Math.max(0, Math.min(1, record.score)) : 0;
+      if (score < this.cfg.minScore) {
+        continue;
+      }
+
+      const type = normalizeEntityType(record.entity_group ?? record.entity);
+      const canonicalUri = buildCanonicalEntityUri(type, entityText);
+      const current = deduped.get(canonicalUri);
+      if (!current || score > current.score) {
+        deduped.set(canonicalUri, {
+          text: entityText,
+          type,
+          score,
+          canonicalUri,
+        });
+      }
+    }
+
+    return Array.from(deduped.values())
+      .sort((a, b) => b.score - a.score)
+      .slice(0, this.cfg.maxEntitiesPerMemory);
+  }
+}

package/src/extract.ts

@@ -3,6 +3,8 @@ import type { MemoryBraidConfig } from "./config.js";
 import { MemoryBraidLogger } from "./logger.js";
 import type { ExtractedCandidate } from "./types.js";
 
+type MlProvider = "openai" | "anthropic" | "gemini";
+
 const HEURISTIC_PATTERNS = [
   /remember|remember that|keep in mind|note that/i,
   /i prefer|prefer to|don't like|do not like|hate|love/i,
@@ -145,14 +147,11 @@ function parseJsonObjectArray(raw: string): Array<Record<string, unknown>> {
 }
 
 async function callMlEnrichment(params: {
-  provider: "openai" | "anthropic" | "gemini";
+  provider: MlProvider;
   model: string;
   timeoutMs: number;
   candidates: ExtractedCandidate[];
 }): Promise<Array<Record<string, unknown>>> {
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), params.timeoutMs);
-
   const prompt = [
     "Classify the memory candidates.",
     "Return ONLY JSON array.",
@@ -160,6 +159,52 @@ async function callMlEnrichment(params: {
     "Category one of: preference, decision, fact, task, other.",
     JSON.stringify(params.candidates.map((candidate, index) => ({ index, text: candidate.text }))),
   ].join("\n");
+  return callMlJson({
+    provider: params.provider,
+    model: params.model,
+    timeoutMs: params.timeoutMs,
+    prompt,
+  });
+}
+
+async function callMlExtraction(params: {
+  provider: MlProvider;
+  model: string;
+  timeoutMs: number;
+  maxItems: number;
+  messages: Array<{ role: string; text: string }>;
+}): Promise<Array<Record<string, unknown>>> {
+  const recent = params.messages.slice(-30).map((item) => ({
+    role: item.role,
+    text: item.text,
+  }));
+
+  const prompt = [
+    "Extract durable user memories from this conversation.",
+    "Return ONLY JSON array.",
+    "Each item: {text:string, category:string, score:number}.",
+    "Category one of: preference, decision, fact, task, other.",
+    "Keep each text concise and atomic.",
+    `Maximum items: ${params.maxItems}.`,
+    JSON.stringify(recent),
+  ].join("\n");
+
+  return callMlJson({
+    provider: params.provider,
+    model: params.model,
+    timeoutMs: params.timeoutMs,
+    prompt,
+  });
+}
+
+async function callMlJson(params: {
+  provider: MlProvider;
+  model: string;
+  timeoutMs: number;
+  prompt: string;
+}): Promise<Array<Record<string, unknown>>> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), params.timeoutMs);
 
   try {
     if (params.provider === "openai") {
@@ -183,7 +228,7 @@ async function callMlEnrichment(params: {
             },
             {
               role: "user",
-              content: prompt,
+              content: params.prompt,
             },
           ],
         }),
@@ -212,7 +257,7 @@ async function callMlEnrichment(params: {
           model: params.model,
           max_tokens: 1000,
           temperature: 0,
-          messages: [{ role: "user", content: prompt }],
+          messages: [{ role: "user", content: params.prompt }],
         }),
         signal: controller.signal,
       });
@@ -236,7 +281,7 @@ async function callMlEnrichment(params: {
         },
         body: JSON.stringify({
           generationConfig: { temperature: 0 },
-          contents: [{ role: "user", parts: [{ text: prompt }] }],
+          contents: [{ role: "user", parts: [{ text: params.prompt }] }],
         }),
         signal: controller.signal,
       },
@@ -251,6 +296,19 @@ async function callMlEnrichment(params: {
   }
 }
 
+function normalizeCategory(value: unknown, fallback: ExtractedCandidate["category"] = "other"): ExtractedCandidate["category"] {
+  if (
+    value === "preference" ||
+    value === "decision" ||
+    value === "fact" ||
+    value === "task" ||
+    value === "other"
+  ) {
+    return value;
+  }
+  return fallback;
+}
+
 function applyMlResult(
   candidates: ExtractedCandidate[],
   result: Array<Record<string, unknown>>,
@@ -282,14 +340,7 @@ function applyMlResult(
     if (!keep) {
       continue;
     }
-    const category =
-      ml.category === "preference" ||
-      ml.category === "decision" ||
-      ml.category === "fact" ||
-      ml.category === "task" ||
-      ml.category === "other"
-        ? (ml.category as ExtractedCandidate["category"])
-        : candidate.category;
+    const category = normalizeCategory(ml.category, candidate.category);
     const score = typeof ml.score === "number" ? Math.max(0, Math.min(1, ml.score)) : candidate.score;
     out.push({
       ...candidate,
@@ -301,6 +352,39 @@ function applyMlResult(
   return out;
 }
 
+function applyMlExtractionResult(
+  result: Array<Record<string, unknown>>,
+  maxItems: number,
+): ExtractedCandidate[] {
+  const out: ExtractedCandidate[] = [];
+  const seen = new Set<string>();
+
+  for (const item of result) {
+    const rawText = typeof item.text === "string" ? item.text : "";
+    const text = normalizeWhitespace(rawText);
+    if (!text || text.length < 20 || text.length > 3000) {
+      continue;
+    }
+    const key = sha256(normalizeForHash(text));
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+
+    out.push({
+      text,
+      category: normalizeCategory(item.category),
+      score: typeof item.score === "number" ? Math.max(0, Math.min(1, item.score)) : 0.5,
+      source: "ml",
+    });
+    if (out.length >= maxItems) {
+      break;
+    }
+  }
+
+  return out;
+}
+
 export async function extractCandidates(params: {
   messages: unknown[];
   cfg: MemoryBraidConfig;
@@ -308,43 +392,86 @@ export async function extractCandidates(params: {
   runId?: string;
 }): Promise<ExtractedCandidate[]> {
   const normalized = normalizeMessages(params.messages);
-  const heuristic = pickHeuristicCandidates(normalized, params.cfg.capture.ml.maxItemsPerRun);
+  const heuristic = pickHeuristicCandidates(normalized, params.cfg.capture.maxItemsPerRun);
 
   params.log.debug("memory_braid.capture.extract", {
     runId: params.runId,
+    mode: params.cfg.capture.mode,
+    maxItemsPerRun: params.cfg.capture.maxItemsPerRun,
     totalMessages: normalized.length,
     heuristicCandidates: heuristic.length,
   });
 
-  if (
-    params.cfg.capture.extraction.mode !== "heuristic_plus_ml" ||
-    !params.cfg.capture.ml.provider ||
-    !params.cfg.capture.ml.model
-  ) {
+  if (params.cfg.capture.mode === "local") {
+    params.log.debug("memory_braid.capture.mode", {
+      runId: params.runId,
+      mode: params.cfg.capture.mode,
+      decision: "heuristic_only",
+      candidates: heuristic.length,
+    });
+    return heuristic;
+  }
+
+  if (!params.cfg.capture.ml.provider || !params.cfg.capture.ml.model) {
+    params.log.warn("memory_braid.capture.ml", {
+      runId: params.runId,
+      reason: "missing_provider_or_model",
+      mode: params.cfg.capture.mode,
+      hasProvider: Boolean(params.cfg.capture.ml.provider),
+      hasModel: Boolean(params.cfg.capture.ml.model),
+      fallback: "heuristic",
+      candidates: heuristic.length,
+    });
     return heuristic;
   }
 
   try {
-    const ml = await callMlEnrichment({
+    if (params.cfg.capture.mode === "hybrid") {
+      const ml = await callMlEnrichment({
+        provider: params.cfg.capture.ml.provider,
+        model: params.cfg.capture.ml.model,
+        timeoutMs: params.cfg.capture.ml.timeoutMs,
+        candidates: heuristic,
+      });
+      const enriched = applyMlResult(heuristic, ml);
+      params.log.debug("memory_braid.capture.ml", {
+        runId: params.runId,
+        mode: params.cfg.capture.mode,
+        provider: params.cfg.capture.ml.provider,
+        model: params.cfg.capture.ml.model,
+        requested: heuristic.length,
+        returned: ml.length,
+        enriched: enriched.length,
+        fallbackUsed: ml.length === 0,
+      });
+      return enriched;
+    }
+
+    const mlExtractedRaw = await callMlExtraction({
       provider: params.cfg.capture.ml.provider,
       model: params.cfg.capture.ml.model,
       timeoutMs: params.cfg.capture.ml.timeoutMs,
-      candidates: heuristic,
+      maxItems: params.cfg.capture.maxItemsPerRun,
+      messages: normalized,
     });
-    const enriched = applyMlResult(heuristic, ml);
+    const mlExtracted = applyMlExtractionResult(mlExtractedRaw, params.cfg.capture.maxItemsPerRun);
     params.log.debug("memory_braid.capture.ml", {
       runId: params.runId,
+      mode: params.cfg.capture.mode,
       provider: params.cfg.capture.ml.provider,
       model: params.cfg.capture.ml.model,
-      requested: heuristic.length,
-      returned: ml.length,
-      enriched: enriched.length,
+      returned: mlExtractedRaw.length,
+      extracted: mlExtracted.length,
+      fallbackUsed: mlExtracted.length === 0,
     });
-    return enriched;
+    return mlExtracted.length > 0 ? mlExtracted : heuristic;
   } catch (err) {
     params.log.warn("memory_braid.capture.ml", {
       runId: params.runId,
+      mode: params.cfg.capture.mode,
       error: err instanceof Error ? err.message : String(err),
+      fallback: "heuristic",
+      candidates: heuristic.length,
     });
     return heuristic;
   }

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({
@@ -458,6 +605,21 @@ const memoryBraidPlugin = {
           reason: "startup",
         });
 
+        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(() => {