supermemory-free

使用 Supermemory.ai 免费套餐进行云知识备份和检索。将高价值洞察存储到云端，并在本地内存不足时搜索回来。使用标准 /v3/documents 和 /v3/search 端点（没有 Pro-only 功能）。

# Supermemory Free — Cloud Knowledge Backup

Backs up important knowledge and insights to Supermemory.ai's cloud using the **free tier API**.  
Uses only `/v3/documents` (store) and `/v3/search` (retrieve) — no Pro-only endpoints.

## Prerequisites

Set in `.env`
```
SUPERMEMORY_OPENCLAW_API_KEY="sm_..."
```

## Tools

### supermemory_cloud_store
Store a knowledge string to the cloud.

```bash
python3 skills/supermemory-free/store.py "Your knowledge string here"

# With optional container tag (namespace/filter)
python3 skills/supermemory-free/store.py "knowledge string" --tag openclaw

# With metadata
python3 skills/supermemory-free/store.py "knowledge string" --tag fixes --source "session"

# Output raw JSON
python3 skills/supermemory-free/store.py "knowledge string" --json
```

**When to use:**
- User asks to "remember" something permanently
- Important configuration/setup knowledge
- Resolved problems / solutions discovered
- Key facts you want cross-session persistence for

---

### supermemory_cloud_search
Search the cloud memory for relevant knowledge.

```bash
python3 skills/supermemory-free/search.py "your query"

# With container tag filter
python3 skills/supermemory-free/search.py "your query" --tag openclaw

# More results
python3 skills/supermemory-free/search.py "your query" --limit 10

# Higher precision (less noise)
python3 skills/supermemory-free/search.py "your query" --threshold 0.7

# Search across ALL tags
python3 skills/supermemory-free/search.py "your query" --no-tag
```

**When to use:**
- Local memory (MEMORY.md, daily logs) doesn't have the answer
- User references something from "a long time ago"
- Cross-session knowledge lookup
- "Do you remember when..." queries

---

### Auto-Capture (Cron)
Scans recent session memory logs and automatically pushes high-value insights to Supermemory cloud.

```bash
# Run manually
python3 skills/supermemory-free/auto_capture.py

# Dry run (show what would be captured, no upload)
python3 skills/supermemory-free/auto_capture.py --dry-run

# Scan last N days (default: 3)
python3 skills/supermemory-free/auto_capture.py --days 7

# Force re-upload even if already seen
python3 skills/supermemory-free/auto_capture.py --force

# Verbose mode
python3 skills/supermemory-free/auto_capture.py --verbose
```

**Install cron job (runs daily at 2:00 AM UTC):**
```bash
bash skills/supermemory-free/install_cron.sh
```

**Remove cron job:**
```bash
bash skills/supermemory-free/install_cron.sh --remove
```

**Check cron status:**
```bash
bash skills/supermemory-free/install_cron.sh --status
```

---

## What Gets Auto-Captured

The auto-capture script identifies "high-value" insights from memory logs using these heuristics:

| Pattern | Label | Example |
|---------|-------|---------|
| Resolved errors / fixes | `fix` | `Fixed: SSL cert error by running...` |
| Error context | `error` | `Exception: Connection refused on port 5432` |
| Configuration paths | `config` | `/etc/nginx/sites-available/default` |
| API/endpoint info | `api` | `Endpoint: POST /v3/documents for storage` |
| User preferences | `preference` | `User prefers Python over Node for scripts` |
| Decisions made | `decision` | `Decided to use PostgreSQL because...` |
| Learned facts | `insight` | `Learned that cron syntax for...` |
| Installs / setup | `setup` | `Installed nginx, configured with...` |
| Bullet-point blocks | `bullet` | `- Key finding: X works better than Y` |

**Deduplication:** Already-uploaded items are tracked in `.capture_state.json` — re-running is safe.

---

## Container Tags

Use `--tag` to namespace your memories:

| Tag | Purpose |
|-----|---------|
| `openclaw` | General OpenClaw session knowledge (default) |
| `fixes` | Bug fixes and solutions |
| `config` | Configuration and setup |
| `user-prefs` | User preferences |
| `projects` | Project-specific knowledge |

---

## Files

| File | Purpose |
|------|---------|
| `store.py` | CLI tool: upload knowledge to cloud |
| `search.py` | CLI tool: search cloud knowledge |
| `auto_capture.py` | Cron script: auto-analyze memory logs |
| `install_cron.sh` | Install/remove/status of cron job |
| `.capture_state.json` | Dedup state (auto-generated, gitignore) |
| `SKILL.md` | This file |
| `_meta.json` | Skill metadata |

---

## API Info

