@jonathangu/openclawbrain 0.3.0 → 0.3.1

package/docs/configuration.md

@@ -2,20 +2,29 @@
 
 This guide covers the practical operator setup for **OpenClawBrain v2**.
 
-For repo truth, read:
+If you want the repo's exact truth contract first, read:
 - `README.md`
 - `docs/RELEASE_CONTRACT.md`
-- `docs/END_STATE.md`
+- `docs/EVIDENCE.md`
 
-## Quick start
+## Happy-path operator flow
 
-Install the plugin with OpenClaw's plugin installer:
+1. install the plugin with the OpenClaw plugin installer
+2. configure embeddings and choose a `brainRoot`
+3. prefer `brainWorkerMode=child`
+4. run `openclawbrain init <workspace>`
+5. check `openclawbrain status`
+6. run the validation harnesses appropriate to the claim you want to make
+
+## Install
+
+Published package:
 
 ```bash
 openclaw plugins install @jonathangu/openclawbrain
 ```
 
-If you're running from a local OpenClaw checkout:
+From a local OpenClaw checkout:
 
 ```bash
 pnpm openclaw plugins install @jonathangu/openclawbrain
@@ -27,21 +36,15 @@ For local development, link your working copy:
 openclaw plugins install --link /path/to/openclawbrain
 ```
 
-`openclaw plugins install` handles plugin registration, enabling, and compatible slot selection automatically.
+The plugin installer is the supported install boundary.
 
-## Context engine slot
+## Important host-seam truth
 
-If you must set it manually, point the context engine slot at `openclawbrain`:
+On current OpenClaw hosts, **do not manually write** `plugins.slots.contextEngine` for OpenClawBrain.
 
-```json
-{
-  "plugins": {
-    "slots": {
-      "contextEngine": "openclawbrain"
-    }
-  }
-}
-```
+That older seam is not the stable install story anymore. OpenClawBrain now uses a hook-based compatibility bridge on hosts where `api.registerContextEngine` is gone.
+
+If you are debugging an older host build, treat any manual slot override as version-specific surgery rather than normal operator setup.
 
 ## Recommended starting configuration
 
@@ -74,7 +77,7 @@ Why these defaults:
 
 ## Initialization
 
-The transcript layer works immediately after install. Learned retrieval needs an explicit init:
+The transcript-memory layer works immediately after install. Learned retrieval needs an explicit init pass:
 
 ```bash
 openclawbrain init /path/to/workspace
@@ -84,7 +87,7 @@ That creates the initial graph, writes `state.db`, snapshots pack `v000001`, and
 
 ## Embeddings
 
-OpenClawBrain currently targets tested OpenAI-compatible embeddings APIs.
+OpenClawBrain currently targets tested OpenAI-compatible `/v1/embeddings` APIs.
 
 ### Local Ollama
 
@@ -103,7 +106,11 @@ OpenClawBrain currently targets tested OpenAI-compatible embeddings APIs.
 }
 ```
 
-This defaults to `http://127.0.0.1:11434/v1`.
+Default base URL:
+
+```text
+http://127.0.0.1:11434/v1
+```
 
 ### Remote OpenAI-compatible endpoint
 
@@ -123,7 +130,7 @@ This defaults to `http://127.0.0.1:11434/v1`.
 }
 ```
 
-If the endpoint requires auth, provide `OPENCLAWBRAIN_EMBEDDING_API_KEY`.
+If the remote endpoint requires auth, set `OPENCLAWBRAIN_EMBEDDING_API_KEY`.
 
 ## Important environment variables
 
@@ -137,8 +144,19 @@ If the endpoint requires auth, provide `OPENCLAWBRAIN_EMBEDDING_API_KEY`.
 | `OPENCLAWBRAIN_EMBEDDING_PROVIDER` | Embedding provider (`openai`, `openai-resp`, `ollama`) |
 | `OPENCLAWBRAIN_EMBEDDING_MODEL` | Embedding model used for init/retrieval/teach |
 | `OPENCLAWBRAIN_EMBEDDING_BASE_URL` | Optional embeddings API base URL |
-| `OPENCLAWBRAIN_EMBEDDING_API_KEY` | Optional explicit auth for remote embedding endpoints |
+| `OPENCLAWBRAIN_EMBEDDING_API_KEY` | Optional auth for remote embedding endpoints |
 | `OPENCLAWBRAIN_SHADOW_MODE` | Record routing without injecting learned context |
+| `OPENCLAWBRAIN_WORKER_MODE` | Worker mode; prefer `child` for the real operator boundary |
+
+## Child-worker boundary
+
+`brainWorkerMode=child` is the recommended serving boundary.
+
+Why:
+- serving reads immutable promoted packs
+- the learner runs in a separate supervised child process
+- status/doctor surfaces can report PID, heartbeat, restart, and exit truth clearly
+- `in_process` remains useful for development or debugging, but it should not be treated as the production operator boundary
 
 ## Operator commands
 
@@ -156,13 +174,17 @@ openclawbrain doctor
 
 ## Validation commands
 
-Deterministic runtime proof harness:
+### Deterministic runtime proof harness
 
 ```bash
