openclaw-self-improvement-runtime

npm: @shikanga/openclaw-self-improvement-runtime

An OpenClaw 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

clawhub install @shikanga/openclaw-self-improvement-runtime

Then enable it in your openclaw.json:

{
  "plugins": {
    "entries": {
      "self-improvement-runtime": {
        "enabled": true
      }
    }
  }
}

Restart the gateway:

systemctl --user restart openclaw-gateway

Configuration

All fields are optional. Defaults work out of the box.

{
  "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

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:

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