mcp-memory-service 部署（语义记忆服务）

更新于 2026-10-28

mcp-memory-service 部署（语义记忆服务）

给 AI Agent 用的语义长期记忆服务（doobidoo/mcp-memory-service，v11.15.0，Apache-2.0）：sqlite-vec 存向量 + MCP/REST 双协议 + 知识图谱 + 自动 consolidate。2026-10-12 部署。

现状

项	值
容器	`mcp-memory`（compose 在 `/data/docker-compose/mcp-memory/`）
端口	`172.17.0.1:4480` → 容器 8000（8000/8765 已被占）
域名	mcp-memory.hsfp.cn（NPM proxy host id=199 → :4480，全站 Authentik SSO）
数据	`/data/mcp-memory/data/memory.db`（sqlite-vec + FTS5）+ `backups/`（每日自动备份）
嵌入模型	paraphrase-multilingual-MiniLM-L12-v2（ONNX int8，384 维，CPU，多语言含中文）
认证	`MCP_API_KEY`（`.env`，600 权限），请求头 `X-API-Key`；`/api/health` 免鉴权
MCP 端点	`http://172.17.0.1:4480/mcp`（streamable HTTP；走域名会被 SSO 拦，本机客户端直连 4480）

关键 API：POST /api/memories（存）、POST /api/search（语义检索，返回 similarity_score）、/mcp（streamable HTTP，接 pi/Claude 用）、/api/health。

部署过程（含三个坑）

拉镜像：dockerd 直连 Docker Hub 跑几分钟零进展 → 用自家 docker.hsfp.cn 中转（POST /api/pull → GitHub Actions → 阿里云 ACR，约 80 秒）→ unset 代理 后 skopeo copy docker://registry.cn-beijing.aliyuncs.com/dockerhub_happen/doobidoo_mcp-memory-service:latest docker-daemon:doobidoo/mcp-memory-service:latest，43 秒落地 693MB。这条路径再次被验证是最稳的。
嵌入模型下载（最大的坑）：镜像启动时从 AWS S3 拉 all-MiniLM-L6-v2 的 ONNX 包（80MB），实测 16KB/s，卡一个多小时没进展。HF_ENDPOINT=hf-mirror 无效——默认模型写死了 S3 地址，只有非默认模型才走 HuggingFace。 → 解法：宿主机从 hf-mirror 预下载文件，挂载进容器缓存目录，并设 MCP_MEMORY_ONNX_ALLOW_DOWNLOAD=0。
挂载层级多一层 = 静默降级成伪向量：容器期望 ~/.cache/mcp_memory/onnx_models/all-MiniLM-L6-v2/onnx/model.onnx；我第一次把宿主 onnx/all-MiniLM-L6-v2/onnx/ 挂到 .../all-MiniLM-L6-v2，容器里就变成 .../all-MiniLM-L6-v2/all-MiniLM-L6-v2/onnx/。服务不报错，只在日志里一行 ERROR ... ONNX model is not cached，然后回退到 SentenceTransformer→兜底伪向量，/api/health 照样 200、写入检索都能"跑通"，但语义是假的。排查要看启动日志里有没有 ONNX model loaded. Embedding dimension: 384。正确挂法：宿主目录内容直接就是 onnx/（即 /data/mcp-memory/onnx/onnx/model.onnx）。

值得记的模型格式坑

