ClawHub

Daily Growth & Maturity

Automation

Self-reflection, correction logging, persistent memory, WAL protocol, cold-boot recovery, and automated daily review with self-healing cron. Evaluates own work, catches mistakes, learns from corrections, manages tiered memory that compounds execution quality across restarts and context resets. Includes a mandatory daily cron that rewrites workspace .md files with new lessons — auto-created on first session if missing. Use when: (1) a command, tool, or operation fails; (2) the user corrects you or rejects your work; (3) you realize your knowledge is outdated or incorrect; (4) you discover a better approach; (5) you complete significant work and want to evaluate the outcome; (6) context persistence and session state management is needed; (7) recovering from a restart or context reset.

Install

openclaw skills install self-maturing

Self-Improving Agent v3

Self-reflection + correction logging + tiered memory + WAL protocol + cold-boot recovery + automated daily review cron in one system. No API keys required. File-based. Works with existing OpenClaw memory (MEMORY.md, memory/) without overwriting anything.

What's new in v3.2

  • Automated daily review cron — a nightly cron job rewrites your .md files with new lessons. No behavioral compliance needed. The cron forces it.
  • Self-healing cron — SOUL.md hook verifies the cron exists on every session start. If missing, creates it immediately. No manual step survives a context reset.
  • Seed content — memory.md ships with a bootstrap entry so cold-boot reads return content immediately (fixes the empty-memory → no-habit → stays-empty cycle).
  • Persistence auto-fix — init detects non-persistent storage and auto-symlinks to /data/ if available.
  • Dry-run — agent_memory.py dry-run simulates a daily review without modifying files. Test before the cron fires.
  • Auto-inject workspace hooks — init automatically injects SOUL.md, AGENTS.md, and HEARTBEAT.md hooks. Creates minimal files if they don't exist. Zero manual steps.
  • Corrections trimming — nightly cron trims corrections.md to 50 entries, archiving the rest.
  • Post-install verification — agent_memory.py verify checks persistence, directories, hook content, cron, corrections health, and workspace hooks.
  • Model safety — cron-prompt explicitly warns against specifying a model (avoids silent "model not allowed" failures).
  • Cron management — agent_memory.py cron-prompt outputs the daily review prompt. mark-cron records installation.

Architecture

Two memory systems, complementary — never conflicting:

