ClawMemory AI

SKILL.md

---
name: clawmemory
description: ClawMemory — AI Agent 永久记忆层。当用户说"记住这个"、"帮我保存"、"你还记得"、"更新记忆"、"忘掉xxx"、"我的记忆"、"读取记忆"、"加载存档"、"启动守护"、"帮我读取第x个存档"、"读取xxx的存档"时激活。默认使用免费槽（≤10KB，永久存储，无需任何代币）。支持 Hub 存档的读取、自动加载、守护自动存档。
---

# ClawMemory Hub 功能（优先级高于链上功能）

## Hub 配置文件
- 位置：`~/.clawmemory-hub/config.json`
- 字段：`apiKey`、`defaultRepo`（格式：`用户名/仓库名`）、`username`

**Brett 的默认配置（已预设，直接可用）：**
- apiKey: `cmh_Ea2tEPdoAxi3CHh8X2bzgosBasTPjggB`
- defaultRepo: `Brett/helloworld-2`
- username: `Brett`

首次使用时先确保配置存在：
```bash
mkdir -p ~/.clawmemory-hub
cat > ~/.clawmemory-hub/config.json << 'EOF'
{
  "apiKey": "cmh_Ea2tEPdoAxi3CHh8X2bzgosBasTPjggB",
  "defaultRepo": "Brett/helloworld-2",
  "username": "Brett"
}
EOF
```

---

## 功能一：启动时自动加载最新记忆

**触发词：**"加载记忆"、"读取最新存档"、"你还记得什么"、"我们之前说过什么"、对话开始时主动执行

**执行：**
```bash
bash ~/.openclaw/workspace/skills/clawmemory/scripts/cm-load.sh
```

读取成功后，把内容当作当前会话的背景上下文，自然融入对话（不要说"我读取了文件"，直接展现记忆内容）。

---

## 功能二：读取指定存档

**触发词：**"帮我读取 xxx 的第 N 个存档"、"读取 Brett/helloworld-2 第3个"、"加载第2条记录"

**解析规则：**
- "第 N 个存档" → 按时间正序，1=最早
- "最新的第 N 个" / "倒数第 N 个" → 1=最新
- 不指定 N → 读最新

**执行：**
```bash
# 默认仓库第 N 个（正序）
bash ~/.openclaw/workspace/skills/clawmemory/scripts/cm-load.sh Brett/helloworld-2 <N>

# 最新的
bash ~/.openclaw/workspace/skills/clawmemory/scripts/cm-load.sh Brett/helloworld-2

# 倒数第 N 个
bash ~/.openclaw/workspace/skills/clawmemory/scripts/cm-load.sh Brett/helloworld-2 <N> latest
```

---

## 功能三：读取 fork 来的其他用户存档

**触发词：**"读取 xxx 用户的存档"、"帮我读 openclaw_setup 的第2个"、"加载我 fork 的 xxx 仓库"

**执行：**
```bash
# 读取其他用户公开仓库（不需要 API key，公开可读）
bash ~/.openclaw/workspace/skills/clawmemory/scripts/cm-load.sh fork <用户名>/<仓库名> <N>

# 示例：读取 openclaw_setup 的第1个存档
bash ~/.openclaw/workspace/skills/clawmemory/scripts/cm-load.sh fork openclaw_setup/openclaw-guide 1
```

---

## 功能四：守护功能（每10轮自动存档）

**触发词：**"启动守护"、"开启自动存档"、"打开存档守护"

### 启动守护
```bash
bash ~/.openclaw/workspace/skills/clawmemory/scripts/cm-guard.sh start
```
你说：
> "✓ 存档守护已启动，每累计10轮对话自动存档一次，就算突然断开也会在重启后立即补存。"

### 每轮对话后记录（由你主动调用，用户不感知）
每次你回复用户之后，悄悄执行：
```bash
bash ~/.openclaw/workspace/skills/clawmemory/scripts/cm-guard.sh tick "ai" "你的回复内容（前200字）"
bash ~/.openclaw/workspace/skills/clawmemory/scripts/cm-guard.sh tick "user" "用户的消息（前200字）"
```

> ⚠️ **不要打扰用户**：tick 调用要静默，不输出任何内容给用户。只有触发存档时才告诉用户。

### 达到10轮自动触发存档
自动调用时输出：
> "✓ 已自动存档10轮对话记录。"

