Mem0 自托管 REST 服务器（server/）工程指南：Docker-only 的 FastAPI、pgvector 与热重载开发栈

本文以 server/AGENTS.md 为核心骨架，系统讲解 Mem0 自托管服务器的定位、命令体系、端口规划与工程约定，并结合 server/Makefile、server/docker-compose.yaml、server/dev.Dockerfile 与 server/main.py 的源码证据，还原"生产镜像构建 + Compose 开发栈热重载"两条路径的完整实现细节。读完后，你可以直接在 Docker 中构建、运行和调试这套 REST 服务，并理解其热重载、密钥管理、默认配置与请求日志的底层机制。

一、定位：Docker-only 的 Python SDK REST 封装

server/ 目录提供的是一个自托管 FastAPI REST 服务器，其本质是对仓库中 Python SDK（mem0/ 包）的 HTTP 封装。server/AGENTS.md 开篇即给出两条强约束：

1. Docker only——"Docker only; there is no local non-Docker path"，即不存在绕过 Docker 的本地运行路径，任何"直接用 uvicorn 跑"的方案都不应引入；
2. SDK 约定继承——服务器从仓库导入 Python SDK 代码，因此凡是触及 SDK 代码，都须遵守 mem0/AGENTS.md 中的约定。

从源码结构看，这种"封装"关系体现在 server/main.py 与 server/server_state.py：所有 /memories、/search 等端点最终都通过 get_memory_instance() 调用 SDK 的 Memory 实例，REST 层只负责鉴权、参数校验、请求日志与错误映射，记忆提取与向量存储逻辑完全复用 SDK。

二、命令体系：两条路径的构建与运行

server/AGENTS.md 给出了四组核心命令，它们在 server/Makefile 中都有对应 target，可直接复制执行：

# 生产镜像
make build        # docker build -t mem0-api-server .
make run_local    # docker run -p 8000:8000 with .env

# 开发栈（FastAPI + PostgreSQL/pgvector + Neo4j）
docker-compose up

2.1 生产镜像：make build 与 make run_local

对照 server/Makefile#L58-L62：

build:
	docker build -t mem0-api-server .

run_local:
	docker run -p 8000:8000 -v $(shell pwd):/app mem0-api-server --env-file .env

生产镜像由 server/Dockerfile 构建，基于 python:3.12-slim，以 pip install --no-cache-dir -r requirements.txt 安装依赖，EXPOSE 8000，入口为 uvicorn main:app --host 0.0.0.0 --port 8000。注意 run_local 通过 --env-file .env 传入环境变量并挂载当前目录，因此运行前需准备 server/.env.example 描述的 .env 文件（见第五节）。

2.2 开发栈：docker compose up

开发栈由 server/docker-compose.yaml 定义，定义了三服务：mem0（API）、postgres（pgvector）、mem0-dashboard（Next.js 面板）。make up target（server/Makefile#L7-L21）在启动前还会做三件事：

• 用 lsof 检查 3000/8888 端口是否已被占用，占用则报错退出并提示排查命令；
• docker compose up -d --build 构建并启动；
• 轮询等待就绪：wait-api 轮询 $(API_URL)/auth/setup-status，wait-dashboard 轮询 $(DASHBOARD_URL)/api/health。

此外 Makefile 还提供日常运维 target：down（停止栈）、clean（docker compose down -v 连卷删除）、logs（docker compose logs -f）、health（分别探测 API /docs、Dashboard /api/health 与 pg_isready）、bootstrap（up + 双等待 + seed 一步到位）、seed（调用 server/scripts/seed.sh 创建首个 admin 与 API key，支持 EMAIL/PASSWORD/NAME/OUTPUT=json 变量覆盖）。

2.3 端口规划

server/AGENTS.md 给出的开发栈端口约定如下：

服务	端口
mem0 API	8888
PostgreSQL (pgvector)	8432
Neo4j HTTP	8474
Neo4j Bolt	8687

其中 API 与 Postgres 端口可直接在 server/docker-compose.yaml 中验证：mem0 服务映射 8888:8000，postgres 服务映射 8432:5432。关于 Neo4j：文档将其列为开发栈存储组件（5.x + APOC 插件）之一，而从当前 server/docker-compose.yaml 结构看，compose 文件仅定义了 mem0、postgres、mem0-dashboard 三个服务，未内置 Neo4j；结合 server/dev.Dockerfile 中 pip install -e .[graph] 安装了 SDK 的 graph 扩展这一事实，可以推断 Neo4j 属于图记忆场景下的可选配套组件，端口表是其接入时的约定值。

