OpenClawBrain

A graph-brain memory layer for OpenClaw agents that keeps useful context bounded.

OpenClawBrain organizes memories and tool-call history into a graph, retrieves a small useful slice before the prompt is built, and learns from outcomes in the background. The live path serves promoted packs only, so latency stays predictable and the hot path does not call a live LLM on every traversal hop. Publicly, the story is performance first, cost second, mechanism third: better agent performance is the win, lower cost is plausible, and bounded useful memory plus background learning are the mechanism. Checked replay is already better than no_brain on real traces, but the replay set is still small and mixed, so direct spend savings and learned_route dominance are not proven. If the memory layer is unavailable, the agent keeps running.

Status: actively developed. See CHANGELOG.md for current package versions and release history.

Documentation · Claims boundary · Changelog · Contributing · npm: plugin · npm: CLI

Start Here

| Audience | Start here | What you get | | --- | --- | --- | | Evaluator | How it works | A fast read on what OpenClawBrain is and how it behaves | | Operator | Install and verify | The one-command front door and the next docs to read | | Contributor | For contributors | Architecture docs, setup, and contribution boundaries |

How it works

1. Store. OpenClawBrain keeps conversation history and explicit user corrections as durable memory.
2. Retrieve. Before OpenClaw builds a prompt, the installed extension compiles a bounded slice of context from the currently promoted pack.
3. Learn. After the response path completes, the learning pipeline exports turns, builds a candidate pack, and only serves it after promotion.
4. Trace. Operator surfaces record why the serve path chose the current pack and whether learned routing is active.

What makes it different:

• Useful context stays bounded on the live path, and learning stays off that path so latency stays predictable.
• The runtime serves promoted packs, not partially written state.
• Explicit user corrections can outrank stale recap material when they conflict.
• The extension fails open. When the memory layer is unavailable, the agent still answers.

Mental model: learner, teacher, and route_fn

If you only remember one explanation, use this one:

• Learner = the background OpenClawBrain pipeline. It watches exported events, binds feedback to prior decisions, builds candidate packs, and updates the learned routing policy.
• Teacher = the optional local model that produces extra supervision artifacts off the hot path.
• route_fn = the learned policy artifact the live runtime uses to decide which bounded graph blocks to inject before prompt build.

In one pass:

1. OpenClaw turns produce interactions plus explicit feedback such as corrections, teachings, approvals, and suppressions.
2. OpenClawBrain normalizes those into event exports and serve-time route traces.
3. The learner builds a candidate pack with graph blocks, embeddings, structural metadata, and a learned route_fn.
4. Background learning attaches supervision from human feedback, harvested labels, and teacher artifacts, then updates the routing policy.
5. Only promoted packs serve on the live path. The runtime injects a small useful slice of context, and the hot path stays bounded instead of calling a live LLM on every traversal hop. It fails open if nothing safe or useful is available.

That is why OpenClawBrain is more than retrieval: it does not just find similar past text. It learns which context helps, keeps that learning off the hot path, and only serves immutable promoted packs.

Install and verify

Prerequisites:

• A working OpenClaw installation
• Node.js 20+
• npm

The public operator front door is one command pinned to one OpenClaw home:

openclawbrain install --openclaw-home ~/.openclaw
openclaw gateway restart
openclawbrain status --openclaw-home ~/.openclaw --detailed

install is the public front door for the selected home. It writes or repairs the hook for that home and pins the activation root the runtime serves from. status --detailed is the quick verification surface.

Activation and teacher wiring are separate checks. Seeing BRAIN LOADED or an attached home means the runtime hook is wired correctly for that OpenClaw home. It does not by itself prove that an optional teacher model is configured. Teacher wiring lives on its own config path (brainTeacherEnabled, brainTeacherProvider, brainTeacherModel) and should be verified through status fields such as teacherConfigured, teacherProvider, teacherModel, and teacherConfigError.

When you need durable operator evidence today, run the proof surface for the same home:

openclawbrain proof --openclaw-home ~/.openclaw

The intended canonical lane is the same install command with optional --proof. Until that lands cleanly across every operator surface, proof stays a separate follow-up command. proof writes summary.md, steps.json, verdict.json, raw step logs, and proof pointers under one bundle directory.

Manual native-package lane (not the public default):

openclaw plugins install @openclawbrain/openclaw
openclawbrain install --openclaw-home ~/.openclaw

openclaw plugins update openclawbrain
openclawbrain install --openclaw-home ~/.openclaw

Use that manual lane only for explicit compatibility or maintainer work on the native package layer. The public operator story stays on openclawbrain install.

A healthy install or repair should report the profile as attached. After the first promoted pack is available, detailed status should also report serveState=serving_active_pack. If you are using an optional teacher model, the same detailed status should also show teacherConfigured=true, the expected provider/model, and teacherConfigError=null.

Next docs:

• Quick start
• Troubleshooting
• Lifecycle

Scope and boundaries

OpenClawBrain is a memory layer for OpenClaw. It does not own the gateway.

It does:

• Provide one operator front door for install and repair on a selected OpenClaw home
• Store sessions and explicit corrections as durable memory
• Build candidate packs in the background and promote them when ready
• Keep the live path on promoted packs so useful context stays bounded and latency stays predictable
• Expose status, rollback, detach, uninstall, and learning inspection commands
• Fail open when memory compilation cannot safely add context

It does not:

• Start, stop, or reconfigure the OpenClaw gateway for you
• Edit LaunchAgent files or gateway environment files
• Claim same-gateway multi-profile attachment as a proven public lane
• Claim shared-root concurrent write safety

Documentation

Start with the index at docs/README.md.

Key docs:

• Quick start for the one-command install path
• Troubleshooting for the most common operator issues
• Architecture overview for the high-level system design
• Learning pipeline for export, candidate packs, promotion, and rollback
• Fail-open design for fallback behavior
• Architecture deep dive for the existing architecture notes

For contributors

If you want to work on the repo, start here:

• CONTRIBUTING.md
• docs/architecture/overview.md
• docs/architecture/deep-dive.md
• CLAIMS.md

Repo setup and validation:

npm install
npm test
npm run release:verify

If you change the public story, update the README, docs index, changelog, and claims boundary in the same pass.