openclaw-persistent-memory

持久记忆系统——自动上下文捕获和语义搜索

# OpenClaw Persistent Memory

Persistent memory system that automatically captures context across sessions using SQLite + FTS5.

## Features

- 🧠 **Auto-capture** - Important observations saved automatically after each response
- 🔍 **Auto-recall** - Relevant memories injected before each prompt
- 💾 **SQLite + FTS5** - Fast full-text search across all memories
- 🛠️ **Tools** - `memory_search`, `memory_get`, `memory_store`, `memory_delete`
- 📊 **Progressive disclosure** - Token-efficient retrieval

## Setup

1. **Install the npm package:**
   ```bash
   npm install -g openclaw-persistent-memory
   ```

2. **Start the worker service:**
   ```bash
   openclaw-persistent-memory start
   ```

3. **Install the OpenClaw extension:**
   ```bash
   # Copy extension to OpenClaw extensions directory
   cp -r node_modules/openclaw-persistent-memory/extension ~/.openclaw/extensions/openclaw-mem
   cd ~/.openclaw/extensions/openclaw-mem && npm install
   ```

4. **Configure OpenClaw** (in `~/.openclaw/openclaw.json`):
   ```json
   {
     "plugins": {
       "slots": {
         "memory": "openclaw-mem"
       },
       "allow": ["openclaw-mem"],
       "entries": {
         "openclaw-mem": {
           "enabled": true,
           "config": {
             "workerUrl": "http://127.0.0.1:37778",
             "autoCapture": true,
             "autoRecall": true
           }
         }
       }
     }
   }
   ```

5. **Restart OpenClaw gateway**

## Tools Provided

| Tool | Description |
|------|-------------|
| `memory_search` | Search memories with natural language |
| `memory_get` | Get a specific memory by ID |
| `memory_store` | Save important information |
| `memory_delete` | Delete a memory by ID |

## API Endpoints

Worker runs on `http://127.0.0.1:37778`:

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/health` | GET | Health check |
| `/api/stats` | GET | Database statistics |
| `/api/search` | POST | Full-text search |
| `/api/observations` | GET | List recent observations |
| `/api/observations/:id` | GET | Get observation |
| `/api/observations/:id` | DELETE | Delete observation |
| `/api/observations/:id` | PATCH | Update observation |

## Troubleshooting

### Worker not running
```bash
curl http://127.0.0.1:37778/api/health
# If fails, restart:
openclaw-persistent-memory start
```

### Auto-recall not working
- Check OpenClaw logs: `tail ~/.openclaw/logs/*.log | grep openclaw-mem`
- Verify `plugins.slots.memory` is set to `"openclaw-mem"`
- Restart gateway after config changes

---

## 中文说明

# OpenClaw Persistent Memory

持久记忆系统，使用 SQLite + FTS5 自动跨会话捕获上下文。

## 功能

- 🧠 **自动捕获** - 每次响应后自动保存重要观察
- 🔍 **自动回忆** - 在每次提示前注入相关记忆
- 💾 **SQLite + FTS5** - 在所有记忆中进行快速全文搜索
- 🛠️ **工具** - `memory_search`、`memory_get`、`memory_store`、`memory_delete`
- 📊 **渐进式披露** - 节省 token 的检索

## 设置

1. **安装 npm 包：**
   ```bash
   npm install -g openclaw-persistent-memory
   ```

2. **启动 worker 服务：**
   ```bash
   openclaw-persistent-memory start
   ```

3. **安装 OpenClaw 扩展：**
   ```bash
   # Copy extension to OpenClaw extensions directory
   cp -r node_modules/openclaw-persistent-memory/extension ~/.openclaw/extensions/openclaw-mem
   cd ~/.openclaw/extensions/openclaw-mem && npm install
   ```

4. **配置 OpenClaw**（在 `~/.openclaw/openclaw.json` 中）：
   ```json
   {
     "plugins": {
       "slots": {
         "memory": "openclaw-mem"
       },
       "allow": ["openclaw-mem"],
       "entries": {
         "openclaw-mem": {
           "enabled": true,
           "config": {
             "workerUrl": "http://127.0.0.1:37778",
             "autoCapture": true,
             "autoRecall": true
           }
         }
       }
     }
   }
   ```

5. **重启 OpenClaw 网关**

## 提供的工具

| 工具 | 说明 |
|------|-------------|
| `memory_search` | 用自然语言搜索记忆 |
| `memory_get` | 按 ID 获取特定记忆 |
| `memory_store` | 保存重要信息 |
| `memory_delete` | 按 ID 删除记忆 |

## API 端点

Worker 运行在 `http://127.0.0.1:37778`：

| 端点 | 方法 | 说明 |
|----------|--------|-------------|
| `/api/health` | GET | 健康检查 |
| `/api/stats` | GET | 数据库统计 |
| `/api/search` | POST | 全文搜索 |
| `/api/observations` | GET | 列出最近的观察 |
| `/api/observations/:id` | GET | 获取观察 |
| `/api/observations/:id` | DELETE | 删除观察 |
| `/api/observations/:id` | PATCH | 更新观察 |

## 故障排查

### Worker 未运行
```bash
curl http://127.0.0.1:37778/api/health
# If fails, restart:
openclaw-persistent-memory start
```

### 自动回忆不工作
- 检查 OpenClaw 日志：`tail ~/.openclaw/logs/*.log | grep openclaw-mem`
- 验证 `plugins.slots.memory` 已设置为 `"openclaw-mem"`
- 配置更改后重启网关