Self-Learning System#

A continuous learning loop that automatically captures learnings, tracks improvements, and verifies their effectiveness.

Inspiration: This skill fuses the structured recording format and detection triggers from pskoett/self-improving-agent (6.1k installs) with a verification/hypothesis loop that most agent learning systems lack.

🤖 Agent: What You Must Do (Not Optional)#

These are required behaviors, not suggestions. Execute them during conversation without being told.

During Every Conversation#

1. Detect learning opportunities in real-time. After every user message or tool result, mentally check:

   • Did the user correct me? → run python3 scripts/reflect.py --detect "USER_MESSAGE"
   • Did a tool fail? → log to .learning-trail.json immediately
   • Did I learn something new? → log to .learning-trail.json immediately

2. Log corrections immediately. When the user says "不对", "错了", "no", "actually", etc.: bash

   python3 scripts/learn.py --log correction "具体纠正了什么"
   
   

   Set pattern_key for dedup: --log correction "message" --area behavior --priority high

3. Log errors automatically. When a tool call fails or returns unexpected output: bash

   python3 scripts/learn.py --log error "工具名: 错误简述" --area tooling --priority medium
   
   

4. After significant tasks, append to today's daily log: bash

   python3 scripts/reflect.py --log "完成了什么"
   
   

At Session Start#

1. Check .hook-context.txt (written by plugin hook at gateway startup): Use read(path="memory/.hook-context.txt") to check it. If it shows pending verifications or patterns ready for promotion, act on them.

2. Run a quick status check: bash

   python3 scripts/learn.py --status
   
   

During Daily Cycle (via cron, 3AM)#

1. The full cycle runs automatically: python3 scripts/learn.py --cycle
   • 🌙 Dream: Distills recent daily logs into MEMORY.md (dedup + compress)
   • Auto-promotes patterns (≥2 occurrences across ≥2 sessions)
   • Auto-generates session summaries (L1)
   • Auto-triggers skill generation (via skillgen.py --auto)
   • Records record_change for verification tracking
   • Checks for overdue verifications

⚠️ Mandatory: Read Before Edit#

CRITICAL RULE — 任何文件编辑前必须先 read 获取当前内容。

bash

# ❌ 错误：凭记忆构造 oldText
edit(path="MEMORY.md", oldText="我印象中的内容", newText="新内容")

# ✅ 正确：先读文件，拿到实际内容
read(path="MEMORY.md")
# 然后用实际内容构造 oldText
edit(path="MEMORY.md", oldText="从 read 结果中复制的精确文本", newText="新内容")

为什么： edit 工具要求 oldText 与文件内容 逐字符匹配（含空白和换行）。凭记忆构造几乎必然失败，导致 cron 假性 error。

适用场景： 编辑 MEMORY.md、TOOLS.md、USER.md、AGENTS.md、SOUL.md 等任何文件。

Record Changes for Verification#

1. When you modify any core file (MEMORY.md, TOOLS.md, SOUL.md, AGENTS.md): bash

   python3 scripts/learn.py --record-change MEMORY.md "what was changed" "why this should help"
   
   

   This populates the verification loop so 7 days later the system checks if it helped.

Score Conversations#

1. At the end of significant conversations, rate yourself: bash

   python3 scripts/learn.py --score 8 7 9 8 7 "brief justification"
   
   

   (accuracy, usefulness, efficiency, tone, proactiveness, 0-10 each)

Learning Loop#

text

Session / Task
    ↓
  [DETECT]     ← Automatic triggers: corrections, errors, feature requests
    ↓
  [LOG]        ← Structured entries with IDs, priorities, categories
    ↓
  [EXTRACT]    ← Distill patterns from repeated entries
    ↓
  [PROMOTE]    ← To AGENTS.md / SOUL.md / TOOLS.md / MEMORY.md
    ↓
  [VERIFY]     ← 7-day check: did this change actually help?
    ↓
  [ADAPT]      ← Reinforce success, revert failure
    ↓
  (back to detect on next interaction)

Memory Management#

The skill also manages the agent's memory system — daily logs, user preferences, and knowledge retention.

Memory Architecture (三层)#

