Self Improving Agent

Self-Improving Agent (Low-Noise Edition)

A conservative self-improvement system that treats .learnings/ as a write-first

cache layer. Nothing reaches the main system files without human review.

Quick Reference

| Action | Target | Auto? |

|--------|--------|-------|

| Log a learning | .learnings/LEARNINGS.md | Yes |

| Log an error | .learnings/ERRORS.md | Yes |

| Log a feature gap | .learnings/FEATURE_REQUESTS.md | Yes |

| Promote to MEMORY.md | Requires user approval | No |

| Promote to SOUL.md | Requires user approval + review | No |

| Promote to AGENTS.md | Requires user approval | No |

| Promote to TOOLS.md | Requires user approval | No |

Core Principles

• Write to cache first. All observations go to .learnings/. No exceptions.
• Never auto-promote. The cache is not the system. Promotion is a deliberate act.
• SOUL.md is sacred. Modifications require explicit human review every time.
• MEMORY.md is for stable truths. Only long-term preferences, decisions, and goals belong there.
• Errors and learnings stay separate. Different logs, different purposes.
• Silence is better than noise. If unsure whether something is worth logging, don't log it.
• No cross-session broadcasting of raw learnings. Only promote distilled, verified content.

Logging Format

Learning Entry

## [YYYY-MM-DD] Category: brief title

- **Type**: correction | knowledge_gap | best_practice
- **Context**: What was happening
- **Learning**: What was learned
- **Confidence**: low | medium | high
- **Promote?**: no (default) | candidate | promoted

Error Entry

## [YYYY-MM-DD] brief description

- **Command/Tool**: What failed
- **Error**: The error message or symptom
- **Root Cause**: What actually went wrong
- **Resolution**: How it was fixed
- **Recurrence**: first | repeated

Feature Request Entry

## [YYYY-MM-DD] brief description

- **Gap**: What capability is missing
- **User Need**: Why it matters
- **Priority**: low | medium | high

Promotion Gates

A cached item may be promoted to a system file only when ALL of these are true:

• Repeated — The same insight has appeared in 2+ separate sessions
• Verified — The insight was confirmed correct (not a one-off misunderstanding)
• User-approved — The user explicitly agrees to promote it
• Relevant long-term — It's not a temporary workaround or context-specific hack

Promotion Targets

| Content Type | Target File | Extra Requirement |

|---|---|---|

| User preference / long-term decision | MEMORY.md | Stable across sessions |

| Identity / behavior guideline | SOUL.md | Human review mandatory |

| Agent capability / role definition | AGENTS.md | Verified in practice |

| Tool usage pattern / integration | TOOLS.md | Tested and confirmed |

Promotion Process

• Agent proposes promotion with rationale
• User reviews the exact content to be written
• User explicitly approves
• Agent writes to target file
• Agent marks the cached entry as Promote?: promoted

Best Practices (Low-Noise)

• Don't log obvious things. "Python needs indentation" is not a learning.
• Don't log things already in the codebase or docs.
• One entry per insight. No walls of text.
• Prefer updating an existing entry over creating a duplicate.
• Review .learnings/ periodically. Prune stale entries.
• When in doubt, skip the log. You can always add it later.

OpenClaw Integration

See references/openclaw-integration.md for how this skill fits into the

OpenClaw workspace architecture.

Key Boundaries

┌─────────────────────────────────────┐
│  Main System Layer (protected)      │
│  SOUL.md · MEMORY.md · AGENTS.md   │
│  TOOLS.md                           │
│  ← promotion requires approval →    │
├─────────────────────────────────────┤
│  Cache Layer (free-write)           │
│  .learnings/LEARNINGS.md            │
│  .learnings/ERRORS.md               │
│  .learnings/FEATURE_REQUESTS.md     │
└─────────────────────────────────────┘