@xdarkicex/openclaw-memory-libravdb 1.6.20 → 1.6.22

package/docs/install.md

@@ -37,7 +37,8 @@ openclaw plugins install @xdarkicex/openclaw-memory-libravdb
 ```
 
 If you use the OpenClaw.ai plugin UI instead of the CLI, install the same
-package and then assign the plugin id `libravdb-memory` to the `memory` slot.
+package and then assign the plugin id `libravdb-memory` to the `memory` and
+`contextEngine` slots.
 
 Activate the plugin in `~/.openclaw/openclaw.json`:
 
@@ -45,7 +46,8 @@ Activate the plugin in `~/.openclaw/openclaw.json`:
 {
   "plugins": {
     "slots": {
-      "memory": "libravdb-memory"
+      "memory": "libravdb-memory",
+      "contextEngine": "libravdb-memory"
     }
   }
 }
@@ -57,7 +59,8 @@ If you run the daemon on a non-default endpoint, add a plugin config:
 {
   "plugins": {
     "slots": {
-      "memory": "libravdb-memory"
+      "memory": "libravdb-memory",
+      "contextEngine": "libravdb-memory"
     },
     "entries": {
       "libravdb-memory": {
@@ -73,7 +76,7 @@ If you run the daemon on a non-default endpoint, add a plugin config:
 
 When `sidecarPath` is set to `"auto"`, the plugin resolves endpoints in this order on macOS/Linux:
 
-1. `LIBRAVDB_RPC_ENDPOINT` if it is set to a valid daemon endpoint
+1. `LIBRAVDB_GRPC_ENDPOINT` if it is set to a valid daemon endpoint
 2. `$HOME/.libravdbd/run/libravdb.sock` if it exists
 3. `/opt/homebrew/var/libravdbd/run/libravdb.sock` if it exists
 4. `/usr/local/var/libravdbd/run/libravdb.sock` if it exists
@@ -81,7 +84,7 @@ When `sidecarPath` is set to `"auto"`, the plugin resolves endpoints in this ord
 
 ## Sidecar Daemon Install
 
-The daemon owns the local database, embeddings, and JSON-RPC endpoint.
+The daemon owns the local database, embeddings, and gRPC endpoint.
 
 Default endpoints:
 
@@ -155,12 +158,68 @@ libravdbd serve
 That mode is useful for debugging or validating a local release asset before
 you wrap it in `brew services`, `systemd`, or `launchd`.
 
+### Containers and Docker
+
+The npm plugin does not start `libravdbd`. In a container, either run a separate
+daemon sidecar or use a small entrypoint wrapper that starts the daemon before
+the OpenClaw gateway.
+
+Keep the daemon assets and database in a mounted volume and point both the
+daemon and plugin at paths inside the container:
+
+```sh
+export LIBRAVDB_GRPC_ENDPOINT=unix:/home/node/.openclaw/libravdbd/run/libravdb.sock
+export LIBRAVDB_DB_PATH=/home/node/.openclaw/libravdbd/data.libravdb
+export LIBRAVDB_ONNX_RUNTIME=/home/node/.openclaw/libravdbd/models/onnxruntime/lib/libonnxruntime.so
+export LIBRAVDB_EMBEDDING_MODEL=/home/node/.openclaw/libravdbd/models/nomic-embed-text-v1.5
+export LIBRAVDB_ONNX_DEVICE=cpu
+libravdbd serve &
+
+# Wait for socket to be ready
+for i in {1..30}; do
+  [ -S "$LIBRAVDB_GRPC_ENDPOINT" ] && break
+  sleep 0.5
+done
+
+node dist/index.js gateway --bind lan --port 18789
+```
+
+Use matching plugin config:
+
+```json
+{
+  "plugins": {
+    "slots": {
+      "memory": "libravdb-memory",
+      "contextEngine": "libravdb-memory"
+    },
+    "entries": {
+      "libravdb-memory": {
+        "enabled": true,
+        "config": {
+          "sidecarPath": "unix:/home/node/.openclaw/libravdbd/run/libravdb.sock",
+          "embeddingBackend": "onnx-local",
+          "embeddingRuntimePath": "/home/node/.openclaw/libravdbd/models/onnxruntime/lib/libonnxruntime.so",
+          "embeddingModelPath": "/home/node/.openclaw/libravdbd/models/nomic-embed-text-v1.5",
+          "onnxDevice": "cpu"
+        }
+      }
+    }
+  }
+}
+```
+
+For public bots, deny manual memory tools unless users are supposed to query the
+store directly. The context engine can still use LibraVDB for recall while
+`memory_search` and `memory_get` remain unavailable to channel users.
+
 ## Lifecycle Management
 
 ### Plugin Lifecycle
 
 - Install the package with `openclaw plugins install`.
-- Activate it by assigning `libravdb-memory` to the `memory` slot.
+- Activate it by assigning `libravdb-memory` to the `memory` and
+  `contextEngine` slots.
 - Update it with your normal OpenClaw plugin update flow.
 - Disable it by removing the slot assignment from `~/.openclaw/openclaw.json`.
 
@@ -185,7 +244,7 @@ openclaw memory status
 Healthy output should show that:
 
 - the daemon answered the local health check
-- the memory slot is active
+- the memory and context-engine slots are active
 - the plugin can read stored counts and runtime settings
 
 If OpenClaw cannot reach the daemon, verify the endpoint first:

package/docs/installation.md

@@ -60,20 +60,22 @@ or run `libravdbd serve` in a terminal for validation.
 
 ## Activation
 
-Assign `libravdb-memory` to the OpenClaw memory slot:
+Assign `libravdb-memory` to the OpenClaw memory and context-engine slots:
 
 ```json
 {
   "plugins": {
     "slots": {
-      "memory": "libravdb-memory"
+      "memory": "libravdb-memory",
+      "contextEngine": "libravdb-memory"
     }
   }
 }
 ```
 
-The plugin registers both memory and context-engine capabilities at runtime;
-current OpenClaw config only needs the `memory` slot assignment.
+The memory slot owns `openclaw memory ...` and memory-runtime calls. The
+context-engine slot enables automatic bootstrap, ingest, after-turn, and recall
+hooks during sessions.
 
 If the daemon uses a non-default endpoint, add `sidecarPath`:
 
@@ -81,7 +83,8 @@ If the daemon uses a non-default endpoint, add `sidecarPath`:
 {
   "plugins": {
     "slots": {
-      "memory": "libravdb-memory"
+      "memory": "libravdb-memory",
+      "contextEngine": "libravdb-memory"
     },
     "entries": {
       "libravdb-memory": {
@@ -97,7 +100,7 @@ If the daemon uses a non-default endpoint, add `sidecarPath`:
 
 When `sidecarPath` is `"auto"`, macOS/Linux endpoint resolution checks:
 
-1. `LIBRAVDB_RPC_ENDPOINT`
+1. `LIBRAVDB_GRPC_ENDPOINT`
 2. `$HOME/.libravdbd/run/libravdb.sock`
 3. `/opt/homebrew/var/libravdbd/run/libravdb.sock`
 4. `/usr/local/var/libravdbd/run/libravdb.sock`
@@ -117,6 +120,59 @@ Default data path:
 $HOME/.libravdbd/data_nomic-embed-text-v1_5.libravdb
 ```
 
