feat(openclaw-agent-memory): register OB1 as active-memory capability for governed recall and writeback (#279)

[MicScalise]

Closes the architecture gap left by PR #281. Companion to #280.

What this changes

PR #281 added two additive memory hooks (registerMemoryPromptSupplement, registerMemoryCorpusSupplement) so OB1 results contribute alongside whatever active memory plugin happens to be selected. That was the safe minimum. It did not make OB1 be the active memory plugin — agents still couldn't reach OB1 from memory_search, and when plugins.slots.memory = "nbj-ob1-agent-memory" was set the slot stayed empty (`openclaw doctor` reported "No active memory plugin is registered for the current config").

This PR fills the slot. Inside register(api):

• api.registerMemoryCapability({ promptBuilder, runtime }) — emits an OB1 discipline section into the active memory prompt and provides a real MemoryPluginRuntime that produces per-agent search managers.
• OB1MemorySearchManager (src/search-manager.ts, new) — implements the surface OpenClaw consumers actually call: search, status, probeVectorAvailability, close, hasIndexedContent, warmSession, sync. search() wraps client.recall() and maps OB1 memories to OpenClaw's chunk shape ({source, path, startLine, endLine, score, snippet}) using a synthetic openbrain://memory/<id> path. status() reports backend="ob1" so downstream code that branches on backend === "qmd" treats us as a generic plugin-owned backend.
• Standard tool wrappers — memory_search, memory_get, memory_store register under the names OpenClaw's host and active-memory plugin look for. The seven existing openbrain_* tools stay registered as the advanced governance surface (review queue, recall traces, explicit usage reporting) and remain unchanged.
• memory_store semantics — typed memory_type parameter maps to OB1 governance categories (decisions, lessons, constraints, outputs, failures, next_steps, unresolved_questions).
• client.ts schema_version — every recall and writeback now sends the required schema_version literal (openbrain.openclaw.recall.v1 / openbrain.openclaw.writeback.v1). Without it the Edge Function returned 400 Invalid recall payload. This was a latent bug because no agent had actually invoked the plugin's recall path before this work — pure tool-call paths bypassed the issue.
• LLM tool-call coercion — coerceObjectFields() helper JSON.parses string-shaped object args (LLMs occasionally JSON.stringify nested object parameters, which the Edge Function's zod schema then rejects). Applied on openbrain_recall and openbrain_writeback.
• Default runtime.name = "openclaw" on writeback — agents calling openbrain_writeback without a runtime field used to land rows with runtime_name="unknown". Default it from the plugin so attribution is automatic; explicit input still wins.

Activation contract (unchanged from existing OpenClaw memory plugin model)

registerMemoryCapability declares candidacy. The user activates by setting:

{ "plugins": { "slots": { "memory": "nbj-ob1-agent-memory" } } }

Without that slots entry the plugin stays dormant and does not affect existing memory routing.

Why additive supplements (#281) are still useful

This PR doesn't supersede #281. The additive supplements still let OB1 contribute prompt + corpus contributions when a different memory plugin is active (e.g., users on memory-core or memory-lancedb who want OB1 governance signals layered on top). The two PRs serve different deployment styles.

Verified live

End-to-end against a self-hosted Supabase + agent-memory-api Edge Function, running an OpenClaw 2026.5.7 gateway locally:

• Cross-session recall: agent "personal-assistant" wrote a uniquely-tagged decision via openbrain_writeback in session A, then in a fresh session B called memory_search with the marker as query. Recall returned the exact memory with content match. Trace row shows runtime_name=openclaw, items=3.
• Second-agent verification: agent "dev-gpu" recalled 9 prior memories on a generic "Hermes-OB1" query. Same runtime_name=openclaw attribution.
• Hermes side unaffected: Hermes recall against the same backend continues to work post-cutover.
• openclaw doctor moves from "No active memory plugin is registered" to recognizing OB1 as the active memory plugin (after plugins.slots.memory is set).

Tools surface notes

When OB1 is selected as the active memory plugin, OpenClaw's host policy auto-exposes memory_search and memory_get to agents under the default tools.profile = "coding". The seven openbrain_* governance tools are registered but require either tools.profile = "full" per-agent or explicit tools.allow listing — same convention OpenClaw uses for any plugin-specific tool surface. Documented in the README.

Diff scope

• integrations/openclaw-agent-memory/plugin/openclaw.plugin.json — adds memory_search, memory_get, memory_store to contracts.tools.
• integrations/openclaw-agent-memory/plugin/src/index.ts — +252 LoC. New: capability registration block, three standard tool wrappers, coerceObjectFields helper, runtime.name default. Existing 7 openbrain_* tools unchanged in shape.
• integrations/openclaw-agent-memory/plugin/src/client.ts — +5 LoC. schema_version on recall + writeback request bodies.
• integrations/openclaw-agent-memory/plugin/src/search-manager.ts — new (242 LoC). OB1MemorySearchManager class + createOB1Runtime factory.

No new dependencies. No dist/ regeneration committed (please run npm run build to refresh).

Test plan

• cd integrations/openclaw-agent-memory/plugin && npm install --ignore-scripts --omit=peer && npm run build — esbuild succeeds (~24kb bundle).
• Configure OB1 agent-memory-api endpoint + access key + workspaceId in ~/.openclaw/openclaw.json under plugins.entries.nbj-ob1-agent-memory.config.
• Set plugins.slots.memory = "nbj-ob1-agent-memory" to select.
• Restart gateway.
• Run openclaw plugins inspect nbj-ob1-agent-memory --runtime --json — confirm activated: true, all 10 tools registered.
• Drive an agent turn calling memory_search — confirm a recall trace lands with runtime_name=openclaw.

Related

• Closes [Bug] @natebjones/ob1-agent-memory v0.1.1 — plugin loads as memory-slot owner but neither auto-invokes nor exposes its 7 tools to agents in OpenClaw 2026.5.7 #279.
• Companion to feat(integrations): add hermes-agent-memory native provider for OB1 #280 (Hermes-side MemoryProvider for OB1).
• Builds on fix(openclaw-agent-memory): wire memory-host hooks for auto-recall (#279) #281 (additive supplements stay in place).

[alanshurafa]

Thanks for the contribution. This is a substantial piece, and the inline comments explaining the Edge Function quirks are genuinely helpful.

Two notes on client.ts:

schema_version is placed before the ...input spread in both recall() and writeback() — the same ordering raised on #278 and #290, where a model-supplied value would override the constant. Moving each line to just after ...input fixes it.

recall() now defaults scope.include_unconfirmed to true (was false). The rationale in your comment is sound — writes start as requires_review=true, so otherwise naive recall returns nothing. But defaulting recall to include un-reviewed memories changes the Agent Memory trust posture, which is a maintainer decision. Labeled risk: privacy and flagged for security/privacy review rather than treated as settled.

On the bigger picture: #283 is the active-memory-slot approach (#281 is the additive-supplement approach). Activation looks correctly opt-in (gated on plugins.slots.memory), so existing deployments are unaffected by default. The direction choice and four-PR merge ordering are escalated to the maintainer separately. dist/index.js is not regenerated here.

Recommend author refresh for the schema_version reorder; the include_unconfirmed default and the active-slot direction need security/privacy and product review from the maintainer.

— Alan (community reviewer; non-binding)