rocky-know-how v3.4.8

Experience & Knowledge Auto-Learning System for OpenClaw Agents

让 AI Agent 从失败中学习，在成功后自动记录，形成经验闭环。

🎯 When to Use / 适用场景

🏗️ Architecture / 架构

Triple-Layer Storage / 三层存储

~/.openclaw/.learnings/
├── experiences.md    ← Main data (v1 compatible, all experiences)
├── memory.md         ← HOT layer (≤100 lines, always loaded)
├── domains/          ← WARM layer (by area: infra, code, wx...)
│   ├── infra.md
│   ├── code.md
│   └── global.md
├── projects/         ← WARM layer (by project)
├── archive/          ← COLD layer (90+ days)
├── drafts/           ← Auto-generated drafts (LLM judged)
├── pending/          ← Session context (before processing)
└── corrections.md    ← Correction log (auto-dedup)

Event-Driven Integration / 事件驱动

✅ v3.1.1: before_compaction hook now properly triggers experience recording (LLM extract + write). memoryFlush still used for memory/*.md files.

🔄 Experience Recording Flow / 经验记录流程

before_compaction-Driven (Core) / before_compaction 驱动（核心）

v3.1.1: Hook triggers synchronously during compaction, before compact() executes.

before_compaction hook fires
    │
    ▼
① Save session context 保存上下文
    └─ handler.js → pending/*.json
    │
    ▼
② Extract & write 提取并写入
    ├─ processPendingItem() → LLM judgment
    └─ experiences.md written
    │
    ▼
③ Auto-review  auto-review.sh
    ├─ Similar experience detection
    └─ Tag → TOOLS.md promotion check
    │
    ▼
Compaction continues (compact() executes)

bootstrap (Startup) / 启动时

agent:bootstrap triggers
    ├─ Load domains/*.md → inject experience reminder into systemPrompt
    └─ Check drafts/ → process old drafts (fallback)

before_reset (Fallback) / 重置兜底

/reset or /new triggers
    └─ handler.js saves context → pending/*.json

🛡️ Safety & Security / 安全机制

📊 Scripts Reference / 脚本说明

✅ Verified Testing / 测试验证

Models Tested / 已测试模型

Test Coverage / 测试覆盖

🚀 Installation / 安装

1. Install Skill / 安装技能

# Clone
git clone https://gitee.com/rocky_tian/skill.git
cd skill/rocky-know-how

# Install
bash scripts/install.sh

# Verify
bash scripts/stats.sh

2. Configure memoryFlush / 配置 memoryFlush（重要）

This config is for memory/*.md file writing only (v3.1.1). Experience recording is now handled by before_compaction hook.

Add the following to your ~/.openclaw/openclaw.json:

{
  "agents": {
    "defaults": {
      "compaction": {
        "memoryFlush": {
          "enabled": true,
          "softThresholdTokens": 8000,
          "prompt": "会话即将压缩。请按以下流程处理经验，再写记忆：\n\n【第一步：处理旧草稿】\n检查 ~/.openclaw/.learnings/drafts/ 目录是否有旧草稿：\n  - 旧草稿 + 当前对话没提到同问题 → 说明已解决 → 调 record.sh 转正式经验\n  - 旧草稿 + 当前对话还在处理同问题 → 保留草稿不动\n\n【第二步：提取新经验】\n扫描当前对话，遇到以下情况值得记录：\n  - 同一问题失败≥2次后解决\n  - 踩坑后找到正确方案\n  - 发现重要配置/命令/技巧\n判断逻辑：\n  - 无旧草稿 + 第1轮就搞定 → 直接 record.sh 写正式经验\n  - 同问题有旧草稿（多轮调试）→ 写/更新草稿到 drafts/\n  - 没有值得记录的 → 跳过\n\n【第三步：写记忆文件】\n将重要记忆追加到 memory/YYYY-MM-DD.md（已有则追加，不覆盖）\n\n完成后回复 NO_REPLY。\n\nrecord.sh 用法：bash ~/.openclaw/skills/rocky-know-how/scripts/record.sh \"问题\" \"踩坑过程\" \"正确方案\" \"预防措施\" \"tag1,tag2\" \"领域\"",
          "systemPrompt": "会话即将压缩。按顺序处理：旧草稿→新经验→记忆文件。经验优先，记忆精简。"
        }
      }
    }
  }
}

Why softThresholdTokens: 8000?

OpenClaw default is 4000, but experience recording (judge + record.sh + memory write) needs ~3000-5500 tokens. 8000 provides enough headroom.

Why not use default 4000?

4000 tokens is too tight. If there are old drafts to process or the memory content is long, it may exceed the budget and cause the flush to fail.

3. Configure Hooks / 配置 Hook

# Add hook config to openclaw.json (under hooks.internal.entries)
# install.sh does this automatically

Hooks needed:

• agent:bootstrap → handler (inject experience reminder)
• before_reset → handler (fallback save)

📈 Key Advantages / 核心优势

1. before_compaction-driven auto-learning — Experience recording triggered before every compaction
2. LLM dual-judgment — First judges if worth saving, then decides create vs append
3. Triple degradation — LLM → keyword → write, never loses data
4. Multi-provider — Supports OpenAI, Anthropic, OAuth providers (zai/stepfun/minimax)
5. Production proven — 45+ real experiences, 2.6MB data, stable operation
6. Safety first — 5 security mechanisms (regex injection, path traversal, write lock, etc.)

Version: 3.4.8 | Tested: 2026-04-25 | License: MIT