oh-memos-mcp 3.1.5 → 3.1.6

package/CHANGELOG.md

@@ -6,6 +6,89 @@ This project follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [3.1.6] - 2026-08-26
+
+仅 MCP server（npm `oh-memos-mcp`）。Python 包与容器镜像无改动，仍为 3.1.5。
+
+### 🔤 `memos_canvas` 的 ref 里，引号读不回来
+
+`ref` 走 JSON 转义而非标签转义，因为 Windows 路径的反斜杠必须逐字返回，
+否则锚点失效。但 `renderRef` 在 `JSON.stringify` 之后又替换了一次裸引号：
+
+```js
+JSON.stringify(ref).slice(1, -1).replace(/"/g, "\\u0022")   // 旧
+```
+
+`JSON.stringify` 已经把 `"` 写成 `\"`。那个 `replace` 只匹配裸引号，
+**JSON 留下的反斜杠还在前面**，于是落盘成 `\\u0022`；`parseRef` 走 `JSON.parse`，
+`\\` 解成一个字面反斜杠，取回 `"` 而不是 `"`。少匹配了一个反斜杠。
+
+现在匹配 `\"` 整体：`.replace(/\\"/g, "\\u0022")`。引号仍须离开标签 ——
+`"` 会提前终止它所在的 Mermaid `["..."]` —— 但这次是**替换**已转义的序列，
+不是在它上面再叠一层。
+
+反斜杠一侧一直是对的：`\\` 就是 JSON 在磁盘上的正确表示，`parseRef` 会解回单反斜杠。
+只有引号这一条路径坏了。
+
+### 🗑️ `memos_canvas` 新增 `delete` 动作
+
+此前只有 open/update/show/list，清理必须手动删 `.mmd`。而画布的定位是**短期**状态，
+注定会产生废弃文件 —— 加之全局规则禁止手工改动记忆文件，等于没有合法的清理路径。
+
+`action="delete"` 在有未完成节点（doing/todo/blocked）时**拒绝**并给出逃生口，
+全 done 或空画布直接删：
+
+```
+❌ Canvas '000-x' still has 1 unfinished node (0 doing · 0 todo · 1 blocked)
+   Review it first: memos_canvas(action="show", name="000-x")
+   Delete anyway:   memos_canvas(action="delete", name="000-x", confirm=true)
+```
+
+**没有套用 `MEMOS_ENABLE_DELETE`**。那道门是保护长期记忆的：走 API、有 embedding 成本、
+且 Lite 模式下整个禁用。画布是本地文件、不走 API，而 Lite 模式下它恰恰是少数可用功能之一 ——
+套上那道门等于在最需要清理的模式里砍掉清理能力。`confirm` 这种「拒绝并给出下一步」
+与 `MAX_NODES`、非法 status 是同一个既有模式。
+
+删除是硬删，不做回收站：画布存在的意义就是任务收尾后被丢弃，
+回收站只会攒下它本该清掉的文件。`deleteCanvas` 复用 `canvasPath`，遍历防护自动继承。
+
+### 🔢 前缀水位线：`delete` 破坏了「前缀永不复用」
+
+加上 delete 之后有两个 e2e 断言失败。**不是断言写错** —— `nextPrefix` 用现存文件算
+`max+1`，在只增不减的世界里「前缀永不复用」自动成立，delete 打破了这个不变量：
+删掉最高前缀的画布后，那个前缀会被重新发放。
+
+后果正是 `nextPrefix` 自己注释里警告过的：前缀嵌在它铸出的每个节点 id 里，
+commit message 或记忆正文引用的 `001-N3` 会变得指向两个不同画布的节点。
+
+修法是 `{cube}/canvas/.prefix-hwm` 水位线文件，`saveCanvas` 与 `deleteCanvas` 都抬升它，
+只增不减。delete 侧必须抬升：文件是该前缀唯一的记录，删掉后若水位线仍低于它，
+就会被重新发放。旧 cube 没有这个文件时（`readPrefixHwm` 返回 -1），
+从现存文件恢复下限，所以升级不会因为水位线缺失而复用前缀。
+
+水位线损坏或不可读时退回扫描文件，与 `parseCanvas` 一致 ——
+画布是恢复态，读取时机正是刚丢失上下文的那一刻，抛异常是最坏的选择。
+
+### 🧪 测试
+
+canvas 单测 41 → 45（format）、28 → 44（store），canvas e2e 15 → 31 项。
+两个修复都做了反向验证，还原实现后对应用例确实变红：转义 3 项、水位线 1 项（含 delete 侧那次抬升）。
+
+e2e 补了「旧 cube（无水位线）删除后不复用前缀」这条真实升级路径 ——
+它跨 store 与 handler，单测碰不到。
+
+顺带改掉一个自己写坏的用例：名字叫 "does not free the prefix it used"，
+断言却在验证前缀被释放了。名字与断言矛盾的测试比没有测试更坏。
+
+`memos_canvas` 的 schema 改了（action enum 加 `delete`，新增 `confirm`），
+两处冻结的哈希同步重算：`schema-semantic-baseline.json` 与
+`protocol-contract.test.ts` 的 `EXPECTED_SCHEMA_HASHES`。
+
+门禁：vitest 511 passed、tsc、canvas e2e 31 项、pack 契约 104 文件、
+schema budget +0.8%（限 5%）、semantic 快照 17 工具、protocol v2、lite smoke。
+
+---
+
 ## [3.1.5] - 2026-08-26
 
 3.1.1～3.1.4 都是「仅 MCP server」的版本，Python 包与容器镜像停在 3.1.0。

package/README.md