SystemLocationPurpose
OpenClaw nativeMEMORY.md, memory/*.mdFacts, events, decisions, daily logs
Self-improving~/self-improving/Execution quality: corrections, patterns, preferences
Workspace (OpenClaw native — skill never overwrites these):
├── MEMORY.md               # Long-term curated facts (auto-injected on boot)
├── SESSION-STATE.md         # Hot RAM — current task, pending actions
└── memory/
    └── YYYY-MM-DD.md       # Daily logs (searchable via memory_search)

~/self-improving/ (this skill manages):
├── memory.md               # HOT: ≤100 lines, load on every session
├── index.md                # Topic index with line counts
├── corrections.md          # Last 50 corrections
├── heartbeat-state.md      # Maintenance markers
├── projects/               # Per-project learnings
├── domains/                # Domain-specific (code, comms, etc.)
└── archive/                # COLD: decayed patterns

What auto-loads on restart (OpenClaw hardcoded)

These files are injected into the system prompt automatically:

  • MEMORY.md, SOUL.md, AGENTS.md, IDENTITY.md, USER.md, HEARTBEAT.md, TOOLS.md, BOOTSTRAP.md

What does NOT auto-load

These require explicit reads by the agent:

  • SESSION-STATE.md — must be read on first action after boot
  • ~/self-improving/memory.md — must be read before non-trivial work
  • memory/YYYY-MM-DD.md — found via memory_search

Where to store what

Content typeStore in
Facts, events, decisionsMEMORY.md (OpenClaw native)
Daily work logmemory/YYYY-MM-DD.md
Current task + session stateSESSION-STATE.md
Corrections and mistakes~/self-improving/corrections.md
Confirmed preferences/rules~/self-improving/memory.md
Project-specific patterns~/self-improving/projects/{name}.md
Domain patterns (code, comms)~/self-improving/domains/{name}.md

Daily Review Cron (THE KEY FEATURE)

This is what makes v3 work. A nightly cron job forces a full review and .md rewrite cycle. The agent doesn't need to "remember" to do it — the cron makes it mandatory.

What the cron does (every night):

  1. Reads ~/self-improving/memory.md, corrections.md, and any project files
  2. Reads SESSION-STATE.md for the day's work
  3. Reviews what was learned that day — new patterns, corrections, preferences, rules
  4. Writes new lessons to ~/self-improving/memory.md (promotes confirmed patterns to HOT)
  5. Rewrites SOUL.md, AGENTS.md, IDENTITY.md, HEARTBEAT.md — hardcodes new permanent rules, removes stale guidance, updates with latest operational reality
  6. Updates ~/self-improving/index.md with current file sizes
  7. Demotes patterns unused >30 days from HOT to WARM
  8. Reports what changed in each file

Setup

The cron is created automatically during agent_memory.py init. If you need to recreate it:

python3 ./skills/self-improving/scripts/agent_memory.py cron-prompt

This outputs the prompt text. Create a cron job with:

  • Schedule: Daily at your preferred time (e.g., 11 PM local)
  • Session target: isolated
  • Payload kind: agentTurn
  • Delivery: announce (so the user sees what changed)

Why a cron?

v2 relied on the agent following WAL protocol and writing lessons during work. In practice, agents skip this on context resets — the protocols are in SOUL.md but behavioral compliance is unreliable. The cron is a forcing function: even if the agent forgets to log lessons during the day, the nightly review catches everything.

Cold-Boot Recovery Protocol

This is the most important runtime section. On any restart, context reset, or new session:

Step 1: Read SESSION-STATE.md (IMMEDIATE — before any response)

Read SESSION-STATE.md → know what you were just doing

This file is your "hot RAM." It tells you: current task, pending actions, recent decisions. Without it, you're amnesiac about recent work.

Step 2: Read ~/self-improving/memory.md (before non-trivial work)

Read ~/self-improving/memory.md → know your learned patterns

This is your corrections/preferences tier. Small file (≤100 lines). Contains confirmed rules and recent lessons.

Step 3: memory_search if needed

memory_search("relevant query") → find context in daily logs

Daily logs (memory/YYYY-MM-DD.md) are NOT loaded by default. Use memory_search to find them.

Why this matters

MEMORY.md auto-loads and covers ~90% of long-term facts. But SESSION-STATE.md and self-improving/memory.md cover the remaining ~10%: what you were JUST doing and what MISTAKES you've learned from. Skipping them means repeating errors or losing task context.

WAL Protocol (Write-Ahead Log)

Write state BEFORE responding. If you crash/compact after responding but before saving, context is lost. WAL prevents this.

The daily review cron is a safety net, but WAL is still best practice for high-value lessons you don't want to risk losing.

TriggerWrite toThen
User states preference~/self-improving/memory.mdRespond
User makes decisionSESSION-STATE.mdRespond
User corrects you~/self-improving/corrections.mdRespond
User gives deadlineSESSION-STATE.mdRespond
Significant task completedmemory/YYYY-MM-DD.mdRespond
About to lose context (compaction)memory/YYYY-MM-DD.mdLet compaction proceed

SESSION-STATE.md (Hot RAM)

Lives in workspace root. Survives compaction, restarts, context loss. Read first every session, update every cycle.

# SESSION-STATE.md — Active Working Memory

## Current Task
[What we're working on RIGHT NOW]

## Key Context
[Critical facts for current work]

## Pending Actions
- [ ] ...

## Recent Decisions
[Decisions made this session]

---
*Last updated: [timestamp]*

Update discipline:

  • Session start: Read FIRST, before anything else
  • During work: Update BEFORE responding (WAL)
  • Session end / pre-compaction: Update with final state
  • After major decision: Update immediately

Learning Signals

Log immediately → corrections.md, evaluate for memory.md:

  • "No, that's not right..." / "Actually, it should be..."
  • "I prefer X, not Y" / "Remember that I always..."
  • "Stop doing X" / "Why do you keep..."

Log if explicit → memory.md:

  • "Always do X for me" / "Never do Y"
  • "My style is..." / "For [project], use..."

Track, promote after 3x:

  • Same instruction repeated 3+ times → ask to confirm as permanent rule
  • Workflow that works well repeatedly
  • User praises specific approach

Ignore (don't log):

  • One-time instructions ("do X now")
  • Context-specific ("in this file...")
  • Hypotheticals ("what if...")
  • Silence (absence of correction ≠ approval)

Self-Reflection

After completing significant work, pause and evaluate:

  1. Did it meet expectations? — Compare outcome vs intent
  2. What could be better? — Identify improvements for next time
  3. Is this a pattern? — If yes, log to corrections.md
CONTEXT: [type of task]
REFLECTION: [what I noticed]
LESSON: [what to do differently]

Tiered Memory

TierLocationLimitBehavior
HOT~/self-improving/memory.md≤100 linesRead on session start + before non-trivial work
WARMprojects/, domains/≤200 lines eachLoad on context match
COLDarchive/UnlimitedLoad on explicit query only

Promotion & Demotion

  • Pattern used 3x in 7 days → promote to HOT
  • Pattern unused 30 days → demote to WARM
  • Pattern unused 90 days → archive to COLD
  • Never delete without asking user

Conflict Resolution

  1. Most specific wins (project > domain > global)
  2. Most recent wins (same level)
  3. If ambiguous → ask user

Workspace Integration (Non-Destructive)

Never overwrite existing files. Add sections, don't replace.

SOUL.md — add:

## Self-Improving
On EVERY new session or context reset, IMMEDIATELY:
1. Read SESSION-STATE.md and ~/self-improving/memory.md before doing anything else.
2. VERIFY the daily review cron exists: use the cron tool (action=list) and look for "Self-Improving Daily Review". If it does NOT exist, CREATE IT NOW:
   - name: "Self-Improving Daily Review + .md Rewrite"
   - schedule: cron "0 23 * * *" in user's timezone
   - sessionTarget: isolated
   - payload: agentTurn with the review prompt (run: python3 ./skills/self-improving/scripts/agent_memory.py cron-prompt)
   - Do NOT set a model — use the default
   - delivery: announce
   After creating, run: python3 ./skills/self-improving/scripts/agent_memory.py mark-cron
   This is NON-NEGOTIABLE. The skill does not work without this cron.
3. When the user corrects you or you learn something reusable, IMMEDIATELY write to ~/self-improving/corrections.md BEFORE responding (WAL protocol). The nightly cron reviews corrections.md — if nothing is written during the day, the cron has nothing to promote. WAL is what feeds the cron.
4. Prefer learned rules when relevant. Keep self-inferred rules revisable.

AGENTS.md — add to Memory section:

- **Self-improving:** ~/self-improving/ — execution-quality memory (preferences, patterns, corrections)
- Use MEMORY.md / memory/ for factual continuity. Use ~/self-improving/ for compounding execution quality.

HEARTBEAT.md — add:

## Self-Improving Check
- Read ./skills/self-improving/heartbeat-rules.md
- Use ~/self-improving/heartbeat-state.md for run markers
- If no file in ~/self-improving/ changed since last review, skip maintenance

Gateway Config (Optional but Recommended)

Index ~/self-improving/ in memory search so corrections and patterns are discoverable via memory_search:

{
  agents: {
    defaults: {
      memorySearch: {
        extraPaths: ["~/self-improving"]
      }
    }
  }
}

Quick Queries

User saysAction
"What do you know about X?"Search all tiers for X
"What have you learned?"Show last 10 from corrections.md
"Show my patterns"List memory.md (HOT)
"Show [project] patterns"Load projects/{name}.md
"Memory stats"Run agent_memory.py stats
"Forget X"Remove from all tiers (confirm first)
"Forget everything"Export → wipe → confirm

Common Traps

TrapWhy It FailsBetter Move
Skipping SESSION-STATE.md on bootLose context of what you were doingALWAYS read it first
Learning from silenceCreates false rulesWait for explicit correction or 3x evidence
Promoting too fastPollutes HOT memoryKeep tentative until confirmed
Reading every namespaceWastes contextLoad only HOT + smallest matching files
Compaction by deletionLoses trust/historyMerge, summarize, or demote instead
Overwriting workspace filesDestroys existing contextComplement, never replace
Not writing before respondingCrash = lost contextWAL: always write first
Empty memory bootstrapNo feedback loop formsv3 seeds memory.md on init
No forcing functionAgent skips reviews after resetsv3 daily cron forces it

Setup

One command. Zero manual steps.

python3 ./skills/self-improving/scripts/agent_memory.py init

This does everything:

  1. Creates ~/self-improving/ directory structure with seeded files
  2. Auto-fixes persistence (symlinks to /data/ if needed)
  3. Auto-injects hooks into SOUL.md, AGENTS.md, HEARTBEAT.md (creates them if missing)
  4. Creates SESSION-STATE.md and today's daily log

The SOUL.md hook then auto-creates the daily review cron on the next session start. No manual cron setup needed.

Verify everything is working:

python3 ./skills/self-improving/scripts/agent_memory.py verify

Test what the nightly cron would do:

python3 ./skills/self-improving/scripts/agent_memory.py dry-run

References

  • Learning mechanics: See references/learning.md
  • Security boundaries: See references/boundaries.md
  • Scaling rules: See references/scaling.md
  • Memory operations: See references/operations.md
  • Heartbeat rules: See heartbeat-rules.md

Scope

This skill ONLY:

  • Learns from user corrections and self-reflection
  • Stores patterns in local files (~/self-improving/)
  • Creates SESSION-STATE.md for session state management
  • Maintains heartbeat state for recurring maintenance
  • Provides cold-boot recovery protocol
  • Sets up a daily review cron for automated .md rewriting

This skill NEVER:

  • Overwrites existing MEMORY.md, memory/, AGENTS.md, SOUL.md, HEARTBEAT.md (during init — the daily cron DOES rewrite these with new lessons)
  • Accesses calendar, email, contacts, or makes network requests
  • Reads files outside ~/self-improving/ and workspace root
  • Infers preferences from silence or observation
  • Deletes memory without explicit user confirmation
  • Modifies its own SKILL.md
More in Automation