三、开发栈内部实现：热重载是如何生效的

"Hot reload: the dev Dockerfile mounts both server/ and mem0/" 是 server/AGENTS.md 的关键约定，其实现链条由三个文件共同完成：

1. server/dev.Dockerfile：基于 python:3.12，安装 Poetry 与 server/requirements.txt 依赖，随后把仓库根目录的 pyproject.toml、poetry.lock、mem0/ 拷贝进容器并执行 pip install -e .[graph]，即以可编辑模式安装 SDK；最后拷贝 server/ 代码，CMD 为 uvicorn main:app --host 0.0.0.0 --port 8000 --reload。
2. server/docker-compose.yaml#L14-L21：mem0 服务以 .（即 server/ 目录）为构建上下文、server/dev.Dockerfile 为 Dockerfile，并把 .:/app 卷挂载进容器。由于 SDK 是可编辑安装且源码目录被挂载，修改 server/ 或 mem0/ 下任何 Python 文件后，uvicorn --reload 会自动重载进程——SDK 改动无需重新构建镜像。
3. 启动命令（server/docker-compose.yaml#L20-L21）：

rm -rf /app/packages && pip install -q --force-reinstall --no-deps mem0ai \
  && alembic upgrade head \
  && uvicorn main:app --host 0.0.0.0 --port 8000 --reload

即：每次容器启动先强制重装可编辑安装的 mem0ai 包（保证包元数据与挂载源码一致），再执行 Alembic 数据库迁移（迁移脚本见 server/alembic/versions），最后以 reload 模式启动 uvicorn。配套的 PYTHONDONTWRITEBYTECODE=1 与 PYTHONUNBUFFERED=1 避免字节码缓存干扰热重载、保证日志实时输出；./history 目录挂载到 /app/history 用于持久化记忆变更历史。

Postgres 侧（server/docker-compose.yaml#L32-L50）使用官方 pgvector/pgvector:pg17 镜像（PostgreSQL 17 + pgvector 0.8.0），shm_size 128MB，数据落在 postgres_db 卷；server/init-db.sh 挂载到 /docker-entrypoint-initdb.d/，在容器初始化时创建 mem0_app 数据库（存放用户/认证/API key 等应用数据），而默认的 postgres 库由 pgvector 承载记忆向量。Dashboard 服务从 server/dashboard 目录构建，监听 3000 端口，通过 API_INTERNAL_URL=http://mem0:8000 在容器网络内直连 API。

四、工程约定（Conventions）

server/AGENTS.md 的 Conventions 一节逐条列出了必须遵守的工程边界，结合仓库实现可以进一步理解其理由：

• 框架：FastAPI 跑在 uvicorn 上，开发环境开启 auto-reload。入口即 server/main.py 中的 FastAPI(title="Mem0 REST APIs", ...) 实例，OpenAPI 文档暴露在 /docs。
• 存储：PostgreSQL + pgvector 扩展，Neo4j 5.x + APOC 插件。
• 热重载：如上节所述，dev Dockerfile 同时挂载 server/ 与 mem0/，SDK 编辑即时生效。
• 只用 Docker Compose 做本地开发，明确"不要添加直接用 uvicorn 运行的路径"。这与 AGENTS.md 首句"Docker only"呼应，保证所有开发者与 CI 使用同一运行路径。
• SDK 约定继承：服务器导入仓库内的 Python SDK，触及 SDK 代码时须遵循 mem0/AGENTS.md。

五、密钥与配置边界：.env 纪律

server/AGENTS.md 结尾给出硬性规则：永不提交 .env；compose 服务的凭据只能以占位符形式存在于 .env.example。仓库中的 server/.env.example 正是这一规则的直接产物，其完整变量如下：

