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 中的连接配置应与上面的本机端口一致：

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

2. 启动 Docker 服务

在项目根目录执行：

docker compose up -d
docker compose ps

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

检查 PostgreSQL 的 pgvector：

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

停止服务但保留数据：

docker compose down

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

docker compose down -v

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

二、本地后端服务

1. 后端需要配置什么

在项目根目录创建 .env：

cp .env.example .env

至少配置以下内容：

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：

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

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

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

3. 启动后端

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

后端地址：

检查后端：

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

期望结果中包含：

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

三、本地前端服务

1. 前端需要配置什么

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

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

默认保持空文件即可：

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

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

当前页面 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. 安装并启动前端

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

前端会监听 0.0.0.0:3000。

访问地址：

本机：http://localhost:3000
局域网：http://本机局域网IP:3000

四、完整启动顺序

建议打开三个终端窗口。

终端 1：启动 Docker：

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

终端 2：启动后端：

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

终端 3：启动前端：

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

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

五、停止本地服务

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

Docker 服务执行：

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

内部使用文档.md 5.0 KB Cronologia Originale