rocky-know-how v3.1.0
Experience & Knowledge Auto-Learning System for OpenClaw Agents
让 AI Agent 从失败中学习，在成功后自动记录，形成经验闭环。
🎯 When to Use / 适用场景
| Scenario 场景 | Action 操作 |
|---|---|
| Failed 2+ times 失败≥2次 | bash scripts/search.sh "关键词" |
| Solved after failures 解决后 | bash scripts/record.sh "问题" "踩坑" "方案" "预防" "tags" "area" |
| Auto on compaction 压缩时 | memoryFlush driven — auto extract → judge → write or draft |
| Auto on reset 重置时 | Fully automatic — Hook saves pending context |
| Tag used 3x/7days 晋升 | bash scripts/promote.sh |
| Tag unused 30days 降级 | bash scripts/demote.sh |
🏗️ 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 / 事件驱动
| Event 事件 | Trigger 触发 | Function 功能 |
|---|---|---|
agent:bootstrap | Agent startup 启动 | Inject experience reminder into systemPrompt + process old drafts |
memoryFlush | Before compaction (config required) | Core: extract experience → judge → write formal or draft |
before_reset | Before session reset 重置前 | Save context as pending (fallback) |
⚠️ Note:
before_compaction/after_compactionhooks are gated byownsCompactionin OpenClaw's source code and are not currently functional. We usememoryFlushinstead.
🔄 Experience Recording Flow / 经验记录流程
memoryFlush-Driven (Core) / memoryFlush 驱动（核心）
Requires config — see Setup section below.
memoryFlush triggers (token threshold reached)
│
▼
① Process old drafts 处理旧草稿
├─ Old draft + current NOT mentioning same issue → Resolved → record.sh (formal)
└─ Old draft + current still working on it → Keep draft
│
▼
② Extract new experience 提取新经验
├─ No draft + solved in 1 round → record.sh (formal directly)
├─ Same issue has draft (multi-round) → Write/update draft
└─ Nothing worth recording → Skip
│
▼
③ Write memory file 写记忆文件
└─ Append to memory/YYYY-MM-DD.md
│
▼
④ Reply NO_REPLY → Compaction begins
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 / 安全机制
| Mechanism 机制 | Implementation 实现 |
|---|---|
| Regex injection prevention 正则注入防护 | escape_grep() sed escaping |
| Path traversal filtering 路径穿越过滤 | replace(/[^a-zA-Z0-9_-]/g, '') |
| Concurrent write lock 并发写锁 | .write_lock/ directory atomic lock |
| Tag dedup promotion Tag去重晋升 | record.sh dedup + promote.sh threshold |
| Graceful degradation 降级容错 | LLM → keyword → write fallback chain |
📊 Scripts Reference / 脚本说明
| Script 脚本 | Lines 行数 | Function 功能 |
|---|---|---|
| handler.js | 1,110 | Core hook handler (4 events, LLM integration) |
| search.sh | 539 | Search experiences (keyword / preview / all) |
| record.sh | 476 | Write new experience (with dedup & lock) |
| demote.sh | 371 | Demote HOT tags to WARM |
| compact.sh | 348 | Compress layers when exceeding limits |
| clean.sh | 247 | Remove test/invalid entries |
| vectors.sh | 232 | Vector search via LM Studio embeddings |
| promote.sh | 185 | Promote WARM tags to HOT (≥3x/7days) |
| import.sh | 172 | Import experiences from other sources |
| archive.sh | 167 | Archive old experiences to COLD |
| install.sh | 161 | Install skill to workspace |
| stats.sh | 153 | Show statistics dashboard |
| auto-review.sh | 136 | Auto-review pending drafts |
| append-record.sh | 100 | Append solution to existing experience |
| summarize-drafts.sh | 80 | Summarize and process drafts |
| update-record.sh | 77 | Update existing experience |
| common.sh | 41 | Shared utility functions |
| uninstall.sh | 37 | Remove skill |
| Total 共计 | 4,632 |
✅ Verified Testing / 测试验证
Models Tested / 已测试模型
| Model 模型 | Provider | Forward Test 正向 | Reverse Test 逆向 | Status |
|---|---|---|---|---|
| deepseek-v4 | deepseek (api-key) | ✅ Pass | ✅ Pass (144/150) | Verified |
| glm-5.1 | zai (api-key) | ✅ Pass | ✅ Pass (146/150) | Verified |
| MiniMax-M2.7-highspeed | minimax-portal (OAuth) | ✅ Pass | ✅ Pass (146/150) | Verified |
Test Coverage / 测试覆盖
| Test 测试 | Result 结果 |
|---|---|
| agent:bootstrap → systemPrompt injection | ✅ 12→952 chars |
| before_compaction → pending save | ✅ task/tools/errors extracted |
| after_compaction → LLM dual-judge → write | ✅ EXP auto-created |
| before_reset → fallback save | ✅ pending saved |
| record.sh write + search | ✅ Write & find |
| auto-review.sh process draft | ✅ Draft → archive |
| compact.sh dry-run | ✅ All layers healthy |
| promote.sh tag promotion | ✅ Threshold check |
| stats.sh dashboard | ✅ Full panel |
| 5 safety mechanisms | ✅ All present |
🚀 Installation / 安装（下载即用）
一键安装
# Clone
git clone https://gitee.com/rocky_tian/skill.git
cd skill/rocky-know-how
# 一键安装（自动配置 Hook + memoryFlush + 重启网关）
bash scripts/install.sh
# 验证安装
bash scripts/stats.sh
install.sh 自动完成：
- ✅ 创建经验诀窍目录结构
- ✅ 初始化存储文件
- ✅ 配置 Hook（agent:bootstrap / before_compaction / after_compaction / before_reset）
- ✅ 配置 memoryFlush（softThresholdTokens: 8000）
- ✅ 重启网关使配置生效
📈 Key Advantages / 核心优势
- memoryFlush-driven auto-learning — Experience recording triggered before every compaction
- LLM dual-judgment — First judges if worth saving, then decides create vs append
- Triple degradation — LLM → keyword → write, never loses data
- Multi-provider — Supports OpenAI, Anthropic, OAuth providers (zai/stepfun/minimax)
- Production proven — 45+ real experiences, 2.6MB data, stable operation
- Safety first — 5 security mechanisms (regex injection, path traversal, write lock, etc.)
Version: 3.1.0 | Tested: 2026-04-24 | License: MIT