PR #74802: fix(memory): install local embedding runtime deps

• Repository: openclaw/openclaw
• Author: LLagoon3
• State: closed | merged: False
• Link: https://github.com/openclaw/openclaw/pull/74802

Description (problem / solution / changelog)

Summary

• Problem: local memory search can select the bundled memory-core runtime without installing node-llama-cpp into the managed plugin runtime dependency root.
• Why it matters: agents.defaults.memorySearch.provider = "local" can fail before indexing/search starts with Cannot find package 'node-llama-cpp' even when the model file exists or the package is installed globally.
• What changed: add [email protected] to bundled runtime dependency selection when memory-core is included and local memory search is configured; update the local setup hint to use openclaw doctor --fix.
• What did NOT change (scope boundary): no root/package dependency is added for node-llama-cpp, preserving the release guardrail that keeps it operator-installed/managed runtime only.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #74777
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: local embeddings import node-llama-cpp from the managed plugin runtime, but runtime dependency selection did not include that package for local memory search.
• Missing detection / guardrail: bundled runtime dependency tests covered declared plugin package dependencies, but not config-gated optional local embedding runtime deps.
• Contributing context (if known): reproduced from a local memory_search failure where plugin-runtime-deps lacked node-llama-cpp despite global installation.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/plugins/bundled-runtime-deps.test.ts
• Scenario the test should lock in: scanning/ensuring bundled runtime deps includes [email protected] only when local memory search is enabled.
• Why this is the smallest reliable guardrail: the bug is in runtime dependency selection, before embeddings execute.
• Existing test that already covers this (if any): none for the config-gated local embedding runtime dep.
• If no new test is added, why not: N/A

User-visible / Behavior Changes

openclaw doctor --fix and gateway startup can repair/install the local embedding runtime dependency into the managed runtime when local memory search is configured. The missing-runtime hint now points users to openclaw doctor --fix instead of global npm installation.

Diagram (if applicable)

Before:
[local memorySearch config] -> [memory-core runtime deps] -> [chokidar only] -> [node-llama-cpp import fails]

After:
[local memorySearch config] -> [memory-core runtime deps] -> [chokidar + node-llama-cpp] -> [local embeddings can load]

Security Impact (required)

• New permissions/capabilities? (Yes/No): No
• Secrets/tokens handling changed? (Yes/No): No
• New/changed network calls? (Yes/No): No
• Command/tool execution surface changed? (Yes/No): No
• Data access scope changed? (Yes/No): No
• If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

• OS: Linux
• Runtime/container: local pnpm workspace
• Model/provider: local memory search provider
• Integration/channel (if any): N/A
• Relevant config (redacted): agents.defaults.memorySearch.provider = "local"

Steps

1. Configure local memory search.
2. Start or repair bundled memory-core runtime deps.
3. Exercise runtime dependency scan/ensure paths.

Expected

• Managed runtime deps include [email protected] for local memory search.

Actual

• Before this fix, the managed runtime deps did not include node-llama-cpp, so bare import resolution failed from plugin-runtime-deps.

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

• Verified scenarios:
  • pnpm exec vitest run src/plugins/bundled-runtime-deps.test.ts --config test/vitest/vitest.plugins.config.ts
  • pnpm exec vitest run extensions/memory-core/src/memory/embeddings.test.ts extensions/memory-core/src/memory/search-manager.test.ts --config test/vitest/vitest.extension-memory.config.ts
  • pnpm exec vitest run test/openclaw-npm-release-check.test.ts --config test/vitest/vitest.tooling.config.ts
  • pnpm exec oxfmt --check --threads=1 src/plugins/bundled-runtime-deps-selection.ts src/plugins/bundled-runtime-deps.test.ts extensions/memory-core/src/memory/provider-adapters.ts
  • pnpm tsgo:core
  • pnpm check:changed
• Edge cases checked: disabled local memory search does not add node-llama-cpp.
• What you did not verify: full end-to-end local embedding model load with native node-llama-cpp in the managed runtime.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? (Yes/No): Yes
• Config/env changes? (Yes/No): No
• Migration needed? (Yes/No): No
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: node-llama-cpp native install can still fail on unsupported local toolchains.
  • Mitigation: dependency remains config-gated to local memory search and the setup hint points users to the managed repair path plus pnpm rebuild guidance.

Changed files

• extensions/memory-core/src/memory/provider-adapters.ts (modified, +2/-2)
• src/plugins/bundled-runtime-deps-selection.ts (modified, +127/-5)
• src/plugins/bundled-runtime-deps.test.ts (modified, +230/-0)