@@ -327,7 +327,7 @@ only when `MEMOS_ENABLE_DELETE=true`; the other 16 are available by default.
 | `memos_admin` | Maintenance — `action`: `list_cubes` / `register_cube` / `create_user` / `validate_cubes` / `stats` / `calendar` |
 | `memos_export_wiki` | Export a cube as an interlinked markdown wiki (page per memory + index + mermaid graph) |
 | `memos_import_wiki` | Import an exported wiki back into a cube; supports dry-run and versioning edited pages, never deletes memories |
-| `memos_canvas` | Symbolic task canvas — short-term task state that survives context compaction. `action`: `open` / `update` / `show` / `list`. Nodes carry greppable ids (`000-N1`) and a `ref` anchoring them to evidence: `mem:<memory_id>` / `file:<path>` / `note:<text>` |
+| `memos_canvas` | Symbolic task canvas — short-term task state that survives context compaction. `action`: `open` / `update` / `show` / `list` / `delete` (a canvas with unfinished nodes needs `confirm=true`). Nodes carry greppable ids (`000-N1`) and a `ref` anchoring them to evidence: `mem:<memory_id>` / `file:<path>` / `note:<text>` |
 | `memos_distill_skill` | Create an inert, reviewable Skill candidate under `<project_path>/skill-candidates`; it never installs the candidate automatically |
 | `memos_list_skill_candidates` | List generated Skill candidates without modifying or installing them |
 | `memos_review_skill_candidate` | Approve or reject a candidate with reviewer audit metadata; approval does not install |

package/dist/canvas-format.js