+## Container Layout
+
+In Docker, keep the daemon, model assets, socket, logs, and database in the
+same mounted OpenClaw state volume. A typical container-side layout is:
+
+```text
+/home/node/.openclaw/bin/libravdbd
+/home/node/.openclaw/libravdbd/run/libravdb.sock
+/home/node/.openclaw/libravdbd/data.libravdb
+/home/node/.openclaw/libravdbd/models/onnxruntime/lib/libonnxruntime.so
+/home/node/.openclaw/libravdbd/models/nomic-embed-text-v1.5/embedding.json
+```
+
+Start the daemon with explicit local ONNX paths before starting the gateway:
+
+```sh
+LIBRAVDB_GRPC_ENDPOINT=unix:/home/node/.openclaw/libravdbd/run/libravdb.sock \
+LIBRAVDB_DB_PATH=/home/node/.openclaw/libravdbd/data.libravdb \
+LIBRAVDB_ONNX_RUNTIME=/home/node/.openclaw/libravdbd/models/onnxruntime/lib/libonnxruntime.so \
+LIBRAVDB_EMBEDDING_MODEL=/home/node/.openclaw/libravdbd/models/nomic-embed-text-v1.5 \
+LIBRAVDB_ONNX_DEVICE=cpu \
+  /home/node/.openclaw/bin/libravdbd serve
+```
+
+Then configure the plugin with the same socket and asset paths:
+
+```json
+{
+  "plugins": {
+    "slots": {
+      "memory": "libravdb-memory",
+      "contextEngine": "libravdb-memory"
+    },
+    "entries": {
+      "libravdb-memory": {
+        "enabled": true,
+        "config": {
+          "sidecarPath": "unix:/home/node/.openclaw/libravdbd/run/libravdb.sock",
+          "embeddingBackend": "onnx-local",
+          "embeddingRuntimePath": "/home/node/.openclaw/libravdbd/models/onnxruntime/lib/libonnxruntime.so",
+          "embeddingModelPath": "/home/node/.openclaw/libravdbd/models/nomic-embed-text-v1.5",
+          "onnxDevice": "cpu"
+        }
+      }
+    }
+  }
+}
+```
+
+Do not let a container initialize a database with deterministic fallback
+embeddings and later switch the same file to ONNX embeddings. Move the fallback
+database aside first, then let the daemon create a fresh ONNX-backed store.
+
 ## Verification
 
 Run:
