PR #67242: plugin-sdk: add stable embeddings subpath export

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

Description (problem / solution / changelog)

Summary

• Problem: when a third-party plugin occupies plugins.slots.memory (e.g. a custom associative-memory plugin), memory-core does not load. With memory-core disabled, the embedding provider API is effectively unavailable through the public SDK — the only path that exposes it today (plugin-sdk/memory-core-host-engine-embeddings) is memory-core-owned, and the embedding registry is empty. Third-party memory-slot plugins are forced to duplicate the embedding implementation (OpenAI/Gemini factories, batching, input limits, multimodal helpers) just to function.
• Why it matters: without this, any third-party plugin in the memory slot must either (a) reach into memory-core internals via a non-public path that offers no semver protection, or (b) reimplement the embedding stack. Both are fragile: a memory-core refactor breaks silently, and duplicated implementations drift over time.
• What changed: new stable subpath openclaw/plugin-sdk/embeddings that re-exports the embedding API (factory functions, registry, types, batch helpers) from memory-host-sdk, independent of whether the memory-core extension is active. Bundled extensions (memory-core, ollama) migrated to dogfood the new path and conform to the extension SDK self-import guardrail.
• What did NOT change: the old internal path keeps working for backward compatibility; memory-core runtime logic is untouched; API baseline hash unchanged (new path re-exports the same symbols).

Change Type (select all)

• Feature (additive public SDK surface)
• Bug fix
• 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

None.

Root Cause (if applicable)

N/A (additive public SDK surface, not a bug fix).

Regression Test Plan (if applicable)

N/A. The repo's existing pnpm plugin-sdk:check-exports and pnpm plugin-sdk:api:check gates lock in the new subpath contract; no new unit test is meaningful for an additive re-export barrel whose API baseline is already verified by these checks.

User-visible / Behavior Changes

None. Existing plugins continue to work unchanged. Plugin authors can switch to the new path when they want stable, documented imports.

Diagram (if applicable)

N/A.

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No

Repro + Verification

Environment

• OS: darwin 24.6.0 (arm64)
• Runtime/container: Node 22.22.0, pnpm 10.32.1
• Model/provider: OpenAI text-embedding-3-small
• Integration/channel: none (CLI-only test bot)
• Relevant config: plugins.slots.memory = memory-core, OpenAI key in auth-profiles.json

Steps

1. pnpm build on this branch
2. pnpm pack → install the tarball into an isolated test directory with OPENCLAW_STATE_DIR pointing at a fresh state dir
3. openclaw plugins list — confirm memory-core loads
4. openclaw memory status — confirm embedding provider is ready
5. openclaw memory index — index a test .md file (triggers the factory call path)
6. openclaw memory search "marine arthropod lifespan" --min-score 0 — semantic query over a test doc mentioning "crustaceans", "exoskeleton", "live over 50 years"

Expected

• Memory-core loads through the new openclaw/plugin-sdk/embeddings path without module-resolution errors
• Indexing issues an embedding request successfully
• Semantic search returns the matching chunk even without keyword overlap

Actual

• Memory-core loaded (55 plugins loaded, 0 errors)
• memory status reported Vector: ready, FTS: ready, provider openai, model text-embedding-3-small
• memory index produced Memory index updated (main), Indexed: 1/1 files · 1 chunks
• memory search "marine arthropod lifespan" returned the expected chunk with score 0.17 (no keyword overlap — confirms real vector similarity)

Evidence

• pnpm tsgo — passes
• pnpm plugin-sdk:check-exports — plugin-sdk exports synced.
• pnpm plugin-sdk:api:gen — baseline regenerated, hash unchanged (new path exposes the same symbols as the old one)
• pnpm build — succeeded, dist/plugin-sdk/embeddings.{js,d.ts} generated
• Semantic-search log snippet: "score": 0.17198…, "snippet": "… Lobsters are crustaceans with a hard exoskeleton … live over 50 years …"

Human Verification (required)

The PR was deployed and tested with the memory-core plugin on top of 2026.4.14. The build succeeded and the basic memory-core functionality (search) with embeddings worked. openclaw memory status and openclaw memory index also worked.

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 — the old memory-core-host-engine-embeddings path keeps working
• Config/env changes? No
• Migration needed? No (third-party plugins can switch to the new path at their own pace)

Risks and Mitigations

• Risk: SDK surface grows by one subpath.
  • Mitigation: the new subpath is narrow and purpose-built per the src/plugin-sdk/CLAUDE.md boundary rules; it is not a broad convenience barrel.
• Risk: two paths pointing at the same API may confuse consumers.
  • Mitigation: sdk-overview.md and sdk-migration.md mark the old path with "prefer plugin-sdk/embeddings".

Changed files

• docs/plugins/sdk-migration.md (modified, +2/-1)
• docs/plugins/sdk-overview.md (modified, +2/-1)
• extensions/memory-core/src/memory/embeddings.ts (modified, +2/-2)
• extensions/memory-core/src/memory/manager-embedding-ops.ts (modified, +1/-1)
• extensions/memory-core/src/memory/manager-sync-ops.ts (modified, +1/-1)
• extensions/memory-core/src/memory/provider-adapters.ts (modified, +1/-1)
• extensions/ollama/src/memory-embedding-adapter.ts (modified, +1/-1)
• package.json (modified, +4/-0)
• scripts/lib/plugin-sdk-entrypoints.json (modified, +1/-0)
• src/plugin-sdk/embeddings.ts (added, +5/-0)