# 青龙部署 MemOS 自托管版方案

> 版本: v1.0
> 创建日期: 2026-02-07
> 适用节点: 青龙 (1号机, 192.168.0.31)
> 目标: 为 OpenClaw 集成 MemOS 记忆系统

---

## 📋 目录

1. [概述](#概述)
2. [环境准备](#环境准备)
3. [数据库部署](#数据库部署)
4. [MemOS 安装](#memos-安装)
5. [配置集成](#配置集成)
6. [OpenClaw 插件](#openclaw-插件)
7. [验证测试](#验证测试)
8. [故障排查](#故障排查)

---

## 一、概述

### 1.1 目标

在青龙 (192.168.0.31) 上部署 MemOS 自托管版，为 OpenClaw 提供记忆能力。

### 1.2 架构

```
┌─────────────────────────────────────────────────────────────┐
│                      青龙 (192.168.0.31)                      │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   ┌─────────────────────────────────────────────────┐      │
│   │               MemOS Server                      │      │
│   │  ┌─────────┐  ┌─────────┐  ┌─────────────┐    │      │
│   │  │  Neo4j  │  │ Qdrant  │  │  FastAPI    │    │      │
│   │  │ (图数据库)│  │(向量数据库)│  │  API 服务   │    │      │
│   │  └─────────┘  └─────────┘  └─────────────┘    │      │
│   └─────────────────────────────────────────────────┘      │
│                          │                                  │
│                          ▼                                  │
│   ┌─────────────────────────────────────────────────┐      │
│   │               OpenClaw Gateway                  │      │
│   │  ┌─────────────────────────────────────────┐    │      │
│   │  │  MemOS Cloud OpenClaw Plugin            │    │      │
│   │  │  - 启动前召回上下文                      │    │      │
│   │  │  - 结束后保存记忆                       │    │      │
│   │  └─────────────────────────────────────────┘    │      │
│   └─────────────────────────────────────────────────┘      │
│                                                             │
│   ┌─────────────────────────────────────────────────┐      │
│   │               现有服务                            │      │
│   │  - MiniMax/DeepSeek (LLM)                       │      │
│   │  - nomic-embed-text (Embedding)                 │      │
│   └─────────────────────────────────────────────────┘      │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

### 1.3 资源需求

| 组件 | CPU | 内存 | 存储 | 说明 |
|------|-----|------|------|------|
| Neo4j | 1 核 | 2GB | 10GB | 图数据库 |
| Qdrant | 1 核 | 1GB | 5GB | 向量数据库 |
| MemOS | 1 核 | 1GB | 1GB | API 服务 |
| **总计** | **2 核** | **4GB** | **16GB** | 青龙可满足 |

---

## 二、环境准备

### 2.1 SSH 连接

```bash
# 从 2号机 连接青龙
sshpass -p '3efvVGY&' ssh root@192.168.0.31

# 或直接登录
ssh root@192.168.0.31
```

### 2.2 系统检查

```bash
# 1. 检查系统版本
cat /etc/os-release

# 2. 检查 Docker
docker --version
docker-compose --version

# 3. 检查内存
free -h

# 4. 检查磁盘
df -h

# 5. 检查 CPU
lscpu | grep "CPU(s)"
```

### 2.3 安装 Docker (如未安装)

```bash
# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y apt-transport-https ca-certificates curl software-properties-common

# 添加 Docker 官方 GPG 密钥
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# 添加 Docker 仓库
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 安装 Docker
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# 启动 Docker
sudo systemctl start docker
sudo systemctl enable docker

# 添加当前用户到 docker 组 (免 sudo)
sudo usermod -aG docker $USER
```

### 2.4 创建目录结构

```bash
# 创建部署目录
sudo mkdir -p /opt/memos
sudo chown -R $USER:$USER /opt/memos

cd /opt/memos

# 创建数据目录
mkdir -p data/neo4j
mkdir -p data/qdrant
mkdir -p logs

# 创建配置目录
mkdir -p config
```

---

## 三、数据库部署

### 3.1 使用 Docker 部署

#### 3.1.1 创建 Docker Compose 配置

```bash
# 创建 docker-compose.yml
cat > /opt/memos/docker-compose.yml << 'EOF'
version: '3.8'

services:
  # Neo4j 图数据库
  neo4j:
    image: neo4j:5.12
    container_name: memos-neo4j
    restart: unless-stopped
    ports:
      - "7474:7474"
      - "7687:7687"
    environment:
      NEO4J_AUTH: neo4j/memos_password
      NEO4J_PLUGINS: ["apoc", "graph-data-science"]
      NEO4J_dbms_memory_heap_initial__size: 512m
      NEO4J_dbms_memory_heap_max__size: 2g
      NEO4J_dbms_tx__log__rotation_rotation__keep__number: 10
    volumes:
      - ./data/neo4j/data:/data
      - ./data/neo4j/logs:/logs
      - ./data/neo4j/import:/var/lib/neo4j/import
    networks:
      - memos-network
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:7474"]
      interval: 30s
      timeout: 10s
      retries: 5

  # Qdrant 向量数据库
  qdrant:
    image: qdrant/qdrant:v1.7.0
    container_name: memos-qdrant
    restart: unless-stopped
    ports:
      - "6333:6333"
      - "6334:6334"
    environment:
      QDRANT__SERVICE__API_PORT: 6333
      QDRANT__STORAGE__STORAGE_PATH: /qdrant/storage
    volumes:
      - ./data/qdrant:/qdrant/storage
    networks:
      - memos-network
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:6333/dashboard"]
      interval: 30s
      timeout: 10s
      retries: 5

networks:
  memos-network:
    driver: bridge
EOF
```

#### 3.1.2 启动数据库

```bash
cd /opt/memos

# 启动服务
docker compose up -d

# 查看启动状态
docker compose ps

# 查看日志
docker compose logs -f
```

#### 3.1.3 验证数据库

```bash
# 1. 检查 Neo4j
curl -u neo4j:memos_password http://localhost:7474

# 2. 检查 Qdrant
curl http://localhost:6333/dashboard

# 3. 检查健康状态
docker compose exec neo4j cypher-query "RETURN 1"
```

### 3.2 数据库连接信息

| 数据库 | 地址 | 端口 | 用户名 | 密码 |
|--------|------|------|--------|------|
| Neo4j | localhost | 7474/7687 | neo4j | memos_password |
| Qdrant | localhost | 6333 | - | - |

---

## 四、MemOS 安装

### 4.1 安装依赖

```bash
# 安装 Python 3.11+
sudo apt install -y python3.11 python3.11-venv python3-pip

# 创建虚拟环境
python3.11 -m venv /opt/memos/venv
source /opt/memos/venv/bin/activate

# 升级 pip
pip install --upgrade pip

# 安装 MemOS
cd /opt/memos
git clone https://github.com/MemTensor/MemOS.git
cd MemOS
pip install -e .

# 安装额外依赖
pip install pymemgraph  # Neo4j driver
pip install fastapi uvicorn
```

### 4.2 环境变量配置

```bash
# 创建 .env 文件
cat > /opt/memos/.env << 'EOF'
# MemOS 配置
MEMOS_MODE=self_hosted

# Neo4j 配置
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=memos_password

# Qdrant 配置
QDRANT_URL=http://localhost:6333

# LLM 配置 (使用现有资源)
# 方案1: 使用 OpenAI
OPENAI_API_KEY=your_openai_api_key

# 方案2: 使用阿里百炼 (推荐)
DASHSCOPE_API_KEY=your_dashscope_api_key

# Embedding 配置 (使用现有资源)
# 方案1: 使用 OpenAI
OPENAI_EMBEDDING_API_KEY=your_openai_embedding_api_key

# 方案2: 使用 Voyage AI
VOYAGE_API_KEY=your_voyage_api_key

# 方案3: 使用本地 embedding (nomic-embed-text)
EMBEDDING_PROVIDER=ollama
EMBEDDING_BASE_URL=http://localhost:11434/v1
EMBEDDING_MODEL=nomic-embed-text:latest

# 日志配置
LOG_LEVEL=INFO
EOF

# 应用环境变量
source /opt/memos/.env
```

### 4.3 创建启动脚本

```bash
# 创建启动脚本
cat > /opt/memos/start.sh << 'EOF'
#!/bin/bash

# 激活虚拟环境
source /opt/memos/venv/bin/activate
source /opt/memos/.env

# 设置工作目录
cd /opt/memos/MemOS/src

# 启动 MemOS API 服务
echo "Starting MemOS API Server..."
uvicorn memos.api.server_api:app \
  --host 0.0.0.0 \
  --port 8001 \
  --workers 4 \
  --reload \
  >> /opt/memos/logs/memos.log 2>&1 &

echo "MemOS started on http://localhost:8001"
echo "Dashboard: http://localhost:8001/docs"
EOF

chmod +x /opt/memos/start.sh
```

### 4.4 创建 systemd 服务

```bash
# 创建 systemd 服务文件
sudo cat > /etc/systemd/system/memos.service << 'EOF'
[Unit]
Description=MemOS Memory Operating System
After=network.target docker.service
Requires=docker.service

[Service]
Type=simple
User=root
WorkingDirectory=/opt/memos
ExecStart=/opt/memos/start.sh
ExecReload=/bin/kill -HUP $MAINPID
Restart=always
RestartSec=10
Environment="PATH=/opt/memos/venv/bin"
EnvironmentFile=/opt/memos/.env

# 日志
StandardOutput=append:/opt/memos/logs/memos-system.log
StandardError=append:/opt/memos/logs/memos-error.log

[Install]
WantedBy=multi-user.target
EOF

# 重新加载 systemd
sudo systemctl daemon-reload

# 启用服务
sudo systemctl enable memos

# 启动服务
sudo systemctl start memos

# 检查状态
sudo systemctl status memos
```

---

## 五、配置集成

### 5.1 配置本地 Embedding

如果使用本地 nomic-embed-text：

```bash
# 1. 确保 Ollama 运行
curl http://localhost:11434/api/version

# 2. 拉取 embedding 模型
ollama pull nomic-embed-text:latest

# 3. 验证模型
ollama list
```

### 5.2 配置 LLM

#### 方案1: 使用阿里百炼 (推荐)

```bash
# 在 .env 中配置
DASHSCOPE_API_KEY=your_api_key
DASHSCOPE_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1

# 可用模型:
# - qwen3-max
# - qwen3-plus
# - qwen-turbo
```

#### 方案2: 使用 OpenAI

```bash
# 在 .env 中配置
OPENAI_API_KEY=your_api_key
OPENAI_BASE_URL=https://api.openai.com/v1

# 可用模型:
# - gpt-4
# - gpt-4-turbo
# - gpt-3.5-turbo
```

---

## 六、OpenClaw 插件

### 6.1 安装 MemOS Cloud OpenClaw 插件

MemOS 官方提供 OpenClaw 插件，可以自动管理记忆：

```bash
# 1. 克隆插件仓库
cd /opt/memos
git clone https://github.com/MemTensor/MemOS-Cloud-OpenClaw-Plugin.git
cd MemOS-Cloud-OpenClaw-Plugin

# 2. 安装依赖
pip install -r requirements.txt
```

### 6.2 插件配置

```bash
# 创建配置
cat > /opt/memos/openclaw-plugin/config.yaml << 'EOF'
# MemOS OpenClaw Plugin 配置

# MemOS 连接配置
memos:
  api_url: http://localhost:8001  # MemOS API 地址
  api_key: ""  # 自托管不需要 key，空字符串

# 用户配置
user:
  default_id: "yh6788"  # 默认用户 ID
  mem_cube_id: "default"  # 默认记忆立方体

# 行为配置
behavior:
  # 启动时召回多少条记忆
  recall_limit: 20
  
  # 保存记忆的触发条件
  save_triggers:
    - "对话结束"
    - "关键信息提取"
    - "用户明确要求保存"
  
  # 自动提取的主题
  auto_extract_topics:
    - "用户偏好"
    - "工作内容"
    - "学习进度"
    - "项目状态"

# 日志配置
logging:
  level: INFO
  file: /opt/memos/logs/openclaw-plugin.log
EOF
```

### 6.3 插件工作流程

```
┌─────────────────────────────────────────────────────────────┐
│                    MemOS OpenClaw Plugin                    │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   OpenClaw 启动                                              │
│        │                                                     │
│        ▼                                                     │
│   ┌─────────────────────────────────┐                      │
│   │  1. ON_LAUNCH                   │                      │
│   │     - 从 MemOS 召回上下文        │                      │
│   │     - 加载用户偏好              │                      │
│   │     - 加载会话历史              │                      │
│   └─────────────────────────────────┘                      │
│                      │                                       │
│                      ▼                                       │
│   ┌─────────────────────────────────┐                      │
│   │  2. ON_MESSAGE                  │                      │
│   │     - 监控对话内容              │                      │
│   │     - 提取关键信息              │                      │
│   │     - 更新记忆                  │                      │
│   └─────────────────────────────────┘                      │
│                      │                                       │
│                      ▼                                       │
│   ┌─────────────────────────────────┐                      │
│   │  3. ON_TERMINATE                │                      │
│   │     - 保存完整对话              │                      │
│   │     - 更新用户画像              │                      │
│   │     - 生成摘要                  │                      │
│   └─────────────────────────────────┘                      │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

---

## 七、验证测试

### 7.1 检查服务状态

```bash
# 1. 检查 Docker 服务
docker compose ps

# 2. 检查 MemOS 进程
ps aux | grep uvicorn

# 3. 检查端口监听
netstat -tlnp | grep -E "7474|7687|6333|8001"

# 4. 检查 systemd 服务
systemctl status memos
```

### 7.2 API 测试

```bash
# 1. 测试 MemOS 健康检查
curl http://localhost:8001/health

# 2. 测试 API 文档
curl http://localhost:8001/docs

# 3. 添加测试记忆
curl -X POST http://localhost:8001/product/add \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "test_user",
    "mem_cube_id": "default",
    "messages": [{"role": "user", "content": "I like programming with Python"}],
    "async_mode": "sync"
  }'

# 4. 搜索测试记忆
curl -X POST http://localhost:8001/product/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What do I like",
    "user_id": "test_user",
    "mem_cube_id": "default"
  }'
```

### 7.3 OpenClaw 集成测试

```bash
# 1. 检查插件是否加载
cat /opt/memos/logs/openclaw-plugin.log

# 2. 测试插件与 MemOS 连接
python -c "
import requests
import json

# 测试连接
resp = requests.get('http://localhost:8001/health')
print(f'MemOS Status: {resp.status_code}')

# 测试添加记忆
data = {
    'user_id': 'yh6788',
    'mem_cube_id': 'default',
    'messages': [{'role': 'user', 'content': 'Test memory from OpenClaw'}],
    'async_mode': 'sync'
}
resp = requests.post('http://localhost:8001/product/add', json=data)
print(f'Add Memory: {resp.status_code}')
print(json.dumps(resp.json(), indent=2))
"
```

---

## 八、故障排查

### 8.1 常见问题

#### Q1: Neo4j 连接失败

```bash
# 检查 Neo4j 日志
docker logs memos-neo4j --tail 100

# 检查 Neo4j 是否就绪
curl -u neo4j:memos_password http://localhost:7474

# 重启 Neo4j
docker restart memos-neo4j
```

#### Q2: Qdrant 连接失败

```bash
# 检查 Qdrant 日志
docker logs memos-qdrant --tail 100

# 检查 Qdrant 健康
curl http://localhost:6333/dashboard

# 重启 Qdrant
docker restart memos-qdrant
```

#### Q3: MemOS 启动失败

```bash
# 查看 MemOS 日志
tail -f /opt/memos/logs/memos.log

# 检查虚拟环境
source /opt/memos/venv/bin/activate
which python
python --version

# 检查依赖
pip list | grep memos
```

#### Q4: API 返回错误

```bash
# 检查 API 响应
curl -v http://localhost:8001/health

# 检查配置
cat /opt/memos/.env | grep -E "NEO4J|QDRANT|API"
```

### 8.2 日志位置

| 组件 | 日志位置 |
|------|----------|
| MemOS 主日志 | `/opt/memos/logs/memos.log` |
| MemOS 系统日志 | `/opt/memos/logs/memos-system.log` |
| MemOS 错误日志 | `/opt/memos/logs/memos-error.log` |
| Neo4j 日志 | `docker logs memos-neo4j` |
| Qdrant 日志 | `docker logs memos-qdrant` |
| OpenClaw 插件 | `/opt/memos/logs/openclaw-plugin.log` |

### 8.3 常用命令

```bash
# 重启所有服务
cd /opt/memos
docker compose restart
systemctl restart memos

# 查看所有日志
tail -f /opt/memos/logs/memos.log

# 停止所有服务
cd /opt/memos
docker compose down
systemctl stop memos

# 完全重置 (危险!)
cd /opt/memos
docker compose down -v
rm -rf data/
docker compose up -d
```

---

## 九、性能优化

### 9.1 Neo4j 优化

```bash
# 在 docker-compose.yml 中调整
neo4j:
  environment:
    NEO4J_dbms_memory_heap_initial__size: 1g
    NEO4J_dbms_memory_heap_max__size: 4g
    NEO4J_dbms_transaction_log_rotation_rotation__keep__number: 50
```

### 9.2 Qdrant 优化

```bash
# 在 docker-compose.yml 中配置
qdrant:
  environment:
    QDRANT__SERVICE__HTTP_PORT: 6333
    QDRANT__SERVICE__GRPC_PORT: 6334
    QDRANT__STORAGE__PERFORMANCE__MAX_SCORING_THREADS: 4
```

### 9.3 MemOS 优化

```bash
# 调整 uvicorn workers
# 单机部署建议: CPU核心数 - 1
workers = 3  # 4核CPU
```

---

## 十、备份与恢复

### 10.1 备份策略

```bash
# 创建备份脚本
cat > /opt/memos/backup.sh << 'EOF'
#!/bin/bash

BACKUP_DIR=/opt/memos/backups
DATE=$(date +%Y%m%d_%H%M%S)

mkdir -p $BACKUP_DIR

# 1. 备份 Neo4j
echo "Backing up Neo4j..."
docker exec memos-neo4j neo4j-admin dump --database=neo4j --to=/backups/neo4j_$DATE.dump

# 2. 备份 Qdrant
echo "Backing up Qdrant..."
docker exec memos-qdrant tar czf /backups/qdrant_$DATE.tar.gz -C /qdrant/storage .

# 3. 备份 MemOS 配置
echo "Backing up MemOS config..."
tar czf $BACKUP_DIR/memos_config_$DATE.tar.gz /opt/memos/.env /opt/memos/config/

echo "Backup completed: $DATE"
EOF

chmod +x /opt/memos/backup.sh

# 添加定时任务 (每天凌晨 3 点执行)
(crontab -l 2>/dev/null || echo "") | grep -v "backup.sh" > /tmp/crontab.tmp
echo "0 3 * * * /opt/memos/backup.sh" >> /tmp/crontab.tmp
crontab /tmp/crontab.tmp
rm /tmp/crontab.tmp
```

### 10.2 恢复脚本

```bash
# 创建恢复脚本
cat > /opt/memos/restore.sh << 'EOF'
#!/bin/bash

BACKUP_FILE=$1

if [ -z "$BACKUP_FILE" ]; then
  echo "Usage: $0 <backup_file.tar.gz>"
  exit 1
fi

# 停止服务
cd /opt/memos
docker compose down
systemctl stop memos

# 恢复 Neo4j
docker exec -i memos-neo4j neo4j-admin load --from=- --database=neo4j --force

# 恢复 Qdrant
docker exec -i memos-qdrant tar xzf /backups/qdrant_latest.tar.gz -C /qdrant/storage

# 重启服务
docker compose up -d
systemctl start memos

echo "Restore completed"
EOF
```

---

## 十一、总结

### 11.1 部署清单

| 步骤 | 操作 | 状态 |
|------|------|------|
| 1 | SSH 连接青龙 | ☐ |
| 2 | 安装 Docker | ☐ |
| 3 | 部署 Neo4j + Qdrant | ☐ |
| 4 | 安装 MemOS | ☐ |
| 5 | 配置 LLM + Embedding | ☐ |
| 6 | 配置 OpenClaw 插件 | ☐ |
| 7 | 验证测试 | ☐ |
| 8 | 配置备份 | ☐ |

### 11.2 下一步

1. **测试阶段** (1-2天)
   - 测试云端版 MemOS (快速验证)
   - 评估功能和性能

2. **部署阶段** (1周)
   - 按本文档在青龙部署
   - 集成 OpenClaw 插件

3. **优化阶段** (持续)
   - 性能调优
   - 备份策略
   - 监控告警

---

*文档版本: v1.0 (2026-02-07)*
*作者: 2号机 (守护者)*