Migrate legacy before_agent_start hook to before_prompt_build and use registerMemoryCapability

[vorflux]

Migrate legacy before_agent_start hook to before_prompt_build and use registerMemoryCapability

Summary

Resolves the OpenClaw plugin API compatibility warning triggered when loading @supermemory/openclaw-supermemory in OpenClaw 2026.4.8:

Compatibility warnings:
openclaw-supermemory still uses legacy before_agent_start; keep regression coverage on this plugin, and prefer before_model_resolve/before_prompt_build for new work.

Changes

index.ts

• Hook migration: Replaced api.on("before_agent_start", ...) with api.on("before_prompt_build", ...) for the recall handler
• sessionKey capture: Extracted sessionKey assignment into a dedicated session_start hook. This ensures sessionKey is captured even when allowPromptInjection=false (which blocks before_prompt_build entirely). Without this, deployments disabling prompt injection would lose session-scoped memory writes.
• Memory registration: Consolidated three deprecated calls (registerMemoryRuntime, registerMemoryPromptSection, registerMemoryFlushPlan) into the unified registerMemoryCapability API, with a runtime typeof fallback for OpenClaw versions before 2026.4.7

types/openclaw.d.ts

• Added registerMemoryCapability?(capability: any): void with JSDoc noting it's preferred since OpenClaw 2026.4.7
• Retained deprecated method stubs with @deprecated annotations pointing to registerMemoryCapability

package.json

• Bumped peerDependencies.openclaw from >=2026.1.29 to >=2026.2.17 (the version that introduced before_prompt_build and session_start)
• Bumped version from 2.0.23 to 2.1.0 (semver minor for new peer dep requirement)

index.test.ts (new)

• Added 7 unit tests covering:
  • registerMemoryCapability path (new API)
  • Fallback to deprecated methods (old API)
  • before_prompt_build hook registration (not before_agent_start)
  • session_start hook registration and handler behavior
  • agent_end hook registration
  • No-op when API key is not configured

tsconfig.json

• Added *.test.ts to exclude list (CI uses Node types, not Bun types, so bun:test import fails in tsc)

bun.lock

• Updated to reflect the peer dependency version change. The large diff is from the lockfile format change only.

Backward Compatibility

OpenClaw Version	before_prompt_build	session_start	registerMemoryCapability	Behavior
< 2026.2.17	N/A	N/A	N/A	Not supported (peer dep blocks install)
2026.2.17 - 2026.4.6	Yes	Yes	No	Uses before_prompt_build + session_start hooks; falls back to deprecated registerMemory* methods
>= 2026.4.7	Yes	Yes	Yes	Full new API path

Breaking change from previous version: The peer dep floor moved from >=2026.1.29 to >=2026.2.17. Users on OpenClaw 2026.1.29-2026.2.16 must upgrade.

Known Issues (pre-existing, not introduced by this PR)

• ERROR: cli command already registered: supermemory (openclaw-supermemory) -- caused by both registerCliSetup() and registerCli() registering under the supermemory CLI namespace. This appears in both before and after openclaw plugins inspect output.
• Shape: non-capability / Capability mode: none -- this is expected for kind: "memory" plugins. These inspect fields track provider capabilities (text-inference, speech, etc.), not memory subsystem registration. OpenClaw's own memory-core plugin shows the same values.

Testing

Unit Tests (bun test)

7/7 pass, 25 assertions

$ bun test
(pass) plugin registration > uses registerMemoryCapability when available
(pass) plugin registration > falls back to deprecated methods when registerMemoryCapability is absent
(pass) plugin registration > registers before_prompt_build hook (not before_agent_start) when autoRecall is enabled
(pass) plugin registration > registers session_start hook to capture sessionKey independently of prompt hooks
(pass) plugin registration > session_start handler captures sessionKey from context
(pass) plugin registration > registers agent_end hook when autoCapture is enabled
(pass) plugin registration > skips hook registration when not configured (no API key)

Type Checking (bun run check-types)

Pass -- tsc --noEmit exits 0 with no diagnostics.

Lint (bun run lint)

Pass -- Biome CI checked 21 files, no errors or warnings. Only a pre-existing info-level notice about biome.json schema version mismatch.

Plugin Inspection (openclaw plugins inspect openclaw-supermemory)

Before (main, v2.0.23):

Legacy before_agent_start: yes
Typed hooks: agent_end, before_agent_start

Compatibility warnings:
openclaw-supermemory still uses legacy before_agent_start; keep regression coverage
on this plugin, and prefer before_model_resolve/before_prompt_build for new work.

After (this branch, v2.1.0):

Legacy before_agent_start: no
Typed hooks: agent_end, before_prompt_build, session_start

(no compatibility warnings)

End-to-End Integration Test (OpenClaw 2026.4.8 + Local Supermemory API)

Ran a full integration test against a local Supermemory API server (wrangler dev, self-hosted mode with pgvector) with real seeded memories:

Setup:

• Local Supermemory API on localhost:8787 (wrangler dev, self-hosted mode)
• PostgreSQL with pgvector for vector search
• 3 test memories seeded with Gemini embeddings (matching the API's embedding model)
• Real API key created via database seeding

Agent prompt: "What do you know about me? What food do I like?"

Agent response:

I know:
- you live in San Francisco
- you have a dog named Max
- you enjoy hiking on weekends
- you're a software engineer working on AI projects
- you prefer TypeScript over JavaScript

Food you like:
- pizza

All 3 seeded memories were successfully recalled via the before_prompt_build hook and injected into the agent's context. The agent correctly synthesized the information from all memories.

Gateway logs confirmed:

• supermemory: initialized (container: openclaw_HPX3yfzK47d7sXbCEnAkRj) -- plugin loaded with correct container tag
• supermemory: agent_end fired: provider="undefined" success=true -- capture hook fired
• 2 new documents created in the database after the conversation (capture working)

Smoke Test (Dummy Key)

Also verified graceful error handling with an invalid API key:

• supermemory: recall failed -- 401 {"error":"Unauthorized"} -- before_prompt_build hook fired, error handled gracefully
• supermemory: capture failed -- 401 ... -- capture attempted, failed gracefully
• Agent still responded normally ("Hello") despite API errors

Version Verification

• before_prompt_build introduced in OpenClaw 2026.2.17 (verified: not in 2026.2.15, present in 2026.2.17)
• session_start present in OpenClaw 2026.2.17 (verified via npm pack)
• registerMemoryCapability introduced in OpenClaw 2026.4.7 (verified: not in 2026.4.5, present in 2026.4.7)

---

Session Details

• Session: View Session
• Requested by: Dhravya Shah (dhravya@supermemory.com)
• Address comments on this PR. Add (aside) to your comment to have me ignore it.