@@ -157,6 +213,8 @@ Common causes:
 - `sidecarPath` points at the wrong endpoint
 - ONNX Runtime assets are missing or unpacked in the wrong place
 - a model asset failed checksum validation
+- `embeddingBackend` is set to `onnx-local` but `embeddingRuntimePath` or
+  `embeddingModelPath` is missing from plugin config
 
 Check the daemon first:
 
@@ -171,6 +229,15 @@ For foreground debugging:
 libravdbd serve
 ```
 
+### Deterministic fallback embeddings
+
+If daemon logs mention deterministic fallback mode, the daemon did not find the
+configured ONNX runtime or model manifest. Stop the daemon, set
+`LIBRAVDB_ONNX_RUNTIME` and `LIBRAVDB_EMBEDDING_MODEL`, confirm the model
+directory contains `embedding.json`, then restart. If a database was created
+while fallback mode was active, move that `.libravdb` file and its adjacent
+`.embedding.json` aside before starting with ONNX assets.
+
 ### Incompatible database or embedding profile
 
 If the daemon exits with `database format is incompatible` or `database
@@ -202,9 +269,10 @@ setup, or republish the release with corrected checksums.
 
 ### Default memory still appears active
 
-Confirm that `libravdb-memory` is assigned to `plugins.slots.memory`.
-Without that slot entry, OpenClaw's default memory path can continue to run in
-parallel.
+Confirm that `libravdb-memory` is assigned to both `plugins.slots.memory` and
+`plugins.slots.contextEngine`. Without the memory slot, OpenClaw's default
+memory path can continue to run in parallel. Without the context-engine slot,
+automatic session ingest and recall may not run.
 
 ### Lifecycle journal looks empty
 

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "libravdb-memory",
   "name": "LibraVDB Memory",
   "description": "Persistent vector memory with three-tier hybrid scoring",
-  "version": "1.6.20",
+  "version": "1.6.22",
   "kind": [
     "memory",
     "context-engine"
@@ -19,21 +19,43 @@
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
-    "if": {
-      "properties": {
-        "embeddingBackend": {
-          "const": "remote"
+    "allOf": [
+      {
+        "if": {
+          "properties": {
+            "embeddingBackend": {
+              "const": "remote"
+            }
+          },
+          "required": [
+            "embeddingBackend"
+          ]
+        },
+        "then": {
+          "required": [
+            "embeddingEndpoint"
+          ]
         }
       },
-      "required": [
-        "embeddingBackend"
-      ]
-    },
-    "then": {
-      "required": [
-        "embeddingEndpoint"
-      ]
-    },
+      {
+        "if": {
+          "properties": {
+            "embeddingBackend": {
+              "const": "onnx-local"
+            }
+          },
+          "required": [
+            "embeddingBackend"
+          ]
+        },
+        "then": {
+          "required": [
+            "embeddingRuntimePath",
+            "embeddingModelPath"
+          ]
+        }
+      }
+    ],
     "properties": {
       "dbPath": {
         "type": "string"
@@ -137,7 +159,8 @@
         "type": "number"
       },
       "embeddingRuntimePath": {
-        "type": "string"
+        "type": "string",
+        "description": "Path to the ONNX Runtime library visible to the daemon, for example /opt/homebrew/opt/libravdbd/models/onnxruntime/lib/libonnxruntime.dylib or /home/node/.openclaw/libravdbd/models/onnxruntime/lib/libonnxruntime.so."
       },
       "onnxDevice": {
         "type": "string",
@@ -171,7 +194,8 @@
         "default": "bge-small-en-v1.5"
       },
       "embeddingModelPath": {
-        "type": "string"
+        "type": "string",
+        "description": "Directory visible to the daemon containing embedding.json, model.onnx, and tokenizer.json for the selected embeddingProfile."
       },
       "embeddingTokenizerPath": {
         "type": "string"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xdarkicex/openclaw-memory-libravdb",
-  "version": "1.6.20",
+  "version": "1.6.22",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -79,6 +79,6 @@
   "dependencies": {
     "@connectrpc/connect": "^1.7.0",
     "@connectrpc/connect-node": "^1.7.0",
-    "@xdarkicex/libravdb-contracts": "^0.3.0"
+    "@xdarkicex/libravdb-contracts": "^2.0.8"
   }
 }