变量	默认值/示例	说明
OPENAI_API_KEY	空	默认 LLM 与 embedder 的密钥
ANTHROPIC_API_KEY / GOOGLE_API_KEY	注释掉的可选项	其他内置提供商的密钥
POSTGRES_HOST	postgres	Compose 网络内主机名
POSTGRES_PORT	5432	容器内端口
POSTGRES_DB	postgres	pgvector 使用的库
POSTGRES_USER	postgres	数据库用户
POSTGRES_PASSWORD	空（必填）	缺失时 compose 拒绝启动
POSTGRES_COLLECTION_NAME	memories	向量集合名
ADMIN_API_KEY	空	管理员 API key
JWT_SECRET	空	Dashboard JWT 签名密钥
AUTH_DISABLED	false	仅限本地开发
DASHBOARD_URL	http://localhost:3000	用于 CORS 白名单
APP_DB_NAME	mem0_app	应用数据库名
MEM0_DEFAULT_LLM_MODEL	gpt-5-mini	默认 LLM 模型
MEM0_DEFAULT_EMBEDDER_MODEL	text-embedding-3-small	默认 embedding 模型
MEM0_TELEMETRY	true	匿名遥测，false 退出
REQUEST_LOG_RETENTION_DAYS	30	make prune-logs 的保留天数

两条关键约束在代码中可验证：

• POSTGRES_PASSWORD 强制必填：server/docker-compose.yaml#L40 使用 ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env} 语法——变量为空时 Compose 直接报错退出，不存在回退默认密码；
• JWT_SECRET 启动期校验：server/main.py#L90-L94 中，若 AUTH_DISABLED 未开启而 JWT_SECRET 缺失，进程直接抛出 RuntimeError；若设置了 ADMIN_API_KEY 但长度小于 16 字符，会打印警告（server/main.py#L48 定义 MIN_KEY_LENGTH = 16）。

六、服务器运行时行为：默认配置、内置提供商与请求日志

理解服务器"默认长什么样"，可以深入 server/main.py：

• 默认配置：server/main.py#L120-L139 的 DEFAULT_CONFIG 声明向量存储为 pgvector（连接参数全部来自 POSTGRES_* 环境变量），LLM 与 embedder 默认 openai 提供商，模型分别为 MEM0_DEFAULT_LLM_MODEL（默认 gpt-5-mini）与 MEM0_DEFAULT_EMBEDDER_MODEL（默认 text-embedding-3-small）。
• 内置提供商白名单：server/main.py#L62-L63 定义 BUNDLED_LLM_PROVIDERS = ("openai", "anthropic", "gemini") 与 BUNDLED_EMBEDDER_PROVIDERS = ("openai", "gemini")。POST /configure 会经 _validate_bundled_providers 校验（server/main.py#L232-L259）：非内置提供商返回 400，提示需自行安装包、重建容器并扩展白名单——这解释了为何 Dockerfile 要预装依赖，也解释了 .env.example 中为何只列出三个提供商的密钥。
• 配置脱敏：GET /configure 返回前会经 _redact_config 递归处理，命中 SENSITIVE_CONFIG_KEYS（如 api_key、jwt_secret、password、token 等，server/main.py#L49-L58）的值一律替换为 [redacted]。
• 请求日志：中间件 log_requests（server/main.py#L292-L319）为每个请求生成 request id、计时，并异步把 method、path、状态码、延迟、认证方式写入 request_logs 表；/api/health、/docs、/redoc、/openapi.json 与 /requests 前缀路径被跳过（server/main.py#L59-L60）。由于该表只增不减，server/README.md 建议生产环境把 make prune-logs 接入 cron/systemd 定期清理，REQUEST_LOG_RETENTION_DAYS 控制保留窗口。
• CORS 收紧：CORSMiddleware 的 allow_origins 只允许 DASHBOARD_URL（server/main.py#L160-L167），即只有本机 Dashboard 可跨域调用 API。

七、小结

围绕 server/AGENTS.md 的三条主线——命令（make build/make run_local/docker compose up）、端口（8888/8432/8474/8687）、约定（Docker only、热重载、SDK 约定继承、.env 纪律）——在当前仓库中全部有可验证的落地实现：Makefile target 与 Compose 服务一一对应，dev Dockerfile 的可编辑安装加卷挂载实现了"SDK 改动免重建"，POSTGRES_PASSWORD 强制校验与启动期 JWT_SECRET 检查保证了安全默认值。对需要自托管 Mem0 或在此基础上二次开发的读者，按第五节准备好 .env，用 make up 拉起开发栈、通过 /docs 验证接口，是进入该服务器内部世界最短的路径；更多运维细节（首次引导 make bootstrap、密码重置、请求日志清理、pgvector 镜像迁移）可参阅 server/README.md。