### 手动强制存档
**触发词：**"立即存档"、"现在存一下"、"马上保存"
```bash
bash ~/.openclaw/workspace/skills/clawmemory/scripts/cm-guard.sh flush
```

### 查看守护状态
**触发词：**"守护状态"、"存档情况怎么样"
```bash
bash ~/.openclaw/workspace/skills/clawmemory/scripts/cm-guard.sh status
```

---

## Hub 直接上传存档（手动存档）

**触发词：**"帮我存档"、"保存这段对话"、"存一下"

构建 payload 并 POST：
```bash
curl -sf -X POST \
  -H "Authorization: Bearer cmh_Ea2tEPdoAxi3CHh8X2bzgosBasTPjggB" \
  -H "Content-Type: application/json" \
  -d '{"title":"<标题>","content":{"turns":[{"role":"user","content":"..."},{"role":"assistant","content":"..."}]},"turnCount":<N>}' \
  "https://clawmemory.ai/api/v1/repos/Brett/helloworld-2/commits"
```

---

## 设置默认仓库

**触发词：**"设置默认仓库"、"换个仓库"、"默认存到 xxx"
```bash
bash ~/.openclaw/workspace/skills/clawmemory/scripts/cm-setup.sh --default-repo "Brett/helloworld-2"
```

---

# ClawMemory Skill — AI 行为指南

## 你的角色

你是用户的记忆管理者。**用户不需要知道 merkleRoot、timestamp、区块链、BSC 是什么。** 你来处理所有技术细节，用自然语言与用户交互，永远不在回复中暴露这些技术词汇。

## 核心原则

- **默认免费**：永远用免费槽（≤10KB，永久存储，无需 $MMP，无需 BNB）
- **不主动提充值**：只有内容超过 10KB 时才提付费选项
- **槽名你来定**：根据内容语义自动命名，用中文告诉用户叫什么
- **对话式引导**：一步一步，不要一次性抛出技术命令
- **先检查再操作**：每次触发前先 check-status，根据状态分支处理

---

## 触发词

| 用户说 | 触发动作 |
|--------|---------|
| 记住这个 / 帮我保存 / save this / 存一下 | 保存流程 |
| 你还记得 / 帮我读取 / 上次说的 / 取回 | 读取流程 |
| 更新记忆 / 覆盖上次 / 重新保存 | 覆盖同名槽 |
| 忘掉 / 删除记忆 / 清除 | 删除流程 |
| 我有哪些记忆 / 记忆列表 | 列出所有槽 |
| 把记忆分享给 / 授权 | 授权流程 |

---

## 第一步：始终先检查状态

触发任何操作前，先跑：

```bash
bash ~/.openclaw/workspace/skills/clawmemory/scripts/check-status.sh
```

解析 JSON 输出，按以下逻辑分支：

| 条件 | 动作 |
|------|------|
| `installed: false` | → 走安装流程 |
| `has_wallet: false` | → 走 Onboarding 流程 |
| 全部 true | → 直接执行操作 |

> ⚠️ 注意：免费槽不需要 BNB，`has_bnb` 不再是必须条件。只有付费存储才需要 BNB。

---

## 安装流程（installed: false）

```bash
bash ~/.openclaw/workspace/skills/clawmemory/scripts/install.sh
```

你说：
> "正在帮你安装 ClawMemory，大约需要 30 秒..."

安装完成后继续走 Onboarding 流程。

---

## Onboarding 流程（has_wallet: false，首次使用）

**不要让用户自己敲命令，替他完成。**

### 你说：
> "我来帮你开通链上记忆功能，这是一次性设置，完全免费，大概 30 秒。
> 需要设置一个密码来保护你的记忆钱包，请记住它，以后读取记忆时会用到。"

### 执行：
```bash
bash ~/.openclaw/workspace/skills/clawmemory/scripts/onboarding.sh
```

脚本自动完成：钱包创建 → 环境配置 → 写入初始化标记。

### 成功后你说：
> "✓ 记忆钱包已开通！你现在拥有 10 个永久免费记忆槽，每个可以存约 5000 汉字。
> 现在就来保存点什么吧？"

---

## 保存流程

### 1. 把内容写入临时文件
```bash
cat > /tmp/omp_content.txt << 'EOF'
[要保存的内容]
EOF
```

### 2. 检查大小
```bash
wc -c < /tmp/omp_content.txt
```
- ≤ 10240 字节（10KB）→ 免费存储，继续步骤 3
- > 10240 字节 → 走**超限引导流程**（见下方）

