# Memory Agents Lab 使用文档

本文档面向第一次运行本项目的使用者，说明如何启动 Web 应用、配置模型 API 和 Docker 基础设施。当前可验收的是 Text2Mem 与 ReMe；Mem0、Letta 和 memU 仅保留未启用适配器骨架。

项目目录：

```text
/memory-agents-web/
```

## 一、项目组成

```text
memory-agents-web/
├── backend/                 # FastAPI 后端和五种记忆适配器
├── frontend/                # Next.js Web 前端
├── infra/initdb/            # PostgreSQL 初始化脚本
├── docker-compose.yml       # PostgreSQL + pgvector + Redis
├── .env.example             # 后端和基础设施配置模板
└── 使用文档.md              # 本文档
```

当前项目是单工作区模式，不需要注册和登录。默认工作区标识为 `local-workspace`。

## 二、环境要求

基础运行环境：

- macOS、Linux 或 Windows + WSL；
- Docker Desktop；
- Docker Compose；
- Python 3.13（运行当前 ReMe 适配器）；
- Node.js 20+；
- npm；
- uv，推荐使用它创建 Python 虚拟环境。

只运行 Text2Mem 或基础 Web 界面时，Python 3.11 也可以；但按当前默认配置同时运行 ReMe 时，请统一使用 Python 3.13。

检查环境：

```bash
docker --version
docker compose version
python3 --version
node --version
npm --version
uv --version
```

## 三、配置文件

### 1. 创建后端配置文件

在项目根目录执行：

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

后端启动时会读取项目根目录下的 `.env`。

### 2. 根目录 `.env` 配置项

#### 项目运行配置

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

说明：

- `WORKSPACE_ID`：当前单工作区标识；不要在同一个数据库中随意改动，否则会看不到之前的记忆。
- `DATA_DIR`：本地文件型适配器和降级存储的数据目录。
- `DEMO_FALLBACK`：保留本地启动能力。真实框架没有安装时不会伪装成已接入，而是显示不可用状态。

#### OpenAI-compatible 模型 API

```dotenv
LLM_BASE_URL=https://api.openai.com/v1
LLM_API_KEY=你的模型API-Key
LLM_MODEL=gpt-4o-mini

EMBEDDING_BASE_URL=https://api.openai.com/v1
EMBEDDING_API_KEY=你的Embedding API-Key
EMBEDDING_MODEL=text-embedding-3-small
EMBEDDING_DIMENSIONS=1536
EMBEDDING_MIN_SCORE=0.35
```

当前 ReMe 第二阶段推荐使用通义千问 Embedding：

```dotenv
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
```

这组配置使用 OpenAI-compatible `/embeddings` 接口。也可以替换为其他兼容 OpenAI API 的 Embedding 服务。`EMBEDDING_MIN_SCORE` 控制项目 pgvector 结果进入回答证据的最低余弦相似度；`0.35` 是当前 `text-embedding-v4` 测试起点，更换模型后应重新标定。

如果只想先体验 Text2Mem，可以暂时不填写 `LLM_API_KEY`。此时 Text2Mem 会使用本地模式回答，并仍然记录记忆和审计事件。

项目启动时会把 `LLM_*` 配置同步给部分依赖 OpenAI 环境变量命名的 SDK。如果某个 SDK 使用特殊配置方式，应以该 SDK 当前版本文档为准。

#### Docker 基础设施连接

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

对应的 Docker 服务为：

| 服务 | 地址 | 用途 |
|---|---|---|
| PostgreSQL + pgvector | `localhost:54329` | 结构化记忆、向量扩展、审计数据 |
| Redis | `localhost:6379` | 缓存和异步任务基础设施 |

#### 可选框架配置

```dotenv
LETTA_BASE_URL=http://localhost:8283
LETTA_API_KEY=
LETTA_ENABLED=false

MEM0_ENABLED=false
REME_ENABLED=true
MEMU_ENABLED=false
```

当前只应保持 `REME_ENABLED=true`。Mem0、Letta 和 memU 即使安装了 SDK，也仍应保持关闭，直到各自的持久化、删除、重置和验收闭环补齐。

### 3. 前端配置文件

前端使用单独的配置文件：

```bash
cd frontend
cp .env.local.example .env.local
```

默认保持未设置：

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

未设置时，前端会在浏览器运行时使用当前页面的协议和主机名，动态组合 `:8000` 后端地址。只有后端使用不同主机或端口时才设置 `NEXT_PUBLIC_API_URL`；不要为局域网访问写死 `localhost` 或某个局域网 IP。

