统一记忆与memo0实测

# 容器中统一记忆系统与 mem0 插件测试教程

## 1 概述

本教程演示如何在一个运行 OpenClaw 应用的 Docker 容器内，对 **统一记忆系统插件（unified-memory v3.0）** 和 **mem0 插件（mem0-provider v3.0）** 进行完整的功能测试。测试内容包括：

- 单条记忆的增、删、查
- 批量记忆的增、删、查
- 用户/智能体之间的记忆隔离与共享机制
- 后端连接问题的排查与修复

通过学习本教程，你将掌握记忆系统插件的 CRUD 操作、配置方法以及故障诊断思路。

## 2 环境准备

### 2.1 容器信息

| 项目 | 值 |
|------|-----|
| 容器 ID | `889d6b423dc4` |
| 基础镜像 | `openclaw-custom:latest` |
| 运行状态 | `Up 6 minutes (healthy)` |
| 端口映射 | `8766→8766` (OpenClaw 网关), `8089→18789` |
| 网络 | `my-fixed-net` (172.30.0.0/24), `registry-net` (172.32.0.0/24) |

### 2.2 插件配置

两个插件均已启用，在 `openclaw.json` 中配置如下：

```json
{
  "unified-memory": {
    "enabled": true,
    "config": {
      "apiUrl": "http://172.17.0.1:8765",
      "enabled": true
    }
  },
  "mem0-provider": {
    "enabled": true,
    "config": {
      "apiUrl": "http://172.30.0.6:8000",
      "apiKey": "mem0-admin-k3y-s3cur3-2026-x9k2m4p7q8",
      "userId": "openclaw_main",
      "enabled": true
    }
  }
}
```

> **注意**：`unified-memory` 使用独立的 Python 后端服务（`172.17.0.1:8765`），而 `mem0-provider` 连接的是同一 Docker 网络中的 `mem0-mem0-1` 容器的 8000 端口。

## 3 统一记忆系统插件测试

### 3.1 单条记忆增删查

#### 3.1.1 添加记忆（Extract）

使用 `POST /extract` 端点向系统添加一条记忆：

```bash
curl -X POST http://172.17.0.1:8765/extract \
  -H "Content-Type: application/json" \
  -d '{
    "text": "用户常使用Python编写数据处理脚本",
    "user_id": "test_user",
    "agent_id": "main"
  }'
```

- **参数说明**：
  - `text`：记忆内容文本
  - `user_id`：关联的用户标识
  - `agent_id`：写入的智能体标识

成功响应：

```json
{"success": true}
```

#### 3.1.2 检索记忆（Search）

使用 `POST /retrieve` 端点进行语义检索：

```bash
curl -X POST http://172.17.0.1:8765/retrieve \
  -H "Content-Type: application/json" \
  -d '{
    "query": "数据处理",
    "user_id": "test_user",
    "agent_id": "main",
    "limit": 10
  }'
```

- `query`：检索关键词
- `limit`：返回结果上限

成功响应返回记忆列表，包含 `factId`、`text`、`score` 等字段。

#### 3.1.3 查看用户画像

```bash
curl -X GET http://172.17.0.1:8765/user/test_user
```

返回该用户的偏好 JSON，包含 `created_at` 和 `updated_at` 时间戳。

#### 3.1.4 删除单条记忆

从检索结果中获取 `factId`，然后执行删除：

```bash
curl -X DELETE http://172.17.0.1:8765/memory/{factId}
```

- **注意事项**：`unified-memory` 的删除操作需要先通过检索获得记忆的唯一 ID。删除时需验证 `source`（即写入的智能体）。

### 3.2 批量记忆增删查

#### 3.2.1 批量存储

逐条调用 `/extract`，每条间隔 1 秒：

```bash
for i in $(seq 1 5); do
  curl -X POST http://172.17.0.1:8765/extract \
    -H "Content-Type: application/json" \
    -d "{\"text\":\"批量测试记忆编号 $i\", \"user_id\":\"batch_user\", \"agent_id\":\"main\"}"
  sleep 1
done
```

所有请求均返回 `{"success": true}`。

#### 3.2.2 批量检索

执行与单条相同检索命令，观察返回记忆数量增加。

```bash
curl -X POST http://172.17.0.1:8765/retrieve \
  -H "Content-Type: application/json" \
  -d '{"query":"批量测试", "limit":20}'
```