@@ -123,9 +123,19 @@ export function allocateNodeId(canvas) {
  * Windows paths are the reason: `C:\Users\x` contains backslashes, which JSON
  * escapes and which must come back byte-identical or the anchor stops resolving.
  * Label escaping is for prose; refs get JSON, which is lossless.
+ *
+ * One transform sits on top of JSON: `JSON.stringify` renders a quote as `\"`,
+ * and that bare quote would still close the Mermaid label. Promoting the whole
+ * two-character escape to `\u0022` keeps the label intact while staying valid
+ * JSON, so `parseRef` decodes it back to `"`.
+ *
+ * The `\\` in the pattern is load-bearing. Replacing only the quote leaves
+ * JSON's backslash in front of the substitution, producing `\\u0022` — which
+ * JSON.parse reads as a literal backslash followed by `u0022`, so a ref
+ * containing a quote comes back as the text `\u0022` instead of the quote.
  */
 function renderRef(ref) {
-    return JSON.stringify(ref).slice(1, -1).replace(/"/g, "\\u0022");
+    return JSON.stringify(ref).slice(1, -1).replace(/\\"/g, "\\u0022");
 }
 function parseRef(raw) {
     try {
@@ -142,10 +152,7 @@ export function renderCanvas(canvas) {
         updatedTime: canvas.updatedTime,
         prefix: canvas.prefix,
     };
-    const lines = [
-        `%%${JSON.stringify(meta)}%%`,
-        "graph LR",
-    ];
+    const lines = [`%%${JSON.stringify(meta)}%%`, "graph LR"];
     for (const node of canvas.nodes) {
         const parts = [
             `status: ${node.status}`,
@@ -192,9 +199,12 @@ export function parseCanvas(content) {
         try {
             const raw = metaMatch[0].slice(2, -2);
             const parsed = JSON.parse(raw);
-            canvas.taskGoal = typeof parsed.taskGoal === "string" ? parsed.taskGoal : "";
-            canvas.createdTime = typeof parsed.createdTime === "string" ? parsed.createdTime : null;
-            canvas.updatedTime = typeof parsed.updatedTime === "string" ? parsed.updatedTime : null;
+            canvas.taskGoal =
+                typeof parsed.taskGoal === "string" ? parsed.taskGoal : "";
+            canvas.createdTime =
+                typeof parsed.createdTime === "string" ? parsed.createdTime : null;
+            canvas.updatedTime =
+                typeof parsed.updatedTime === "string" ? parsed.updatedTime : null;
             if (typeof parsed.prefix === "string" && /^\d{3}$/.test(parsed.prefix)) {
                 canvas.prefix = parsed.prefix;
                 prefixFromHeader = true;

package/dist/canvas-store.d.ts

@@ -35,6 +35,24 @@ export declare function canvasPath(cubesDir: string, cubeId: string, name: strin
 export declare function loadCanvas(cubesDir: string, cubeId: string, name: string): Canvas | null;
 /** Writes atomically and returns the path written. */
 export declare function saveCanvas(cubesDir: string, cubeId: string, name: string, canvas: Canvas): string;
+/**
+ * Remove a canvas file. Returns false when it was not there to begin with.
+ *
+ * Deliberately not atomic and deliberately not a soft delete. A canvas is
+ * short-term state whose whole purpose is to be discarded once the task closes;
+ * a trash directory would just accumulate the files this exists to remove. The
+ * decision about whether losing this particular canvas is acceptable belongs to
+ * the caller, which is why the handler asks before reaching this function.
+ *
+ * `canvasPath` runs first, so a traversal-shaped name throws rather than
+ * unlinking something outside the canvas directory.
+ *
+ * The watermark is raised before the unlink, because the file is the only other
+ * record of the prefix and it is about to stop existing. A cube written before
+ * the watermark existed has none, so without this the delete would leave no
+ * trace of the prefix at all and `nextPrefix` would reissue it.
+ */
+export declare function deleteCanvas(cubesDir: string, cubeId: string, name: string): boolean;
 export interface CanvasEntry {
     /** Filename without the extension — the handle callers pass back in. */
     name: string;
@@ -57,6 +75,12 @@ export declare function listCanvases(cubesDir: string, cubeId: string): CanvasEn
  * two canvases' ids ambiguous. Returning null instead of wrapping keeps the
  * failure visible — a caller that has 1000 canvases in one cube has a different
  * problem than a naming collision.
+ *
+ * The watermark is consulted alongside the files on disk because `deleteCanvas`
+ * exists: deriving the maximum from surviving files alone would hand a deleted
+ * canvas's prefix to the next one, which is the ambiguity this function is
+ * written to avoid. Files are still scanned so that a cube predating the
+ * watermark, or one whose watermark was lost, allocates correctly.
  */
 export declare function nextPrefix(cubesDir: string, cubeId: string): string | null;
 //# sourceMappingURL=canvas-store.d.ts.map

package/dist/canvas-store.js

@@ -19,7 +19,7 @@
  */
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
 import { basename, join, resolve, sep } from "node:path";
-import { parseCanvas, renderCanvas, slugify } from "./canvas-format.js";
+import { parseCanvas, renderCanvas, slugify, } from "./canvas-format.js";
 export class CanvasPathError extends Error {
     constructor(message) {
         super(message);
@@ -28,6 +28,18 @@ export class CanvasPathError extends Error {
 }
 const CANVAS_DIR = "canvas";
 const CANVAS_EXT = ".mmd";
+/**
+ * Highest prefix ever issued in this cube, kept outside the canvas files.
+ *
+ * Without it, `nextPrefix` derives the watermark from the files that happen to
+ * exist, and deleting the newest canvas hands its prefix to the next one — which
+ * is exactly the id ambiguity `nextPrefix` refuses to create. The name starts
+ * with a dot and does not end in `.mmd`, so `slugify` can never mint it and
+ * `listCanvases` never reads it as a canvas.
+ */
+const PREFIX_HWM_FILE = ".prefix-hwm";
+/** Leading three digits of a canvas name — the prefix it minted its ids from. */
+const PREFIX_RE = /^(\d{3})/;
 /** `cube_id` is machine-derived (`detectCubeFromPath`), so this is a shape check
  *  rather than a sanitiser — a value that does not look like a cube id is a bug
  *  upstream, and guessing at what it meant would hide it. */
@@ -71,7 +83,8 @@ export function canvasPath(cubesDir, cubeId, name) {
     const dir = resolve(cubesDir, rawCube, CANVAS_DIR);
     const full = resolve(dir, `${slug}${CANVAS_EXT}`);
     const dirWithSep = dir.endsWith(sep) ? dir : dir + sep;
-    if (!full.startsWith(dirWithSep) || basename(full) !== `${slug}${CANVAS_EXT}`) {
+    if (!full.startsWith(dirWithSep) ||
+        basename(full) !== `${slug}${CANVAS_EXT}`) {
         throw new CanvasPathError(`resolved path escapes the canvas directory: ${full}`);
     }
     return full;
@@ -120,8 +133,41 @@ export function saveCanvas(cubesDir, cubeId, name, canvas) {
         }
         throw err;
     }
+    // After the rename, so a failed write never advances the watermark. Recorded
+    // on every save rather than only on create: it is idempotent, and a cube whose
+    // watermark was lost recovers it on the next update to any canvas.
+    const m = PREFIX_RE.exec(name);
+    if (m)
+        bumpPrefixHwm(cubesDir, cubeId, m[1]);
     return path;
 }
+/**
+ * Remove a canvas file. Returns false when it was not there to begin with.
+ *
+ * Deliberately not atomic and deliberately not a soft delete. A canvas is
+ * short-term state whose whole purpose is to be discarded once the task closes;
+ * a trash directory would just accumulate the files this exists to remove. The
+ * decision about whether losing this particular canvas is acceptable belongs to
+ * the caller, which is why the handler asks before reaching this function.
+ *
+ * `canvasPath` runs first, so a traversal-shaped name throws rather than
+ * unlinking something outside the canvas directory.
+ *
+ * The watermark is raised before the unlink, because the file is the only other
+ * record of the prefix and it is about to stop existing. A cube written before
+ * the watermark existed has none, so without this the delete would leave no
+ * trace of the prefix at all and `nextPrefix` would reissue it.
+ */
+export function deleteCanvas(cubesDir, cubeId, name) {
+    const path = canvasPath(cubesDir, cubeId, name);
+    if (!existsSync(path))
+        return false;
+    const m = PREFIX_RE.exec(name);
+    if (m)
+        bumpPrefixHwm(cubesDir, cubeId, m[1]);
+    unlinkSync(path);
+    return true;
+}
 /**
  * Every canvas in a cube, sorted by name.
  *
@@ -147,7 +193,11 @@ export function listCanvases(cubesDir, cubeId) {
         const name = file.slice(0, -CANVAS_EXT.length);
         const path = join(dir, file);
         try {
-            entries.push({ name, path, canvas: parseCanvas(readFileSync(path, "utf8")) });
+            entries.push({
+                name,
+                path,
+                canvas: parseCanvas(readFileSync(path, "utf8")),
+            });
         }
         catch {
             continue; // unreadable file should not hide the readable ones
@@ -159,7 +209,47 @@ export function listCanvases(cubesDir, cubeId) {
 // ============================================================================
 // Prefix allocation
 // ============================================================================
-const PREFIX_RE = /^(\d{3})/;
+function prefixHwmPath(cubesDir, cubeId) {
+    const dir = canvasDirFor(cubesDir, cubeId);
+    return dir ? join(dir, PREFIX_HWM_FILE) : null;
+}
+/**
+ * Highest prefix ever issued, or -1 when there is no usable record.
+ *
+ * Any unreadable or out-of-range value reads as -1 rather than throwing: losing
+ * the watermark degrades allocation back to filesystem-derived, which is a
+ * weaker guarantee but not a broken one.
+ */
+function readPrefixHwm(cubesDir, cubeId) {
+    const path = prefixHwmPath(cubesDir, cubeId);
+    if (!path || !existsSync(path))
+        return -1;
+    try {
+        const n = Number(readFileSync(path, "utf8").trim());
+        return Number.isInteger(n) && n >= 0 && n <= 999 ? n : -1;
+    }
+    catch {
+        return -1;
+    }
+}
+/** Raise the watermark to `prefix` if that is higher. Never lowers it. */
+function bumpPrefixHwm(cubesDir, cubeId, prefix) {
+    const path = prefixHwmPath(cubesDir, cubeId);
+    if (!path)
+        return;
+    const n = Number(prefix);
+    if (!Number.isInteger(n) || n < 0 || n > 999)
+        return;
+    if (n <= readPrefixHwm(cubesDir, cubeId))
+        return;
+    try {
+        writeFileSync(path, String(n), "utf8");
+    }
+    catch {
+        // Best effort. A canvas that saved but failed to record its prefix is
+        // still a usable canvas; refusing the save would be the worse trade.
+    }
+}
 /**
  * Next unused three-digit canvas prefix, or null once 999 is taken.
  *
@@ -168,9 +258,15 @@ const PREFIX_RE = /^(\d{3})/;
  * two canvases' ids ambiguous. Returning null instead of wrapping keeps the
  * failure visible — a caller that has 1000 canvases in one cube has a different
  * problem than a naming collision.
+ *
+ * The watermark is consulted alongside the files on disk because `deleteCanvas`
+ * exists: deriving the maximum from surviving files alone would hand a deleted
+ * canvas's prefix to the next one, which is the ambiguity this function is
+ * written to avoid. Files are still scanned so that a cube predating the
+ * watermark, or one whose watermark was lost, allocates correctly.
  */
 export function nextPrefix(cubesDir, cubeId) {
-    let max = -1;
+    let max = readPrefixHwm(cubesDir, cubeId);
     for (const entry of listCanvases(cubesDir, cubeId)) {
         const m = PREFIX_RE.exec(entry.name);
         if (!m)

package/dist/handlers/canvas.js

@@ -28,7 +28,7 @@
  */
 import { MEMOS_CUBES_DIR } from "../config.js";
 import { NODE_STATUSES, allocateNodeId, countByStatus, formatCanvasHeadline, slugify, truncateSummary, } from "../canvas-format.js";
-import { CanvasPathError, listCanvases, loadCanvas, nextPrefix, saveCanvas, } from "../canvas-store.js";
+import { CanvasPathError, deleteCanvas, listCanvases, loadCanvas, nextPrefix, saveCanvas, } from "../canvas-store.js";
 import { ERR_PARAM_INVALID, ERR_PARAM_MISSING, ERR_OPERATION_FAILED, errorResponse, getCubeIdFromArgs, } from "./utils.js";
 const STATUS_LIST = NODE_STATUSES.join(", ");
 /** Ceiling on nodes in one canvas. Past this the canvas has stopped being a
@@ -36,14 +36,20 @@ const STATUS_LIST = NODE_STATUSES.join(", ");
 const MAX_NODES = 40;
 function statusIcon(status) {
     switch (status) {
-        case "done": return "✓";
-        case "doing": return "▶";
-        case "blocked": return "✗";
-        default: return "○";
+        case "done":
+            return "✓";
+        case "doing":
+            return "▶";
+        case "blocked":
+            return "✗";
+        default:
+            return "○";
     }
 }
 function parseStatus(raw) {
-    const value = String(raw ?? "").trim().toLowerCase();
+    const value = String(raw ?? "")
+        .trim()
+        .toLowerCase();
     return NODE_STATUSES.includes(value)
         ? value
         : null;
@@ -126,14 +132,16 @@ function actionOpen(cubeId, args) {
     };
     try {
         const path = saveCanvas(MEMOS_CUBES_DIR, cubeId, name, canvas);
-        return [{
+        return [
+            {
                 type: "text",
                 text: [
                     renderCanvasView(name, path, canvas),
                     "",
                     `Canvas \`${name}\` created. Node ids will be \`${prefix}-N1\`, \`${prefix}-N2\`, …`,
                 ].join("\n"),
-            }];
+            },
+        ];
     }
     catch (err) {
         return pathErrorResponse(err);
@@ -189,7 +197,9 @@ function actionUpdate(cubeId, args) {
     else {
         // Append a new node.
         if (summaryRaw === undefined || String(summaryRaw).trim() === "") {
-            return errorResponse("`summary` is required when appending a node", ERR_PARAM_MISSING, ['memos_canvas(action="update", name="...", summary="<step>", status="doing")']);
+            return errorResponse("`summary` is required when appending a node", ERR_PARAM_MISSING, [
+                'memos_canvas(action="update", name="...", summary="<step>", status="doing")',
+            ]);
         }
         if (canvas.nodes.length >= MAX_NODES) {
             return errorResponse(`Canvas '${name}' already has ${MAX_NODES} nodes`, ERR_OPERATION_FAILED, [
@@ -212,7 +222,8 @@ function actionUpdate(cubeId, args) {
     canvas.updatedTime = new Date().toISOString();
     try {
         const path = saveCanvas(MEMOS_CUBES_DIR, cubeId, name, canvas);
-        return [{
+        return [
+            {
                 type: "text",
                 text: [
                     `${statusIcon(touched.status)} \`${touched.id}\` ${touched.summary}` +
@@ -220,7 +231,8 @@ function actionUpdate(cubeId, args) {
                     "",
                     renderCanvasView(name, path, canvas),
                 ].join("\n"),
-            }];
+            },
+        ];
     }
     catch (err) {
         return pathErrorResponse(err);
@@ -241,18 +253,84 @@ function actionShow(cubeId, args) {
         return pathErrorResponse(err);
     }
     if (canvas === null) {
-        return errorResponse(`Canvas '${name}' not found in cube '${cubeId}'`, ERR_PARAM_INVALID, [
-            'List canvases: `memos_canvas(action="list", project_path="<cwd>")`',
-        ]);
+        return errorResponse(`Canvas '${name}' not found in cube '${cubeId}'`, ERR_PARAM_INVALID, ['List canvases: `memos_canvas(action="list", project_path="<cwd>")`']);
     }
     // Recompute the path for display only; load already proved it resolves.
     const entry = listCanvases(MEMOS_CUBES_DIR, cubeId).find((e) => e.name === name);
-    return [{ type: "text", text: renderCanvasView(name, entry?.path ?? name, canvas) }];
+    return [
+        { type: "text", text: renderCanvasView(name, entry?.path ?? name, canvas) },
+    ];
+}
+/**
+ * Delete a canvas file.
+ *
+ * A canvas with open work is refused unless `confirm=true`. The asymmetry is the
+ * point: a canvas whose nodes are all `done` is finished bookkeeping and deleting
+ * it needs no ceremony, while one still holding `doing`/`todo`/`blocked` nodes is
+ * the only record of where a task stopped — and that record is most valuable at
+ * exactly the moment the model has lost its context and might delete it by
+ * mistake. The refusal names what would be lost so the decision is informed.
+ *
+ * This is not gated behind MEMOS_ENABLE_DELETE. That gate protects long-term
+ * memories behind the HTTP provider; a canvas is a local file with an
+ * hours-long lifetime, and in Lite mode the canvas is one of the few things that
+ * works — gating it there would remove cleanup precisely where it is needed.
+ */
+function actionDelete(cubeId, args) {
+    const name = String(args.name ?? "").trim();
+    if (!name) {
+        return errorResponse("`name` is required to delete a canvas", ERR_PARAM_MISSING, ['List canvases: `memos_canvas(action="list", project_path="<cwd>")`']);
+    }
+    let canvas;
+    try {
+        canvas = loadCanvas(MEMOS_CUBES_DIR, cubeId, name);
+    }
+    catch (err) {
+        return pathErrorResponse(err);
+    }
+    if (canvas === null) {
+        return errorResponse(`Canvas '${name}' not found in cube '${cubeId}'`, ERR_PARAM_INVALID, ['List canvases: `memos_canvas(action="list", project_path="<cwd>")`']);
+    }
+    const counts = countByStatus(canvas);
+    const open = counts.doing + counts.todo + counts.blocked;
+    if (open > 0 && args.confirm !== true) {
+        return errorResponse(`Canvas '${name}' still has ${open} unfinished node${open === 1 ? "" : "s"} ` +
+            `(${counts.doing} doing · ${counts.todo} todo · ${counts.blocked} blocked)`, ERR_PARAM_INVALID, [
+            `Review it first: \`memos_canvas(action="show", name="${name}")\``,
+            `Delete anyway: \`memos_canvas(action="delete", name="${name}", confirm=true)\``,
+        ]);
+    }
+    try {
+        const removed = deleteCanvas(MEMOS_CUBES_DIR, cubeId, name);
+        if (!removed) {
+            // loadCanvas found it a moment ago, so this is a concurrent delete rather
+            // than a caller mistake. Same end state either way.
+            return [{ type: "text", text: `Canvas \`${name}\` was already gone.` }];
+        }
+        const tally = `${counts.done} done · ${counts.doing} doing · ${counts.todo} todo` +
+            (counts.blocked > 0 ? ` · ${counts.blocked} blocked` : "");
+        return [
+            {
+                type: "text",
+                text: [
+                    `🗑️ Deleted canvas \`${name}\` from \`${cubeId}\` (${canvas.nodes.length} node${canvas.nodes.length === 1 ? "" : "s"}: ${tally})`,
+                    "",
+                    `**Goal was**: ${canvas.taskGoal || "(none recorded)"}`,
+                    "",
+                    "The file is gone — `mem:` refs it cited still exist in the graph.",
+                ].join("\n"),
+            },
+        ];
+    }
+    catch (err) {
+        return pathErrorResponse(err);
+    }
 }
 function actionList(cubeId) {
     const entries = listCanvases(MEMOS_CUBES_DIR, cubeId);
     if (entries.length === 0) {
-        return [{
+        return [
+            {
                 type: "text",
                 text: [
                     `## 🗺️ Canvases: ${cubeId}`,
@@ -261,7 +339,8 @@ function actionList(cubeId) {
                     "",
                     'Open one: `memos_canvas(action="open", goal="<task>", project_path="<cwd>")`',
                 ].join("\n"),
-            }];
+            },
+        ];
     }
     // Unfinished first: after a compaction the open work is the only part that
     // still matters.
@@ -284,7 +363,9 @@ function actionList(cubeId) {
 // ============================================================================
 export async function handleMemosCanvas(arguments_) {
     const cubeId = getCubeIdFromArgs(arguments_);
-    const action = String(arguments_.action ?? "").trim().toLowerCase();
+    const action = String(arguments_.action ?? "")
+        .trim()
+        .toLowerCase();
     switch (action) {
         case "open":
             return actionOpen(cubeId, arguments_);
@@ -294,8 +375,10 @@ export async function handleMemosCanvas(arguments_) {
             return actionShow(cubeId, arguments_);
         case "list":
             return actionList(cubeId);
+        case "delete":
+            return actionDelete(cubeId, arguments_);
         default:
-            return errorResponse(`Unknown canvas action: ${String(arguments_.action ?? "(none)")}`, ERR_PARAM_INVALID, ["Valid actions: open, update, show, list"]);
+            return errorResponse(`Unknown canvas action: ${String(arguments_.action ?? "(none)")}`, ERR_PARAM_INVALID, ["Valid actions: open, update, show, list, delete"]);
     }
 }
 /**

package/dist/tools-registry.d.ts

@@ -212,6 +212,7 @@ export declare const toolSchemas: {
         inputSchema: z.ZodObject<{
             action: z.ZodEnum<{
                 show: "show";
+                delete: "delete";
                 list: "list";
                 update: "update";
                 open: "open";
@@ -229,6 +230,7 @@ export declare const toolSchemas: {
                 blocked: "blocked";
             }>>;
             ref: z.ZodOptional<z.ZodString>;
+            confirm: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>;
     };
     memos_delete: {

package/dist/tools-registry.js

@@ -25,14 +25,26 @@ const cubeIdParam = z
 // Brief variants for every tool except the hot paths (save/search): the full
 // routing story is told once there; repeating it on every tool cost ~1.4k
 // tokens of pure duplication on the tool surface.
-const projectPathBrief = z.string().optional()
+const projectPathBrief = z
+    .string()
+    .optional()
     .describe("Project root; cube_id is derived from it (details: memos_search)");
-const cubeIdBrief = z.string().optional()
+const cubeIdBrief = z
+    .string()
+    .optional()
     .describe("Explicit cube id; prefer project_path");
 const cubeIdBriefDefault = cubeIdBrief.default(MEMOS_DEFAULT_CUBE);
 const memoryTypeEnum = z.enum([
-    "ERROR_PATTERN", "DECISION", "MILESTONE", "BUGFIX",
-    "FEATURE", "CONFIG", "CODE_PATTERN", "GOTCHA", "PROGRESS", "SYNTHESIS",
+    "ERROR_PATTERN",
+    "DECISION",
+    "MILESTONE",
+    "BUGFIX",
+    "FEATURE",
+    "CONFIG",
+    "CODE_PATTERN",
+    "GOTCHA",
+    "PROGRESS",
+    "SYNTHESIS",
 ]);
 // ============================================================================
 // Tool Schema Definitions
@@ -51,15 +63,29 @@ Afterwards use memos tools for ALL memory operations — never mkdir/Write memor
 Query may carry a type prefix ("DECISION auth"). Pass context (recent turns) when the query is ambiguous or refers to earlier conversation — enables LLM intent analysis + query expansion.
 Large results are compacted; use memos_get(memory_id) for full details. NEVER create memory files via mkdir/Write — all memories live here.`,
         inputSchema: z.object({
-            query: z.string().describe("Search query. Can be natural language or prefixed with memory type (e.g., 'ERROR_PATTERN ModuleNotFoundError')"),
-            context: z.array(z.object({
+            query: z
+                .string()
+                .describe("Search query. Can be natural language or prefixed with memory type (e.g., 'ERROR_PATTERN ModuleNotFoundError')"),
+            context: z
+                .array(z.object({
                 role: z.enum(["user", "assistant"]),
                 content: z.string(),
-            })).optional().describe("Recent conversation turns (last 5-10); triggers context-aware search"),
+            }))
+                .optional()
+                .describe("Recent conversation turns (last 5-10); triggers context-aware search"),
             project_path: projectPathParam,
             cube_id: cubeIdParam,
-            top_k: z.number().int().optional().default(10).describe("Max results (default 10)"),
-            compact: z.boolean().optional().default(true).describe("Compact large results (default true)"),
+            top_k: z
+                .number()
+                .int()
+                .optional()
+                .default(10)
+                .describe("Max results (default 10)"),
+            compact: z
+                .boolean()
+                .optional()
+                .default(true)
+                .describe("Compact large results (default true)"),
         }),
     },
     memos_think: {
@@ -69,8 +95,18 @@ YOU synthesize the answer from it, citing [n]; persist valuable syntheses via me
             query: z.string().describe("The question to gather evidence for"),
             project_path: projectPathBrief,
             cube_id: cubeIdBriefDefault,
-            top_k: z.number().int().optional().default(15).describe("Evidence pool size (3-30)"),
-            fresh_days: z.number().int().optional().default(30).describe("Days before time-sensitive memories count as stale"),
+            top_k: z
+                .number()
+                .int()
+                .optional()
+                .default(15)
+                .describe("Evidence pool size (3-30)"),
+            fresh_days: z
+                .number()
+                .int()
+                .optional()
+                .default(30)
+                .describe("Days before time-sensitive memories count as stale"),
         }),
     },
     memos_export_wiki: {
@@ -79,8 +115,15 @@ Default output <project_path>/docs/memory-wiki; re-export replaces only files it
         inputSchema: z.object({
             project_path: projectPathBrief,
             cube_id: cubeIdBriefDefault,
-            output_dir: z.string().optional().describe("Target directory (default: <project_path>/docs/memory-wiki)"),
-            include_archived: z.boolean().optional().default(false).describe("Also export archived memories"),
+            output_dir: z
+                .string()
+                .optional()
+                .describe("Target directory (default: <project_path>/docs/memory-wiki)"),
+            include_archived: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe("Also export archived memories"),
         }),
     },
     memos_import_wiki: {
@@ -89,9 +132,20 @@ Use after editing exported pages (fixes, cleanup, migration to a fresh cube). Re
         inputSchema: z.object({
             project_path: projectPathBrief,
             cube_id: cubeIdBriefDefault,
-            wiki_dir: z.string().optional().describe("Wiki directory (default: <project_path>/docs/memory-wiki)"),
-            dry_run: z.boolean().optional().default(false).describe("Preview the diff without writing (default false)"),
-            on_edit: z.enum(["skip", "version"]).optional().default("skip").describe("Edited pages: skip (default) or save as new version (old memory kept)"),
+            wiki_dir: z
+                .string()
+                .optional()
+                .describe("Wiki directory (default: <project_path>/docs/memory-wiki)"),
+            dry_run: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe("Preview the diff without writing (default false)"),
+            on_edit: z
+                .enum(["skip", "version"])
+                .optional()
+                .default("skip")
+                .describe("Edited pages: skip (default) or save as new version (old memory kept)"),
         }),
     },
     memos_save: {
@@ -99,7 +153,9 @@ Use after editing exported pages (fixes, cleanup, migration to a fresh cube). Re
 🚨 MUST pass memory_type explicitly (decision tree: memos_suggest). In Lite mode this remains the primary durable write path.
 This is the ONLY way to persist memories — never mkdir/Write memory files.`,
         inputSchema: z.object({
-            content: z.string().describe("Memory content. Be detailed — include context, rationale, relevant code/commands."),
+            content: z
+                .string()
+                .describe("Memory content. Be detailed — include context, rationale, relevant code/commands."),
             memory_type: memoryTypeEnum.describe("**REQUIRED**. bug fix → BUGFIX/ERROR_PATTERN · decision → DECISION · gotcha → GOTCHA · " +
                 "template → CODE_PATTERN · config → CONFIG · feature → FEATURE · achievement → MILESTONE · " +
                 "status update → PROGRESS · synthesized answer → SYNTHESIS. Full rules: memos_suggest"),
@@ -112,9 +168,18 @@ This is the ONLY way to persist memories — never mkdir/Write memory files.`,
         inputSchema: z.object({
             project_path: projectPathBrief,
             cube_id: cubeIdBriefDefault,
-            limit: z.number().int().optional().default(20).describe("Max memories returned"),
+            limit: z
+                .number()
+                .int()
+                .optional()
+                .default(20)
+                .describe("Max memories returned"),
             memory_type: memoryTypeEnum.optional().describe("Filter by type"),
-            compact: z.boolean().optional().default(true).describe("Compact large results"),
+            compact: z
+                .boolean()
+                .optional()
+                .default(true)
+                .describe("Compact large results"),
         }),
     },
     memos_get: {
@@ -130,7 +195,9 @@ This is the ONLY way to persist memories — never mkdir/Write memory files.`,
 
 Use when: unsure what to search for, or unsure which memory_type \`memos_save\` should use.`,
         inputSchema: z.object({
-            context: z.string().describe("Current context (error message, code, user question)"),
+            context: z
+                .string()
+                .describe("Current context (error message, code, user question)"),
         }),
     },
     memos_distill_skill: {
@@ -139,7 +206,10 @@ Use when: unsure what to search for, or unsure which memory_type \`memos_save\`
             project_path: projectPathBrief,
             title: z.string().describe("Candidate skill title"),
             summary: z.string().describe("Reviewed workflow summary"),
-            memory_ids: z.array(z.string()).min(1).describe("Evidence memory IDs supporting this workflow"),
+            memory_ids: z
+                .array(z.string())
+                .min(1)
+                .describe("Evidence memory IDs supporting this workflow"),
         }),
     },
     memos_list_skill_candidates: {
@@ -157,21 +227,42 @@ Use when: unsure what to search for, or unsure which memory_type \`memos_save\`
     },
     memos_install_skill_candidate: {
         description: `Install an approved candidate into <project_path>/.claude/skills/<slug>/SKILL.md. Requires explicit action; refuses overwrite, symlinks, malformed candidates, and unapproved status.`,
-        inputSchema: z.object({ project_path: projectPathBrief, candidate_id: z.string() }),
+        inputSchema: z.object({
+            project_path: projectPathBrief,
+            candidate_id: z.string(),
+        }),
     },
     memos_graph: {
         description: `Knowledge-graph queries; mode selects:
 related = nodes+edges around a query · path = trace between two node ids · impact = forward blast radius of one memory · schema = graph structure & statistics · import = validate Graphify node-link JSON (dry-run only).`,
         inputSchema: z.object({
-            mode: z.enum(["related", "path", "impact", "schema", "import"]).describe("Query kind"),
+            mode: z
+                .enum(["related", "path", "impact", "schema", "import"])
+                .describe("Query kind"),
             query: z.string().optional().describe("related: search query"),
             source_id: z.string().optional().describe("path: start node id"),
             target_id: z.string().optional().describe("path: end node id"),
             memory_id: z.string().optional().describe("impact: source memory id"),
-            max_depth: z.number().int().optional().default(3).describe("path/impact: max hops"),
-            sample_size: z.number().int().optional().default(100).describe("schema: nodes sampled"),
-            graph_json: z.string().optional().describe("import: Graphify graph.json contents; validation is dry-run and never writes data"),
-            project_key: z.string().optional().describe("import: stable project namespace label"),
+            max_depth: z
+                .number()
+                .int()
+                .optional()
+                .default(3)
+                .describe("path/impact: max hops"),
+            sample_size: z
+                .number()
+                .int()
+                .optional()
+                .default(100)
+                .describe("schema: nodes sampled"),
+            graph_json: z
+                .string()
+                .optional()
+                .describe("import: Graphify graph.json contents; validation is dry-run and never writes data"),
+            project_key: z
+                .string()
+                .optional()
+                .describe("import: stable project namespace label"),
             project_path: projectPathBrief,
             cube_id: cubeIdBriefDefault,
         }),
@@ -180,35 +271,78 @@ related = nodes+edges around a query · path = trace between two node ids · imp
         description: `Maintenance & diagnostics; action selects:
 list_cubes · register_cube (fix "not loaded") · create_user (fix "user does not exist") · validate_cubes (repair config mismatches) · stats (per-type counts) · calendar (milestone timeline) · capabilities (Full/Lite behavior and unsupported operations).`,
         inputSchema: z.object({
-            action: z.enum(["list_cubes", "register_cube", "create_user", "validate_cubes", "stats", "calendar", "capabilities"]).describe("Operation"),
+            action: z
+                .enum([
+                "list_cubes",
+                "register_cube",
+                "create_user",
+                "validate_cubes",
+                "stats",
+                "calendar",
+                "capabilities",
+            ])
+                .describe("Operation"),
             cube_id: cubeIdBrief,
             project_path: projectPathBrief,
-            cube_path: z.string().optional().describe("register_cube: cube directory (auto-detected if omitted)"),
+            cube_path: z
+                .string()
+                .optional()
+                .describe("register_cube: cube directory (auto-detected if omitted)"),
             user_id: z.string().optional().describe("create_user: user id"),
             user_name: z.string().optional().describe("create_user: display name"),
-            fix: z.boolean().optional().default(true).describe("validate_cubes: auto-fix"),
-            include_status: z.boolean().optional().default(false).describe("list_cubes: check registration"),
-            mode: z.enum(["project", "student"]).optional().describe("calendar: view mode"),
-            semester: z.string().optional().describe("calendar student: 'YYYY-Season' or 'current'"),
+            fix: z
+                .boolean()
+                .optional()
+                .default(true)
+                .describe("validate_cubes: auto-fix"),
+            include_status: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe("list_cubes: check registration"),
+            mode: z
+                .enum(["project", "student"])
+                .optional()
+                .describe("calendar: view mode"),
+            semester: z
+                .string()
+                .optional()
+                .describe("calendar student: 'YYYY-Season' or 'current'"),
             course: z.string().optional().describe("calendar student: course filter"),
             week: z.number().int().optional().describe("calendar student: week 1-18"),
-            view: z.enum(["list", "week", "month"]).optional().describe("calendar student: format"),
+            view: z
+                .enum(["list", "week", "month"])
+                .optional()
+                .describe("calendar student: format"),
         }),
     },
     memos_canvas: {
         description: `Task canvas — short-term task state that survives context compaction.
-action: open (needs goal) · update (append node; node_id edits one) · show · list.
+action: open (needs goal) · update (append node; node_id edits one) · show · list · delete.
 Node ids are greppable (000-N1); ref anchors evidence: mem:<id> / file:<path> / note:<text>.`,
         inputSchema: z.object({
-            action: z.enum(["open", "update", "show", "list"]),
+            action: z.enum(["open", "update", "show", "list", "delete"]),
             project_path: projectPathBrief,
             cube_id: cubeIdBrief,
-            name: z.string().optional().describe("update/show: canvas name (from list)"),
+            name: z
+                .string()
+                .optional()
+                .describe("update/show/delete: canvas name (from list)"),
             goal: z.string().optional().describe("open: the task"),
-            node_id: z.string().optional().describe("update: edit this node, else append"),
-            summary: z.string().optional().describe("update: step text (required to append)"),
+            node_id: z
+                .string()
+                .optional()
+                .describe("update: edit this node, else append"),
+            summary: z
+                .string()
+                .optional()
+                .describe("update: step text (required to append)"),
             status: z.enum(["todo", "doing", "done", "blocked"]).optional(),
             ref: z.string().optional().describe("update: evidence anchor"),
+            confirm: z
+                .boolean()
+                .optional()
+                .describe("delete: required only when the canvas still has unfinished nodes"),
         }),
     },
     // Delete tool schema (registered conditionally)
@@ -230,11 +364,21 @@ Before deleting, always:
 2. Show the memory content that will be deleted
 3. Get explicit user approval`,
         inputSchema: z.object({
-            memory_id: z.string().optional().describe("ID of the specific memory to delete. Get this from memos_search or memos_list."),
-            memory_ids: z.array(z.string()).optional().describe("List of memory IDs to delete in batch."),
+            memory_id: z
+                .string()
+                .optional()
+                .describe("ID of the specific memory to delete. Get this from memos_search or memos_list."),
+            memory_ids: z
+                .array(z.string())
+                .optional()
+                .describe("List of memory IDs to delete in batch."),
             project_path: projectPathBrief,
             cube_id: cubeIdBriefDefault,
-            delete_all: z.boolean().optional().default(false).describe("Set to true to delete ALL memories in the cube. DANGEROUS! Requires explicit user confirmation."),
+            delete_all: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe("Set to true to delete ALL memories in the cube. DANGEROUS! Requires explicit user confirmation."),
         }),
     },
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-memos-mcp",
-  "version": "3.1.5",
+  "version": "3.1.6",
   "description": "MCP Server for oh-memos — Intelligent Memory Management (Node.js, no Python required)",
   "type": "module",
   "main": "dist/index.js",