## 四、启动基础设施

回到项目根目录：

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

查看运行状态：

```bash
docker compose ps
```

正常情况下，两个服务都应显示 `healthy` 或 `running`。

检查 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 数据，只有在确认不需要历史记忆时使用。

## 五、启动 FastAPI 后端

### 推荐方式：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]'
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

后端地址：

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

如果已经创建过 `.venv-reme`，后续只需要：

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

### 精简方式：只运行 Text2Mem（Python 3.11+）

如果将 `.env` 中 `REME_ENABLED=false`，可以只安装基础依赖：

```bash
cd backend
uv venv --python 3.11 .venv
source .venv/bin/activate
uv pip install -e .
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

不要在一个已经安装大量旧版框架依赖的虚拟环境中强行混用不同 Python 版本要求。

## 六、启动 Next.js 前端

另开一个终端窗口：

```bash
cd "/memory-agents-web/frontend"
cp .env.local.example .env.local
npm install
npm run dev
```

本机打开：<http://localhost:3000>；局域网设备打开：`http://本机局域网IP:3000`。前端会在每次请求时根据当前页面动态计算同一主机的 `:8000` 后端地址；Next.js 开发服务器也会在启动时自动读取本机网卡地址，不需要写死局域网 IP。

前端页面包含：

- 五种记忆系统切换；
- AI 编程助手对话区；
- 当前系统状态；
- 当前记忆列表；
- 最近审计事件；
- 清空当前系统记忆按钮。

## 七、五种适配器状态

### 1. Text2Mem

Text2Mem 是本项目内置的教学型 IR 执行引擎，不需要额外安装 SDK。

在对话中发送类似内容：

```text
记住：我偏好使用 Python + FastAPI，数据库选 PostgreSQL。
```

系统会记录：

- `ENC/Encode` 写入操作；
- 记忆内容、来源和置信度；
- `RET/Retrieve` 检索操作；
- 审计事件。

当前还会将陈述分为 `semantic`、`episodic`、`procedural` 和 `task-state`，对完全重复的内容去重，并使用关键词、记忆类型与可选 Embedding 进行融合检索。“上次部署遇到了什么问题？”这类问句只检索，不会被误存为新记忆。

### 2. Mem0（后续项）

当前只有试验性 `add/search` 骨架，右侧记忆投影、单条删除、重置和冲突验收尚未完成。下列命令只用于后续开发，不表示当前已可用。

安装 SDK：

```bash
cd backend
source .venv-reme/bin/activate
uv pip install mem0ai
```

当前在根目录 `.env` 中保持关闭：

```dotenv
MEM0_ENABLED=false
```

Mem0 的模型、Embedding 和向量后端会随版本变化。后续补齐闭环时请先核对官方 Python Quickstart：<https://docs.mem0.ai/open-source/python-quickstart>。

### 3. Letta（后续项）

当前尚未完成 Agent ID 持久化、Core / Archival / Recall 投影和删除闭环。下列命令只用于后续开发。

安装客户端：

```bash
cd backend
source .venv-reme/bin/activate
uv pip install letta-client
```

启动目标版本的 Letta 服务端，并确认服务地址。例如：

```dotenv
LETTA_BASE_URL=http://localhost:8283
LETTA_API_KEY=
```

当前保持 `LETTA_ENABLED=false`，不会启动或调用 Letta。

Letta 的 Python 客户端文档：<https://docs.letta.com/api/python>。

注意：Letta 客户端和服务端需要版本匹配。如果服务端 API 变化，Web 端会显示调用错误，不会自动降级成假数据。

### 4. ReMe（当前启用）

当前适配器使用官方 SDK 依赖和 Python 3.13：

```bash
cd backend
source .venv-reme/bin/activate
uv pip install -e '.[reme]'
```

回到项目后启用：

```dotenv
REME_ENABLED=true
```

ReMe 会通过 `auto_memory` 将稳定偏好、项目事实、进度变化、可复用故障经验和长期流程规则写入 Markdown，再用 `reindex` 建立文件索引。ReMe 0.4.1.0 虽支持向量 + BM25/RRF，但本项目当前保持其内部 `embedding_store` 为空，实际使用查询改写、工程术语扩展和多查询 BM25；配置 Qwen Embedding 后，由项目的 pgvector 索引提供向量召回。两路结果去重后，模型只依据证据回答。官方仓库：<https://github.com/agentscope-ai/ReMe>。

适配器会使用文件型记忆，并将数据放在项目 `DATA_DIR` 对应目录下。

需要特别理解两点：