-node scripts/validate-brain-runtime-behavior.ts
+pnpm exec tsx scripts/validate-brain-runtime-behavior.ts
 ```
 
-Disposable host-surface harness:
+Use this when you want a real signal on:
+- immediate post-teach retrieval
+- serve-from-last-promoted-pack after worker failure
+
+### Disposable host-surface harness
 
 ```bash
 node scripts/validate-openclaw-install.mjs --setup-only
@@ -173,6 +195,21 @@ OPENCLAWBRAIN_VALIDATION_MODEL=ollama/qwen2.5:7b-instruct \
 node scripts/validate-openclaw-install.mjs
 ```
 
+Current honest status:
+- sterile preflight/config seam repairs are real
+- deterministic runtime proof is real
+- the full sterile host harness is still not frozen end to end because it currently stalls during `openclawbrain init`
+
+So treat the host harness as active proof work, not a closed release gate.
+
+## Fallback behavior
+
+- if the brain has not been initialized, OpenClawBrain serves transcript-memory context only
+- if embeddings are not configured, learned retrieval and `brain_teach` stay disabled
+- local loopback embedding endpoints do not require a bearer token by default
+- if the worker is unavailable, serving still uses the last promoted pack
+- `openclawbrain status` and `openclawbrain doctor` expose embedding and worker truth so operator state stays visible
+
 ## Session reset note
 
 OpenClawBrain preserves history through compaction, but it does not override OpenClaw's core session reset policy. If sessions reset sooner than you want, increase OpenClaw's `session.reset.idleMinutes`.

package/docs/evidence/2026-03-16/1fc8ee6fd7892e3deb27d111434df948bca2a66b/channels-status.txt

@@ -0,0 +1,20 @@
+[plugins] [openclawbrain] Plugin loaded (enabled=true, db=/Users/cormorantai/.openclaw-ocbphase1/lcm.db, threshold=0.75)
+│
+◇  Doctor changes ──────────────────────────────╮
+│                                               │
+│  Telegram configured, enabled automatically.  │
+│                                               │
+├───────────────────────────────────────────────╯
+│
+◇  Doctor ──────────────────────────────────────────────╮
+│                                                       │
+│  Run "openclaw doctor --fix" to apply these changes.  │
+│                                                       │
+├───────────────────────────────────────────────────────╯
+Checking channel status (probe)…
+Gateway not reachable; showing config-only status.
+Config: /Users/cormorantai/.openclaw-ocbphase1/openclaw.json
+Mode: local
+
+
+Tip: https://docs.openclaw.ai/cli#status adds gateway health probes to status output (requires a reachable gateway).

package/docs/evidence/2026-03-16/1fc8ee6fd7892e3deb27d111434df948bca2a66b/config-snapshot.json

@@ -0,0 +1,94 @@
+{
+  "gitSha": "1fc8ee6fd7892e3deb27d111434df948bca2a66b",
+  "artifactDir": "/Users/cormorantai/openclawbrain/docs/evidence/2026-03-16/1fc8ee6fd7892e3deb27d111434df948bca2a66b",
+  "validationMode": "sterile-lane",
+  "validationLaneName": "ocbphase1",
+  "validationRoot": "/Users/cormorantai/.openclaw-ocbphase1",
+  "validationHome": "/Users/cormorantai",
+  "validationStateDir": "/Users/cormorantai/.openclaw-ocbphase1",
+  "fixtureWorkspace": "/Users/cormorantai/.openclaw-ocbphase1/workspace-fixture",
+  "configPath": "/Users/cormorantai/.openclaw-ocbphase1/openclaw.json",
+  "lcmDbPath": "/Users/cormorantai/.openclaw-ocbphase1/lcm.db",
+  "brainRoot": "/Users/cormorantai/.openclaw-ocbphase1/openclawbrain",
+  "validationRecordFile": "/Users/cormorantai/.openclaw-ocbphase1/validation-records/validation-assemble.jsonl",
+  "validationGatewayPort": 19031,
+  "config": {
+    "meta": {
+      "lastTouchedVersion": "2026.3.13",
+      "lastTouchedAt": "2026-03-16T15:23:45.483Z"
+    },
+    "models": {
+      "providers": {
+        "ollama": {
+          "baseUrl": "http://127.0.0.1:11434",
+          "apiKey": "ollama-local",
+          "api": "ollama",
+          "models": [
+            {
+              "id": "qwen2.5:7b-instruct",
+              "name": "qwen2.5:7b-instruct",
+              "reasoning": false,
+              "input": [
+                "text"
+              ],
+              "cost": {
+                "input": 0,
+                "output": 0,
+                "cacheRead": 0,
+                "cacheWrite": 0
+              },
+              "contextWindow": 262144,
+              "maxTokens": 16384
+            }
+          ]
+        }
+      }
+    },
+    "agents": {
+      "defaults": {
+        "model": {
+          "primary": "ollama/qwen2.5:7b-instruct"
+        },
+        "workspace": "/Users/cormorantai/.openclaw-ocbphase1/workspace-fixture",
+        "compaction": {
+          "mode": "safeguard"
+        }
+      }
+    },
+    "commands": {
+      "native": "auto",
+      "nativeSkills": "auto",
+      "restart": true,
+      "ownerDisplay": "raw"
+    },
+    "gateway": {
+      "port": 19031,
+      "mode": "local"
+    },
+    "plugins": {
+      "load": {
+        "paths": [
+          "/Users/cormorantai/openclawbrain"
+        ]
+      },
+      "slots": {},
+      "entries": {
+        "openclawbrain": {
+          "enabled": true,
+          "config": {
+            "enabled": true
+          }
+        }
+      },
+      "installs": {
+        "openclawbrain": {
+          "source": "path",
+          "sourcePath": "/Users/cormorantai/openclawbrain",
+          "installPath": "/Users/cormorantai/openclawbrain",
+          "version": "0.3.0",
+          "installedAt": "2026-03-16T15:23:45.475Z"
+        }
+      }
+    }
+  }
+}

package/docs/evidence/2026-03-16/1fc8ee6fd7892e3deb27d111434df948bca2a66b/doctor.json

@@ -0,0 +1,14 @@
+{
+  "command": "openclaw",
+  "args": [
+    "doctor",
+    "--non-interactive"
+  ],
+  "cwd": "/Users/cormorantai/openclawbrain",
+  "exitCode": 0,
+  "signal": null,
+  "ok": true,
+  "stdout": "▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄\n██░▄▄▄░██░▄▄░██░▄▄▄██░▀██░██░▄▄▀██░████░▄▄▀██░███░██\n██░███░██░▀▀░██░▄▄▄██░█░█░██░█████░████░▀▀░██░█░█░██\n██░▀▀▀░██░█████░▀▀▀██░██▄░██░▀▀▄██░▀▀░█░██░██▄▀▄▀▄██\n▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀\n                  🦞 OPENCLAW 🦞                    \n \n┌  OpenClaw doctor\n[plugins] [openclawbrain] Plugin loaded (enabled=true, db=/Users/cormorantai/.openclaw-ocbphase1/lcm.db, threshold=0.75)\n│\n◇  Install ─────────────────────────────────────────────────────────╮\n│                                                                   │\n│  - package-lock.json present in a pnpm workspace. If you ran npm  │\n│    install, remove it and reinstall with pnpm.                    │\n│                                                                   │\n├───────────────────────────────────────────────────────────────────╯\n│\n◇  Doctor changes ──────────────────────────────╮\n│                                               │\n│  Telegram configured, enabled automatically.  │\n│                                               │\n├───────────────────────────────────────────────╯\n│\n◇  Doctor ──────────────────────────────────────────────╮\n│                                                       │\n│  Run \"openclaw doctor --fix\" to apply these changes.  │\n│                                                       │\n├───────────────────────────────────────────────────────╯\n│\n◇  Gateway auth ──────────────────────────────────────────────────╮\n│                                                                 │\n│  Gateway auth is off or missing a token. Token auth is now the  │\n│  recommended default (including loopback).                      │\n│                                                                 │\n├─────────────────────────────────────────────────────────────────╯\n│\n◇  State integrity ────────────────────────────────────────────────────────╮\n│                                                                          │\n│  - OAuth dir not present ($OPENCLAW_HOME/credentials). Skipping create   │\n│    because no WhatsApp/pairing channel config is active.                 │\n│  - Multiple state directories detected. This can split session history.  │\n│    - /Users/cormorantai/.openclaw                                        │\n│    Active state dir: $OPENCLAW_HOME                                      │\n│                                                                          │\n├──────────────────────────────────────────────────────────────────────────╯\n│\n◇  Other gateway-like services detected ───────────────────────────────────────╮\n│                                                                              │\n│  - com.openclawbrain.daemon.activation.0ec88212fa7d (user, plist:            │\n│    /Users/cormorantai/Library/LaunchAgents/com.openclawbrain.daemon.activat  │\n│  ion.0ec88212fa7d.plist)                                                     │\n│  - com.openclawbrain.daemon.activation.546e84bf06ac (user, plist:            │\n│    /Users/cormorantai/Library/LaunchAgents/com.openclawbrain.daemon.activat  │\n│  ion.546e84bf06ac.plist)                                                     │\n│  - com.openclawbrain.daemon.activation.b3eeb450ca08 (user, plist:            │\n│    /Users/cormorantai/Library/LaunchAgents/com.openclawbrain.daemon.activat  │\n│  ion.b3eeb450ca08.plist)                                                     │\n│                                                                              │\n├──────────────────────────────────────────────────────────────────────────────╯\n│\n◇  Cleanup hints ─────────────────────────────────────────╮\n│                                                         │\n│  - launchctl bootout gui/$UID/ai.openclaw.gateway       │\n│  - rm ~/Library/LaunchAgents/ai.openclaw.gateway.plist  │\n│                                                         │\n├─────────────────────────────────────────────────────────╯\n│\n◇  Gateway recommendation ───────────────────────────────────────────────╮\n│                                                                        │\n│  Recommendation: run a single gateway per machine for most setups.     │\n│  One gateway supports multiple agents.                                 │\n│  If you need multiple gateways (e.g., a rescue bot on the same host),  │\n│  isolate ports + config/state (see docs:                               │\n│  /gateway#multiple-gateways-same-host).                                │\n│                                                                        │\n├────────────────────────────────────────────────────────────────────────╯\n│\n◇  Security ─────────────────────────────────╮\n│                                            │\n│  - No channel security warnings detected.  │\n│  - Run: openclaw security audit --deep     │\n│                                            │\n├────────────────────────────────────────────╯\n│\n◇  Skills status ────────────╮\n│                            │\n│  Eligible: 9               │\n│  Missing requirements: 43  │\n│  Blocked by allowlist: 0   │\n│                            │\n├────────────────────────────╯\n│\n◇  Plugins ──────╮\n│                │\n│  Loaded: 8     │\n│  Disabled: 34  │\n│  Errors: 0     │\n│                │\n├────────────────╯\n│\n◇  Gateway ──────────────╮\n│                        │\n│  Gateway not running.  │\n│                        │\n├────────────────────────╯\n│\n◇  Gateway connection ───────────────────────────────────────────╮\n│                                                                │\n│  Gateway target: ws://127.0.0.1:19031                          │\n│  Source: local loopback                                        │\n│  Config: /Users/cormorantai/.openclaw-ocbphase1/openclaw.json  │\n│  Bind: loopback                                                │\n│                                                                │\n├────────────────────────────────────────────────────────────────╯\n│\n◇  Gateway ────────────────────────╮\n│                                  │\n│  Gateway service not installed.  │\n│                                  │\n├──────────────────────────────────╯\nRun \"openclaw doctor --fix\" to apply changes.\n│\n└  Doctor complete.\n\n",
+  "stderr": "[plugins] plugins.allow is empty; discovered non-bundled plugins may auto-load: openclawbrain (/Users/cormorantai/openclawbrain/index.ts). Set plugins.allow to explicit trusted ids.\n",
+  "error": null
+}

package/docs/evidence/2026-03-16/1fc8ee6fd7892e3deb27d111434df948bca2a66b/gateway-probe.txt

@@ -0,0 +1,24 @@
+[plugins] [openclawbrain] Plugin loaded (enabled=true, db=/Users/cormorantai/.openclaw-ocbphase1/lcm.db, threshold=0.75)
+│
+◇  Doctor changes ──────────────────────────────╮
+│                                               │
+│  Telegram configured, enabled automatically.  │
+│                                               │
+├───────────────────────────────────────────────╯
+│
+◇  Doctor ──────────────────────────────────────────────╮
+│                                                       │
+│  Run "openclaw doctor --fix" to apply these changes.  │
+│                                                       │
+├───────────────────────────────────────────────────────╯
+Gateway Status
+Reachable: no
+Probe budget: 3000ms
+
+Discovery (this machine)
+Found 4 gateway(s) via Bonjour (local.)
+
+Targets
+Local loopback ws://127.0.0.1:19031
+  Connect: failed - connect failed: connect ECONNREFUSED 127.0.0.1:19031
+

package/docs/evidence/2026-03-16/1fc8ee6fd7892e3deb27d111434df948bca2a66b/gateway-status.txt

@@ -0,0 +1,31 @@
+[plugins] [openclawbrain] Plugin loaded (enabled=true, db=/Users/cormorantai/.openclaw-ocbphase1/lcm.db, threshold=0.75)
+│
+◇  Doctor changes ──────────────────────────────╮
+│                                               │
+│  Telegram configured, enabled automatically.  │
+│                                               │
+├───────────────────────────────────────────────╯
+│
+◇  Doctor ──────────────────────────────────────────────╮
+│                                                       │
+│  Run "openclaw doctor --fix" to apply these changes.  │
+│                                                       │
+├───────────────────────────────────────────────────────╯
+Service: LaunchAgent (not loaded)
+File logs: /tmp/openclaw/openclaw-2026-03-16.log
+
+Config (cli): $OPENCLAW_HOME/openclaw.json
+Config (service): $OPENCLAW_HOME/openclaw.json
+
+Gateway: bind=loopback (127.0.0.1), port=19031 (env/config)
+Probe target: ws://127.0.0.1:19031
+Dashboard: http://127.0.0.1:19031/
+Probe note: Loopback-only gateway; only local clients can connect.
+
+Runtime: unknown (Bad request.
+Could not find service "ai.openclaw.gateway" in domain for user gui: 501)
+
+
+
+Troubles: run openclaw status
+Troubleshooting: https://docs.openclaw.ai/troubleshooting

package/docs/evidence/2026-03-16/1fc8ee6fd7892e3deb27d111434df948bca2a66b/init-capture.json

@@ -0,0 +1,15 @@
+{
+  "command": "node",
+  "args": [
+    "bin/openclawbrain.js",
+    "init",
+    "/Users/cormorantai/.openclaw-ocbphase1/workspace-fixture"
+  ],
+  "cwd": "/Users/cormorantai/openclawbrain",
+  "exitCode": 0,
+  "signal": null,
+  "ok": true,
+  "stdout": "{\n  \"command\": \"init\",\n  \"workspaceRoot\": \"/Users/cormorantai/.openclaw-ocbphase1/workspace-fixture\",\n  \"summary\": \"Brain initialized: 3 nodes (3 chunk), 4 edges\",\n  \"packVersion\": 6\n}\n",
+  "stderr": "[brain] Discovering sources...\n[brain] Found 2 sources\n[brain] Created 3 chunks\n[brain] Computing embeddings...\n[brain] Embedded 3/3 nodes\n[brain] Created 4 edges (2 sibling, 2 semantic)\n[brain] Brain initialized: 3 nodes (3 chunk), 4 edges\n",
+  "error": null
+}