Mem0 记忆服务

Mem0 是 Infra Compose 管理的长期记忆服务。它只在宿主机 127.0.0.1:8888 暴露 REST API，并启用 API Key 鉴权；不部署 Dashboard、 Neo4j 或独立 Qdrant。

当前架构

容器：mem0
Compose 真相源：/volume2/docker/infra/docker-compose.yaml
API：http://127.0.0.1:8888
关系数据库：Infra PostgreSQL 中独立的 mem0_app 数据库
向量数据：Infra PostgreSQL 中启用 pgvector 的 mem0 数据库
记忆抽取模型：LiteLLM 的 grok-fast
Embedding：LiteLLM 的 voyage-4，固定 1024 维
LiteLLM 地址：容器内通过 http://host.docker.internal:4000/v1 访问

Mem0 不持有 Grok、Voyage 或 OpenAI 的供应商凭据。模型凭据只归 LiteLLM 管理，Mem0 使用内部占位 Key 访问本机网关。

宿主机目录

mem0/Dockerfile：固定 Mem0 OSS v2.0.12 源码提交并构建服务镜像
mem0/.env：仅保存三个运行 Secret，不进入 Git，权限必须为 0600
mem0/history/：服务的本地历史状态，不进入 Git
PostgreSQL 数据：由 postgres 服务的数据目录统一持久化

mem0/.env 只允许以下键：

POSTGRES_PASSWORD
JWT_SECRET
ADMIN_API_KEY

禁止将 .env、数据库文件、历史目录、模型 Key 或响应内容提交到仓库。

兼容性修复

最终运行镜像必须安装 Debian libpq5。psycopg 默认可退回纯 Python 实现，但仍需系统 libpq；缺失时 Alembic 会在容器启动阶段报 no pq wrapper available。

Mem0 使用 OpenAI SDK 调用 embedding 时会发送 encoding_format=\"float\"，而 Voyage 仅接受 base64。因此 LiteLLM 的 voyage-4 路由必须配置：

additional_drop_params: ["encoding_format"]

该规则只作用于 voyage-4，不得改成全局丢弃参数，避免影响 Grok、GPT 和其他模型。

部署与完整测试

合并 Gitea PR 并完成 FF-only 同步后，执行：

cd /volume2/docker
sudo env INFRA_MEM0_DEPLOY=YES \
  ./ops/deploy-and-test-infra-mem0.sh

脚本会：

校验 Secret 文件权限与键集合。
幂等创建或更新 mem0 数据库角色以及 mem0、mem0_app 数据库。
确认 pgvector 扩展存在。
构建镜像并先验证 psycopg 能加载 pq 实现。
仅重建 mem0 容器。
配置 grok-fast、voyage-4 和 1024 维向量存储。
创建一条临时记忆、检索验证后删除。

成功标志：

memory_create_search_delete_smoke=passed
litellm_restarted=false
other_services_restarted=none

日常检查

sudo docker compose \
  -f /volume2/docker/infra/docker-compose.yaml ps mem0

sudo docker inspect mem0 \
  --format 'status={{.State.Status}} restart={{.RestartCount}} health={{if .State.Health}}{{.State.Health.Status}}{{else}}none{{end}}'

curl -fsS --max-time 10 \
  http://127.0.0.1:8888/openapi.json >/dev/null

API 业务请求必须携带 X-API-Key。检查时不得把 ADMIN_API_KEY 打印到终端、命令历史或日志。

故障排查

模型链路异常时运行只读诊断：

cd /volume2/docker
sudo ./ops/diagnose-infra-mem0-provider.sh

诊断会从 Mem0 容器内分别测试 grok-fast 和 voyage-4，并输出脱敏后的 Mem0/LiteLLM 错误。常见故障：

no pq wrapper available：镜像缺少 libpq5，检查 Dockerfile 与实际镜像。
Voyage 拒绝 encoding_format=float：检查 LiteLLM 的单模型 additional_drop_params 配置是否已部署。
HTTP 502 provider_unavailable：先直测 LiteLLM 对话与 embedding 路由，不要直接修改数据库。
维度不一致：voyage-4、Mem0 embedder 和 pgvector collection 必须全部为 1024 维；不要在已有 collection 上直接改维度。

安全与变更边界

不直接编辑 PostgreSQL 数据目录。
不删除 mem0、mem0_app 数据库或 mem0/history/ 来处理应用错误。
不把 Mem0 端口暴露到局域网或公网；跨服务访问应走受控网络或反向代理。
模型、维度、数据库结构和鉴权策略变更必须单独提 PR 并完成端到端测试。
失败时保留容器日志、镜像和数据库现场，先诊断，再决定回滚方案。

README.md Unescape Escape