Self Improvement Loop

---

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 | /workspace/.learnings/ | Read LEARNINGS.md, ERRORS.md, FEATURE_REQUESTS.md | | write | /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 ~/.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:

## 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

# 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 |

---

Security Notes

File Cleanup Policy

archive.sh includes an automated maintenance task that removes orphaned pending notification files older than 7 days:

find "$PENDING_DIR" -name "*.json" -mtime +7 -delete

What: Stale notification JSON files in .learnings/.pending_notifications/

When: Runs every time archive.sh executes (after archiving resolved/promoted entries)

Why: Prevents accumulation of abandoned notification records

Scope: Only files in each agent's own .learnings/.pending_notifications/ subdirectory

Impact: Deliberate and safe — these files are ephemeral by design, never contain secrets, and are re-created if needed

This cleanup is the reason for the suspicious.destructive_delete_command moderation flag on published versions. It is a legitimate housekeeping operation, not a general-purpose delete mechanism.

---

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