- ReMe 只对稳定偏好、项目事实、进度变化、可复用故障经验和长期流程规则运行 `auto_memory`；普通问句只检索。
- 右侧面板统计的是 Markdown 记忆文件数，不是原子事实数。一个文件可以合并多条对话事实；单条删除按钮实际删除整个文件并重建索引。
- ReMe 默认的后台文件监听、资源整理、摘要监听和 Dream 定时任务已关闭自动调度，避免无人操作时修改文件或产生模型成本；每次聊天仍会显式 `reindex`，扩展能力需另行接入对应 Job。

### 5. memU（后续项）

当前尚未完成后台队列、重试、预算、同意与候选记忆审批闭环。下列命令只用于后续开发。

memU 当前官方仓库要求较新的 Python 版本，建议使用 Python 3.13 虚拟环境。安装：

```bash
git clone https://github.com/NevaMind-AI/memU.git /tmp/memU
cd /tmp/memU
git rev-parse HEAD
uv pip install -e .
```

当前保持关闭：

```dotenv
MEMU_ENABLED=false
```

memU 官方仓库：<https://github.com/NevaMind-AI/memU>。

后续实现目标是只生成待审批的候选记忆，默认不向用户主动推送，也不自动执行高风险动作；这些尚不是当前可验收功能。

## 八、常用 API

```text
GET  /api/health
GET  /api/systems
POST /api/chat
GET  /api/memories?system=text2mem
DELETE /api/memories/{memory_id}?system=text2mem
GET  /api/audit?system=text2mem
POST /api/reset
```

聊天请求示例：

```bash
curl -X POST http://localhost:8000/api/chat \
  -H 'content-type: application/json' \
  -d '{
    "system": "text2mem",
    "message": "记住：项目使用 PostgreSQL 和 FastAPI"
  }'
```

## 九、测试和构建

后端：

```bash
cd backend
source .venv-reme/bin/activate
uv pip install "pytest>=8.3,<9" "pytest-asyncio>=0.25,<1" "ruff>=0.9,<1"
python -m pytest -q
ruff check app tests
python -m compileall -q app tests
```

前端：

```bash
cd frontend
npm run build
npm audit --omit=dev
```

## 十、常见问题

### 页面显示“后端尚未启动”

确认后端是否运行：

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

如果无法访问，请先启动 FastAPI。

### 页面显示 `postgres` 之外的存储模式

这表示后端连接 PostgreSQL 失败，暂时使用了本地 JSON 降级存储。请检查：

```bash
docker compose ps
docker compose logs postgres
```

并确认 `.env` 中的 `DATABASE_URL` 与 Docker 端口一致。

`/api/health` 会在降级时附带 `storage_error`。如果更换了 Embedding 向量维度，现有 `memory_embeddings` 表与新维度不一致也会触发降级；应先迁移或在确认无需历史数据后重建数据卷。

### 当前只有 Text2Mem 和 ReMe 可用

当前项目只启用 Text2Mem 和 ReMe；Mem0、Letta、memU 保持关闭。查看 `/api/systems` 可以获得具体 `setup_hint`。

### 模型 API 没有配置

Text2Mem 仍可使用本地证据模式，但不会调用外部模型。若要让模型生成自然语言回答，请填写 `LLM_API_KEY` 并重启后端；模型服务临时失败时，Text2Mem 也会自动退回本地证据模式，写入和检索仍可继续。

### ReMe 处理时间较长

ReMe 一轮写入会依次执行记忆提取、重建索引、可选向量同步、检索和证据回答，通常比 Text2Mem 慢。前端聊天请求允许最长 120 秒，删除和重置允许 60 秒；处理中不要重复发送同一条消息。如果超过时限，检查后端日志和模型服务延迟。

### 如何清空记忆

可以在 Web 页面点击“清空记忆”，也可以调用：

```bash
curl -X POST http://localhost:8000/api/reset \
  -H 'content-type: application/json' \
  -d '{"system":"text2mem"}'
```

如果要清空所有系统：

```bash
curl -X POST http://localhost:8000/api/reset \
  -H 'content-type: application/json' \
  -d '{}'
```

## 十一、安全提醒

- 不要把 `.env`、API Key、真实用户数据提交到 Git；
- 不要在公开网络直接暴露没有登录和权限控制的单工作区 Web 端；
- `docker compose down -v` 会删除本地数据库数据；
- 当前没有注册、登录和多租户隔离，只适合本地学习、演示和受控内网；
- 启用主动式记忆前，应先配置预算、频率限制、关闭开关和人工审批。