fix: auto-install node-llama-cpp for local embeddings (memory_search)

OpenClaw's default memorySearch.provider is 'local', which requires
node-llama-cpp. This optional peer dependency was never auto-installed,
causing memory_search to silently fail for every EverClaw user.

Changes:
- diagnose.sh: Add check A10 (node-llama-cpp detection)
- setup.mjs: Add Stage 5 (auto-install with --skip-embeddings flag)
- install.sh: Add node-llama-cpp check on every install/upgrade
- Dockerfile: Install node-llama-cpp@3.18.1 in production image
- CHANGELOG.md, SKILL.md, README.md: Documentation updates

Detection uses NODE_PATH + require.resolve (CJS) since ESM import()
ignores NODE_PATH. All installs are non-blocking with graceful fallback.

Author: profbernardoj

CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to EverClaw are documented here.
 
+## [UNRELEASED] — Local Embeddings Fix (node-llama-cpp)
+
+### Fixed
+- **Silent `memory_search` failure on all fresh installs** — OpenClaw's default `memorySearch.provider` is `"local"`, which requires `node-llama-cpp`. This optional peer dependency was never auto-installed, causing `memory_search` to silently fail for every EverClaw user. Now detected and installed automatically across all modalities.
+
+### Added
+- **`diagnose.sh` check A10** — New diagnostic check detects whether `node-llama-cpp` is installed. Reports clear fix instructions if missing.
+- **`setup.mjs` Stage 5 (Memory Search)** — Auto-installs `node-llama-cpp@3.18.1` globally during setup. Shows real-time progress. Post-install verification confirms the module loads correctly.
+- **`--skip-embeddings` flag** — New `setup.mjs` flag to skip the node-llama-cpp install (for headless/minimal installs).
+- **`install.sh` node-llama-cpp check** — Runs on every install/upgrade, catching existing users who never re-run setup.
+- **Dockerfile node-llama-cpp install** — Production Docker image now includes `node-llama-cpp@3.18.1` for container users.
+
+### Technical Notes
+- Detection uses `NODE_PATH="$(npm root -g)"` with `require.resolve()` (CJS). ESM `import()` ignores `NODE_PATH` in Node.js — `require.resolve` is the reliable cross-platform approach for global module detection.
+- All installs are non-blocking: failure gracefully degrades to remote embedding providers or no memory search.
+- Version pinned to `node-llama-cpp@3.18.1` (latest stable, matches OpenClaw's peer dependency).
+
 ## [2026.4.7.0355] - 2026-04-07 — Morpheus Agent Flavor + Docker Matrix Build
 
 ### Added

Dockerfile

@@ -105,6 +105,12 @@ WORKDIR /app
 # Copy built OpenClaw from stage 1
 COPY --from=openclaw-builder --chown=node:node /openclaw /app
 
+# Install node-llama-cpp for local embeddings (optional peer dep of OpenClaw).
+# Without this, memory_search silently fails on all fresh installs.
+# Uses --no-save to avoid modifying package.json; || true so build doesn't
+# fail if native compilation fails on some architectures.
+RUN cd /app && npm install node-llama-cpp@3.18.1 --no-save 2>&1 || true
+
 # Copy EverClaw skill into the workspace
 COPY --from=openclaw-builder --chown=node:node /everclaw-skill /home/node/.openclaw/workspace/skills/everclaw
 

README.md

@@ -315,6 +315,7 @@ When a session ends, your MOR comes back. Open a new session with the same token
 - **ETH or USDC on Base** — to swap for MOR tokens
 - **macOS or Linux** — macOS Keychain or libsecret for native key storage; encrypted file fallback works everywhere
 - **age, zstd, jq** — for backup/restore features (auto-installed by `install.sh`)
+- **node-llama-cpp** — for local memory search embeddings (auto-installed by `setup.mjs` and `install.sh`)
 
 That's it. No external accounts. No API keys. No subscriptions.
 

SKILL.md

@@ -101,6 +101,7 @@ node ~/.openclaw/workspace/skills/everclaw/scripts/setup.mjs --key <API_KEY> --a
 | `--restart` | Restart OpenClaw [REDACTED] after apply |
 | `--with-ollama` | Also setup local Ollama inference as final fallback |
 | `--ollama-model <model>` | Override auto-detected Ollama model (e.g. `gemma4:26b`) |
+| `--skip-embeddings` | Skip node-llama-cpp install (local embeddings) |
 | `--security-tier <tier>` | Set security tier: `low`, `recommended`, `maximum` |
 | `--no-security` | Skip security tier setup |
 

scripts/diagnose.sh

@@ -293,6 +293,18 @@ print(count)
   elif [[ "$non_streaming" -eq 0 ]]; then
     pass "All models have streaming enabled"
   fi
+
+  # A10: Is node-llama-cpp installed for local embeddings (memory_search)?
+  if command -v node &>/dev/null; then
+    if NODE_PATH="$(npm root -g 2>/dev/null)" node -e "try { require.resolve('node-llama-cpp'); process.exit(0) } catch { process.exit(1) }" 2>/dev/null; then
+      pass "Local embeddings available (node-llama-cpp installed)"
+    else
+      warn "node-llama-cpp not installed — memory_search (local embeddings) will not work"
+      fix "Install it: npm install -g node-llama-cpp@3.18.1"
+      fix "Or set memorySearch.provider to 'openai', 'gemini', or 'voyage' in openclaw.json"
+      fix "Memory search works without this, but only with a remote embedding provider"
+    fi
+  fi
 }
 
 # ═════════════════════════════════════════════════════════════════════════════

