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

Mem0 自托管 REST 服务器server/工程指南Docker-only 的 FastAPI、pgvector 与热重载开发栈【免费下载链接】embedchainThe Memory Layer for AI Agents - Drop-in memory infrastructure for AI agents and apps. Context that persists. Built for production.项目地址: https://gitcode.com/GitHub_Trending/em/embedchain本文以 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 SDKmem0/包的 HTTP 封装。server/AGENTS.md 开篇即给出两条强约束Docker only——Docker only; there is no local non-Docker path即不存在绕过 Docker 的本地运行路径任何直接用 uvicorn 跑的方案都不应引入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 up2.1 生产镜像make build与make run_local对照 server/Makefile#L58-L62build: 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 定义定义了三服务mem0API、postgrespgvector、mem0-dashboardNext.js 面板。make uptargetserver/Makefile#L7-L21在启动前还会做三件事用lsof检查 3000/8888 端口是否已被占用占用则报错退出并提示排查命令docker compose up -d --build构建并启动轮询等待就绪wait-api轮询$(API_URL)/auth/setup-statuswait-dashboard轮询$(DASHBOARD_URL)/api/health。此外 Makefile 还提供日常运维 targetdown停止栈、cleandocker compose down -v连卷删除、logsdocker compose logs -f、health分别探测 API/docs、Dashboard/api/health与pg_isready、bootstrapup 双等待 seed 一步到位、seed调用 server/scripts/seed.sh 创建首个 admin 与 API key支持EMAIL/PASSWORD/NAME/OUTPUTjson变量覆盖。2.3 端口规划server/AGENTS.md 给出的开发栈端口约定如下服务端口mem0 API8888PostgreSQL (pgvector)8432Neo4j HTTP8474Neo4j Bolt8687其中 API 与 Postgres 端口可直接在 server/docker-compose.yaml 中验证mem0服务映射8888:8000postgres服务映射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 bothserver/andmem0/ 是 server/AGENTS.md 的关键约定其实现链条由三个文件共同完成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。server/docker-compose.yaml#L14-L21mem0服务以.即server/目录为构建上下文、server/dev.Dockerfile为 Dockerfile并把.:/app卷挂载进容器。由于 SDK 是可编辑安装且源码目录被挂载修改server/或mem0/下任何 Python 文件后uvicorn --reload会自动重载进程——SDK 改动无需重新构建镜像。启动命令server/docker-compose.yaml#L20-L21rm -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。配套的PYTHONDONTWRITEBYTECODE1与PYTHONUNBUFFERED1避免字节码缓存干扰热重载、保证日志实时输出./history目录挂载到/app/history用于持久化记忆变更历史。Postgres 侧server/docker-compose.yaml#L32-L50使用官方pgvector/pgvector:pg17镜像PostgreSQL 17 pgvector 0.8.0shm_size128MB数据落在postgres_db卷server/init-db.sh 挂载到/docker-entrypoint-initdb.d/在容器初始化时创建mem0_app数据库存放用户/认证/API key 等应用数据而默认的postgres库由 pgvector 承载记忆向量。Dashboard 服务从 server/dashboard 目录构建监听 3000 端口通过API_INTERNAL_URLhttp://mem0:8000在容器网络内直连 API。四、工程约定Conventionsserver/AGENTS.md 的 Conventions 一节逐条列出了必须遵守的工程边界结合仓库实现可以进一步理解其理由框架FastAPI 跑在 uvicorn 上开发环境开启 auto-reload。入口即 server/main.py 中的FastAPI(titleMem0 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 结尾给出硬性规则永不提交.envcompose 服务的凭据只能以占位符形式存在于.env.example。仓库中的 server/.env.example 正是这一规则的直接产物其完整变量如下变量默认值/示例说明OPENAI_API_KEY空默认 LLM 与 embedder 的密钥ANTHROPIC_API_KEY/GOOGLE_API_KEY注释掉的可选项其他内置提供商的密钥POSTGRES_HOSTpostgresCompose 网络内主机名POSTGRES_PORT5432容器内端口POSTGRES_DBpostgrespgvector 使用的库POSTGRES_USERpostgres数据库用户POSTGRES_PASSWORD空必填缺失时 compose 拒绝启动POSTGRES_COLLECTION_NAMEmemories向量集合名ADMIN_API_KEY空管理员 API keyJWT_SECRET空Dashboard JWT 签名密钥AUTH_DISABLEDfalse仅限本地开发DASHBOARD_URLhttp://localhost:3000用于 CORS 白名单APP_DB_NAMEmem0_app应用数据库名MEM0_DEFAULT_LLM_MODELgpt-5-mini默认 LLM 模型MEM0_DEFAULT_EMBEDDER_MODELtext-embedding-3-small默认 embedding 模型MEM0_TELEMETRYtrue匿名遥测false退出REQUEST_LOG_RETENTION_DAYS30make 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_requestsserver/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_URLserver/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。【免费下载链接】embedchainThe Memory Layer for AI Agents - Drop-in memory infrastructure for AI agents and apps. Context that persists. Built for production.项目地址: https://gitcode.com/GitHub_Trending/em/embedchain创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

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

相关推荐

需求像Bug？把Bug生命周期搬到临时需求管理，拯救团队节奏

只做一件事，把产品做到极致：简申的长期主义与产品决策逻辑

数据流图DFD分层建模实战：从顶层图到子图平衡的完整指南

更多资讯

PDF行程单解析实战：从半结构化文档到报销自动化

CTF竞赛中Java爆破技术的Frida高效实现

网站流量攻击类型分析与防御实战指南

BERT中文NER实战：从字词错位到CRF标签对齐的完整链路

MCP与Function Call在LLM工具调用中的架构对比与实践

OSM路网入Neo4j：Java路由服务的Dijkstra/A*算路与接口封装

今日更新

PLFM_RADAR：从被动告警到主动感知的微服务健康监控系统

SPI隔离设计实战：MAX14431BAEE+与STM32F407工业级应用

数字隔离器如何根治SPI通信地环路干扰：MAX14431与TM4C129实战

本周精选

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

基于DRV8818与STM32的双极步进电机驱动方案实战解析

DRV8818PWPR+PIC18F45K80双极步进电机控制方案实战

本月热门

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

基于DRV8818与STM32的双极步进电机驱动方案实战解析

DRV8818PWPR+PIC18F45K80双极步进电机控制方案实战

读完文章，想聊聊您的网站？