@cup319/mmpl 2.7.0 → 2.8.0

package/README.md

@@ -7,7 +7,7 @@
 
 ## 核心特性
 
-- **8 个精简工具**：write、search、manage、evolve、compress、palace、symbol、stats
+- **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 间隔复习）
@@ -140,7 +140,7 @@ curl http://127.0.0.1:7680/
 { "type": "summary" }
 ```
 
-到这里你已经跑通了完整闭环。8 个工具的完整说明见下文「工具一览」。
+到这里你已经跑通了完整闭环。9 个工具的完整说明见下文「工具一览」。
 
 > **常驻保活**：HTTP server 自身不会自我守护。Windows 推荐 `nssm install MMPL node D:\path\to\dist\index.js`，Linux/macOS 推荐 `systemd` 或 `pm2 start dist/index.js --name mmpl`。
 
@@ -181,6 +181,29 @@ HTTP server 启动后不自我守护，靠外部保活：
 
 > 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 标签。
@@ -208,6 +231,7 @@ v2.5.1 之前默认走 stdio，每个 client 各 spawn 一个进程。该模式
 |------|------|
 | `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） |

package/dist/index.js

@@ -943,6 +943,40 @@ var Storage = class _Storage {
     `);
     return rows.map((r) => this.rowToMemory(r));
   }
+  /**
+   * 分页列出记忆，支持按 status / type / permanent / 强度区间 / 关键词过滤，
+   * 支持白名单字段排序。返回 { items, total } —— total 是过滤后总条数
+   * （不受分页影响），用于客户端计算 has_more / 总页数。
+   *
+   * 与 getActiveMemories/getMemoriesByStatus 的区别：本方法做确定性分页浏览，
+   * 不依赖语义检索，专供 memory_list 工具浏览全库使用。
+   */
+  async listMemories(opts) {
+    const conditions = [];
+    if (opts.status) conditions.push(`status = '${this.escape(opts.status)}'`);
+    if (opts.type) conditions.push(`type = '${this.escape(opts.type)}'`);
+    if (opts.permanent !== void 0) conditions.push(`permanent = ${opts.permanent ? "true" : "false"}`);
+    if (opts.minStrength !== void 0) conditions.push(`strength >= ${Number(opts.minStrength)}`);
+    if (opts.maxStrength !== void 0) conditions.push(`strength <= ${Number(opts.maxStrength)}`);
+    if (opts.q) conditions.push(`content LIKE '%${this.escape(opts.q)}%'`);
+    const where = conditions.length ? `WHERE ${conditions.join(" AND ")}` : "";
+    const validOrderBy = /* @__PURE__ */ new Set([
+      "created_at",
+      "strength",
+      "importance",
+      "last_accessed",
+      "access_count"
+    ]);
+    const orderBy = validOrderBy.has(opts.orderBy ?? "") ? opts.orderBy : "created_at";
+    const order = opts.order === "asc" ? "ASC" : "DESC";
+    const limit = Math.min(Math.max(opts.limit ?? 20, 1), 500);
+    const offset = Math.max(opts.offset ?? 0, 0);
+    const total = this.N((await this.get(`SELECT COUNT(*) as c FROM memories ${where}`))?.c) ?? 0;
+    const rows = await this.all(
+      `SELECT * FROM memories ${where} ORDER BY ${orderBy} ${order} LIMIT ${limit} OFFSET ${offset}`
+    );
+    return { items: rows.map((r) => this.rowToMemory(r)), total };
+  }
   async updateMemoryBatch(ids, updates) {
     for (const id of ids) {
       await this.updateMemory(id, updates);
@@ -21662,6 +21696,111 @@ async function handleMetrics(deps) {
   return { content: [{ type: "text", text: JSON.stringify({ metrics, report }, null, 2) }] };
 }
 
+// src/tools/memory-list.ts
+var TRUNC_LIGHT = 100;
+function serializeLight(m, fullContent) {
+  const item = {
+    memory_id: m.id,
+    type: m.type,
+    status: m.status,
+    strength: Number(m.strength?.toFixed(3)),
+    permanent: m.permanent
+  };
+  if (fullContent || m.content.length <= TRUNC_LIGHT) {
+    item.content = m.content;
+    item.content_length = m.content.length;
+  } else {
+    item.content = m.content.slice(0, TRUNC_LIGHT) + "...";
+    item.content_length = m.content.length;
+    item.content_truncated = true;
+  }
+  item.created_at_iso = m.created_at ? new Date(m.created_at).toISOString() : null;
+  return item;
+}
+function serializeDetail(m, fullContent) {
+  const TRUNC_DETAIL = 300;
+  const item = {
+    memory_id: m.id,
+    type: m.type,
+    status: m.status,
+    strength: Number(m.strength?.toFixed(3)),
+    importance: Number(m.importance?.toFixed(3)),
+    permanent: m.permanent,
+    tags: m.tags,
+    access_count: m.access_count,
+    created_at: m.created_at,
+    created_at_iso: m.created_at ? new Date(m.created_at).toISOString() : null,
+    last_accessed: m.last_accessed,
+    last_accessed_iso: m.last_accessed ? new Date(m.last_accessed).toISOString() : null,
+    anchor_id: m.anchor_id,
+    compressed: m.compressed
+  };
+  if (fullContent || m.content.length <= TRUNC_DETAIL) {
+    item.content = m.content;
+    item.content_length = m.content.length;
+  } else {
+    item.content = m.content.slice(0, TRUNC_DETAIL) + "...";
+    item.content_length = m.content.length;
+    item.content_truncated = true;
+  }
+  return item;
+}
+function registerMemoryList(server, deps) {
+  server.tool(
+    "memory_list",
+    "\u5217\u51FA\u8BB0\u5FC6\uFF1A\u5206\u9875\u67E5\u8BE2\u3001\u6309\u7C7B\u578B/\u72B6\u6001/\u5F3A\u5EA6/\u5173\u952E\u8BCD\u8FC7\u6EE4\u3001\u652F\u6301\u6392\u5E8F",
+    {
+      status: external_exports.enum(["active", "infrequent", "archived"]).optional().describe("\u72B6\u6001\u8FC7\u6EE4\uFF1B\u4E0D\u4F20=\u5168\u90E8"),
+      type: external_exports.enum(["fact", "preference", "instruction", "event", "skill"]).optional().describe("\u7C7B\u578B\u8FC7\u6EE4"),
+      permanent: external_exports.boolean().optional().describe("\u53EA\u770B\u6C38\u4E45\u8BB0\u5FC6\uFF08true\uFF09/\u53EA\u770B\u975E\u6C38\u4E45\uFF08false\uFF09\uFF1B\u4E0D\u4F20=\u5168\u90E8"),
+      min_strength: external_exports.number().optional().describe("\u6700\u4F4E\u5F3A\u5EA6\u8FC7\u6EE4\uFF080-1\uFF09"),
+      max_strength: external_exports.number().optional().describe("\u6700\u9AD8\u5F3A\u5EA6\u8FC7\u6EE4\uFF080-1\uFF09"),
+      q: external_exports.string().optional().describe("\u5173\u952E\u8BCD\u6A21\u7CCA\u5339\u914D\uFF08LIKE\uFF09\uFF0C\u53EF\u9009"),
+      order_by: external_exports.enum(["created_at", "strength", "importance", "last_accessed", "access_count"]).optional().describe("\u6392\u5E8F\u5B57\u6BB5\uFF0C\u9ED8\u8BA4 created_at"),
+      order: external_exports.enum(["asc", "desc"]).optional().describe("\u6392\u5E8F\u65B9\u5411\uFF0C\u9ED8\u8BA4 desc"),
+      limit: external_exports.number().optional().describe("\u6BCF\u9875\u6570\u91CF\uFF0C\u9ED8\u8BA4 20\uFF0C\u786C\u4E0A\u9650 500"),
+      offset: external_exports.number().optional().describe("\u504F\u79FB\u91CF\uFF0C\u9ED8\u8BA4 0"),
+      detail: external_exports.boolean().optional().describe("\u8FD4\u56DE\u5168\u5B57\u6BB5\uFF08importance/tags/access_count \u7B49\uFF09\uFF1B\u9ED8\u8BA4 false \u53EA\u8FD4\u56DE\u6838\u5FC3\u5B57\u6BB5"),
+      full_content: external_exports.boolean().optional().describe("\u8FD4\u56DE\u5B8C\u6574 content\uFF08\u9ED8\u8BA4 light \u622A\u65AD\u5230 100 \u5B57\u7B26\uFF0Cdetail \u622A\u65AD\u5230 300\uFF09")
+    },
+    async (params) => {
+      const { storage } = deps;
+      const limit = Math.min(Math.max(params.limit ?? 20, 1), 500);
+      const offset = Math.max(params.offset ?? 0, 0);
+      const fullContent = params.full_content ?? false;
+      const detail = params.detail ?? false;
+      const { items, total } = await storage.listMemories({
+        status: params.status,
+        type: params.type,
+        permanent: params.permanent,
+        minStrength: params.min_strength,
+        maxStrength: params.max_strength,
+        q: params.q,
+        orderBy: params.order_by,
+        order: params.order,
+        limit,
+        offset
+      });
+      const serialized = items.map(
+        (m) => detail ? serializeDetail(m, fullContent) : serializeLight(m, fullContent)
+      );
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            items: serialized,
+            total,
+            limit,
+            offset,
+            mode: detail ? "detail" : "light",
+            has_more: offset + items.length < total
+          }, null, 2)
+        }]
+      };
+    }
+  );
+}
+
 // src/index.ts
 BigInt.prototype.toJSON = function() {
   return Number(this);
@@ -21748,7 +21887,7 @@ async function main() {
   const createMcpServer = () => {
     const server = new McpServer({
       name: "MMPL",
-      version: "2.7.0"
+      version: "2.8.0"
     });
     registerMemoryWrite(server, deps);
     registerMemorySearch(server, deps);
@@ -21758,6 +21897,7 @@ async function main() {
     registerMemoryPalace(server, deps);
     registerMemorySymbol(server, deps);
     registerMemoryStats(server, deps);
+    registerMemoryList(server, deps);
     return server;
   };
   const httpHost = process.env.MCP_HTTP_HOST ?? "127.0.0.1";
@@ -21771,7 +21911,7 @@ async function main() {
   void embeddingService.ready().catch((err) => {
     console.error("[startup] embedding service init failed:", err);
   });
-  console.error(`MMPL (Memory Palace) MCP Server v2.7.0 listening on http://${httpHost}:${httpPort}${httpPath}`);
+  console.error(`MMPL (Memory Palace) MCP Server v2.8.0 listening on http://${httpHost}:${httpPort}${httpPath}`);
   const gracefulShutdown = async (signal) => {
     console.error(`
 [shutdown] Received ${signal}, gracefully shutting down...`);