@cup319/mmpl 2.8.1 → 3.0.0

package/README.md

@@ -1,288 +1,50 @@
-# MMPL MCP
+# @cup319/mmpl
 
-[![npm version](https://img.shields.io/npm/v/@cup319/mmpl)](https://www.npmjs.com/package/@cup319/mmpl)
-[![license](https://img.shields.io/npm/l/@cup319/mmpl)](https://cnb.cool/cnb-t/mmpl/-/blob/main/LICENSE)
-
-基于 DuckDB 的向量记忆系统，具备完整的记忆生命周期管理，以常驻 HTTP MCP Server 形式运行（v2.5.1+，多 client 共享单进程，避免 DuckDB 文件锁冲突）。���
-
-## 核心特性
-
-- **9 个精简工具**：write、search、list、manage、evolve、compress、palace、symbol、stats
-- **模型自动下载**：首次启动自动从 HuggingFace 下载 ONNX 模型（默认 all-MiniLM-L6-v2，90MB，384维）
-- **跨平台支持**：Windows + Linux，自动适配路径和信号处理
-- **记忆生命周期**：Active → Infrequent → Archived → Permanent（含衰减、强化、SM-2 间隔复习）
-- **混��检索**：BM25（FTS5）+ 向量（HNSW）+ 场景 + 用户画像
-- **L0-L3 分层管道**：原始记录 → 原子事实 → 场景块 → 用户画像
-- **符号压缩**：任务工具调用对 → Mermaid 符号图 + 钻取回放
-- **可选 LLM 分析**：重要性评分、类型分类、实体抽取、情感分析
-
-## 安装
-
-### 方式一：全局安装（推荐，自带 `mmpl` 命令）
+MMPL (Memory Palace) — DuckDB 向量记忆 MCP Server（单二进制，Rust 实现）。
 
 ```bash
 npm install -g @cup319/mmpl
+mmpl          # 启动 → http://127.0.0.1:7680/mcp
 ```
 
-装完即可直接用 `mmpl` 命令启动 server（详见下文「快速上手」）。
+- 零 node_modules 原生依赖（二进制在 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 三路融合 + SM-2 强化
+- **v0.5.1 起出厂默认 = 知识库模式**（stability_days=30 / review_boost=0.5，无复习半衰期 ~20.8 天）
+- SIGTERM 优雅关停
 
-### 方式二：项目内安装
+## 记忆保持怎么配？
 
-```bash
-npm install @cup319/mmpl
-```
+| 想要 | 做法 |
+|---|---|
+| **全部永久** | MCP 里执行一次 `memory_manage action=forgetting_disable`（自动持久化，重启生效）；或环境变量 `MMPL_FORGET=0` |
+| **单条永久** | `memory_write action=encode input="…" permanent=true`；已有条目 `reinforce_action=promote_to_permanent` |
+| **换个场景档** | 启动时 `MMPL_PROFILE=code|vocab|assistant|lab`（默认 `knowledge`） |
 
-安装后入口在 `node_modules/@cup319/mmpl/dist/index.js`。作为 MCP Server 使用时，在 client 配置中指向这个路径，或用 `node ./node_modules/@cup319/mmpl/dist/index.js` 启动。
+场景档位一览：`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`。
 
-```bash
-git clone https://cnb.cool/cnb-t/mmpl.git
-cd mmpl
-npm install
-npm run build      # 产物在 dist/index.js
-node dist/index.js
-```
-
-## 快速上手（5 分钟教程）
+环境变量：`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`）。
 
-这一节带你从零跑通：安装 → 启动 → 连接 client → 写入/检索第一条记忆。
+## Hermes Agent 插件接入
 
-> **前置条件**：Node.js ≥ 20。首次启动会从 HuggingFace 自动下载 ONNX 模型（默认 `all-MiniLM-L6-v2`，~90MB，国内网络会自动切到 `hf-mirror.com` 镜像）。
-
-### Step 1：启动 server
-
-全局安装后，任意终端执行：
+MMPL 可作为 [Hermes Agent](https://hermes-agent.nousresearch.com) 的**原生 MemoryProvider 插件**（与 holographic 等并列的记忆后端）：插件源码在仓库 `integrations/hermes/` 目录，纯 HTTP 客户端、零 Python 依赖，把上面 9 个 MCP 工具透传给 Agent 并自动沉淀对话。
 
 ```bash
-mmpl
-# 等价于：node ./node_modules/@cup319/mmpl/dist/index.js
-```
-
-看到类似输出即成功（首启会多花 5–10 秒加载 ONNX 模型）：
-
-```
-MMPL (Memory Palace) MCP Server v2.7.0 listening on http://127.0.0.1:7680/mcp
-```
-
-> **重要**：mmpl 只有 HTTP 一种模式，**没有 stdio、没有 CLI flag**。所有配置（host/port/path、DB 路径、模型路径、LLM key）都走环境变量。多个 client 共享这同一个进程，**不要起第二个 server**——DuckDB 文件是单进程独占的。
-
-### Step 2：验证 server 活着
-
-```bash
-curl http://127.0.0.1:7680/
-# {"status":"ok","server":"mmpl","sessions":0}
-```
-
-### Step 3：在 client 里连接
-
-ZCode (`~/.zcode/cli/config.json`)：
-
-```json
-{
-  "mcp": {
-    "servers": {
-      "mmpl": { "type": "http", "url": "http://127.0.0.1:7680/mcp" }
-    }
-  }
-}
-```
-
-Claude Desktop / Claude Code（`claude_desktop_config.json` 或 `~/.claude.json`）：
-
-```json
-{
-  "mcpServers": {
-    "mmpl": { "type": "http", "url": "http://127.0.0.1:7680/mcp" }
-  }
-}
-```
-
-重连 client 后，`sessions` 会 +1：
-
-```bash
-curl http://127.0.0.1:7680/
-# {"status":"ok","server":"mmpl","sessions":1}
-```
-
-### Step 4：写入第一条记忆
-
-在连接好的 client 里让 AI 调用 `memory_write`（以 encode 模式写入一条 fact）：
-
-```jsonc
-// 工具名: memory_write
-{
-  "action": "encode",
-  "input": "用户的本地时区是 Asia/Shanghai (UTC+8)，工作时间 09:00-18:00。",
-  "type": "preference",
-  "tags": ["timezone", "work-hours"]
-}
-```
-
-返回 `memory_id` 即写入成功。
-
-### Step 5：检索记忆
-
-```jsonc
-// 工具名: memory_search
-{
-  "mode": "quick",
-  "query": "用户在哪个时区？几点上班？"
-}
-```
-
-会命中刚才写入的那条，返回内容及相似度评分。`mode` 可选 `quick` / `deep` / `hybrid` / `keyword`。
-
-### Step 6：看统计
-
-```jsonc
-// 工具名: memory_stats
-{ "type": "summary" }
-```
-
-到这里你已经跑通了完整闭环。9 个工具的完整说明见下文「工具一览」。
-
-> **常驻保活**：HTTP server 自身不会自我守护。Windows 推荐 `nssm install MMPL node D:\path\to\dist\index.js`，Linux/macOS 推荐 `systemd` 或 `pm2 start dist/index.js --name mmpl`。
-
-## 配置
-
-### 部署：常驻 HTTP MCP Server（推荐 — 多 client 共享）
+# 1. 拷贝插件
+mkdir -p $HERMES_HOME/plugins/mmpl
+cp integrations/hermes/__init__.py integrations/hermes/plugin.yaml $HERMES_HOME/plugins/mmpl/
 
-v2.5.1 起，mmpl 默认作为 **Streamable HTTP MCP server** 运行：一个常驻进程独占 DuckDB，被多个 MCP client（ZCode / Claude Desktop / IDE 等）共享。这从根本上避免了 stdio 模式下多 client 各自 spawn 进程、争抢同一个 `.duckdb` 文件导致的 `Connection closed` 错误。
+# 2. config.yaml:
+#    memory: { provider: mmpl }
+#    plugins:
+#      mmpl: { url: "http://127.0.0.1:7680/mcp", top_k: 5 }
 
-启动命令见上文「快速上手 · Step 1」。完整启动示例（带环境变量）：
-
-```bash
-EMBEDDING_PROVIDER=onnx \
-DB_PATH=./data/memory.duckdb \
-ONNX_MODEL_PATH=./models/all-MiniLM-L6-v2.onnx \
-ANALYZER_API_URL=https://api.z.ai/api/paas/v4/chat/completions \
-ANALYZER_API_KEY=<your-api-key> \
-ANALYZER_MODEL=glm-4-flash \
-node ./node_modules/@cup319/mmpl/dist/index.js
-# 或全局安装后直接：mmpl
-```
-
-client 配置（每个 client 一份，只填 URL）见「快速上手 · Step 3」。
-
-**Health check（确认 server 活着）**
-
-```bash
-curl http://127.0.0.1:7680/
-# {"status":"ok","server":"mmpl","sessions":3}
-```
-
-**常驻进程管理（可选）**
-
-HTTP server 启动后不自我守护，靠外部保活：
-
-- **Windows**: `nssm install MemoryPalace node D:\path\to\dist\index.js`，或用 Task Scheduler
-- **Linux/macOS**: systemd unit 或 `pm2 start dist/index.js --name mmpl`
-
-> server 默认只绑 `127.0.0.1`（本机访问）。多 client 共享时**不要**起第二个 server 进程——DuckDB 文件是单进程独占的，第二个进程会启动失败；多个 client 都连同一个 HTTP URL 即可。
-
-### ZCode 集成：常驻 + 无弹窗（开箱即用）
-
-如果你在 ZCode 里用 mmpl，推荐用仓库自带的部署示例 [`examples/zcode-deploy/`](./examples/zcode-deploy/)。它通过 SessionStart/Stop hook 实现：
-
-- **常驻运行**：server 启动一次后一直留在后台，切换 ZCode session 不重启（避免每次等 5–10s ONNX 加载）
-- **无 node.exe 黑窗**：所有 `spawn` 配 `windowsHide: true`（修复了 Windows 上启动时弹 `C:\...\node.exe` 窗口的问题）
-- **日志落盘**：server 的 stdout/stderr 重定向到 `.mmpl-server.log`，排查启动失败有据可查
-
-一键安装：
-
-```bash
-# 1. 准备部署目录
-mkdir D:\mmpl-deploy && cd D:\mmpl-deploy
-npm init -y && npm install @cup319/mmpl
-# 2. 复制示例脚本
-cp /path/to/examples/zcode-deploy/*.mjs .
-# 3. 按示例 README 配置 ~/.zcode/cli/config.json 的 hook
-```
-
-完整步骤、配置示例、运行机制、弹窗 bug 修复历史详见 [`examples/zcode-deploy/README.md`](./examples/zcode-deploy/README.md)。
-
-> **澄清**：`@cup319/mmpl` npm 包本身不 spawn 子进程，**不存在弹窗问题**。弹窗只发生在用 `start-mmpl.mjs` 包装启动时（该脚本 spawn 子进程的方式在 Windows 上需要 `windowsHide`），示例脚本已修复。
-
-### 遗留：stdio 模式
-
-v2.5.1 之前默认走 stdio，每个 client 各 spawn 一个进程。该模式已在 v2.5.1 移除（多 client 场景下 DuckDB 文件锁无法解决）。如确需单 client stdio，可 git checkout v2.4.4 标签。
-
-## 环境变量
-
-**Server 启动时（HTTP 进程的 env）**
-
-| 变量 | 默认值 | 说明 |
-|------|--------|------|
-| `EMBEDDING_PROVIDER` | `onnx` | `onnx` / `api` / `tfidf` |
-| `ONNX_MODEL_PATH` | `./models/all-MiniLM-L6-v2.onnx` | ONNX 模型路径 |
-| `DB_PATH` | `./data/memory.duckdb` | DuckDB 数据库路径 |
-| `ANALYZER_API_URL` | — | LLM API 地址（智谱/OpenAI） |
-| `ANALYZER_API_KEY` | — | LLM API 密钥 |
-| `ANALYZER_MODEL` | `glm-4-flash` | 分析用模型 |
-| `TFIDF_DICT_PATH` | `./data/tfidf-dict.json` | TF-IDF 字典路径（可选，仅 tfidf provider 使用，运行时自动生成） |
-| `MCP_HTTP_HOST` | `127.0.0.1` | HTTP server 绑定地址（`0.0.0.0` 开放外网，需自行加防火墙/鉴权） |
-| `MCP_HTTP_PORT` | `7680` | HTTP server 端口 |
-| `MCP_HTTP_PATH` | `/mcp` | MCP 端点路径 |
-
-## 工具一览
-
-| 工具 | 说明 |
-|------|------|
-| `memory_write` | 写入记忆（encode 编码 + capture 捕获） |
-| `memory_search` | 检索记忆（quick/deep/hybrid/keyword + drill 钻取） |
-| `memory_list` | 列出记忆（分页 + 状态/类型/强度/关键词过滤 + 排序） |
-| `memory_manage` | 管理生命周期（forget/reinforce/consolidate/reclaim/reembed） |
-| `memory_evolve` | 自动进化（extract 提取 + persona 画像更新） |
-| `memory_compress` | 压缩记忆（compress/decompress/offload） |
-| `memory_palace` | 记忆宫殿（build/explore/visualize/scenes） |
-| `memory_symbol` | 符号记忆（create/search/export） |
-| `memory_stats` | 统计监控（summary/strength/review/pipeline/metrics） |
-
-## ONNX 模型
-
-首次启动时自动从 HuggingFace 下载模型及 tokenizer 文件（~90MB），支持断点续传。
-
-默认使用 `all-MiniLM-L6-v2`（384维，英文优化）。如需多语言支持，设置 `ONNX_MODEL_PATH` 指向 `paraphrase-multilingual-MiniLM-L12-v2`（384维，50+语言，~470MB）。
-
-自动下载失败时，控制台会打印平台适配的手动下载命令。
-
-### 国内网络环境（镜像加速）
-
-HuggingFace 官方源（`huggingface.co`）在国内访问经常超时。MMPL 内置**自动镜像切换**：
-
-- 启动时探测 `huggingface.co`（3 秒超时）
-- 可达 → 用官方源
-- 不可达 → 自动切到国内镜像 `hf-mirror.com`
-
-控制台会打印实际选用的源，例如：
-```
-[ONNX] HuggingFace 官方源不可达 (3000ms 超时)，切换国内镜像 https://hf-mirror.com
-```
-
-**手动指定镜像源**（覆盖自动探测）：设置 `HF_ENDPOINT` 环境变量（HuggingFace 官方约定）：
-
-```bash
-# Windows
-set HF_ENDPOINT=https://hf-mirror.com
-
-# Linux/macOS
-export HF_ENDPOINT=https://hf-mirror.com
-
-# 或者用自定义镜像
-export HF_ENDPOINT=https://your-mirror.example.com
-```
-
-`HF_ENDPOINT` 优先级最高，设置后会跳过自动探测直接使用。
-
-## 开发
-
-```bash
-npm test         # 单元测试（75 用例）
-npm run lint     # 类型检查
-npm run dev      # 开发模式
+# 3. 保持 mmpl 服务在跑（插件健康检查不过会自动拉起）
 ```
 
-## 许可证
+`hermes memory status` 应列出 `mmpl (no setup needed)`。安装细节与生命周期映射见仓库 `rust/README.md`「Hermes Agent 插件接入」章节。
 
-MIT
+完整文档见仓库 `rust/README.md` 与 `rust/USERS_GUIDE.md`。

package/install.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+/**
+ * MMPL Rust 版 npm 安装器 v5
+ * 双平台：Linux (x86_64) + Windows (x86_64)。优先用包内自带产物（离线可用）；
+ * 缺失时回落 CNB Release 下载（需公开访问）。
+ * 语义向量模型（bge-base-zh-v1.5，~103MB）不在包内——MMPL 首次启动时自动从
+ * hf-mirror.com 下载到 DATA_DIR/models/（v2.9.0 已修复 copy 自覆盖 bug，下载可成功）。
+ */
+const { createWriteStream, existsSync, mkdirSync, chmodSync } = require("fs");
+const { pipeline } = require("stream/promises");
+const { get } = require("https");
+const path = require("path");
+const { execSync } = require("child_process");
+
+const VERSION = "3.0.0";
+const IS_WIN = process.platform === "win32";
+const PLATFORM = IS_WIN ? "windows" : "linux";
+const ARCH = "x86_64";
+
+// 产物命名：Linux 是 tar.gz（mmpl-linux-x86_64）；Windows 是 zip（mmpl.exe + duckdb.dll）。
+const ASSET_NAME = IS_WIN
+  ? `mmpl-v${VERSION}-windows-${ARCH}.zip`
+  : `mmpl-v${VERSION}-linux-${ARCH}.tar.gz`;
+const URL = `https://cnb.cool/cnb-t/MMPL/-/releases/download/rust-v${VERSION}/${ASSET_NAME}`;
+
+const BIN = IS_WIN
+  ? path.join(__dirname, "bin", "mmpl.exe")
+  : path.join(__dirname, "bin", "mmpl");
+const BUNDLED = path.join(__dirname, ASSET_NAME);
+
+function extractLinux(tarPath) {
+  mkdirSync(path.dirname(BIN), { recursive: true });
+  execSync(`tar xzf ${JSON.stringify(tarPath)} -C ${JSON.stringify(path.dirname(BIN))}`);
+  execSync(`mv ${JSON.stringify(path.join(path.dirname(BIN), `mmpl-linux-${ARCH}`))} ${JSON.stringify(BIN)}`);
+  chmodSync(BIN, 0o755);
+}
+
+function extractWindows(zipPath) {
+  mkdirSync(path.dirname(BIN), { recursive: true });
+  if (process.platform === "win32") {
+    execSync(`powershell -NoProfile -Command "Expand-Archive -Force '${zipPath}' '${path.dirname(BIN)}'"`);
+  } else {
+    execSync(`unzip -o ${JSON.stringify(zipPath)} -d ${JSON.stringify(path.dirname(BIN))}`);
+  }
+}
+
+function download(url, redirects = 5) {
+  return new Promise((resolve, reject) => {
+    get(url, { headers: { "User-Agent": "mmpl-installer" } }, (res) => {
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location && redirects > 0) {
+        res.resume();
+        return resolve(download(res.headers.location, redirects - 1));
+      }
+      if (res.statusCode !== 200) {
+        res.resume();
+        return reject(new Error(`HTTP ${res.statusCode} for ${url}`));
+      }
+      resolve(res);
+    }).on("error", reject);
+  });
+}
+
+async function main() {
+  if (existsSync(BIN)) return;
+
+  if (existsSync(BUNDLED)) {
+    console.log(`[mmpl] extracting bundled ${PLATFORM} binary ...`);
+    if (IS_WIN) extractWindows(BUNDLED);
+    else extractLinux(BUNDLED);
+    console.log(`[mmpl] installed: ${BIN}`);
+    return;
+  }
+
+  console.log(`[mmpl] downloading Rust binary v${VERSION} (${PLATFORM}-${ARCH}) ...`);
+  try {
+    const res = await download(URL);
+    const tmpFile = BIN + (IS_WIN ? ".zip.download" : ".tar.gz");
+    await pipeline(res, createWriteStream(tmpFile));
+    if (IS_WIN) extractWindows(tmpFile);
+    else extractLinux(tmpFile);
+    execSync(`rm -f ${JSON.stringify(tmpFile)}`);
+    console.log(`[mmpl] installed: ${BIN}`);
+  } catch (e) {
+    console.warn(`[mmpl] ⚠️ install failed: ${e.message}`);
+    console.warn(`[mmpl] 手动安装: curl -LO ${URL}`);
+    process.exit(0);
+  }
+}
+
+main();

package/package.json

@@ -1,47 +1,37 @@
 {
   "name": "@cup319/mmpl",
-  "version": "2.8.1",
+  "version": "3.0.0",
+  "description": "MMPL (Memory Palace) — 单二进制 DuckDB 记忆 MCP Server (9 工具 + ONNX 语义向量 + 冲突双通道门控 + 场景构建 + 四层钻取) — Linux + Windows 双平台",
+  "license": "MIT",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
-  "description": "MMPL (Memory Palace) — DuckDB 向量记忆系统 (L0-L3 分层 + SM-2 衰减 + 符号压缩 + 9 精简工具)",
-  "type": "module",
-  "main": "dist/index.js",
   "bin": {
-    "mmpl": "dist/index.js"
+    "mmpl": "run.js"
   },
+  "files": [
+    "install.js",
+    "run.js",
+    "README.md",
+    "mmpl-v3.0.0-linux-x86_64.tar.gz",
+    "mmpl-v3.0.0-windows-x86_64.zip"
+  ],
   "scripts": {
-    "build": "tsup",
-    "dev": "tsx src/index.ts",
-    "start": "node dist/index.js",
-    "start:http": "node dist/index.js",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "lint": "tsc --noEmit",
-    "inspector": "npx @modelcontextprotocol/inspector node dist/index.js"
+    "postinstall": "node install.js"
   },
   "keywords": [
     "mcp",
     "memory",
     "palace",
-    "spaced-repetition",
-    "ai-agent"
+    "duckdb",
+    "ai-agent",
+    "windows",
+    "linux"
   ],
-  "license": "MIT",
-  "dependencies": {
-    "@huggingface/transformers": "^4.2.0",
-    "@modelcontextprotocol/sdk": "^1.12.1",
-    "@node-rs/jieba": "^2.0.1",
-    "duckdb": "^1.4.4",
-    "onnxruntime-node": "^1.26.0"
-  },
-  "devDependencies": {
-    "@types/better-sqlite3": "^7.6.13",
-    "@types/node": "^22.15.0",
-    "tsup": "^8.4.0",
-    "tsx": "^4.19.0",
-    "typescript": "^5.8.0",
-    "vitest": "^3.1.0"
+  "repository": {
+    "type": "git",
+    "url": "https://cnb.cool/cnb-t/MMPL.git",
+    "directory": "rust"
   }
 }

package/run.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+/** bin 入口：转发到下载好的二进制（双平台） */
+const { spawn } = require("child_process");
+const path = require("path");
+
+const BIN = path.join(__dirname, "bin", process.platform === "win32" ? "mmpl.exe" : "mmpl");
+const child = spawn(BIN, process.argv.slice(2), {
+  stdio: "inherit",
+  env: process.env,
+});
+child.on("error", (e) => {
+  console.error("[mmpl] binary not found — run `npm rebuild @cup319/mmpl` or see README");
+  process.exit(1);
+});
+child.on("exit", (code) => process.exit(code ?? 1));