- **Base URL:** `https://api.supermemory.ai`
- **Store endpoint:** `POST /v3/documents`
- **Search endpoint:** `POST /v3/search`
- **Auth:** Bearer token from `SUPERMEMORY_OPENCLAW_API_KEY`
- **Free tier limits:** Check https://console.supermemory.ai for current quotas
- **Note:** Cloudflare-compatible headers included — avoids 1010 access denial errors

---

## Troubleshooting

**HTTP 403 / 1010 Access Denied:**  
The scripts include proper `User-Agent`, `Origin`, and `Referer` headers to satisfy Cloudflare. If it recurs, verify the API key is valid at https://console.supermemory.ai.

**No memory files found:**  
Auto-capture looks in `memory/YYYY-MM-DD.md`. Ensure your memory skill is writing daily logs there.

**Re-upload everything:**  
Delete `.capture_state.json` or use `--force` to ignore the dedup state.

---

## 中文说明

# Supermemory Free — 云知识备份

使用 **免费套餐 API** 将重要的知识与洞察备份到 Supermemory.ai 云端。  
仅使用 `/v3/documents`（存储）和 `/v3/search`（检索）——不依赖任何 Pro-only 端点。

## 前置条件

在 `.env` 中设置
```
SUPERMEMORY_OPENCLAW_API_KEY="sm_..."
```

## 工具

### supermemory_cloud_store
将一段知识字符串存储到云端。

```bash
python3 skills/supermemory-free/store.py "Your knowledge string here"

# With optional container tag (namespace/filter)
python3 skills/supermemory-free/store.py "knowledge string" --tag openclaw

# With metadata
python3 skills/supermemory-free/store.py "knowledge string" --tag fixes --source "session"

# Output raw JSON
python3 skills/supermemory-free/store.py "knowledge string" --json
```

**何时使用：**
- 用户要求永久“记住”某件事
- 重要的配置/搭建知识
- 已解决的问题 / 发现的解决方案
- 你希望跨会话持久保存的关键事实

---

### supermemory_cloud_search
在云内存中搜索相关知识。

```bash
python3 skills/supermemory-free/search.py "your query"

# With container tag filter
python3 skills/supermemory-free/search.py "your query" --tag openclaw

# More results
python3 skills/supermemory-free/search.py "your query" --limit 10

# Higher precision (less noise)
python3 skills/supermemory-free/search.py "your query" --threshold 0.7

# Search across ALL tags
python3 skills/supermemory-free/search.py "your query" --no-tag
```

**何时使用：**
- 本地内存（MEMORY.md、每日日志）中没有答案
- 用户提到“很久以前”的某件事
- 跨会话的知识查找
- “你还记得……吗”这类查询

---

### 自动捕获（Cron）
扫描近期的会话内存日志，并自动将高价值洞察推送到 Supermemory 云端。

```bash
# Run manually
python3 skills/supermemory-free/auto_capture.py

# Dry run (show what would be captured, no upload)
python3 skills/supermemory-free/auto_capture.py --dry-run

# Scan last N days (default: 3)
python3 skills/supermemory-free/auto_capture.py --days 7

# Force re-upload even if already seen
python3 skills/supermemory-free/auto_capture.py --force

# Verbose mode
python3 skills/supermemory-free/auto_capture.py --verbose
```

**安装 cron 任务（每天 UTC 凌晨 2:00 运行）：**
```bash
bash skills/supermemory-free/install_cron.sh
```

**移除 cron 任务：**
```bash
bash skills/supermemory-free/install_cron.sh --remove
```

**查看 cron 状态：**
```bash
bash skills/supermemory-free/install_cron.sh --status
```

---

## 哪些内容会被自动捕获

自动捕获脚本使用以下启发式规则从内存日志中识别“高价值”洞察：

| 模式 | 标签 | 示例 |
|---------|-------|---------|
| 已解决的错误 / 修复 | `fix` | `Fixed: SSL cert error by running...` |
| 错误上下文 | `error` | `Exception: Connection refused on port 5432` |
| 配置路径 | `config` | `/etc/nginx/sites-available/default` |
| API/端点信息 | `api` | `Endpoint: POST /v3/documents for storage` |
| 用户偏好 | `preference` | `User prefers Python over Node for scripts` |
| 做出的决策 | `decision` | `Decided to use PostgreSQL because...` |
| 学到的事实 | `insight` | `Learned that cron syntax for...` |
| 安装 / 搭建 | `setup` | `Installed nginx, configured with...` |
| 项目符号块 | `bullet` | `- Key finding: X works better than Y` |

**去重：** 已上传的条目会记录在 `.capture_state.json` 中——重复运行是安全的。

---

## 容器标签

使用 `--tag` 为你的内存划分命名空间：

| 标签 | 用途 |
|-----|---