scripts/install.sh

@@ -424,6 +424,31 @@ else
   echo "⚠️  npm not found. Install Node.js, then run: cd $EVERCLAW_ROOT && npm install"
 fi
 
+# --- Ensure node-llama-cpp for OpenClaw local embeddings ---
+if command -v npm &>/dev/null && command -v node &>/dev/null; then
+  echo "🧠 Checking local embeddings (node-llama-cpp)..."
+  NPM_GLOBAL_ROOT="$(npm root -g 2>/dev/null)"
+  if NODE_PATH="$NPM_GLOBAL_ROOT" node -e "try { require.resolve('node-llama-cpp'); process.exit(0) } catch { process.exit(1) }" 2>/dev/null; then
+    echo "  ✅ node-llama-cpp already installed"
+  else
+    echo "  📦 Installing local embedding engine (node-llama-cpp@3.18.1)..."
+    echo "     One-time install, ~30-90s. May need build tools on some systems."
+    if npm install -g node-llama-cpp@3.18.1; then
+      # Post-install verification
+      if NODE_PATH="$NPM_GLOBAL_ROOT" node -e "try { require.resolve('node-llama-cpp'); process.exit(0) } catch { process.exit(1) }" 2>/dev/null; then
+        echo "  ✅ node-llama-cpp installed — local memory search enabled"
+      else
+        echo "  ⚠️  node-llama-cpp installed but import failed"
+        echo "     You may need build tools: Xcode CLT (macOS) or build-essential (Linux)"
+      fi
+    else
+      echo "  ⚠️  node-llama-cpp install failed (not critical)"
+      echo "     Install manually: npm install -g node-llama-cpp@3.18.1"
+      echo "     If build fails, you may need: Xcode CLT (macOS) or build-essential + cmake (Linux)"
+    fi
+  fi
+fi
+
 # --- Bootstrap EverClaw Key (GLM-5 Starter Access) ---
 echo ""
 echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"

scripts/setup.mjs

@@ -521,6 +521,7 @@ Flags:
   --template       Override OS auto-detection
   --with-ollama    Also setup local Ollama inference fallback
   --ollama-model   Override auto-detected Ollama model (e.g. gemma4:26b)
+  --skip-embeddings  Skip node-llama-cpp install (local embeddings)
   --security-tier  Set security tier (low|recommended|maximum)
   --no-security    Skip security tier prompt
 `);
@@ -549,6 +550,7 @@ const withOllama = args.includes('--with-ollama');
 const ollamaModel = getArg('--ollama-model');
 const securityTierArg = getArg('--security-tier');
 const noSecurity = args.includes('--no-security');
+const skipEmbeddings = args.includes('--skip-embeddings');
 
 // ─── Stage 1: Template Discovery ───────────────────────────────
 
@@ -776,6 +778,56 @@ if (applyMode) {
       console.log('  Or re-run with --restart to do it automatically.\n');
     }
   }
+  // ─── Stage 5: Memory Search (Local Embeddings) ────────────────
+
+  if (skipEmbeddings) {
+    console.log('\n  ─── Memory Search (Local Embeddings) ────────────────────');
+    console.log('  ⏭️  Skipped (--skip-embeddings)');
+  } else {
+    console.log('\n  ─── Memory Search (Local Embeddings) ────────────────────');
+    let npmGlobalRoot = '';
+    try {
+      npmGlobalRoot = execSync('npm root -g', { encoding: 'utf-8', timeout: 5000 }).trim();
+    } catch {
+      // npm root -g failed — fall through to install path (safe)
+    }
+    try {
+      execSync('node -e "try { require.resolve(\'node-llama-cpp\'); process.exit(0) } catch { process.exit(1) }"', {
+        timeout: 10000,
+        stdio: 'pipe',
+        env: { ...process.env, NODE_PATH: npmGlobalRoot },
+      });
+      console.log('  ✅ node-llama-cpp already installed');
+    } catch {
+      console.log('  📦 Installing local embedding engine (node-llama-cpp@3.18.1)...');
+      console.log('     One-time install, ~30-90s. May need build tools on some systems.');
+      try {
+        execSync('npm install -g node-llama-cpp@3.18.1', {
+          timeout: 120000,
+          stdio: 'inherit',
+        });
+        // Post-install verification
+        try {
+          execSync('node -e "try { require.resolve(\'node-llama-cpp\'); process.exit(0) } catch { process.exit(1) }"', {
+            timeout: 10000,
+            stdio: 'pipe',
+            env: { ...process.env, NODE_PATH: npmGlobalRoot },
+          });
+          console.log('  ✅ node-llama-cpp installed — local memory search enabled');
+        } catch {
+          console.log('  ⚠️  node-llama-cpp installed but import failed');
+          console.log('     You may need build tools: Xcode CLT (macOS) or build-essential (Linux)');
+          console.log('     Memory search will fall back to remote provider if configured');
+        }
+      } catch {
+        console.log('  ⚠️  node-llama-cpp install failed (not critical)');
+        console.log('     Memory search will use remote provider or be unavailable');
+        console.log('     Install manually: npm install -g node-llama-cpp@3.18.1');
+        console.log('     If build fails, you may need: Xcode CLT (macOS) or build-essential + cmake (Linux)');
+      }
+    }
+  }
+
 } else {
   // Dry-run — but still allow --test
   if (testMode) {