# @cup319/mmpl 中文文档

规范地址：https://npmcn.com/package/%40cup319/mmpl/

版本：3\.15\.12
npm 元数据更新时间：2026-11-06T08:36:26.764Z
中文译文更新时间：2026-11-11T04:46:44.032Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cup319/mmpl
原文对照：https://npmcn.com/package/%40cup319/mmpl/?lang=original
源码仓库：https://cnb.cool/cnb-t/MMPL

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：82.2 MB，7 个文件
- TypeScript 类型：未声明
- 运行依赖：0 个
- 首次发布：2026-07-18T14:28:19.476Z
- 最新版本发布：2026-11-06T08:36:26.602Z
- 近 30 天下载量：5453（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：32（近 12 个月 32 个）

## 中文简介

MMPL(记忆宫)-QQ DuckDB QQ MCP 服务器(10 ~ : 1: Man L0-L3 + + ONNX + + + + + + +)-Linux + Windows + →

## 安装

```sh
npm install @cup319/mmpl
```

也可以使用：`pnpm add @cup319/mmpl`、`yarn add @cup319/mmpl`、`bun add @cup319/mmpl`

## README

# @cup319/mmpl

MMPL (Memory Palace) — DuckDB 向量记忆 MCP Server（单二进制，Rust 实现）。

当前版本 **3.3.8**：常驻热块 / 每轮 L0 捕获 / 后台四层 CRUD / 默认鉴权 / 模型下载源可选（Linux 包内置 `libonnxruntime.so.1`）。

```bash
npm install -g @cup319/mmpl
mmpl          # 启动 → http://127.0.0.1:7680/mcp
```

-   零 node\_modules 原生依赖（v3.3.0 起 Linux/Windows 双平台二进制直接打包在 npm 包内，postinstall 解包即用、离线可用；包内缺失时才回落 CNB Release 下载）
-   Streamable HTTP MCP（多 client 共享单进程，DuckDB 独占无锁冲突）
-   9 工具：`memory_write` / `memory_search` / `memory_list` / `memory_manage` / `memory_stats` / `memory_evolve` / `memory_compress` / `memory_palace` / `memory_symbol`
-   BM25（jieba + DuckDB FTS5）+ ONNX 语义向量（bge-small-zh）+ RRF 三路融合 + 复习强化
-   **v0.5.1 起出厂默认 = 知识库模式**（stability\_days=30 / review\_boost=0.5，无复习半衰期 ~20.8 天）
-   SIGTERM 优雅关停

## 记忆保持怎么配？

