openClaw_agent_dm/docs/MEM0_ARCHITECTURE.md

# mem0 记忆系统架构文档

> **已废弃 (Deprecated):** 本文档描述的是 v1.0 双 Collection (local + master) 架构，已于 2026-02-28 迁移至单库融合架构。
>
> **请参阅最新文档:**
> - 四层记忆架构: [`docs/MEMORY_ARCHITECTURE.md`](./MEMORY_ARCHITECTURE.md) (v2.1)
> - Skill 开发者指南: [`skills/mem0-integration/SKILL.md`](/root/.openclaw/workspace/skills/mem0-integration/SKILL.md)
>
> 本文件保留作为部署流程和故障排除的参考。基础设施部分（Docker、Tailscale、端口配置）仍然有效。

## 版本信息
- **文档版本**: 1.0.0 (已废弃)
- **创建日期**: 2026-02-22
- **最后更新**: 2026-02-22
- **部署环境**: Ubuntu 24.04 LTS, Docker 29.2.1

---

## 1. 系统架构

### 1.1 整体架构图

```
┌─────────────────────────────────────────────────────────────────┐
│                    Tailscale 虚拟内网                             │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │  中心节点 (vps-vaym)                                     │   │
│  │  Tailscale IP: 100.115.94.1                             │   │
│  │  节点名称：mem0-general-center                          │   │
│  │                                                          │   │
│  │  ┌──────────────────────────────────────────────────┐  │   │
│  │  │  Docker Compose Stack                             │  │   │
│  │  │  ┌──────────────┐  ┌──────────────┐              │  │   │
│  │  │  │  Qdrant      │  │  Dozzle      │              │  │   │
│  │  │  │  Master      │  │  (日志)      │              │  │   │
│  │  │  │  :6333       │  │  :9999       │              │  │   │
│  │  │  └──────────────┘  └──────────────┘              │  │   │
│  │  └──────────────────────────────────────────────────┘  │   │
│  │                                                          │   │
│  │  ┌──────────────────────────────────────────────────┐  │   │
│  │  │  OpenClaw + mem0 Integration                      │  │   │
│  │  │  Gateway: 18789                                   │  │   │
│  │  │  Skill: mem0-integration                          │  │   │
│  │  └──────────────────────────────────────────────────┘  │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
│  未来扩展：                                                      │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐         │
│  │  Agent-1     │  │  Agent-2     │  │  Agent-N     │         │
│  │  (crypto)    │  │  (advert)    │  │  (life)      │         │
│  │  100.64.x.x  │  │  100.64.x.x  │  │  100.64.x.x  │         │
│  └──────────────┘  └──────────────┘  └──────────────┘         │
└─────────────────────────────────────────────────────────────────┘
```

### 1.2 技术栈

| 组件 | 技术 | 版本 | 用途 |
|------|------|------|------|
| **组网** | Tailscale | 1.94.2 | 虚拟内网，安全通信 |
| **向量数据库** | Qdrant | 1.15.3 | 记忆存储和检索 |
| **记忆系统** | mem0 | 1.0.4 | 记忆管理层 |
| **LLM** | DashScope (Qwen) | - | 记忆处理和 embedding |
| **容器** | Docker | 29.2.1 | 服务隔离 |
| **日志** | Dozzle | latest | 实时日志查看 |

### 1.3 数据流

```
用户 → OpenClaw → mem0 Client → Qdrant Local → (异步同步) → Qdrant Master
                      ↓
                  DashScope API (Embedding + LLM)
```

---

## 2. 部署清单

### 2.1 中心节点 (vps-vaym)

**已安装服务**：
- ✅ Tailscale (系统级)
- ✅ Qdrant Master (Docker)
- ✅ Dozzle (Docker)
- ✅ mem0 Integration (OpenClaw Skill)

