koatora20-guava-memory

GuavaMemory 面向 OpenClaw 的结构化情景记忆系统，带 Q 值评分，记录成功/失败模式并提升为可复用技能流程。

## 概述（中文）

GuavaMemory 面向 OpenClaw 的结构化情景记忆系统，带 Q 值评分，记录成功/失败模式并提升为可复用技能流程。

## 技能正文

# GuavaMemory — 面向 OpenClaw 的情景记忆系统

带 Q 值评分的结构化情景记忆。记住有效的做法，遗忘无效的做法。

## 功能说明

- 记录任务情景，附带成功/失败模式与 Q 值
- 通过 `memory_search`（兼容 Voyage AI）搜索过往情景
- 将重复成功的做法提升为可复用的技能流程
- 跟踪反模式，避免重蹈覆辙

## 快速开始

### 1. 设置记忆目录

```bash
mkdir -p memory/episodes memory/skills memory/meta
```

### 2. 初始化索引

```bash
cat > memory/episodes/index.json << 'EOF'
{
  "version": "1.0.0",
  "name": "GuavaMemory",
  "episodes": [],
  "stats": { "total": 0, "avg_q_value": 0, "promotions": 0 },
  "config": {
    "promotion_threshold": 0.85,
    "promotion_min_count": 3,
    "max_episodes_per_search": 3,
    "learning_rate": 0.3
  }
}
EOF
```

### 3. 添加到 AGENTS.md

将以下规则粘贴到你的 AGENTS.md 中：

```markdown
### Episodic Memory Rules
1. **Task start** → `memory_search` for related episodes. Use top 3 by Q-value
2. **Task complete** → Record episode in `memory/episodes/ep_YYYYMMDD_NNN.md`
3. **Record content** → Intent, Context, Success pattern, Failure pattern, Q-value, feel
4. **Skill promotion** → 3 successes with same intent & Q≥0.85 → promote to `memory/skills/`
5. **Anti-patterns** → Record failures in `memory/episodes/anti_patterns.md`
6. **No loops** → Record once per task at completion. No mid-task rewrites
7. **Update index** → Keep `memory/episodes/index.json` in sync
```

## 情景格式

创建类似 `memory/episodes/ep_20260211_001.md` 的文件：

```markdown
# EP-20260211-001: Short description

## Intent
What you were trying to do

## Context
- domain: what area
- tools: what tools used

## Experience

### ✅ Success Pattern
1. Step one
2. Step two
3. Step three

### ❌ Failure Pattern
- What didn't work and why

## Utility
- reward: 0.0-1.0 (1.0 = one-shot success)
- q_value: 0.0-1.0 (updated over time)
- feel: flow | grind | frustration | eureka
```

## Q 值更新

```
Q_new = Q_old + 0.3 * (reward - Q_old)
```

奖励刻度：
- `1.0` → 一次成功
- `0.7` → 经过一些试错后成功
- `0.3` → 成功但非常绕弯
- `0.0` → 失败，用其他方式解决
- `-0.5` → 失败，未解决

## 技能提升

当同一意图以 Q ≥ 0.85 成功 3 次以上时：
1. 将这些情景合并到 `memory/skills/skill-name.md`
2. 提炼出最优流程
3. 将来源情景标记为 `status: "graduated"`

## 搜索脚本

将 `scripts/ep-search.sh` 复制到你的工作区：

```bash
#!/bin/bash
EPISODES_DIR="${HOME}/.openclaw/workspace/memory/episodes"
INDEX="${EPISODES_DIR}/index.json"
echo "🔍 Searching episodes for: $1"
cat "$INDEX" | jq -r '.episodes | sort_by(-.q_value) | .[] | select(.status == "active") | "Q:\(.q_value) | \(.feel) | \(.intent) → \(.file)"'
```

## 依赖要求

- OpenClaw（任意版本）
- `jq`（用于搜索脚本）
- 无其他依赖

## 与 memory_search 的协作原理

情景是 `memory/` 中的纯 Markdown 文件。OpenClaw 的 `memory_search`（Voyage AI）会自动为其建立索引。当你搜索某个任务时，情景会按语义相似度排序。然后按 Q 值过滤，找出真正有效的做法。