#### 3.2.3 统计验证

查看系统统计信息确认存储量变化：

```bash
curl -X GET http://172.17.0.1:8765/stats
```

- 返回字段：`users`、`conversations`、`vectors` 等。
- 批量存储后，`conversations` 增加数量应与存储条数一致。

### 3.3 隔离与共享测试

#### 3.3.1 跨用户隔离测试

为两个不同用户存储“密码”类记忆：

```bash
# 用户A
curl -X POST http://172.17.0.1:8765/extract \
  -d '{"text":"用户A的密码是abc123", "user_id":"user_A", "agent_id":"main"}'

# 用户B
curl -X POST http://172.17.0.1:8765/extract \
  -d '{"text":"用户B的密码是xyz789", "user_id":"user_B", "agent_id":"main"}'
```

然后分别以 `user_id=user_A` 和 `user_id=user_B` 检索 `"密码"`：

```bash
curl -X POST http://172.17.0.1:8765/retrieve \
  -d '{"query":"密码","user_id":"user_A", "limit":5}'

curl -X POST http://172.17.0.1:8765/retrieve \
  -d '{"query":"密码","user_id":"user_B", "limit":5}'
```

**结果**：两个用户返回相同的全局记忆列表，**`user_id` 参数未生效**，检索为全局搜索。

#### 3.3.2 跨智能体隔离测试

分别以 `agent_id=main` 和 `agent_id=assistant2` 检索“专属记忆”：

```bash
curl -X POST http://172.17.0.1:8765/retrieve \
  -d '{"query":"专属记忆","agent_id":"main", "limit":5}'

curl -X POST http://172.17.0.1:8765/retrieve \
  -d '{"query":"专属记忆","agent_id":"assistant2", "limit":5}'
```

**结果**：两者返回相同结果（全局记忆前 6 条），`agent_id` 参数未生效。

#### 3.3.3 隔离机制分析

- **写入隔离**：不同智能体写入不同 `source`，删除时验证 source。
- **检索隔离**：`/retrieve` 端点的 `user_id` 和 `agent_id` 参数未实现过滤逻辑，检索结果为全量共享记忆池。
- **设计策略**：共享优先，所有智能体共用记忆池，但写入时携带 source 标签用于权限控制（如删除）。

## 4 Mem0 Provider 插件测试

### 4.1 插件工具清单

| 工具名 | 功能 | API 映射 |
|--------|------|----------|
| `mem0_search` | 增强搜索（分数过滤 + 关键词匹配） | `POST {apiUrl}/search` |
| `mem0_add` | 存储记忆（去重 + 验证 + 结构化数据） | `POST {apiUrl}/memories` |
| `mem0_delete` | 删除记忆 | `DELETE {apiUrl}/memories/{id}` |
| `mem0_update` | 更新记忆内容/元数据 | `PUT {apiUrl}/memories/{id}` |
| `mem0_list` | 列出记忆（支持 type/tag 过滤） | `GET {apiUrl}/memories` |

### 4.2 服务连接确认

检查 `mem0-provider` 容器日志：

```bash
docker logs 889d6b423dc4 2>&1 | grep -i mem0
```

输出示例：

```
[mem0-provider v2.0] Successfully connected to Mem0 API at http://172.30.0.6:8000
[mem0-provider] Write verified: memory added and fetched (id: 60af0073-5e6...)
```

说明插件已成功连接 Mem0 后端服务。

### 4.3 记忆添加与验证

```bash
curl -X POST http://172.30.0.6:8000/memories \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer mem0-admin-k3y-s3cur3-2026-x9k2m4p7q8" \
  -d '{
    "text": "用户偏好Java开发",
    "user_id": "openclaw_main",
    "agent_id": "main"
  }'
```

- 添加后插件自动执行写入验证（再次拉取该条记忆进行比对）。
- **去重机制**：如果待添加记忆与已有记忆的 Jaccard 相似度 ≥ 0.85，则跳过写入。

### 4.4 记忆搜索

```bash
curl -X POST http://172.30.0.6:8000/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ..." \
  -d '{"query":"Java", "limit":5}'
```

### 4.5 记忆更新

```bash
curl -X PUT http://172.30.0.6:8000/memories/{id} \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ..." \
  -d '{"text":"用户偏好Java和Python开发"}'
```

