OpenClawBrain

A local memory layer for OpenClaw agents that keeps useful context bounded.

OpenClawBrain stores conversation history and explicit corrections, retrieves a bounded slice of the context most likely to matter, learns from outcomes in the background, and records why a retrieval won. The live path serves promoted packs so latency stays predictable. 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.

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.

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.

Advanced or legacy package-management lane:

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

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

Use that manual lane only when you are explicitly managing the native plugin package yourself. The public 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.

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.