LayerStoreContentL1 Session Contextmemory/sessions/*.md会话摘要L2 Persistent StoreMEMORY.md, memory/*.md, memory/skills/蒸馏知识、经验教训L3 User Modelmemory/preferences.json, USER.md用户偏好、沟通风格

Inspired by Nous Research Hermes Agent.

Auto-Daily-Log#

At the end of each session or significant task, write a summary to memory/YYYY-MM-DD.md. Do NOT log individual micro-events (corrections, errors, tool failures) here — those go to .learning-trail.json only.

markdown

### 📝 Session summary
Completed tasks, user requests, decisions, key outcomes.

Keep entries concise (3-5 lines per session).

Memory Types#

TypeLayerWhereExampleSession summariesL1memory/sessions/*.md"2026-05-27 搜了苏超、装了 SearXNG"Daily logsL2memory/YYYY-MM-DD.md"10:30 创建 self-improvement skill"Distilled principlesL2MEMORY.md"Simple before powerful"Auto-generated skillsL2memory/skills/*.md"SearXNG 部署流程"User preferencesL3memory/preferences.json"直接回答，不要解释"User profileL3USER.md"技术背景强，中文沟通"Structured learning—.learning-trail.json所有 LRN/ERR/FEAT 条目

Memory Retention#

MemoryRetentionActionDaily logsKeep foreverAppend-only, never deleteLearning entries90 daysAuto-resolve pending items after 90dVerified principlesKeep foreverPart of long-term knowledgeUser preferencesKeep until changedUpdate when user says otherwiseTool notesKeep until outdatedUpdate when tools change

Memory Search#

When user asks "之前说过什么" or "帮我回忆一下":

1. First check MEMORY.md (distilled knowledge)
2. Then check USER.md (preferences)
3. Then check .learning-trail.json for structured entries
4. Then grep recent memory/*.md files

Memory Flow#

text

会话中
  → 检测到用户偏好 / 知识 / 错误
  → 仅写入 .learning-trail.json（结构化）

会话结束（每次对话结束）
  → 自动生成 L1 会话摘要到 memory/sessions/YYYY-MM-DD-NNN.md
  → 摘要包含：做了什么任务、学到了什么、用户反馈、生成了哪些技能
  → 追加概要到 memory/YYYY-MM-DD.md

心跳/空闲
  → 读取 .learning-trail.json 的 patterns
  → 达到阈值的晋升为 MEMORY.md 原则或 memory/preferences.json 偏好
  → 检查是否有值得生成技能的任务（8+ 工具调用且含写操作/脚本执行）

新会话开始
  → MEMORY.md 自动注入上下文
  → .learning-trail.json 的 watchlist 提醒我注意

Auto-Trigger Points#

Detection Triggers#

Automatically log when you notice:

Corrections → log to .learning-trail.json (category: correction)

• "No, that's not right..."
• "Actually, it should be..."
• "You're wrong about..."
• "That's outdated..."
• User explicitly correcting your output

Feature Requests → log to .learning-trail.json

• "Can you also..."
• "I wish you could..."
• "Is there a way to..."
• "Why can't you..."

Knowledge Gaps → log to .learning-trail.json (category: knowledge_gap)

• User provides info you didn't know
• Documentation you referenced is outdated
• API behavior differs from your understanding

Errors → log to .learning-trail.json

• Command returns non-zero exit code
• Exception or stack trace
• Timeout or connection failure

Successes → log to .learning-trail.json (category: best_practice)

• Found a better approach
• Quicker way to do something
• Cleaner pattern emerged

Scheduled Triggers#

TriggerWhenActionSession endAfter completionAuto-log summary to memory/YYYY-MM-DD.md + memory/sessions/ L1 summarySkill gen checkAfter complex taskAuto-generate skill if 8+ tool calls (with write/exec/workflow) or user says "记住"HeartbeatIdle timeRun learn.py --cycle: check verifications, promote patternsImprove yourselfOn demandFull cycle + reportHookSession startIf hook installed, review pending learnings

Session Summary (L1)#

每次会话/任务完成后，自动生成会话摘要到 memory/sessions/YYYY-MM-DD-NNN.md：

markdown

# Session Summary: 2026-05-27-001

## Tasks Completed
- [任务名称] 做了什么，结果是什么

## Learnings
- [学到了什么]

## Skills Generated
- [生成了哪些技能文件]

## User Feedback
- [用户说了什么重要反馈]

## Open Items
- [未完成的或待确认的]

生成时机： 一个完整的任务流程结束后（如装完 SearXNG、搜完新闻等）

Auto Skill Generation#

当完成一个复杂度达标的任务后，自动生成标准化技能文件。

生成条件（满足任意一个）：

• 任务涉及 8+ 工具调用且包含写操作/脚本执行/链式工作流（纯查询类跳过）
• 用户明确要求"记住这个"或"记下来"
• 重复做过类似任务 ≥ 2 次
• 发现了新的工作流或最佳实践

自动检测机制：

1. 任务完成后，检查是否满足以上条件
2. 满足则生成技能文件，以短横线命名： memory/skills/<task-slug>.md
3. 先检查是否已存在类似技能（grep memory/skills/ 目录），有则更新而非新建

Structured Log Format#

All entries use TYPE-YYYYMMDD-XXX IDs (LRN/ERR/FEAT) and go into memory/.learning-trail.json. Full entry formats: references/cli_ref.md.

Recurring Pattern Detection#

When logging something that might already exist:

1. Search .learning-trail.json for matching Pattern-Key
2. If found: increment Recurrence-Count, update Last-Seen
3. If not found: create new entry with Recurrence-Count: 1

Promotion Rule#

Promote a pattern to workspace core files when all are true:

• Recurrence-Count >= 3
• Seen across at least 2 distinct sessions
• Occurred within a 30-day window

Promotion targets:

Entry TypePromote ToExampleBehavioral patternSOUL.md"Be concise, skip disclaimers"Workflow improvementAGENTS.md"Spawn sub-agents for long tasks"Tool gotchaTOOLS.md"Git push needs auth configured"User preferenceUSER.md / preferences.json"User prefers direct answers"Universal principleMEMORY.md"Simple before powerful"Reusable procedurememory/skills/*.md"SearXNG 部署流程"

技能复用流程：

1. 新任务到来 → 搜索 memory/skills/ 目录匹配关键词
2. 找到匹配 → 读取技能文件，从 Procedure 开始执行
3. 未找到 → 从头推理，完成后生成新技能文件

Auto-generated skill template: references/cli_ref.md.

Verification Loop#

learn.py --cycle checks after 7 days if the change helped. Verification API and outcomes: references/cli_ref.md.

CLI Commands#

bash

python3 scripts/learn.py --cycle     # Full cycle: check verifications + promote patterns
python3 scripts/learn.py --verify    # Only check pending verifications
python3 scripts/learn.py --status    # Show learning stats
python3 scripts/learn.py --log learning "message" --area behavior --priority high

CLI params reference: references/cli_ref.md.

Hook Integration (Session Start)#

For automatic reminders at session start, install the hook:

bash

# Copy hook files (HOOK.md + handler.js) to OpenClaw hooks directory
cp skills/self-improvement/hooks/openclaw/HOOK.md ~/.openclaw/hooks/self-improvement/HOOK.md
cp skills/self-improvement/hooks/openclaw/handler.js ~/.openclaw/hooks/self-improvement/handler.js

# Enable it
openclaw hooks enable self-improvement

# Verify
openclaw hooks list

Important: OpenClaw hooks require HOOK.md + handler.js at the top level of the hook directory. Shell scripts ( hook.sh) are not supported.

The hook checks .learning-trail.json on session start for:

• Pending high-priority items
• Verifications due for review
• Patterns ready for promotion

Quick Reference#

SituationActionCommand/operation failsLog to .learning-trail.jsonUser corrects youLog to .learning-trail.json (correction)User wants missing featureLog to .learning-trail.jsonAPI/external tool failsLog to .learning-trail.jsonKnowledge was outdatedLog to .learning-trail.json (knowledge_gap)Found better approachLog to .learning-trail.json (best_practice)Same error 3x across sessionsPromote to core fileChange applied 7+ days agoRun verification check

Priority Guidelines#

PriorityWhen to UsecriticalBlocks core functionality, data loss risk, security issuehighSignificant impact, affects common workflows, recurring issuemediumModerate impact, workaround existslowMinor inconvenience, nice-to-have

Conflict Resolution#

Priority scoring when principles contradict: references/cli_ref.md.

Forgetting & Auto-Revert#

• 30d without reinforcement → priority demoted; 60d → stale; 90d → wont_fix
• Verification overdue 21+ days → auto-revert
• Details: references/cli_ref.md.

Proposal Workflow#

When the learning system detects a pattern ready for promotion or a change that needs verification, it generates a proposal for user review:

text

Pattern detected (≥3x across ≥2 sessions)
    ↓
Generate proposal: what to change, why, risk level
    ↓
Present to user for approval
    ↓
User says "approve N" or "skip N"
    ↓
Apply approved changes, track for verification

Proposal Format#

Each proposal includes:

• Type: promotion / verification / critical_fix
• Target: Which file to change (TOOLS.md, MEMORY.md, SOUL.md, AGENTS.md)
• Change: Specific text to add/modify
• Motivation: Why this change (pattern evidence)
• Risk: Low (adds info) / Medium (changes behavior)
• Effort: low / medium / high
• Impact: low / medium / high

Auto-apply vs Propose#

Change TypeActionExampleAdd note to TOOLS.md✅ Auto-apply"QWeather needs custom host"Add principle to MEMORY.md✅ Auto-apply"Simple before powerful"Add preference to USER.md✅ Auto-apply"User prefers direct answers"Add guideline to SOUL.md⚠️ Propose"Be concise, skip disclaimers"Add rule to AGENTS.md⚠️ Propose"Spawn sub-agents for long tasks"Create new skill❌ Always askNew skill for recurring task

Usage#

bash

python3 scripts/learn.py --propose    # Generate proposals for review

The agent will present proposals and wait for your approval before applying.

Conversation Scoring#

After each significant interaction, score the response on 5 dimensions (0-10):

DimensionWhat it measuresAccuracyWas the output factually correct?UsefulnessDid it solve the user's actual problem?EfficiencyWere tool calls optimal?ToneMatched SOUL.md persona?ProactivenessAnticipated needs?

Usage#

bash

python3 scripts/learn.py --score 8 9 7 8 6    # Score last conversation
python3 scripts/learn.py --trends 7            # Show 7-day trend

Trend Tracking#

Example in references/cli_ref.md.

Dynamic Memory Injection#

Build topic index → detect conversation topic → inject relevant memories.

bash

python3 scripts/learn.py --build-index
python3 scripts/learn.py --query-memory weather

Topics list: references/cli_ref.md. Index rebuilt during --cycle.

Knowledge Graph#

Connects 事件 → 教训 → 原则. Node types, edge types, and CLI usage: references/cli_ref.md.

Key Principles#

1. Learn automatically. The system should work without being told.
2. Verify or it didn't happen. Every change must be checked later.
3. Reversible first. Always track old state so changes can be undone.
4. Patterns over anecdotes. One error is noise. Three identical errors are a pattern.
5. Structured over freeform. Standardized IDs and categories make learnings searchable.
6. Don't log secrets. Never write tokens, keys, or full source files.
7. Don't learn from noise. Not every interaction is a learning opportunity.
8. Connect memories. Events → lessons → principles form a network, not isolated notes.

References#

• reflection_frameworks.md — Detailed frameworks and patterns
• scripts/learn.py — Learning cycle engine
• scripts/reflect.py — Session data collector + auto-log
• hooks/ — OpenClaw session-start hook template

更新与迁移#

更新流程#

1. 备份 memory/ 目录和 .learning-trail.json
2. 安装新版本
3. 运行迁移检查： python3 scripts/migrate.py
4. 如有问题，运行迁移： python3 scripts/migrate.py --migrate

版本兼容性#

• V2.x → V2.2.0：数据格式兼容，无需迁移
• V1.x → V2.2.0：需要迁移，运行 python3 scripts/migrate.py --migrate

回滚#

如更新后出问题：

1. 恢复备份的 memory/ 目录
2. 恢复备份的 .learning-trail.json
3. 降级到之前的版本

⚠️ Windows 已知问题#

在 Windows 上， openclaw skills update 可能失败，报 EPERM: operation not permitted。

原因： OpenClaw Gateway（Node.js）运行时持有技能目录的文件句柄，导致 update 流程中的 rename 操作被操作系统拒绝。

解决方法：

1. 手动删除旧目录： cmd /c rmdir /s /q "<skills路径>\self-improvement-llm"
2. 重新安装： openclaw skills install self-improvement-llm

Linux/macOS 不受影响，目录在被读取时仍可 rename。

备份与同步#

导出数据#

bash

python3 scripts/sync.py export                    # 导出到当前目录
python3 scripts/sync.py export /path/to/backup.zip  # 导出到指定路径

导出内容：

• memory/MEMORY.md — 长期记忆
• memory/.learning-trail.json — 结构化学习数据
• memory/.memory-index.json — 记忆索引
• memory/preferences.json — 用户偏好
• memory/sessions/ — 会话摘要
• memory/skills/ — 自动生成的技能
• memory/.dreams/ — 梦境蒸馏数据
• memory/*.md — 日常日志

导入数据#

bash

python3 scripts/sync.py import /path/to/backup.zip  # 导入（不覆盖已有）
python3 scripts/sync.py import /path/to/backup.zip --overwrite  # 覆盖导入

多服务器同步#

1. 服务器 A： python3 scripts/sync.py export
2. 传输 zip 到服务器 B
3. 服务器 B： python3 scripts/sync.py import backup.zip

查看状态#

bash

python3 scripts/sync.py status