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 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/:

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:

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

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:

Mark promoted entries as Status: promoted with Promoted-To: .

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.