self-improving-agent

The self-improvement hook implements a session-end error sweep rather than real-time per-command detection (as OpenClaw lacks per-tool-call events).

How it works

1. Trigger: When /new or /reset is issued, the session ends.
2. Scan: The hook scans the transcript for patterns like Error:, command not found, Traceback, npm ERR!, or Permission denied.
3. Log: Matches are appended to <workspace>/.learnings/ERRORS.md as pending entries.
4. Triage: At the next agent:bootstrap, the agent is notified of pending triage entries to review, fix, or delete.

Limitations

• No real-time detection: Errors are only detected at the end of a session.
• Opt-in: The sweep only runs if the .learnings/ directory exists.
• Heuristic: It may produce false positives (e.g., prose containing the word "failed").
• Redaction: Excerpts are redacted with best-effort rules; treat .learnings/ as potentially sensitive.

The self-improvement hook operates during two specific OpenClaw lifecycle events:

1. During agent:bootstrap

Before workspace files are injected, the hook:

• Adds a reminder block to check .learnings/ for relevant entries.
• Prompts the agent to log corrections, errors, and discoveries.
• Includes a pending-triage note if auto-detected errors are awaiting review.

2. During command:new or command:reset (Session End)

When a session ends, the hook performs an error sweep:

• Transcript Location: It looks for the session transcript at context.previousSessionEntry.sessionFile, falling back to <workspace>/sessions/<sessionId>.jsonl.
• Pattern Matching: It scans the transcript against a fixed list of error patterns (e.g., Error:, command not found, Traceback, npm ERR!).
• Error Logging: It appends a pending entry to <workspace>/.learnings/ERRORS.md.
• Deduplication: Each entry is stamped with a deterministic Pattern-Key (e.g., deps.module-not-found) to allow for deduplication and recurrence counting.

The Pattern-Key is a stable, two-level key used to deduplicate semantically identical entries in log files. Using consistent keys ensures that Recurrence-Count and promotion rules function correctly.

Format: area.symptom (exactly two levels, lowercase, hyphenated, e.g., deps.module-not-found).

Rules for Keys:

• Reuse before minting: Check for existing keys before creating new ones using: grep -rh "Pattern-Key:" .learnings/ | sort -u.
• Keep symptoms generic: Do not include file names, versions, or hostnames in the symptom part of the key.
• One key per manual entry: While auto-swept entries may have several, manual entries should use one.
• Avoid generic sweep keys: Keys like runtime.error are considered "unclassified"; replace them with specific keys during triage.

Taxonomy Reference:

When a learning is broadly applicable (not a one-off fix), promote it to a workspace file so every session inherits it. This prevents recurring mistakes and documents project-specific conventions.

Promotion Workflow

1. Distill the learning into a concise rule or fact.
2. Add to the appropriate section in the target file (create if needed).
3. Update the original entry in .learnings/:
   • Change **Status**: pending → **Status**: promoted.
   • Add **Promoted**: [Target File] (e.g., **Promoted**: SOUL.md).

Promotion Targets

Note: If the learning is specific to a project repo (not the workspace), promote it to that project's own agent file (e.g., its AGENTS.md) instead.

When extracting a new skill from a learning, use the SKILL.md template to ensure consistency. A skill is a reusable piece of knowledge or an executable helper derived from a resolved learning entry.

Full Template Structure

A comprehensive skill should include:

• Frontmatter: Contains name (lowercase with hyphens) and description (starting with an action verb and mentioning triggers).
• Quick Reference: A table mapping specific triggers/situations to actions.
• Background: Context on why the knowledge matters.
• Solution: A step-by-step guide and a tested code example.
• Common Variations & Gotchas: Handling different scenarios and avoiding common mistakes.
• Source: Metadata including the Learning ID, Original Category (correction, insight, knowledge_gap, or best_practice), and Extraction Date.

Minimal Template

For simple skills, use a reduced format:

---
name: skill-name-here
description: "What this skill does and when to use it."
---

# Skill Name

[Problem statement in one sentence]

## Solution

[Direct solution with code/commands]

## Source

- Learning ID: LRN-YYYYMMDD-XXX

---
name: skill-name-here
description: "Concise description of when and why to use this skill. Include trigger conditions."
---

# Skill Name

Brief introduction explaining the problem this skill solves and its origin.

## Quick Reference

| Situation | Action |
|-----------|--------|
| [Trigger 1] | [Action 1] |
| [Trigger 2] | [Action 2] |

## Background

Why this knowledge matters. What problems it prevents. Context from the original learning.

## Solution

### Step-by-Step

1. First step with code or command
2. Second step
3. Verification step

### Code Example

```language
// Example code demonstrating the solution

Common Variations

• Variation A: Description and how to handle
• Variation B: Description and how to handle

Gotchas

• Warning or common mistake #1
• Warning or common mistake #2

Related

• Link to related documentation
• Link to related skill

Source

Extracted from learning entry.

• Learning ID: LRN-YYYYMMDD-XXX
• Original Category: correction | insight | knowledge_gap | best_practice
• Extraction Date: YYYY-MM-DD