[integrations] Add OpenClaw native OpenBrain memory contribution

[NomLom]

What this adds

This PR adds a new OB1 integration contribution at:

• integrations/openclaw-native-memory/

It documents and ships the OpenClaw-side integration required to run OpenBrain as the active native memory backend inside OpenClaw.

Why this matters

This replaces a wrapper-heavy flow:

agent -> shell wrapper -> external bridge CLI -> MCP

With a native OpenClaw memory path:

agent -> openbrain-native memory plugin -> OpenBrain MCP

Benefits:

• lower latency
• fewer process hops and fewer failure points
• memory-slot integration inside OpenClaw
• memory prompt section support
• MCP-aligned tool names
• exact-id maintenance flows for stale/wrong/noisy memories

What is included

This contribution is split in the same numbered guide style used elsewhere in OB1:

• README.md
  <refactored documents, dee below>
• AI-INSTRUCTIONS.md
• metadata.json

And it now also includes the actual plugin source needed to build the integration:

• plugin-extension/index.ts
• plugin-extension/openclaw.plugin.json
• plugin-extension/package.json

MCP rebuild / redeploy guidance included

The contribution now also documents the missing operational piece: if the MCP interface changes, you must update and redeploy the Supabase Edge Function before the OpenClaw plugin can use the new contract.

That includes:

• expected MCP tool surface
• why ids matter for maintenance
• supabase functions deploy open-brain-mcp --no-verify-jwt
• validation examples for tools/list, capture_thought, and delete_thought
• required Accept: application/json, text/event-stream header

Tool surface documented here

The contribution reflects the live MCP contract:

• search_thoughts
• capture_thought
• list_thoughts
• thought_stats
• delete_thought

Security

No secrets are included in this PR.

The docs explicitly avoid committing:

• MCP keys
• OpenRouter keys
• live endpoint secrets
• copied local config files

They also document why secret handling must stay in environment/config, not source control.

Notes on maintenance policy

The docs reflect a deliberate maintenance stance:

• use delete_thought for stale, wrong, contradictory, accidental, or low-value noisy entries
• do not treat all duplicates as bad
• reinforcing duplicates can improve retrieval and should not be removed blindly

Tested

Tested on a working local OpenClaw + OpenBrain setup:

• plugin installs successfully
• plugin loads as kind: "memory"
• OpenClaw switches the memory slot to openbrain-native
• runtime exposes all five tools listed above
• MCP server supports exact-id delete flow

Why PR this into OB1

This is the right place for it because it is an integration contribution documenting how to connect OpenBrain to another agent runtime in a way that is reproducible, secure, and operationally maintainable.

[justfinethanku]

Review of OpenClaw Native OpenBrain Memory Integration

Thank you for this substantial contribution! This is an impressive integration that fills a real need for OpenClaw users who want to use OpenBrain as their memory backend. The documentation is thorough, well-structured, and production-ready.

What's Excellent

1. Comprehensive Documentation

• The numbered guide structure (01-08) makes the setup flow crystal clear
• Troubleshooting guide is exceptional - the failure matrix table with symptom → cause → fix → re-validate is exactly what users need
• Security/credential hygiene is explicitly documented with safe patterns (using read -s, avoiding shell history)
• The validation bundle pattern is solid - giving users a copy-paste checklist to confirm everything works

2. Code Quality

• Plugin TypeScript code is clean and well-structured
• Proper error handling with timeout controls
• Support for both URL-key and bearer token auth patterns
• The envelope mode fallback for MCP servers that only accept content is clever
• Good type safety with proper parameter interfaces

3. Security

• No credentials or secrets in any files ✅
• Explicit warnings about credential hygiene
• Proper environment variable patterns documented
• No dangerous SQL operations ✅

4. Production Readiness

• Package install patterns (vs dev patterns)
• Version pinning and rollback guidance
• Bounded retry recipes for transient failures
• Clear maintenance policy (when to delete vs keep duplicates)

Minor Improvements Needed

1. README.md - Missing Standard Sections

Per CONTRIBUTING.md requirements, the README should include:

• Expected outcome - you have this ✅
• Prerequisites - you have this ✅
• Troubleshooting - you link to 05-troubleshooting.md which is fine, but consider adding 2-3 of the most common issues directly in the README (like "plugin not loading" and "401/403 auth errors") with a "See 05-troubleshooting.md for the complete troubleshooting guide" note

2. Integration Category - Consider MCP Server Pattern

The repo's CONTRIBUTING.md states (line 254):

Extensions and integrations must use remote MCP via Supabase Edge Functions. No claude_desktop_config.json, no local Node.js stdio servers.