**目录结构**：
```
/opt/mem0-center/
├── docker-compose.yml      # Docker 配置
├── .env                    # 环境变量
├── qdrant_storage/         # Qdrant 数据
├── snapshots/              # Qdrant 快照
├── tailscale/              # Tailscale 状态
├── logs/                   # 日志
└── backup/                 # 备份

/root/.openclaw/workspace/
├── scripts/                # 部署脚本
│   ├── 01-system-check.sh
│   ├── 02-install-tailscale.sh
│   ├── 03-create-directories.sh
│   ├── 05-start-center.sh
│   ├── 06-create-mem0-skill.sh
│   ├── 07-install-dependencies.sh
│   ├── 10-create-backup.sh
│   └── 12-monitoring.sh
├── skills/mem0-integration/
│   ├── SKILL.md
│   ├── skill.json
│   ├── config.yaml
│   ├── mem0_client.py
│   ├── commands.py
│   └── openclaw_commands.py
├── docs/
│   └── MEM0_DEPLOYMENT.md
└── backup/                 # 备份文件
```

### 2.2 网络配置

**Tailscale**：
- 网络名称：mem0-general-center
- 业务类型：general
- 节点角色：center
- IP 地址：100.115.94.1

**端口映射**：
| 服务 | 容器端口 | 主机端口 | 访问范围 |
|------|---------|---------|---------|
| Qdrant | 6333 | 127.0.0.1:6333 | 仅本地 + Tailscale |
| Dozzle | 8080 | 127.0.0.1:9999 | 仅本地 + Tailscale |
| OpenClaw | 18789 | 18789 | 本地 |

---

## 3. 配置详情

### 3.1 Docker Compose 配置

文件：`/opt/mem0-center/docker-compose.yml`

```yaml
version: '3.8'
services:
  qdrant-master:
    image: qdrant/qdrant:v1.15.3
    ports:
      - "127.0.0.1:6333:6333"
    volumes:
      - ./qdrant_storage:/qdrant/storage
      - ./snapshots:/qdrant/snapshots
    environment:
      - QDRANT__SERVICE__HTTP_PORT=6333
      - QDRANT__LOG_LEVEL=INFO
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "wget", "-q", "--spider", "http://localhost:6333/"]
      interval: 30s
      timeout: 10s
      retries: 3
    deploy:
      resources:
        limits:
          memory: 2G
          cpus: '1.0'

  dozzle:
    image: amir20/dozzle:latest
    ports:
      - "127.0.0.1:9999:8080"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    restart: unless-stopped
```

### 3.2 mem0 配置

文件：`/root/.openclaw/workspace/skills/mem0-integration/config.yaml`

```yaml
local:
  vector_store:
    provider: qdrant
    config:
      host: localhost
      port: 6333
      collection_name: mem0_local
  
  llm:
    provider: openai
    config:
      model: qwen-plus
      api_base: https://dashscope.aliyuncs.com/compatible-mode/v1
  
  embedder:
    provider: openai
    config:
      model: text-embedding-v3
      api_base: https://dashscope.aliyuncs.com/compatible-mode/v1

master:
  vector_store:
    provider: qdrant
    config:
      host: 100.115.94.1  # Tailscale IP
      port: 6333
      collection_name: mem0_shared
```

### 3.3 环境变量

文件：`/opt/mem0-center/.env`

```bash
TS_AUTHKEY=tskey-auth-xxx
QDRANT_PORT=6333
MEM0_DASHSCOPE_API_KEY=sk-xxx
MEM0_LLM_MODEL=qwen-plus
BUSINESS_TYPE=general
NODE_ROLE=center
NODE_NAME=mem0-general-center
```

---

## 4. 使用指南

### 4.1 部署流程

**步骤 1：系统检查**
```bash
./scripts/01-system-check.sh
```

**步骤 2：安装 Tailscale**
```bash
./scripts/02-install-tailscale.sh
# 访问 https://login.tailscale.com/admin/machines 确认上线
```

**步骤 3：创建目录**
```bash
./scripts/03-create-directories.sh
```