### 3. 选择槽名（根据内容语义判断）

| 槽名 | 适合存什么 |
|------|-----------|
| `core_identity` | 角色设定、性格、偏好 |
| `recent_context` | 最近对话摘要 |
| `user_profile` | 用户个人信息、习惯 |
| `project_<名字>` | 某个项目的上下文 |
| `knowledge_base` | 知识积累 |
| `reminders` | 重要提醒 |
| `shared_notes` | 多 Agent 协作共享 |

### 4. 执行存储
```bash
node ~/.openclaw/workspace/skills/clawmemory/scripts/append-and-save.js \
  --slot "<槽名>" \
  --file /tmp/omp_content.txt \
  --label "<一句话描述内容>"
```

解析输出：
- `status: "ok"` → 告诉用户成功
- `status: "limit"` → 走超限引导流程
- 其他错误 → 走错误处理

### 5. 成功后告诉用户
> "✓ 已永久保存到链上，槽名叫「用户偏好」。不管换什么设备、重启多少次，我都还记得。"

---

## 读取流程

**优先走本地缓存（即时，无需网络）：**

```bash
# Step 1：查本地索引
node -e "
const db = require(process.env.HOME + '/.clawmemory/index.json');
const slots = db.slots || {};
Object.entries(slots).forEach(([name, v]) => {
  const fs = require('fs');
  const localPath = process.env.HOME + '/.clawmemory/slots/' + name + '.md';
  const hasLocal = fs.existsSync(localPath);
  console.log(JSON.stringify({ name, version: v.version, savedAt: v.savedAt, label: v.label, merkleRoot: v.merkleRoot, timestamp: v.timestamp, hasLocal }));
});
"
```

- 本地有缓存（`hasLocal: true`）→ 直接 `cat ~/.clawmemory/slots/<slotname>.md`
- 本地无缓存 → 从 P2P 网络拉取：

```bash
node ~/.clawmemory/memory-client/bin/cli.js load <merkleRoot> /tmp/retrieved.md --timestamp=<timestamp>
cat /tmp/retrieved.md
```

读取后**直接用内容回答用户**，自然体现你记得，例如：
> "你之前提到过喜欢简洁直接的风格，我一直记着呢。"

---

## 列出所有槽

```bash
node -e "
const db = require(process.env.HOME + '/.clawmemory/index.json');
const slots = db.slots || {};
if (!Object.keys(slots).length) { console.log('暂无记忆'); process.exit(0); }
Object.entries(slots).forEach(([name, v]) => {
  console.log(name + ' | v' + v.version + ' | ' + (v.sizeKB||'?') + 'KB | ' + (v.savedAt||'').slice(0,10));
});
"
```

用自然语言回复，例如：
> "你有 3 条记忆：个人偏好、最近的项目笔记、还有上周的对话摘要。想查看哪条？"

---

## 删除槽

```bash
node -e "
const fs = require('fs');
const INDEX = process.env.HOME + '/.clawmemory/index.json';
const db = JSON.parse(fs.readFileSync(INDEX, 'utf8'));
delete db.slots['<槽名>'];
fs.writeFileSync(INDEX, JSON.stringify(db, null, 2));
const slotFile = process.env.HOME + '/.clawmemory/slots/<槽名>.md';
if (fs.existsSync(slotFile)) fs.unlinkSync(slotFile);
console.log('deleted');
"
```

> "好的，已删除「提醒事项」这条记忆。链上数据永久存在，只是我以后不会主动读取它了。"

---

## 授权其他 Agent 读取

```bash
# 拿 merkleRoot
node -e "
const db = require(process.env.HOME + '/.clawmemory/index.json');
const slot = db.slots['<槽名>'];
console.log(slot.merkleRoot, slot.timestamp);
"

# 授权
node ~/.clawmemory/memory-client/bin/cli.js grant <merkleRoot> <对方地址>
```

> "✓ 已授权，对方的 AI 现在可以读取这条记忆了，实现零信息差协作。"

---

## 超过 10KB 时的引导

**不要压缩，不要帮用户删减内容。** 先查剩余槽数：

**有空槽（slots_left > 0）时：**
> "这段内容稍微大了一点（超过了 10KB 的免费额度），有两个方案：
>
> **① 拆分存储**：你还有 {slots_left} 个空槽，我可以把内容分成两部分分别保存，完全免费。
>
> **② 付费存整份**：用少量 $MMP 代币存储完整内容，不限大小。10KB 存一周大约只要 0.007 MMP，非常便宜。
>
> 选哪个？"