### 4.6 记忆列表与删除

列出记忆：

```bash
curl -X GET "http://172.30.0.6:8000/memories?type=preference&tag=programming" \
  -H "Authorization: Bearer ..."
```

删除记忆：

```bash
curl -X DELETE http://172.30.0.6:8000/memories/{id} \
  -H "Authorization: Bearer ..."
```

### 4.7 智能体隔离验证

`mem0-provider` 代码中内置了 `AGENT_MEM0_MAP` 映射表：

```
main → guanxing
assistant2 → zimo
assistant3 → tiangong
```

每一条记忆在写入时带有对应的 `agent_id`，检索时也根据 `agent_id` 过滤，因此实现了写入和检索的双重隔离。

## 5 常见问题排查

### 5.1 Mem0 后端连接失败

**现象**：日志显示 `localhost:11434` 连接被拒绝。

**原因**：`mem0-provider` 默认 `apiUrl` 为 `http://localhost:11434`，但实际 Mem0 服务运行在独立容器（`mem0-mem0-1:8000`）。

**解决方案**：

1. 确认 Mem0 服务所在容器的 IP 地址：
   ```bash
   docker inspect mem0-mem0-1 | grep IPAddress
   ```
2. 修改 `openclaw.json` 中的 `apiUrl` 为正确的地址，例如 `http://172.30.0.6:8000`。
3. 建议使用 Docker 服务名而非 IP：
   ```json
   "apiUrl": "http://mem0-mem0-1:8000"
   ```

### 5.2 统一记忆系统隔离失效

**现象**：`user_id` 和 `agent_id` 参数传入后检索结果无变化。

**根因**：`/retrieve` 端点的后端逻辑未对传入参数做过滤，执行的是全量向量搜索。

**临时方案**：

- 在应用层手动过滤结果，根据返回记忆中的 `source` 或 `user_id` 字段进行二次筛选。
- 如果熟悉后端代码，可修改检索逻辑，在向量查询时添加 `where` 过滤条件（例如 `user_id == $user_id`）。

### 5.3 性能优化建议

| 方向 | 建议 |
|------|------|
| **缓存** | `unified-memory` 已内置 30 秒结果缓存，可调整缓存时间。 |
| **去重** | `mem0-provider` 使用 Jaccard 相似度去重（阈值 0.85），可调整阈值。 |
| **批量操作** | `unified-memory` 支持批量删除（`DELETE /memory/batch`），减少请求次数。 |
| **健康检查** | 在插件启动后增加 Mem0 API 连通性检查，避免服务不可用时静默失败。 |

## 6 测试结果总览

| 功能 | unified-memory | mem0-provider |
|------|----------------|---------------|
| 增加（Create） | ✅ 可用 | ✅ 可用（含去重与验证） |
| 读取（Read） | ✅ 可用（检索+统计+画像） | ✅ 可用（搜索+列表） |
| 更新（Update） | ❌ 不支持（覆盖式存储） | ✅ 可用（PUT） |
| 删除（Delete） | ✅ 可用（单条+批量） | ✅ 可用（单条） |
| 批量操作 | ✅ 支持 | ❌ 逐条处理 |
| 隔离（检索） | ⚠️ 未生效（全局共享） | ✅ 按 agent_id 隔离 |
| 结构化数据 | ❌ 仅 tags 字符串 | ✅ type / tags / structuredData |
| 写入验证 | ❌ 无 | ✅ 写入后拉取对比 |
| 去重机制 | ❌ 无 | ✅ Jaccard 相似度 ≥ 0.85 跳过 |

## 7 总结

本教程完整演示了在容器环境中对两种记忆插件的测试流程。关键要点如下：

1. **连接配置**：确保插件 `apiUrl` 指向正确的后端地址（特别是跨容器通信时使用 Docker 网络 IP 或服务名）。
2. **隔离机制**：`unified-memory` 目前仅实现写入隔离，检索为全局共享；`mem0-provider` 提供了完整的接入隔离。
3. **功能完备性**：`mem0-provider` 在更新、去重、结构化数据方面更完善，而 `unified-memory` 的批量删除和内置缓存有优势。

根据实际业务需求，可以选择合适的记忆系统，或在同一项目中同时使用两者以互补功能。