**步骤 4：启动服务**
```bash
./scripts/05-start-center.sh
# 验证：curl http://localhost:6333/
```

**步骤 5：安装 mem0 Skill**
```bash
./scripts/06-create-mem0-skill.sh
./scripts/07-install-dependencies.sh
```

**步骤 6：测试**
```bash
python3 /root/.openclaw/workspace/skills/mem0-integration/mem0_client.py
```

### 4.2 日常管理

**查看服务状态**：
```bash
cd /opt/mem0-center && docker compose ps
```

**查看日志**：
```bash
# Dozzle Web UI
http://100.115.94.1:9999

# 命令行
cd /opt/mem0-center && docker compose logs -f
```

**监控系统**：
```bash
./scripts/12-monitoring.sh
```

**创建备份**：
```bash
./scripts/10-create-backup.sh
```

### 4.3 OpenClaw 命令

通过 Telegram 使用：

```
/memory add <内容>       # 添加记忆
/memory search <关键词>   # 搜索记忆
/memory list             # 列出所有记忆
/memory delete <ID>      # 删除记忆
/memory status           # 查看状态
```

---

## 5. 故障排除

### 5.1 Qdrant 无法启动

**症状**：`docker compose ps` 显示 qdrant-master 为 unhealthy

**解决**：
```bash
# 查看日志
docker compose logs qdrant-master

# 检查端口占用
netstat -tlnp | grep 6333

# 重启服务
docker compose restart qdrant-master
```

### 5.2 mem0 初始化失败

**症状**：`mem0_client.py` 报错

**解决**：
```bash
# 检查环境变量
export OPENAI_API_KEY="sk-xxx"
export OPENAI_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"

# 测试导入
python3 -c "from mem0 import Memory; print('OK')"

# 检查 Qdrant 连接
curl http://localhost:6333/
```

### 5.3 Tailscale 断开

**症状**：`tailscale status` 显示 offline

**解决**：
```bash
# 重新认证
tailscale up --authkey=tskey-auth-xxx

# 检查服务状态
systemctl status tailscaled
```

---

## 6. 扩展部署

### 6.1 部署新 Agent 节点

**在新节点执行**：

1. 安装 Tailscale
```bash
curl -fsSL https://tailscale.com/install.sh | sh
tailscale up --authkey=tskey-auth-xxx --hostname=mem0-general-agent-01
```

2. 部署 Agent（文档待补充）

### 6.2 业务类型扩展

命名规范：
- `mem0-general-center` - 通用业务（当前）
- `mem0-crypto-center` - 加密货币业务
- `mem0-advert-center` - 广告业务
- `mem0-life-center` - 生活业务

---

## 7. 安全配置

### 7.1 访问控制

- **Tailscale 内网**：所有服务仅通过 Tailscale IP 访问
- **端口绑定**：仅绑定 127.0.0.1，不暴露公网
- **API Key 管理**：存储在 .env 文件，权限 600

### 7.2 数据加密

- **Tailscale**：端到端加密
- **Qdrant**：支持 TLS（可选配置）
- **备份**：建议加密存储

---

## 8. 性能优化

### 8.1 资源限制

```yaml
# Docker Compose
deploy:
  resources:
    limits:
      memory: 2G
      cpus: '1.0'
```

### 8.2 缓存配置

```yaml
# mem0 config
cache:
  enabled: true
  ttl: 300  # 5 分钟
  max_size: 1000
```

---

## 9. 变更日志

### v1.0.0 (2026-02-22)
- ✅ 初始部署
- ✅ 中心节点搭建完成
- ✅ mem0 Integration 完成
- ✅ 文档创建

---

## 10. 联系方式

- **Tailscale 管理**：https://login.tailscale.com/admin
- **mem0 文档**：https://docs.mem0.ai
- **Qdrant 文档**：https://qdrant.tech/documentation
- **OpenClaw 文档**：/root/.openclaw/workspace/docs