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:

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

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.

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

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

Common Traps

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