Fix #1559: fix: registerMemoryCapability API not found in OpenClaw 2026.3.31

[Memtensor-AI]

Description

Fixes #1559: the @memtensor/memos-local-openclaw-plugin failed to load on OpenClaw 2026.3.31 because it still called the removed umbrella api.registerMemoryCapability({promptBuilder}) at apps/memos-local-openclaw/index.ts:163. OpenClaw 2026.3.31 split that umbrella into three focused registrars — registerMemoryPromptSection, registerMemoryFlushPlan, registerMemoryRuntime — so the call threw TypeError: api.registerMemoryCapability is not a function and the plugin refused to initialize.

The fix rewrites register() to feature-detect the new registerMemoryPromptSection(builder) API and use it preferentially, falling back to the legacy registerMemoryCapability({ promptBuilder }) for older gateways, and logging a warning if neither method is present. Only the prompt-section builder is needed — the plugin does not implement flush plans or memory runtimes — so this is a minimal, backwards-compatible migration.

Test evidence: a new tests/memory-registration-api.test.ts (3 cases) locks in preference of the new API, the legacy-fallback path, and the no-throw safeguard. Six existing test stubs were extended to expose both entry points. npx vitest run tests/memory-registration-api.test.ts → 3/3 pass; targeted run of touched files (plugin-openclaw-wiring, plugin-impl-access, shutdown-lifecycle, hub-eager-connect, integration, incremental-sharing) → 41/41 pass. Broader npx vitest run --exclude e2e/accuracy → 213 pass; the 3 pre-existing failures (skill-auto-install, task-processor, update-install) exist on the base branch too and are unrelated to this change (confirmed via git stash re-run). npx tsc --noEmit is clean.

Related Issue (Required): Fixes #1559

Type of change

Please delete options that are not relevant.

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Refactor (does not change functionality, e.g. code style improvements, linting)
• Documentation update

How Has This Been Tested?

Automated tests are pending.

• Unit Test
• Test Script Or Test Steps (please provide)
• Pipeline Automated API Test (please provide)

Checklist

• I have performed a self-review of my own code
• I have commented my code in hard-to-understand areas
• I have added tests that prove my fix is effective or that my feature works
• I have created related documentation issue/PR in MemOS-Docs (if applicable)
• I have linked the issue to this PR (if applicable)
• I have mentioned the person who will review this PR

@MatthewZhuang, @CarltonXiang, @syzsunshine219, @World-controller please review this PR.

Reviewer Checklist

• closes fix: registerMemoryCapability API not found in OpenClaw 2026.3.31 #1559
• Made sure Checks passed
• Tests have been provided

[Memtensor-AI]

🤖 Open Code Review

Target: PR #2037
Task: aa7384b576a80c35
Base: dev-20260624-v2.0.22
Head: bugfix/autodev-1559

🔍 OpenCodeReview found 4 issue(s) in this PR.

---

1. apps/memos-local-openclaw/index.ts (L167-L170)

Silent failure risk on old gateways: The intermediate else if branch calls memoryApi.registerMemoryCapability(...) through the narrowed cast type where registerMemoryCapability is typed as optional (?: ...). TypeScript will accept this, but if the runtime gateway object somehow has registerMemoryCapability present on the prototype chain rather than as an own property, typeof checks will still pass — which is intended. This is fine.

However, the more significant concern is: the memoryApi cast strips the type down to only the two optional methods, discarding every other member of OpenClawPluginApi. This means that if you ever need to fall through to the else branch and call api.logger.warn(...), you are correctly falling back to the original api reference — good. But this also means the two paths are tested against different objects at the type level, which can be a subtle maintenance trap if someone later accesses other API members through memoryApi instead of api.

Consider extracting the feature-detection into a small helper or narrowing to a more descriptive named interface to make the intent explicit and guard future misuse:

interface MemoryRegistrationApi {
  registerMemoryPromptSection?: (builder: typeof buildMemoryPromptSection) => void;
  registerMemoryCapability?: (opts: { promptBuilder: typeof buildMemoryPromptSection }) => void;
}
const memoryApi = api as unknown as MemoryRegistrationApi;

This is already done inline, so the only real suggestion is to hoist the interface to a named declaration at the module or function scope for discoverability.

---

2. apps/memos-local-openclaw/index.ts (L176-L178)

Missing error-level escalation at startup: The else branch only emits a warn log, but the consequence is severe — the entire memory prompt injection is silently skipped, so the AI will never recall memories. On an unrecognised gateway version this should arguably throw an error or at the very least use api.logger.error(...) so operators notice immediately rather than debugging broken memory recall later.

Suggested change:

api.logger.error(
  "memos-local: neither api.registerMemoryPromptSection nor api.registerMemoryCapability is available; memory prompt section will not be injected. Plugin may be incompatible with this OpenClaw gateway version.",
);
// Optionally: throw new Error("memos-local: no compatible memory registration API found on OpenClawPluginApi");

---

3. apps/memos-local-openclaw/index.ts (L167-L170)

