feat: OpenBrain ContextEngine plugin v0.0.1 (#3)

Co-authored-by: Jason Woltje <jason@diversecanvas.com>
Co-committed-by: Jason Woltje <jason@diversecanvas.com>

README.md

@@ -1,2 +1,97 @@
 # openclaw-openbrain-context
 
+OpenBrain-backed `ContextEngine` plugin for OpenClaw.
+
+This plugin stores session context in OpenBrain over REST so context can be reassembled from recent history plus semantic matches instead of relying only on in-session compaction state.
+
+## Features
+
+- Registers context engine id: `openbrain`
+- Typed OpenBrain REST client with Bearer auth
+- Session-aware ingest + batch ingest
+- Context assembly from recent + semantic search under token budget
+- Compaction summaries archived to OpenBrain
+- Subagent seed/result handoff helpers
+
+## Requirements
+
+- OpenClaw with plugin/context-engine support (`openclaw >= 2026.3.2`)
+- Reachable OpenBrain REST API
+- OpenBrain API key
+
+## Install (local workspace plugin)
+
+```bash
+pnpm install
+pnpm build
+```
+
+Then reference this plugin in your OpenClaw config.
+
+## OpenBrain Setup (self-host or hosted)
+
+You must provide both of these in plugin config:
+
+- `baseUrl`: your OpenBrain API root (example: `https://brain.your-domain.com`)
+- `apiKey`: Bearer token for your OpenBrain instance
+
+No host or key fallback is built in. Missing `baseUrl` or `apiKey` throws `OpenBrainConfigError` at `bootstrap()`.
+
+## Configuration
+
+Plugin entry id: `openclaw-openbrain-context`  
+Context engine slot id: `openbrain`
+
+### Config fields
+
+- `baseUrl` (required, string): OpenBrain API base URL
+- `apiKey` (required, string): OpenBrain Bearer token
+- `source` (optional, string, default `openclaw`): source prefix; engine stores thoughts under `<source>:<sessionId>`
+- `recentMessages` (optional, integer, default `20`): recent thoughts to fetch for bootstrap/assemble
+- `semanticSearchLimit` (optional, integer, default `10`): semantic matches fetched in assemble
+- `subagentRecentMessages` (optional, integer, default `8`): context lines used for subagent seed/result exchange
+
+## Environment Variable Pattern
+
+Use OpenClaw variable interpolation in `openclaw.json`:
+
+```json
+{
+  "apiKey": "${OPENBRAIN_API_KEY}"
+}
+```
+
+Then set it in your shell/runtime environment before starting OpenClaw.
+
+## Example `openclaw.json`
+
+```json
+{
+  "plugins": {
+    "slots": {
+      "contextEngine": "openbrain"
+    },
+    "entries": {
+      "openclaw-openbrain-context": {
+        "enabled": true,
+        "config": {
+          "baseUrl": "https://brain.example.com",
+          "apiKey": "${OPENBRAIN_API_KEY}",
+          "source": "openclaw",
+          "recentMessages": 20,
+          "semanticSearchLimit": 10,
+          "subagentRecentMessages": 8
+        }
+      }
+    }
+  }
+}
+```
+
+## Development
+
+```bash
+pnpm lint
+pnpm build
+pnpm test
+```