Skip to content

Commit d4178c8

Browse files
mbelinkymbelinky
committed
chore(plugin-sdk): flag memory embedding provider deprecation
1 parent 4d89e00 commit d4178c8

15 files changed

Lines changed: 250 additions & 28 deletions

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ Docs: https://docs.openclaw.ai
77
### Changes
88

99
- Memory: add a core OpenAI-compatible embedding provider for local and hosted OpenAI-style endpoints, with config, doctor, and docs support. (#85269) Thanks @dutifulbob.
10+
- Plugin SDK: mark memory-specific embedding provider registration as deprecated compatibility and surface non-bundled usage in plugin compatibility diagnostics. (#85072) Thanks @mbelinky.
1011

1112
### Fixes
1213

‎docs/plugins/adding-capabilities.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -122,9 +122,9 @@ future feature plugins can consume embeddings without depending on the memory
122122
engine.
123123

124124
Memory search can consume generic `embeddingProviders`. The older
125-
`memoryEmbeddingProviders` contract remains for compatibility while existing
126-
memory-specific providers migrate, but new reusable embedding providers should
127-
use `embeddingProviders`.
125+
`memoryEmbeddingProviders` contract is deprecated compatibility while existing
126+
memory-specific providers migrate; new reusable embedding providers should use
127+
`embeddingProviders`.
128128

129129
## Review checklist
130130

‎docs/plugins/compatibility.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -130,6 +130,9 @@ Current compatibility records include:
130130
`api.runtime.config.loadConfig()` / `api.runtime.config.writeConfigFile(...)`
131131
- legacy memory-plugin split registration while memory plugins move to
132132
`registerMemoryCapability`
133+
- legacy memory-specific embedding provider registration while embedding
134+
providers move to `api.registerEmbeddingProvider(...)` and
135+
`contracts.embeddingProviders`
133136
- legacy channel SDK helpers for native message schemas, mention gating,
134137
inbound envelope formatting, and approval capability nesting
135138
- legacy channel route key and comparable-target helper aliases while plugins

‎docs/plugins/manifest.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -647,7 +647,7 @@ Each list is optional:
647647
| `speechProviders` | `string[]` | Speech provider ids this plugin owns. |
648648
| `realtimeTranscriptionProviders` | `string[]` | Realtime-transcription provider ids this plugin owns. |
649649
| `realtimeVoiceProviders` | `string[]` | Realtime-voice provider ids this plugin owns. |
650-
| `memoryEmbeddingProviders` | `string[]` | Legacy memory embedding provider ids this plugin owns. |
650+
| `memoryEmbeddingProviders` | `string[]` | Deprecated memory-specific embedding provider ids this plugin owns. |
651651
| `mediaUnderstandingProviders` | `string[]` | Media-understanding provider ids this plugin owns. |
652652
| `transcriptSourceProviders` | `string[]` | Transcript source provider ids this plugin owns. |
653653
| `imageGenerationProviders` | `string[]` | Image-generation provider ids this plugin owns. |
@@ -677,9 +677,9 @@ will be removed after the migration window.
677677
General embedding providers should declare `contracts.embeddingProviders` for
678678
each adapter registered with `api.registerEmbeddingProvider(...)`. Use the
679679
general contract for reusable vector generation, including providers consumed by
680-
memory search. `contracts.memoryEmbeddingProviders` is the older
681-
memory-specific compatibility contract and remains while existing providers
682-
migrate to the generic embedding provider seam.
680+
memory search. `contracts.memoryEmbeddingProviders` is deprecated
681+
memory-specific compatibility and remains only while existing providers migrate
682+
to the generic embedding provider seam.
683683

684684
`contracts.gatewayMethodDispatch` currently accepts
685685
`"authenticated-request"`. It is an API hygiene gate for native plugin HTTP

‎docs/plugins/sdk-migration.md‎

Lines changed: 17 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -868,9 +868,23 @@ canonical replacement.
868868
**New**: one call on the memory-state API -
869869
`registerMemoryCapability(pluginId, { promptBuilder, flushPlanResolver, runtime })`.
870870

871-
Same slots, single registration call. Additive memory helpers
872-
(`registerMemoryPromptSupplement`, `registerMemoryCorpusSupplement`,
873-
`registerMemoryEmbeddingProvider`) are not affected.
871+
Same slots, single registration call. Additive prompt and corpus helpers
872+
(`registerMemoryPromptSupplement`, `registerMemoryCorpusSupplement`) are
873+
not affected.
874+
875+
</Accordion>
876+
877+
<Accordion title="Memory embedding provider API">
878+
**Old**: `api.registerMemoryEmbeddingProvider(...)` plus
879+
`contracts.memoryEmbeddingProviders`.
880+
881+
**New**: `api.registerEmbeddingProvider(...)` plus
882+
`contracts.embeddingProviders`.
883+
884+
The generic embedding provider contract is reusable outside memory and is
885+
the supported path for new providers. The memory-specific registration API
886+
remains wired as deprecated compatibility while existing providers migrate.
887+
Plugin inspection reports non-bundled usage as compatibility debt.
874888

875889
</Accordion>
876890

‎docs/plugins/sdk-overview.md‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -111,7 +111,7 @@ also be listed in `contracts.embeddingProviders` in the plugin manifest. This
111111
is the generic embedding surface for reusable vector generation. Memory search
112112
can consume this generic provider surface. The older
113113
`api.registerMemoryEmbeddingProvider(...)` and
114-
`contracts.memoryEmbeddingProviders` seam remains as compatibility while
114+
`contracts.memoryEmbeddingProviders` seam is deprecated compatibility while
115115
existing memory-specific providers migrate.
116116

117117
### Tools and commands
@@ -378,7 +378,7 @@ For an end-to-end authoring guide, see
378378
| `api.registerMemoryFlushPlan(resolver)` | Memory flush plan resolver |
379379
| `api.registerMemoryRuntime(runtime)` | Memory runtime adapter |
380380

381-
### Memory embedding adapters
381+
### Deprecated memory embedding adapters
382382

383383
| Method | What it registers |
384384
| ---------------------------------------------- | ---------------------------------------------- |
@@ -394,12 +394,12 @@ For an end-to-end authoring guide, see
394394
- `MemoryFlushPlan.model` can pin the flush turn to an exact `provider/model`
395395
reference, such as `ollama/qwen3:8b`, without inheriting the active fallback
396396
chain.
397-
- `registerMemoryEmbeddingProvider` lets the active memory plugin register one
398-
or more embedding adapter ids (for example `openai`, `gemini`, or a custom
399-
plugin-defined id).
400-
- User config such as `agents.defaults.memorySearch.provider` and
401-
`agents.defaults.memorySearch.fallback` resolves against those registered
402-
adapter ids.
397+
- `registerMemoryEmbeddingProvider` is deprecated. New embedding providers
398+
should use `api.registerEmbeddingProvider(...)` and
399+
`contracts.embeddingProviders`.
400+
- Existing memory-specific providers continue to work during the migration
401+
window, but plugin inspection reports this as compatibility debt for
402+
non-bundled plugins.
403403

404404
### Events and lifecycle
405405

‎docs/plugins/sdk-provider-plugins.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -685,9 +685,9 @@ API key auth, and dynamic model resolution.
685685
```
686686

687687
Declare the same id in `contracts.embeddingProviders`. This is the
688-
general embedding contract for reusable vector generation. Use
689-
`registerMemoryEmbeddingProvider(...)` only for memory-engine-specific
690-
adapters.
688+
general embedding contract for reusable vector generation, including
689+
memory search. `registerMemoryEmbeddingProvider(...)` is deprecated
690+
compatibility for existing memory-specific adapters.
691691
</Tab>
692692
<Tab title="Image and video generation">
693693
Video capabilities use a **mode-aware** shape: `generate`,

‎docs/plugins/sdk-subpaths.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -342,7 +342,7 @@ and pairing-path families.
342342
| `plugin-sdk/memory-core` | Bundled memory-core helper surface for manager/config/file/CLI helpers |
343343
| `plugin-sdk/memory-core-engine-runtime` | Memory index/search runtime facade |
344344
| `plugin-sdk/memory-core-host-engine-foundation` | Memory host foundation engine exports |
345-
| `plugin-sdk/memory-core-host-engine-embeddings` | Memory host embedding contracts, registry access, local provider, and generic batch/remote helpers |
345+
| `plugin-sdk/memory-core-host-engine-embeddings` | Memory host embedding contracts, registry access, local provider, and generic batch/remote helpers. `registerMemoryEmbeddingProvider` on this surface is deprecated; use the generic embedding provider API for new providers. |
346346
| `plugin-sdk/memory-core-host-engine-qmd` | Memory host QMD engine exports |
347347
| `plugin-sdk/memory-core-host-engine-storage` | Memory host storage engine exports |
348348
| `plugin-sdk/memory-core-host-multimodal` | Memory host multimodal helpers |

‎src/plugin-sdk/memory-core-host-engine-embeddings.ts‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -57,10 +57,13 @@ export {
5757
listRegisteredMemoryEmbeddingProviderAdapters,
5858
listRegisteredMemoryEmbeddingProviders,
5959
} from "../plugins/memory-embedding-provider-runtime.js";
60-
export {
61-
clearMemoryEmbeddingProviders,
62-
registerMemoryEmbeddingProvider,
63-
} from "../plugins/memory-embedding-providers.js";
60+
export { clearMemoryEmbeddingProviders } from "../plugins/memory-embedding-providers.js";
61+
/**
62+
* @deprecated New embedding providers should use `api.registerEmbeddingProvider(...)`
63+
* and `contracts.embeddingProviders`. This memory-specific registrar remains
64+
* available only for compatibility while existing providers migrate.
65+
*/
66+
export { registerMemoryEmbeddingProvider } from "../plugins/memory-embedding-providers.js";
6467
export type {
6568
MemoryEmbeddingBatchChunk,
6669
MemoryEmbeddingBatchOptions,

‎src/plugins/compat/registry.test.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -157,6 +157,11 @@ const knownDeprecatedSurfaceMarkers = [
157157
file: "src/plugins/hook-types.ts",
158158
marker: "@deprecated Use gateway_stop",
159159
},
160+
{
161+
code: "deprecated-memory-embedding-provider-api",
162+
file: "src/plugins/types.ts",
163+
marker: "registerMemoryEmbeddingProvider",
164+
},
160165
{
161166
code: "channel-route-key-aliases",
162167
file: "src/plugin-sdk/channel-route.ts",

0 commit comments

Comments
 (0)