onnx-community/*-ONNX 上的模型多是 external data 格式：onnx/model.onnx 只是几十 KB 的计算图，权重在同目录的 onnx/model.onnx_data 里（如 all-MiniLM 的 90MB）。而代码里走 MCP_ONNX_MODEL_REPO 的 HF 下载路径时，snapshot_download(allow_patterns=[...]) 只匹配 model.onnx，不含 .onnx_data，于是会下到一个缺权重的空壳。要换模型只能走"预下载 + 挂载缓存目录"这条路，且必须连 .onnx_data 一起放。

中文检索效果实测

默认的 all-MiniLM-L6-v2 是纯英文模型，中文完全不可用（2026-10-12 实测，3 条中文记忆）：

查询	all-MiniLM-L6-v2	paraphrase-multilingual-MiniLM-L12-v2
中文「镜像下载太慢怎么办」	❌ 排第一是「廖燕霞…」(0.8154)，正确的排最后 (0.666)	✅ 正确排第一 (0.6831)
中文「我对象的昵称是什么」	✅ 碰对 (0.8761)	✅ 正确 (0.7000)
中文「服务器上都跑了什么服务」	未测	✅ 正确 (0.7242)
英文 `docker image download is slow`	✅ 正确 (0.5996)	✅ 正确 (0.6337)

换模型时注意：向量维度同为 384 但向量空间不通用，必须清库重建（本次直接 rm -rf /data/mcp-memory/data/*）。

域名 + SSO 接入（2026-10-12）

域名：memory.hsfp.cn 已被每日回忆占用（proxy host 189 → :4470），改用 mcp-memory.hsfp.cn。
NPM：proxy host id=199 → 172.17.0.1:4480，证书 id=9（*.hsfp.cn），http2_support: true（API 建站必须显式带，否则浏览器随机 421），advanced_config 里用 Ghost 那套 auth_request 模板全站保护，并加 proxy_buffering off（MCP 的 SSE 流不能被缓冲）。
Authentik：Proxy Provider pk=48（forward_single，external_host https://mcp-memory.hsfp.cn）+ Application slug mcp-memory（名为「AI 记忆服务」）。
⚠️ 坑：API 建的 Proxy Provider 不会自动加入 embedded outpost。新建后必须 PATCH /api/v3/outposts/instances/c66bdb7f-520b-4f0a-8bc1-15e8f6774450/ {"providers":[...]} 手动加上新 pk，否则 outpost 不认这个域名，表现为认证死循环/无法登录（UI 建 Provider 会自动加，所以这个坑只在写脚本时出现）。
⚠️ 坑：PATCH /api/v3/providers/proxy/<pk>/ 改域名会报 internal_host cannot be empty when forward auth is disabled（部分更新触发校验器）。改名不能 PATCH，得 DELETE 后重建（DELETE /api/v3/core/applications/<slug>/ → DELETE /api/v3/providers/proxy/<pk>/ → 重新 POST 两个）。
验证手法：curl -sIL https://mcp-memory.hsfp.cn/api/health 应依次 302 → auth.hsfp.cn/application/o/authorize/ → /if/flow/default-authentication-flow/ → 200。

记忆库内容扩充（2026-10-12）

初始只有 3 条测试数据，已批量扩充到 179 条：

做法：9 个子代理并行读 32 篇核心笔记（我的服务器、Docker与容器运维手册、nginx-proxy-manager使用手册、Authentik接入指南、WireGuard多跳搭建、AI模型供应商与模型清单、pi-web-安装与pi-agent探索、微信解密、飞棚听写、AutoDL、PII 网关等），每组提炼成 JSON 条目，再用脚本写入。
导入脚本：/root/scripts/mcp-memory-import.py（支持多文件/glob、--from-artifacts 自动读子代理产出、批内去重、--dry-run）。实测 178 条 59 秒完成：成功 176、重复 2、失败 0。重复条目服务端返回 success:false, "Duplicate content detected (exact match)"（按 content_hash 判重）。
每条统一打 笔记库 标签，方便后续按标签筛或重建。
提炼要求：每条自包含、≤350 字，优先写具体路径/端口/容器名/命令/结论，禁止编造。

检索实测（Top1 是否命中）：NPM 加反代 ✅、磁盘清理 ✅、pi-web 部署 ✅、微信解密 ✅；「国内拉 docker 镜像太慢」❌（正确的 docker.hsfp.cn 中转那条没进 top5）、「Authentik 登录循环」❌（正确的 picture claim 那条排第 2）。

查看与维护：GET /api/memories?page_size=100&page=N（page_size 上限 100，超了会静默返回空）、GET /api/tags、POST /api/search（纯语义，无关键词混合）。

待办

决定是否接进 pi 当 MCP 工具（http://172.17.0.1:4480/mcp + X-API-Key；走公网域名会被 SSO 拦住）
服务暂未接监控探活（可挂进服务器备份与监控）
检索区分度有限：现用的 paraphrase-multilingual-MiniLM-L12-v2（384 维）对中英混合短查询排序有噪声。若要明显提升，可换 bge-m3（1024 维、多语言检索最强，但 int8 约 570MB/需 2.2GB 权重，CPU 编码慢几倍）或 bge-small-zh-v1.5（512 维、中文专用、仅 95MB，但英文差）。换模型同样要走「预下载 + 挂载」并清库重建