# Memory Agents Lab 内部使用文档

本文档只说明本项目内部开发环境的基础设施、后端和前端如何配置与启动。

当前运行方式：

- PostgreSQL、pgvector、Redis：Docker 启动；
- FastAPI 后端：本地启动；
- Next.js 前端：本地启动；
- 当前可用记忆系统：Text2Mem、ReMe；
- 当前为单工作区模式，不需要注册和登录。

## 一、Docker 基础设施

### 1. Docker 需要配置什么

项目使用根目录下的 `docker-compose.yml`，默认不需要修改。

| 服务 | 容器端口 | 本机端口 | 用途 |
|---|---:|---:|---|
| PostgreSQL + pgvector | 5432 | 54329 | 记忆、审计和向量数据 |
| Redis | 6379 | 6379 | 缓存和异步任务基础设施 |

后端 `.env` 中的连接配置应与上面的本机端口一致：

```dotenv
DATABASE_URL=postgresql://memory:memory@localhost:54329/memory_agents
REDIS_URL=redis://localhost:6379/0
```

### 2. 启动 Docker 服务

在项目根目录执行：

```bash
docker compose up -d
docker compose ps
```

正常状态：PostgreSQL 和 Redis 都显示 `healthy` 或 `running`。

检查 PostgreSQL 的 pgvector：

```bash
docker compose exec postgres \
  psql -U memory -d memory_agents \
  -c "SELECT extname FROM pg_extension WHERE extname = 'vector';"
```

停止服务但保留数据：

```bash
docker compose down
```

停止服务并删除数据库数据：

```bash
docker compose down -v
```

`docker compose down -v` 会删除 PostgreSQL 和 Redis 数据卷，请谨慎使用。

## 二、本地后端服务

### 1. 后端需要配置什么

在项目根目录创建 `.env`：

```bash
cp .env.example .env
```

至少配置以下内容：

```dotenv
APP_ENV=development
WORKSPACE_ID=local-workspace
DATA_DIR=./data
DEMO_FALLBACK=true

# DeepSeek 对话模型
LLM_BASE_URL=https://api.deepseek.com/v1
LLM_API_KEY=你的DeepSeek_API_Key
LLM_MODEL=deepseek-chat

# Qwen Embedding
EMBEDDING_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
EMBEDDING_API_KEY=你的DashScope_API_Key
EMBEDDING_MODEL=text-embedding-v4
EMBEDDING_DIMENSIONS=1536
EMBEDDING_MIN_SCORE=0.35

# Docker 服务
DATABASE_URL=postgresql://memory:memory@localhost:54329/memory_agents
REDIS_URL=redis://localhost:6379/0

# 当前启用状态
LETTA_ENABLED=false
MEM0_ENABLED=false
REME_ENABLED=true
MEMU_ENABLED=false
```

说明：

- `LLM_*` 用于自然语言回答和 ReMe 的记忆提取；
- `EMBEDDING_*` 用于 Text2Mem/ReMe 的向量召回；
- DeepSeek Chat API 不替代 Embedding API；
- `EMBEDDING_DIMENSIONS` 必须与 Embedding API 返回向量维度一致；
- 不要把真实 API Key 提交到 Git；
- `WORKSPACE_ID` 当前固定为 `local-workspace`，不要随意修改，否则可能看不到原有记忆。

### 2. 创建 Python 环境

当前 Text2Mem + ReMe 使用 Python 3.13：

```bash
cd "/memory-agents-web/backend"
uv venv --python 3.13 .venv-reme
source .venv-reme/bin/activate
uv pip install -e '.[reme]'
```

如果已经创建过环境，只需激活：

```bash
cd "/memory-agents-web/backend"
source .venv-reme/bin/activate
```

### 3. 启动后端

```bash
cd "/memory-agents-web/backend"
source .venv-reme/bin/activate
uvicorn app.main:app --host 0.0.0.0 --port 8000
```

后端地址：

- API：<http://localhost:8000>
- Swagger：<http://localhost:8000/docs>
- 健康检查：<http://localhost:8000/api/health>

检查后端：

```bash
curl http://localhost:8000/api/health
```

期望结果中包含：

```json
{
  "status": "ok",
  "storage": "postgres",
  "llm_configured": true,
  "embedding_configured": true
}
```

## 三、本地前端服务

### 1. 前端需要配置什么

前端配置文件为 `frontend/.env.local`：

```bash
cd "/memory-agents-web/frontend"
cp .env.local.example .env.local
```

默认保持空文件即可：

```dotenv
# NEXT_PUBLIC_API_URL=https://api.example.com
```

未设置 `NEXT_PUBLIC_API_URL` 时，前端会根据浏览器当前访问地址动态拼接后端地址：

```text
当前页面 http://localhost:3000       → 后端 http://localhost:8000
当前页面 http://192.168.x.x:3000     → 后端 http://192.168.x.x:8000
```

因此不要把 `localhost` 或某个固定局域网 IP 写入前端配置。只有后端与前端不在同一主机或使用不同端口时，才配置 `NEXT_PUBLIC_API_URL`。

### 2. 安装并启动前端

```bash
cd "/memory-agents-web/frontend"
npm install
npm run dev
```

前端会监听 `0.0.0.0:3000`。

访问地址：

- 本机：<http://localhost:3000>
- 局域网：`http://本机局域网IP:3000`

## 四、完整启动顺序

建议打开三个终端窗口。

终端 1：启动 Docker：

```bash
cd "/memory-agents-web"
docker compose up -d
```

终端 2：启动后端：

```bash
cd "/memory-agents-web/backend"
source .venv-reme/bin/activate
uvicorn app.main:app --host 0.0.0.0 --port 8000
```

终端 3：启动前端：

```bash
cd "/memory-agents-web/frontend"
npm run dev
```

最后打开：<http://localhost:3000>。

## 五、停止本地服务

前端和后端所在终端按 `Ctrl+C` 停止。

Docker 服务执行：

```bash
cd "/memory-agents-web"
docker compose down
```