Tools
Self Improvement Runtime
By Runtime enforcement plugin for OpenClaw — mistake detection, finalization gating, and structured self-correction.
Install
npm install
nodeConfiguration Example
{
"plugins": {
"entries": {
"self-improvement-runtime": {
"enabled": true
}
}
}
}README
# openclaw-self-improvement-runtime
[](https://github.com/phantom-instruction-set/openclaw-self-improvement-runtime/actions/workflows/ci.yml)
**npm:** [@shikanga/openclaw-self-improvement-runtime](https://www.npmjs.com/package/@shikanga/openclaw-self-improvement-runtime)
An [OpenClaw](https://openclaw.ai) workspace plugin that enforces structured self-correction at runtime.
When the agent makes a mistake, this plugin intercepts the normal task flow and requires a demonstrable correction cycle before work can continue — not a reminder, an enforcement gate.
## What it does
- **Detects mistakes** — user corrections and tool failures trigger an incident
- **Gates finalization** — the agent cannot close a turn until it has acknowledged the mistake, identified the root cause, stated a prevention rule, and confirmed verification
- **Enforces closure format** — replies are steered toward a labeled template (`Root cause:`, `Prevention rule:`, `Verification:`) rather than free-form apologies
- **Checks persistence evidence** — closure only counts if a learnings file was actually written during the turn (mtime check)
- **Records everything** — every incident open, revise, bypass, and close is written to a JSONL event log and a status dashboard in the workspace
## Requirements
- OpenClaw `>=2026.5.6`
- Node.js `>=22`
## Installation
```bash
clawhub install @shikanga/openclaw-self-improvement-runtime
```
Then enable it in your `openclaw.json`:
```json
{
"plugins": {
"entries": {
"self-improvement-runtime": {
"enabled": true
}
}
}
}
```
Restart the gateway:
```bash
systemctl --user restart openclaw-gateway
```
## Configuration
All fields are optional. Defaults work out of the box.
```json
{
"plugins": {
"entries": {
"self-improvement-runtime": {
"enabled": true,
"maxReviseCount": 2,
"eventLogRelativePath": "memory/self-improvement-runtime-events.jsonl",
"persistenceCheckPaths": [
"memory/FOREVER_LEARNING.md",
".learnings/LEARNINGS.md",
".learnings/ERRORS.md"
]
}
}
}
}
```
| Field | Default | Description |
|---|---|---|
| `enabled` | `true` | Enable or disable without uninstalling |
| `maxReviseCount` | `2` | Maximum gate retries before degraded bypass |
| `eventLogRelativePath` | `memory/self-improvement-runtime-events.jsonl` | Workspace-relative path for the JSONL event log |
| `persistenceCheckPaths` | `["memory/FOREVER_LEARNING.md", ".learnings/LEARNINGS.md", ".learnings/ERRORS.md"]` | Workspace-relative paths checked for mtime evidence of a learnings write |
## How closure works
When an incident is open, the agent must produce a reply containing all four elements:
```
I made a mistake.
[what was wrong]
Root cause: [why it happened]
Prevention rule: [concrete rule for future behaviour]
Verification: [how you confirmed the fix]
```
The gate checks for labeled sections first. If all four are present and non-trivial, the incident closes. If any are missing, the gate retries with an explicit skeleton. After `maxReviseCount` retries, the gate degrades to allow the conversation to continue — the incident is marked bypassed, not closed.
## Learnings files
The persistence check looks for evidence that the agent actually wrote a lesson to disk during the turn — not just said it would.
The default paths (`memory/FOREVER_LEARNING.md`, `.learnings/LEARNINGS.md`, `.learnings/ERRORS.md`) are workspace-relative and follow the standard OpenClaw workspace layout. You do not need to create these files before installing — the plugin checks for an mtime newer than the incident open time, and simply skips any path that does not exist yet.
If your workspace uses different paths for learnings files, override them via `persistenceCheckPaths` in your `openclaw.json`.
## Observability
Two files are written in the workspace:
- **Event log** (`memory/self-improvement-runtime-events.jsonl`) — one JSON line per event: `mistake_opened`, `gate_retry`, `gate_degraded_bypass`, `mistake_closed`
- **Status dashboard** (`memory/self-improvement-status.md`) — human-readable summary regenerated after each turn
## Running tests
```bash
git clone https://github.com/phantom-instruction-set/openclaw-self-improvement-runtime.git
cd openclaw-self-improvement-runtime
npm install
node --test
```
`npm install` is required before `node --test` — it installs the minimal OpenClaw stub from `test-fixtures/openclaw-stub/` that allows the test suite to resolve the `openclaw` import without a live gateway.
103 tests, 29 suites.
## Releasing a new version
Releases are fully automated via GitHub Actions. The release workflow runs tests first — a failing test blocks the publish.
1. Bump `version` in `package.json`, commit, and push to `main`
2. Tag and push:
```bash
git tag vX.Y.Z
git push origin vX.Y.Z
```
GitHub Actions runs `node --test` then `npm publish --access public` on green.
## License
MIT
tools
Comments
Sign in to leave a comment