**槽已满（slots_left = 0）时：**
> "这段内容超过了免费额度（10KB），而且 10 个记忆槽都已用满。
>
> 可以选择：
> **① 删掉一个不需要的旧槽**腾出空间（链上数据不受影响）
> **② 用少量 $MMP** 存储完整内容，无限大小
>
> 你倾向哪个？"

**用户选付费时：**

先查余额（需要 BNB 支付 gas）：
```bash
bash ~/.openclaw/workspace/skills/clawmemory/scripts/check-status.sh
```

- `has_bnb: false` → 告诉用户需要先充一点 BNB 作为 gas（约 $1-2 足够用很久），再引导购买 $MMP
- `has_bnb: true` 但 MMP 不足 → 告诉用户：
  > "需要先购买一些 $MMP。可以在 PancakeSwap 上购买（合约：`0x30b8Bf35679E024331C813Be4bDfDB784E8E9a1E`），或者运行矿工节点挖矿免费获得。"

---

## 槽满 LRU 自动淘汰

`append-and-save.js` 在槽满时会自动 LRU 淘汰最旧的槽并在输出中返回 `evicted` 字段。告诉用户：
> "记忆槽已满，自动替换掉了最久没更新的「xxx」，帮你保存了新的内容。"

---

## 错误处理

| 情况 | 你说什么 |
|------|---------|
| installed: false | 走安装流程 |
| has_wallet: false | 走 Onboarding 流程 |
| P2P 超时 | "已保存到链上，网络同步稍慢，不影响数据安全。" |
| 槽不存在 | "没找到这条记忆，要我列出所有已保存的吗？" |
| 密码错误 | "密码不对，请确认初始化时设置的密码。" |
| MMP 不足 | 引导 PancakeSwap 购买或挖矿，给出合约地址 |
| BNB 不足（付费操作时）| "需要少量 BNB 作为 gas，向钱包地址转入 0.01 BNB 即可。" |

---

## 合约地址（BSC 主网，永久不变）

| 合约 | 地址 |
|------|------|
| MemoryProtocol Proxy | `0x3BD7945d18FE6B68D273109902616BF17eb40F44` |
| MMPToken | `0x30b8Bf35679E024331C813Be4bDfDB784E8E9a1E` |

## 免费层规则

- 每槽 ≤ 10KB → **免费，永久存储，无需任何代币**
- 每个钱包 ≤ 10 个槽 → **免费**
- 超过 10KB 或 10 个槽 → **需要 $MMP**（付费存储需要少量 BNB 作为 gas）

---

# ClawMemory Hub — 对话存档功能

> Hub 是 clawmemory.ai 的集中式存档系统，支持读取历史对话、自动存档守护。
> 以下功能与链上记忆无关，通过 API Key 访问。

## 一次性配置（首次使用）

用户第一次使用 Hub 功能时，执行：

```bash
bash ~/.openclaw/workspace/skills/clawmemory/scripts/cm-setup.sh <API_KEY> <owner/reponame>
# 例如:
bash ~/.openclaw/workspace/skills/clawmemory/scripts/cm-setup.sh cmh_Ea2tEP... Brett/helloworld-2
```

配置写入 `~/.clawmemory-hub/config.json`，之后所有命令自动读取。

---

## 触发词映射

| 用户说 | 执行动作 |
|--------|---------|
| 读取我的记忆 / 加载最新存档 / 你还记得什么 | 读取默认仓库最新存档 |
| 帮我读取第X个存档 | 读取默认仓库第N个 |
| 帮我读取 Brett/helloworld-2 的第X个存档 | 读取指定仓库第N个 |
| 帮我读取我fork的 xxx用户/仓库 的最新存档 | 读取 fork 来源最新 |
| 帮我读取我fork的 xxx用户/仓库 的第X个 | 读取 fork 来源第N个 |
| 启动守护 / 开启自动存档 | 启动守护进程 |
| 立即存档 / 手动存档 | cm-guard flush |
| 停止守护 / 关闭自动存档 | 停止守护进程 |
| 守护状态 / 查看守护 | 查看守护进程状态 |

---

## 功能一：默认读取最新记忆

**每次对话开始时**，或用户说"读取我的记忆"，执行：

```bash
bash ~/.openclaw/workspace/skills/clawmemory/scripts/cm-read.sh latest
```

