[integrations] OpenClaw plugin: inject schema_version + surface error details in client

[pineapplestrikesback]

Contribution Type

• Integration (/integrations) — bug fix to existing integrations/openclaw-agent-memory/ plugin

What does this do?

Fixes two defects in the OpenClaw plugin's API client (integrations/openclaw-agent-memory/plugin/src/client.ts):

1. schema_version not injected. The Edge Function's recallSchema and writebackSchema both require schema_version (no default), but client.recall() and client.writeback() never injected it — so every call from the plugin to the live API failed with 400 "Invalid recall payload" (or the writeback equivalent) before reaching any business logic. Adds the default to both methods, mirroring the existing auto-fill pattern for workspace_id and project_id. Caller-supplied values still win (preserves the existing agent-memory-api/smoke/live-smoke.mjs payload shape, which hardcodes schema_version directly).
2. data.details dropped from thrown errors. request() used data.error || text and ignored data.details, so details.fieldErrors (which names exactly which fields failed validation) never reached the caller — making payload-shape mismatches opaque to debug. Includes details in the thrown error message.

No changes outside integrations/openclaw-agent-memory/plugin/. metadata.json, README.md, tool definitions, manifest, and the Edge Function are all unchanged.

Repro on current main

# Without schema_version → 400
curl -sX POST "$ENDPOINT/recall" \
  -H "x-brain-key: $KEY" -H 'content-type: application/json' \
  -d '{"workspace_id":"my-ws","query":"test"}'
# {"error":"Invalid recall payload","details":{"fieldErrors":{"schema_version":["Invalid input"]}}}

# With schema_version added → 200
curl -sX POST "$ENDPOINT/recall" \
  -H "x-brain-key: $KEY" -H 'content-type: application/json' \
  -d '{"schema_version":"openbrain.openclaw.recall.v1","workspace_id":"my-ws","query":"test"}'
# {"request_id":"<uuid>","memories":[...],...}

Why this slipped past existing tests

integrations/agent-memory-api/smoke/live-smoke.mjs validates the API directly with schema_version hardcoded in each request body, bypassing the plugin client. The Edge Function was proven correct end-to-end at deploy, but the plugin → API call path was never exercised.

Requirements

None new. Same services as the existing OpenClaw Agent Memory integration:

• Supabase (Edge Functions + database)
• OpenRouter API (for embeddings)
• OpenClaw 2026.3.24-beta.2+ (existing peer dep, unchanged)

Checklist

• I've read CONTRIBUTING.md
• Existing README.md and metadata.json are unchanged (fix to existing files only)
• I tested this on my own Open Brain instance — applied to a live OpenClaw cockpit (CLI 2026.5.9-beta.1, plugin 0.1.1) on 2026-05-09. End-to-end call from the in-cockpit agent succeeds: recall returns scoped memories, writeback creates pending review items, recall trace + usage-reporting paths intact.
• No credentials, API keys, or secrets are included
• All changes are within integrations/openclaw-agent-memory/plugin/ (rule 12 scope check)

Related issue not in this PR (worth flagging)

When debugging the original 400, I found a second defect in the same area this PR does not fix: openbrain_recall and openbrain_writeback in plugin/src/index.ts declare parameters: Type.Record(Type.String(), Type.Any()), which collapses to a no-args schema at the MCP/LLM tool boundary — the LLM can't supply any arguments through these tools (so even with this PR's schema_version fix, the LLM-driven path still 400s on missing query / memory_payload).

Holding that as a separate follow-up PR because it's a larger, more opinionated change (rewriting two parameter schemas to mirror the API's zod schemas) and I didn't want to slow this small fix down. Happy to send the second PR alongside this if you'd prefer them bundled.

[github-actions]

Hey @pineapplestrikesback — welcome to Open Brain Source! 👋

Thanks for submitting your first PR. The automated review will run shortly and check things like metadata, folder structure, and README completeness. If anything needs fixing, the review comment will tell you exactly what.

Once the automated checks pass, a human admin will review for quality and clarity. Expect a response within a few days.

If you have questions, check out CONTRIBUTING.md or open an issue.

[jonbjornn]

Seeing this issue also. Would love to see this merged in as the OpenClaw plugin doesn't appear to be working in current state. @pineapplestrikesback I have another PR that explicitly addresses the parameters: Type.Record(Type.String(), Type.Any()) payload errors, but agree - that's more opinionated than this simple fix!

[alanshurafa]

Thanks for the contribution, and welcome. The error-surfacing change is a real improvement — including data.details in the thrown message will make the API's validation errors much easier to diagnose.

One thing to fix first, and it is the same issue raised on #290: schema_version is placed before the ...input spread in both recall() and writeback(), so a model-supplied schema_version would override the hardcoded constant. Moving each schema_version line to just after ...input makes the intended value always win.

Two notes for the maintainer. #278 also covers what #290 does (the writeback schema_version) and adds the recall path plus error details — it is the broader of the two, worth consolidating rather than landing both. And #278 is one of four related OpenClaw plugin PRs (#278, #281, #283, #309); merge ordering across them depends on a maintainer direction decision and is flagged separately.

Recommend author refresh with the reorder.

— Alan (community reviewer; non-binding)