Self-Improving OpenClaw#

Structured learning loop for OpenClaw agents: capture → review → promote → maintain.

Quick Start#

On first activation, run the init script to create workspace directories:

bash

bash scripts/init-workspace.sh

This creates .learnings/ and .self-improving/ in the workspace root.

Core Workflow#

1. Capture#

When a learning signal fires, log it to the right file in .learnings/:

SignalTarget fileCategoryUser corrects youLEARNINGS.md``correctionUser says "always/never do X"LEARNINGS.md``preferenceYou discover something non-obviousLEARNINGS.md``insightYour knowledge was outdatedLEARNINGS.md``knowledge_gapFound a better approachLEARNINGS.md``best_practiceCommand returns non-zeroERRORS.md—Tool/API fails unexpectedlyERRORS.md—User wants missing capabilityFEATURE_REQUESTS.md—

Use the entry format defined in references/logging-format.md.

2. Review#

During heartbeat or manual review, scan .learnings/ and evaluate each pending item:

1. Check recurrence — search for similar entries.
2. If related entry exists: bump Recurrence-Count, link with See Also.
3. If Recurrence-Count >= 3 within 30 days: add to .learnings/REVIEW_QUEUE.md.
4. Update .self-improving/heartbeat-state.md with review timestamp.

See references/heartbeat-review.md for the full review procedure.

3. Promote#

Move validated patterns up the memory tiers:

ConditionPromote toExamplePattern used 2x, context-specific.self-improving/domains/*.md or projects/*.md"This repo uses pnpm"Pattern used 3x in 7-30 days, cross-task.self-improving/HOT.md"User prefers concise answers"Stable, long-term applicableSOUL.md / AGENTS.md / TOOLS.md / MEMORY.md"Never force push"

See references/promotion-rules.md for the full promotion/demotion rules.

4. Maintain#

Periodically (every 1-2 weeks during heartbeat):

• Demote HOT entries unused for 30 days → domain/project memory.
• Archive domain/project entries unused for 90 days → .self-improving/archive/.
• Compact files exceeding size limits: merge similar entries, summarize verbose ones.
• Never delete without explicit user confirmation. Prefer archive over delete.

Detection Triggers#

Log automatically when you notice these signals:

Corrections (→ LEARNINGS.md, category: correction):

• "No, that's not right..."
• "Actually, it should be..."
• "You're wrong about..."
• "I told you before..."
• "Stop doing X"

Preferences (→ LEARNINGS.md, category: preference):

• "I like when you..."
• "Always do X for me"
• "Never do Y"
• "My style is..."

Feature requests (→ FEATURE_REQUESTS.md):

• "Can you also..."
• "I wish you could..."
• "Is there a way to..."

Errors (→ ERRORS.md):

• Non-zero exit codes
• Exceptions or stack traces
• Timeout or connection failure

Ignore (don't log):

• One-time instructions ("do X now")
• Pure context ("in this file...")
• Hypotheticals ("what if...")

Memory Tiers#

TierLocationSize limitBehaviorRAW.learnings/UnlimitedIntake only, not auto-loadedHOT.self-improving/HOT.md≤80 linesAlways loaded at session startWARM.self-improving/domains/, projects/≤200 lines eachLoad on context matchCOLD.self-improving/archive/UnlimitedLoad on explicit query

Conflict Resolution#

When patterns contradict:

1. Most specific wins: project > domain > HOT/global.
2. Same level: most recent wins.
3. If ambiguous: ask user.

Promotion Targets#

When a learning is stable enough for permanent workspace memory:

Learning typePromote toExampleBehavioral patternsSOUL.md"Be concise, avoid disclaimers"Workflow improvementsAGENTS.md"Spawn sub-agents for long tasks"Tool gotchasTOOLS.md"Git push needs auth first"User preferences/decisionsMEMORY.md"Basim prefers Indonesian for casual chat"

Mark promoted entries as Status: promoted with Promoted-To: <file>.

Transparency#

• When applying a learned pattern, cite the source: (from HOT.md) or (from domains/coding.md:15).
• On "memory stats" request, report entry counts per tier.
• On "what have you learned?" request, show recent corrections and HOT entries.

Security Boundaries#

• Never store credentials, API keys, tokens, or passwords.
• Never store health data or sensitive personal information.
• Never store third-party private data.
• Redact secrets in error logs — use [REDACTED] placeholders.
• Only write to memory files in private/local workspace sessions.

Workspace Layout#

See references/workspace-layout.md for the complete directory structure and file descriptions.

Resources#

scripts/#

• init-workspace.sh — Create .learnings/ and .self-improving/ directories with template files.

references/#

• logging-format.md — Entry format for learnings, errors, and feature requests.
• promotion-rules.md — Full promotion, demotion, and archival rules.
• heartbeat-review.md — Heartbeat review procedure and state tracking.
• workspace-layout.md — Complete directory structure reference.

assets/#

• Template files copied by init-workspace.sh into the workspace.