This contribution is an OpenClaw plugin that consumes an MCP server, which is different from the "integrations must deploy as Edge Functions" pattern used elsewhere in the repo. This is actually a good pattern (it's showing how to connect existing infrastructure), but it might be worth:

• Adding a note in the README clarifying this is a client-side plugin (not an MCP server deployment)
• Confirming with maintainers that this pattern fits the "integrations" category vs needing a new category like "client-plugins" or "agent-connectors"

3. Small Polish Items

• In 01-install-local.md line 43, the path references extension/ but the actual folder is plugin-extension/ - should be consistent
• The package-lock.json is 244KB which is fine (under 1MB), but worth noting in the README that it's included for exact dependency pinning
• Consider adding a "Tested with" section noting specific OpenClaw version(s) this was validated against

4. AI-INSTRUCTIONS.md

This file is interesting but not standard across other contributions. It's not hurting anything, but consider whether it adds value for contributors or if the information belongs in comments within the code itself.

Verification Checklist

✅ Folder structure correct (integrations/openclaw-native-memory/)
✅ Required files present (README.md + metadata.json)
✅ metadata.json valid JSON with all required fields
✅ No credentials, API keys, or secrets
✅ No dangerous SQL operations
✅ No binary blobs over 1MB
✅ No prohibited file types (.exe, .dmg, .zip, .tar.gz)
✅ PR title follows format: [integrations] Short description
✅ Code files present (TypeScript plugin source)
⚠️ README mostly complete (add 2-3 inline troubleshooting items)
⚠️ Integration pattern differs from standard MCP deployment pattern (may need maintainer clarification)

Questions for Maintainers

1. Does the "integrations" category accommodate client-side plugins that consume MCP servers, or should this be in a different category?
2. Is the numbered docs structure (01-08) preferred, or should this be condensed into fewer files?
3. The contribution includes actual plugin source code - is this the right place for it, or should it reference an external package/repo?

Verdict: Minor fixes needed

This is high-quality work that's almost ready to merge. The main items to address:

1. Add 2-3 common troubleshooting scenarios directly in the README
2. Fix the extension/ vs plugin-extension/ path inconsistency in 01-install-local.md
3. Get maintainer confirmation that this integration pattern fits the category

Once those are addressed, this will be a stellar addition to the OB1 repo. The thoroughness of the documentation and the production-ready approach are exactly what the community needs.

Great work, Leon! 🎉

[NomLom]

Thanks for the careful review. I reworked the contribution so the docs are smaller, clearer, and more practical to follow.

The PR now does three things more clearly:

1. It explains what the extension is and why it exists.
   This is about making OpenBrain work as a native OpenClaw memory backend instead of relying on wrapper-style memory flows.

2. It makes the MCP contract changes explicit.
   This extension expects more than the older server shape. In particular, it depends on exact-id maintenance flows, which means:

   • delete_thought is available
   • search_thoughts and list_thoughts return ids in machine-readable structuredContent.items[]
   • human-readable text stays clean while ids remain available for delete, verify, and undo operations

3. It condenses the docs into a smaller, action-oriented set under extensions/openclaw-native-memory/:

   • 01-README.md
   • 02-AI-INSTRUCTIONS.md
   • 03-MCP-SERVER.md
   • 04-OPENCLAW-NATIVE-MEMORY-EXTENSION.md
   • 05-TROUBLESHOOTING.md

I also addressed the practical review points:

• added a real quickstart
• clarified that this is a client-side OpenClaw extension consuming a remote MCP server
• simplified the install flow so it uses manual config editing instead of mutation helpers
• added clearer install, config, validation, and troubleshooting steps
• added a smoke-test script for faster verification
• tightened the MCP server instructions so they distinguish pre-merge vs post-merge source files

On the broader questions:

• moved to the extensions space because it documents how OpenClaw connects to the remote OpenBrain MCP server, but the shape is now cleaner and more focused.
• I agreed the previous doc split was overdone, so I condensed it.
• I kept AI-INSTRUCTIONS.md intentionally because this is something an AI or operator should be able to execute without hunting through a pile of docs.

The installable extension artifact lives here:

• https://github.com/NomLom/openbrain-native-openclaw
• https://github.com/NomLom/openbrain-native-openclaw/releases

I have linked to my releases incase the bins go back into the oven.

That is what these docs now point to for the packaged extension, while this PR focuses on the extension contract, server expectations, and OpenClaw-side setup.

[NomLom]

Heyya, its just about cooked, I linked to my repo, moved the extension there, can move it back if you like, but it might need cooking more in the future, so it's best left there rather than trapped in amber.
I took all the techie detail out and moved it to my repo, so implementing/installing this is if no longer the Krypton Factor.

The extension works, the things I noticed as it takes about 3rd of the time to run compared to the wrapper, and now the openclaw will happily use Openbrain without prompting or ignoring agents.md as the plugin is a native memory extension.

What a journey.

[matthallett1]

hey there! I was just about to test this one out and I saw that you moved it to a different repo. I'll give it a test there, but yeah, please re-submit it when you think it's ready.

[NomLom]

Its having a major refactor, adding new features and a few sanity checks, let me cook it over the weekend, the PR was getting messy.