Inline anonymous cast type reduces maintainability: The anonymous object type in as unknown as { ... } works correctly, but hoisting it to a named interface at module/function scope would improve discoverability and prevent future maintainers from accidentally accessing other OpenClawPluginApi members through memoryApi (where only these two methods are typed). Consider:

interface MemoryRegistrationApi {
  registerMemoryPromptSection?: (builder: typeof buildMemoryPromptSection) => void;
  registerMemoryCapability?: (capability: { promptBuilder: typeof buildMemoryPromptSection }) => void;
}
const memoryApi = api as unknown as MemoryRegistrationApi;

---

4. apps/memos-local-openclaw/index.ts (L176-L178)

Severity of the fallthrough is understated: When neither registration method is found, the entire memory prompt injection is silently skipped — the AI will never surface recalled memories for the user. A warn log is easy to miss in production. Consider using api.logger.error(...) or even throwing to make the misconfiguration immediately visible to operators, rather than manifesting as subtle broken recall behavior:

api.logger.error(
  "memos-local: neither api.registerMemoryPromptSection nor api.registerMemoryCapability is available; memory prompt section will not be injected. The plugin may be incompatible with this OpenClaw gateway version.",
);
// Optionally: throw new Error("memos-local: no compatible memory registration API found");

Generated by cloud-assistant via Open Code Review.

[Memtensor-AI]

🤖 Open Code Review

Target: PR #2037
Task: aa7384b576a80c35
Base: dev-20260624-v2.0.22
Head: bugfix/autodev-1559

🔍 OpenCodeReview found 3 issue(s) in this PR.

---

1. apps/memos-local-openclaw/index.ts (L183)

Unsafe double cast (as unknown as MemoryRegistrationApi) discards type safety without a compensating guard.

The cast api as unknown as MemoryRegistrationApi completely bypasses the TypeScript type checker for the api object. Because OpenClawPluginApi is already imported as an explicit type (line 8), it would be safer — and more idiomatic — to extend or intersect it with the optional fields instead of escaping through unknown. Consider:

type MemoryRegistrationAwareApi = OpenClawPluginApi & MemoryRegistrationApi;
const memoryApi = api as MemoryRegistrationAwareApi;

This still compiles (both sides share a common base), preserves the rest of api's typed members on memoryApi, and makes the intent much clearer: "this API might have these extra fields".

💡 Suggested Change

Before:

    const memoryApi = api as unknown as MemoryRegistrationApi;

After:

    const memoryApi = api as OpenClawPluginApi & MemoryRegistrationApi;

---

2. apps/memos-local-openclaw/index.ts (L193-L202)

Silent failure — the else branch only logs but does not throw or signal the error to the caller.

When neither registrar is present, the method continues executing (the rest of register() runs normally, setting up stores, workers, tools, etc.) even though the memory recall path is permanently broken for this session. This is particularly risky because all the setup work still succeeds — operators may see a healthy startup log with a single error line buried in the middle, and the plugin will appear to be running.

Consider throwing an error (or at minimum returning early) so the host can handle the incompatibility explicitly:

const err = new Error(message);
const errorLog = (api.logger as { error?: (msg: string) => void }).error;
if (typeof errorLog === "function") {
  errorLog.call(api.logger, message);
} else {
  api.logger.warn(message);
}
throw err; // prevent the rest of register() from running in a broken state

---

3. apps/memos-local-openclaw/index.ts (L197)

Repeated as { error?: ... } cast on api.logger duplicates the same unsafe narrowing pattern.

Just like the memoryApi cast above, (api.logger as { error?: (msg: string) => void }) introduces another inline escape hatch. If OpenClawPluginApi already defines logger with a typed interface (e.g., it has warn but not error), this cast silently diverges from the canonical definition. Consider defining a small local type for the extended logger alongside MemoryRegistrationApi at module scope, to keep all type-escaping in one place and make it easy to remove once the SDK is updated:

interface ExtendedLogger {
  warn(msg: string): void;
  error?(msg: string): void;
}
const logger = api.logger as ExtendedLogger;
const errorLog = logger.error;

Generated by cloud-assistant via Open Code Review.

[Memtensor-AI]

🤖 Open Code Review

Target: PR #2037
Task: aa7384b576a80c35
Base: dev-20260624-v2.0.22
Head: bugfix/autodev-1559

✅ OpenCodeReview: No comments generated. Looks good to me.

Generated by cloud-assistant via Open Code Review.

[Memtensor-AI]

❌ Automated Test Results: FAILED

Auto-fix retry 1/2 triggered.

Failed tests:

• npm test

Error details

Tests failed. Failed cases: npm test

Branch: bugfix/autodev-1559

[Memtensor-AI]

Automated Test Results: PASSED\n\nCloud test-engine rerun after resolving the dev-v2.0.22 merge conflict.\n\nRun: tr-4b3ba62f-a76\nScope: memos_local_openclaw\nResult: 58/58 tests passed\nCommand group: memos_local_openclaw/unit\nDuration: 66s\n\nLocal pre-push verification also passed: npm run build, plus focused vitest for the memory-registration API tests.\n\nStatus: merge conflict resolved; automated scope test passed. Manual code review is still required before merge.