Post 6: Brain-first OpenClaw Integration
Brain-first integration is the TypeScript-first runtime boundary: OpenClaw owns orchestration, fail-open behavior, and prompt assembly; OpenClawBrain provides normalized contracts/events plus routing and learning packages. The mode is optional and safe for gradual rollout.
What exactly changes when enabled?
Before brain-first (OOTB OpenClaw)
User message ↓ OpenClaw loads AGENTS/role + local files ↓ Model answers directly from loaded context ↓ Response sent ↓ Manual teach/correction workflow (if you built one)
After brain-first
User message
↓
OpenClaw runtime boundary normalizes events + workspace context
↓
Learned route function scores candidates from existing files + learned state
↓
Bounded [BRAIN_CONTEXT v1]...[/BRAIN_CONTEXT] is assembled into prompt
↓
Model answers with stronger task-relevant prior
↓
Background learner harvests labels and updates routing/graph asynchronously
Why this changes outcomes
- Fast boot: context starts from existing files, without a full fresh-state scan gate.
- Fewer turns: learned routing sends task-relevant priors into prompt assembly before generation.
- Teacher stays off hot path: heavy learning work runs asynchronously while the learned route function serves requests inline.
Runtime ownership boundary
OpenClaw runtime owns: orchestration, fail-open behavior, and prompt assembly.
OpenClawBrain owns: @openclawbrain/contracts, @openclawbrain/events, @openclawbrain/event-export, @openclawbrain/workspace-metadata, @openclawbrain/provenance, @openclawbrain/pack-format, @openclawbrain/activation, @openclawbrain/compiler, and @openclawbrain/learner.
Flow, budgets, and safety defaults
Safe defaults:
- Keep retrieval context bounded and measurable so comparisons stay fair.
- Use data-only
[BRAIN_CONTEXT v1]blocks, not raw tool traces. - Run fail-open by default: if retrieval fails, continue normal OpenClaw flow.
Deep path:
- Prioritize new incoming events first while historical ingestion and graph updates continue in background loops.
Keep human labels, self-label harvesting, and scanner ingestion default-on; that is how routing quality improves continuously after boot.
Security checklist (optional but recommended)
- Block sensitive paths before event/export normalization runs.
- Apply secret redaction before retrieval payloads are assembled.
- Keep prompt input data-only and cap retrieval context aggressively.
- Audit provenance traces for every context payload used on the hot path.
How to enable (package-first)
corepack enable pnpm install pnpm check pnpm release:pack
Then wire the released OpenClawBrain packages into the OpenClaw runtime boundary and keep fail-open behavior enabled for safe rollout.
How this interacts with learning and harvester
- Corrections, human labels, and self-harvested labels are part of the default loop, not optional add-ons.
- Continuous graph learning runs in the background: structural edits, decay, and co-firing updates happen while serving traffic.
- Routing quality improves faster because retrieval, labels, and graph updates are tied to real session flow.
Proof boundary (keep claims honest)
- Mechanism proof: bounded-context routing and learning mechanics improve route quality under controlled tests.
- Product proof: end-to-end operator outcomes require full evaluations (turns, quality, latency, spend) and rollout evidence.
Why this does not break OpenClaw OOTB
Brain-first is opt-in; OpenClaw defaults remain untouched. Rollback is immediate: disable runtime-boundary wiring and restart the gateway. Turning it off does not require data-shape rewrites.
Enablement details and operational defaults are documented in the canonical integration guide: docs/openclaw-integration.md.
Series index: OpenClawBrain v12.2.6+ series.