Self-Improving OpenClaw

Log corrections, errors, feature requests, and recurring patterns into structured workspace learning files, then promote stable patterns into tiered memory a...

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

Signal	Target file	Category
User corrects you	LEARNINGS.md	correction
User says "always/never do X"	LEARNINGS.md	preference
You discover something non-obvious	LEARNINGS.md	insight
Your knowledge was outdated	LEARNINGS.md	knowledge_gap
Found a better approach	LEARNINGS.md	best_practice
Command returns non-zero	ERRORS.md	—
Tool/API fails unexpectedly	ERRORS.md	—
User wants missing capability	FEATURE_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:

Condition	Promote to	Example
Pattern 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 applicable	SOUL.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

Tier	Location	Size limit	Behavior
RAW	.learnings/	Unlimited	Intake only, not auto-loaded
HOT	.self-improving/HOT.md	≤80 lines	Always loaded at session start
WARM	.self-improving/domains/, projects/	≤200 lines each	Load on context match
COLD	.self-improving/archive/	Unlimited	Load 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 type	Promote to	Example
Behavioral patterns	SOUL.md	"Be concise, avoid disclaimers"
Workflow improvements	AGENTS.md	"Spawn sub-agents for long tasks"
Tool gotchas	TOOLS.md	"Git push needs auth first"
User preferences/decisions	MEMORY.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.