memory-mcp

个人跨工具记忆：一个可搜索的情景档案库，收录来自所有设备的 AI 会话，外加一个精选的高信任度语义事实层，通过 MCP 服务器对外暴露。专为自托管的 arm64 主机设计，仅限 WG（WireGuard）网络。完整设计见 docs/mcp/memory-mcp-spec.md。

项目结构

Related MCP server: Memorium

两层结构、两种信任级别

• 情景档案（Qdrant memory_archive）：每个会话的每个分块。使用稠密向量（bge-m3，1024 维）和稀疏向量（TF-IDF 修正）的 RRF 融合混合检索。仅按需检索（search_archive）。

• 语义事实（Postgres）：归档的精选陈述，带出处。默认读取入口（search_memory）。由 remember（来源 user）以及经过人工批准的翻译（来源 distilled）写入 —— 未经 memoryctl review 审阅，任何翻译结果都不会生效。

MCP 接口

工具：remember、search_memory、search_archive、forget（破坏性操作，按查询分两阶段执行）。资源：memory://stats、memory://facts/recent、memory://facts/{id}。

开发

pnpm install
pnpm build        # all packages
pnpm test         # core + server suites (stores are mocked; nothing external touched)
pnpm eval         # golden-set retrieval harness (needs live stores + ingested data)

配置通过环境变量驱动，见 packages/core/src/config.ts（loadConfig）—— 所有变量详见 deploy/.env.example。

运维

cd deploy && cp .env.example .env   # fill in POSTGRES_PASSWORD, STATIC_BEARER, keys
docker compose -f compose.prod.yaml up -d --build
docker compose -f compose.prod.yaml exec memory-mcp memoryctl init
docker compose -f compose.prod.yaml exec memory-mcp memoryctl verify

compose.prod.yaml 假定 Qdrant 和一个兼容 OpenAI 的 LLM 网关已经作为外部容器在你的宿主机上运行 —— 请修改 networks: 段的 name: 字段为你自己的 Docker 网络名。

每日 ingest+distill 和夜间备份由 systemd 定时器（deploy/systemd/）负责。备份在 14 天后自动过期，因此 forget 的删除效果也会在这个窗口期内从备份中传播出去。

安全策略

• 仅 WG 绑定、静态 Bearer（v1）；网关 JWT 是未来计划中的认证方式（第 8 步），前提是服务器前部署一个兼容的 OIDC/JWT 网关。

• 清洗逻辑（gitleaks + 自定义正则表达式）是 fail-closed 的，会在内容被嵌入或存储之前运行。无法解析的输入会让整个文件进入隔离状态（记入台账）；临时性基础设施故障（嵌入服务、Qdrant、gitleaks 不可用）会干净地回滚、不记录任何内容，文件会在下次运行时重试。

• forget 在两个存储中都是直接删除。

• 档案分块在“不可信数据”分隔符中返回 —— 历史会话记录可能包含类似指令的文本，必须将其视为数据而非指令。

如需报告漏洞，请参阅 SECURITY.md。

参与贡献

欢迎提交 issue 和 PR —— 开发环境与约定请参阅 CONTRIBUTING.md，历史记录见 CHANGELOG.md。本项目遵循《行为准则》。

许可证

MIT