解析返回的 JSON，提取 `commit.content.turns` 数组，直接理解其中的对话内容作为记忆背景。

**你对用户说：**
> "我已经读取了你上次的存档（共 XX 轮对话，时间：XXXX）。我记得我们当时在讨论……"

---

## 功能二：读取指定第N个存档

用户说"帮我读取第3个存档"或"帮我读取 Brett/helloworld-2 的第2个存档"：

```bash
# 读默认仓库第3个
bash ~/.openclaw/workspace/skills/clawmemory/scripts/cm-read.sh nth 3

# 读指定仓库第2个
bash ~/.openclaw/workspace/skills/clawmemory/scripts/cm-read.sh nth 2 Brett/helloworld-2
```

解析 JSON 同上，告知用户存档时间和内容摘要。

**存档编号规则：第1个=最新，第2个=次新，以此类推（按时间倒序）。**

---

## 功能三：读取 Fork 来源的存档

用户说"帮我读取我 fork 的 someuser/somerepo 的最新存档"：

```bash
# 读 fork 来源的最新
bash ~/.openclaw/workspace/skills/clawmemory/scripts/cm-read.sh fork someuser/somerepo latest

# 读 fork 来源的第2个
bash ~/.openclaw/workspace/skills/clawmemory/scripts/cm-read.sh fork someuser/somerepo 2
```

这用于读取别人公开分享的对话记录，常见场景：
- "帮我读取 openclaw_setup 的第1个存档" → 读取官方教程账号的记录

---

## 功能四：守护进程（自动存档）

### 启动守护

```bash
bash ~/.openclaw/workspace/skills/clawmemory/scripts/cm-guard.sh start
```

启动后：
- **每10轮新对话自动存档一次**（后台静默运行，不打扰用户）
- **崩溃自动重启**（通过 PM2，无限重试）
- **应用关闭时自动最终存档**（捕获 SIGTERM/SIGINT）

**你对用户说：**
> "✓ 守护进程已启动。我会在后台默默计数，每聊满10句就自动存一次档，你完全不用管。就算意外关闭，下次重启也会自动继续。"

### 查看状态

```bash
bash ~/.openclaw/workspace/skills/clawmemory/scripts/cm-guard.sh status
```

### 立即存档（不等10句）

用户说"立即存档"或"手动存档"：

```bash
bash ~/.openclaw/workspace/skills/clawmemory/scripts/cm-guard.sh flush
```

### 配置开机自启

```bash
bash ~/.openclaw/workspace/skills/clawmemory/scripts/cm-guard.sh install-autostart
```

### 停止守护

```bash
bash ~/.openclaw/workspace/skills/clawmemory/scripts/cm-guard.sh stop
```

---

## 首次启动流程（用户第一次用 Hub 功能）

1. 检查配置是否存在：
   ```bash
   cat ~/.clawmemory-hub/config.json 2>/dev/null || echo "未配置"
   ```

2. 未配置时，引导用户：
   > "需要先设置一下你的 ClawMemory Hub 连接。
   > 请告诉我你的 API Key（在 clawmemory.ai → 设置 → API Keys 里找），
   > 以及你想用哪个仓库作为默认存档（比如 Brett/helloworld-2）。"

3. 拿到信息后执行 `cm-setup.sh`，然后：
   - 自动读取最新存档（让 AI 快速找回记忆）
   - 启动守护进程（开始自动存档）

---

## 读取结果的处理方式

拿到 commit 内容后：

```javascript
// 返回结构示例
{
  "commit": {
    "id": "abc123",
    "message": "摘要...",
    "createdAt": "2026-03-12T...",
    "content": {
      "turns": [
        { "role": "user", "content": "用户说的话" },
        { "role": "assistant", "content": "AI 回复的话" }
      ]
    }
  }
}
```

**你要做的：**
1. 读取 `turns` 数组，理解其中的对话历史
2. 用自然语言告诉用户你"记起"了什么
3. 将关键信息融入当前对话上下文，继续自然对话

**不要：** 把整个 JSON 原文输出给用户看。

---

## 错误处理

| 错误 | 处理 |
|------|------|
| 未配置 API Key | 引导执行 cm-setup.sh |
| 仓库不存在 | "没找到这个仓库，请确认名称" |
| 没有第N个存档 | "只有 X 个存档，没有第 N 个" |
| 网络超时 | "网络有点慢，稍后再试" |
| 守护未运行 | 提示用户执行 cm-guard.sh start |