Per-agent feedback loop for OpenClaw — captures corrections/errors/features, detects patterns per agent workspace, notifies via per-agent channel bot, and ex...
---
name: self-improvement-loop
version: 4.6.13
description: |
Per-agent feedback loop for OpenClaw — captures corrections/errors/features, detects patterns per agent workspace, notifies via per-agent channel bot, and executes A/B/C/D decisions in the correct agent session.
Auto-detects agents from openclaw.json, auto-maps agent ID → channel account → bindings.
A/B/C/D handling logic lives in scripts/agents-append.md (shared); install.sh injects a reference into each agent's AGENTS.md and memory.md.
---
# self-improvement-loop v4.6.13
## Overview
**Core Capability**: Each agent has its own self-improvement feedback loop — isolated learnings directory, independent cron scan, notifications bound to their own channel bot, and A/B/C/D execution in the correct agent session.
```
User corrects code-dev agent
↓
code-dev hook captures → writes to code-dev/.learnings/
↓
self-improvement-code-dev cron (hourly) → scans only code-dev/.learnings/
↓
Pattern detected (count≥2) → notifies user via code bot
↓
User replies A → code-dev agent session executes → writes back to code-dev workspace
```
---
## Data Flow (Per-Agent Isolation)
```
openclaw.json (agents.list + bindings)
│
├─→ install.sh reads agents
│ ↓
│ Creates per-agent directories (e.g., agents/workspace/.learnings/)
│
├─→ install.sh reads channel accounts
│ ↓
│ Writes bindings (agentId → accountId)
│ { "agentId": "code-dev", "match": { "channel": "telegram", "accountId": "code" } }
│
└─→ setup_crons.py creates per-agent cron
↓
Each cron carries --agent flag
LEARNINGS_DIR points to that agent's workspace
delivery uses that agent's account
┌─────────────────────────────────────────────────────────────┐
│ Hook (handler.js) - Global shared, dynamic routing │
│ sessionKey: "agent:code-dev:telegram:..." │
│ → extractAgentId("code-dev") │
│ → getAgentWorkspace("code-dev") → agent workspace path │
│ → learningsDir = workspace + "/.learnings/" │
│ Pushes reminders to context.messages │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ Cron (per-agent) - Independent execution │
│ Name: self-improvement-code-dev │
│ --agent code-dev → bound to code-dev agent session │
│ LEARNINGS_DIR=".../agents/code-dev/.learnings" │
│ delivery: channel=telegram, accountId=code │
│ Scans only its own LEARNINGS_DIR │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ Notification - Sent via respective channel bot │
│ code bot → user conversation with code-dev │
│ moling bot → user conversation with moling │
│ User replies A/B/C/D → OpenClaw routes to correct agent │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ A/B/C/D Execution - Runs in correct agent session │
│ Reads pending JSON → executes skill-creator/skill-improvement
│ Writes back to that agent's learnings directory │
└─────────────────────────────────────────────────────────────┘
```
---
## Permissions Required
| Permission | Scope | Purpose |
|---------------|------------------------------|----------------------------------------------------|
| `exec` | `scripts/` | Run distill.sh, archive.sh (mechanical scan/archive) |
| `read` | `<agent>/workspace/.learnings/` | Read LEARNINGS.md, ERRORS.md, FEATURE_REQUESTS.md |
| `write` | `<agent>/workspace/.learnings/` | Update notified status; create `.pending_notifications/*.json` |
| `cron` | Global | Create and manage self-improvement-{agent} cron jobs |
| `gateway_api` | Gateway :18789 | setup_crons.py calls API to create crons |
| `openclaw.json` | `HOME/.openclaw/` | install.sh reads agent config; writes bindings |
**Security Boundaries**:
- File operations strictly scoped to per-agent learnings directories under `~/.openclaw/workspace/`
- All paths dynamically generated, no hardcoding
- Cron runs in isolated session with minimal toolset
- install.sh prompts for confirmation before writing bindings, can be skipped
---
## Core Components
| Component | Type | Routing Basis |
|---------------------|---------------|--------------------------------------|
| `handler.js` | Global Hook | sessionKey → agent ID → workspace |
| `distill.sh` | Shared Script | `LEARNINGS_DIR` environment variable |
| `setup_crons.py` | Shared Script | agent config → cron --agent flag |
| `install.sh` | Install Script| agents.list + accounts → bindings |
| `agents-append.md` | A/B/C/D Logic | Shared across agents; install.sh injects index reference |
---
## Installation
```bash
bash ~/.openclaw/workspace/skills/self-improvement-loop/install.sh
openclaw gateway restart
```
Installation automatically:
1. Creates `.learnings/` directories for each agent
2. Installs hook and scripts
3. Creates per-agent cron jobs
4. Updates `openclaw.json` bindings (enables message routing)
5. Injects self-improvement index instructions into each agent workspace's `AGENTS.md` and `memory.md`
**A/B/C/D handling logic** is stored in `skills/self-improvement-loop/scripts/agents-append.md` (shared). During install, index references are injected into each agent's `AGENTS.md` and `memory.md`:
```markdown
## Self-Improvement (A/B/C/D)
Before handling A/B/C/D, must consult:
skills/self-improvement-loop/scripts/agents-append.md
```
No manual appending needed after install; skill updates automatically use the latest version for all agents.
---
## Verification
```bash
# Check bindings
python3 -c "import json; print(json.dumps(json.load(open('$HOME/.openclaw/openclaw.json')).get('bindings',[]), indent=2))"
# Check per-agent crons
openclaw cron list | grep self-improvement
# Test distill (specific agent)
LEARNINGS_DIR="$HOME/.openclaw/workspace/agents/code-dev/.learnings" \
bash ~/.openclaw/workspace/skills/self-improvement-loop/scripts/distill.sh --check-only
```
---
## Dependencies
| Dependency | Version | Purpose |
|-------------------|-----------|----------------------------------------|
| OpenClaw | ≥2026.4 | Platform foundation |
| Python3 | ≥3.8 | distill_json.py, write_notified.py |
| Node.js | any | handler.js |
| skill-creator | any | Path A - create skills |
| skill-improvement | any | Path B - improve skills |
---
## Limitations & Known Issues
- **ACP runtime agent (claude)**: No independent channel, falls back to `defaultAccount`
- **API (Gateway)**: API unreachable (404), falls back to CLI for cron creation, sessionTarget downgraded to isolated
- **Concurrent notifications**: When multiple agents trigger simultaneously, user replies may route to wrong agent session
- **sessionTarget=current**: Requires Gateway API support, currently unavailable
---
## See Also
- `references/setup-guide.md` — Full installation and configuration guide
don't have the plugin yet? install it then click "run inline in claude" again.