| 想要 | 做法 |
| --- | --- |
| **全部永久** | MCP 里执行一次 `memory_manage action=forgetting_disable`（自动持久化，重启生效）；或环境变量 `MMPL_FORGET=0` |
| **单条永久** | `memory_write action=encode input="…" permanent=true`；已有条目 `reinforce_action=promote_to_permanent` |
| **换个场景档** | 启动时 \`MMPL\_PROFILE=code |

场景档位一览：`knowledge`(默认, S=30/boost=0.5) / `code`(S=7/boost=1) / `vocab`(S=0.5/boost=2 背单词) / `assistant`(S=1/boost=1) / `lab`(S=0.01 观察遗忘)。

背英语单词：`MMPL_PROFILE=vocab` 启动，词条 `memory_write encode` 录入 → `memory_search` 自测（命中即算一次复习）→ 记得 `reinforce confirm`（稳定期 0.5→1.5→2.5 天递增）、忘了 `reinforce deny` → `mode=deep` 定期捞半忘词强化。详见仓库 `rust/README.md`。

环境变量：`DB_PATH`（默认 `data/memory.duckdb`）/ `HOST` / `PORT`（默认 7680）/ `MCP_PATH`（默认 `/mcp`）/ `MMPL_PROFILE` / `MMPL_FORGET` / `MMPL_STABILITY_DAYS` / `MMPL_REVIEW_BOOST` / `MMPL_ONNX` / `MMPL_MODEL`（v0.5.2 起四档：`base` 默认 / `small` / `m3` / `qwen3`）。

## Windows 开机隐藏自启（无 cmd 窗口）

Windows 版 `mmpl.exe` 是 GUI 子系统（无窗口），但**注册表 Run 键直指 `.cmd` 会弹出并常驻一个 cmd 窗口**；经 npm shim（`node run.js`）启动同样会带出 node 的控制台窗。隐藏启动的正解是 VBS 包一层：

```bat
rem %USERPROFILE%\mmpl\start-mmpl.cmd — 环境变量与日志重定向的唯一配置源
@echo off
set "ORT_DYLIB_PATH=%USERPROFILE%\.dsh\bot\workspace\onnx\onnxruntime.dll"
set "MMPL_MODEL=base"
cd /d "%USERPROFILE%\.dsh\bot\workspace"
"%APPDATA%\npm\node_modules\@cup319\mmpl\bin\mmpl.exe" > "%USERPROFILE%\.dsh\bot\workspace\mmpl.log" 2>&1
```

```vbscript
' %USERPROFILE%\mmpl\start-mmpl.vbs — Run 键指向它，窗口样式 0 = 隐藏
CreateObject("WScript.Shell").Run "cmd.exe /c ""%USERPROFILE%\mmpl\start-mmpl.cmd""", 0, False
```

```bat
reg add HKCU\SOFTWARE\Microsoft\Windows\CurrentVersion\Run /v mmpl-server /d "wscript.exe //nologo \"%USERPROFILE%\mmpl\start-mmpl.vbs\"" /f
```

注意：同一台机器只保留一个 Run 项。若既有 `.cmd` 直指项又有 VBS 项，登录后会双开（其一必现窗）：`reg delete HKCU\...\Run /v <项名> /f` 删掉多余的。

## Hermes Agent 插件接入

MMPL 可作为 [Hermes Agent](https://hermes-agent.nousresearch.com/) 的**原生 MemoryProvider 插件**（与 holographic 等并列的记忆后端）：插件源码在仓库 `integrations/hermes/` 目录，纯 HTTP 客户端、零 Python 依赖，把上面 9 个 MCP 工具透传给 Agent 并自动沉淀对话。

```bash
# 1. 拷贝插件
mkdir -p $HERMES_HOME/plugins/mmpl
cp integrations/hermes/__init__.py integrations/hermes/plugin.yaml $HERMES_HOME/plugins/mmpl/

# 2. config.yaml:
#    memory: { provider: mmpl }
#    plugins:
#      mmpl: { url: "http://127.0.0.1:7680/mcp", top_k: 5 }

# 3. 保持 mmpl 服务在跑（插件健康检查不过会自动拉起）
```

`hermes memory status` 应列出 `mmpl (no setup needed)`。安装细节与生命周期映射见仓库 `rust/README.md`「Hermes Agent 插件接入」章节。

完整文档见仓库 `rust/README.md` 与 `rust/USERS_GUIDE.md`。

## 常见问题

### @cup319/mmpl 是什么？

MMPL\(记忆宫\)-QQ DuckDB QQ MCP 服务器\(10 ~ : 1: Man L0-L3 \+ \+ ONNX \+ \+ \+ \+ \+ \+ \+\)-Linux \+ Windows \+ →

### 如何安装 @cup319/mmpl？

在项目目录运行 npm install @cup319/mmpl，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 mmpl、mmpl-setup，可以用 npx mmpl 直接运行。

### @cup319/mmpl 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/cup319\_\_mmpl 是否存在。

### @cup319/mmpl 可以商用吗？

@cup319/mmpl 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @cup319/mmpl 的下载量有多少？

根据 npm 官方下载统计，@cup319/mmpl 在 2026/10/11 – 2026/11/09 这 30 天内被下载 5,453 次，日均约 182 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cup319/mmpl 还在维护吗？

最新版本 3\.15\.12 发布于 2026/11/06（4 天前）；至今共发布 32 个版本，其中过去 12 个月发布了 32 个；首次发布于 2026/07/18。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。