sage-mem 1.6.0 → 1.6.2

package/README.md

@@ -12,7 +12,7 @@
 
 **Cross-session memory for DeepSeek Harness — plain markdown files, no database, no worker.**
 
-**Current version 1.0.0 (the first stable release).** The public commitments, the capability boundaries and the list of things it explicitly cannot do are in the
+**Current release: `1.6.2`** — the npm badge above is the dynamic source of truth. **Contract baseline: `1.0.0`** — the first stable release, whose public commitments, the capability boundaries and the list of things it explicitly cannot do are frozen in the
 [frozen contract](https://github.com/gezi-wen/sage-mem/blob/main/docs/1.0.0-contract.md).
 
 If it is useful to you, a Star is the most direct feedback.
@@ -84,6 +84,11 @@ The memory management page's file list also has an **Open memory folder** button
 memory directory in the system file manager (Explorer / Finder / the Linux file manager) through a
 detached host-side process and returns without waiting for the window.
 
+While the memory directory is empty, the empty state carries a **Create index skeleton** button: one
+click writes a starter `MEMORY.md` (index format plus the four memory categories). When `MEMORY.md`
+already exists it only says so and changes nothing; it uses the existing reserved-file read/write
+calls rather than a new remote.
+
 ## Quick Start
 
 Requires **DSH `0.1.2-rc.1` or higher** (see [Compatibility](#compatibility)) and **Node.js `>= 18`**.
@@ -459,7 +464,7 @@ Your memories are the files in that directory, openable at any time for confirma
 
 sage-mem is a pure DSH plugin and declares its host requirement through **`engines.dsh`** in `package.json`: `>=0.1.2-rc.1` — **a one-sided open interval with no upper bound**, so no future DSH version will be blocked by this declaration. `engines.node` requires `>= 18`.
 
-Version-by-version verification record:
+Version-by-version compatibility record:
 
 | DSH version | Status |
 | --- | --- |
@@ -473,6 +478,9 @@ Version-by-version verification record:
 | 0.1.7-rc.2 | compatible |
 | 0.2.0-rc.1 | compatible |
 | 0.2.0-rc.2 | compatible |
+| 0.2.1-rc.1 | compatible |
+
+**How to read `compatible`.** It means this plugin's codec and manifest contract has been checked against that host generation (code-level comparison plus the unit/contract suite), **not** that an end-to-end probe was run on that exact host build. The table is a declaration; how each claim was checked is summarized here. Real-host probes so far: `headless` (2026-10-15) and `web` (2026-10-16); the `desktop` profile has **not** been probed yet (see [release-checklist.md](https://github.com/gezi-wen/sage-mem/blob/main/docs/release-checklist.md) §4b). CI runs only on Ubuntu + Node 24 against the `0.2.0-rc.1` peer generation; `engines.node` still declares `>=18`, but Node 18 is not part of the CI matrix.
 
 Two points worth spelling out:
 

package/README.zh.md

@@ -14,7 +14,7 @@
 
 > File-based cross-session memory for DeepSeek Harness — every memory is a plain markdown file you can open, edit and delete. No database, no worker, no port.
 
-**当前版本 1.0.0（稳定版）** —— 公开承诺、能力边界与「明确做不到」的清单见
+**当前发布版本：`1.6.2`** —— 顶部 npm 徽章是动态权威。**契约基线：`1.0.0`** —— 第一个稳定版，公开承诺、能力边界与「明确做不到」的清单冻结在
 [契约冻结](https://github.com/gezi-wen/sage-mem/blob/main/docs/1.0.0-contract.md)。
 
 如果它对你有用，给个 Star 是最直接的反馈。
@@ -85,6 +85,10 @@ sage-mem 补上这一层，做法是：**把该记住的事写成一张张卡片
 记忆管理页的「文件列表」头部还有一个「打开记忆文件夹」按钮：用系统文件管理器打开当前记忆目录
 （Windows Explorer / macOS Finder / Linux 文件管理器）。host 侧起一个 detached 进程就返回，不等窗口。
 
+记忆目录还是空的时候，空态里有一个「建立索引骨架」按钮：一键写入 `MEMORY.md` 的引导文件
+（索引格式 + 四类记忆说明）。**已经存在 `MEMORY.md` 时只提示、不覆盖**；它不走新的 remote，
+用的是原有的保留名读取 / 写入接口。
+
 ## 快速开始
 
 需要 **DSH `0.1.2-rc.1` 或更高**（见[兼容性](#兼容性)）、**Node.js `>= 18`**。
@@ -462,7 +466,7 @@ sage-mem 只做三件事，全都在你本机：
 
 sage-mem 是纯 DSH 插件，用 `package.json` 的 **`engines.dsh`** 声明宿主要求：`>=0.1.2-rc.1` —— **单边开区间、不设上界**，所以任何未来的 DSH 版本都不会被这道声明挡住。`engines.node` 要求 `>= 18`。
 
-逐版本核对记录：
+逐版本兼容记录：
 
 | DSH 版本 | 状态 |
 | --- | --- |
@@ -476,6 +480,9 @@ sage-mem 是纯 DSH 插件，用 `package.json` 的 **`engines.dsh`** 声明宿
 | 0.1.7-rc.2 | compatible |
 | 0.2.0-rc.1 | compatible |
 | 0.2.0-rc.2 | compatible |
+| 0.2.1-rc.1 | compatible |
+
+**`compatible` 怎么读**：它表示本插件的 codec / manifest 契约在该宿主代上核对过（代码层比对 + 单元/契约测试），**不表示**在那个确切宿主构建上跑过端到端探针。这张表是声明，核对方式总结在下面。真实宿主探针目前只跑过 `headless`（2026-10-15）与 `web`（2026-10-16）；`desktop` profile **还没跑过**（见 [release-checklist.md](https://github.com/gezi-wen/sage-mem/blob/main/docs/release-checklist.md) §4b）。CI 只在 Ubuntu + Node 24 上、对着 `0.2.0-rc.1` 一代 peer 跑；`engines.node` 仍声明 `>=18`，但 Node 18 不在 CI 矩阵里。
 
 两点值得说明：
 

package/lib/client.js

@@ -3755,7 +3755,7 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 		// 只负责「按状态/筛选把卡片摆出来 + 四种空态」；状态、筛选语义、动作回调全部由 Section 传。
 		// 抽出的判据：它是 Section 里最大的一块纯渲染，而卡片组件（Card / ArchivedCard）本来就在 50 共享层。
 		function FilesView(props) {
-			const { loading, totalCount, openAdd, statusFilter, setStatusFilter, items, archiveItems, filtered, setTypeFilter, setTagFilter, setQuery, busy, restoring, archDelete, archEdit, archLoad, archSaving, archText, setArchText, openArchEdit, saveArchEdit, cancelArchEdit, restoreFile, setArchDelete, setArchEdit, deleteArchivedFile, expanded, deleting, archiving, archiveReason, setArchiveReason, setArchiving, setDeleting, confirmArchive, toggleLock, openEdit, confirmDelete } = props;
+			const { loading, totalCount, openAdd, createIndexSkeleton, statusFilter, setStatusFilter, items, archiveItems, filtered, setTypeFilter, setTagFilter, setQuery, busy, restoring, archDelete, archEdit, archLoad, archSaving, archText, setArchText, openArchEdit, saveArchEdit, cancelArchEdit, restoreFile, setArchDelete, setArchEdit, deleteArchivedFile, expanded, deleting, archiving, archiveReason, setArchiveReason, setArchiving, setDeleting, confirmArchive, toggleLock, openEdit, confirmDelete } = props;
 			let filesView;
 			if (loading && totalCount === 0) {
 				filesView = h("div", { className: "smem-skeleton", key: "loading", "data-loading": "1" }, [0, 1, 2].map(function (i) {
@@ -3765,6 +3765,7 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 				filesView = h("div", { className: "smem-empty", key: "empty" }, [
 					h("div", { key: "t" }, "还没有记忆文件。对话中值得记住的事会写到这里，也可以手动写入。"),
 					h("button", { type: "button", className: "smem-btn smem-btn-primary", key: "add", onClick: openAdd }, "+ 添加记忆"),
+					h("button", { type: "button", className: "smem-btn", key: "idx", title: "写入一份 MEMORY.md 索引骨架（已有索引不会覆盖）", onClick: createIndexSkeleton }, "建立索引骨架"),
 				]);
 			} else if (statusFilter === "archived" && archiveItems.length === 0) {
 				filesView = h("div", { className: "smem-empty", key: "empty" }, [
@@ -4126,6 +4127,53 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 				setFormFm(null); setFormBaseType(""); setFormTags("");
 			}
 
+			// 空记忆库时「建立索引骨架」写进去的引导文件。它只是给人看的起点：
+			// 索引本来就是手写维护的，这里不猜用户有什么记忆、也不生成假条目。
+			const INDEX_SKELETON = [
+				"# 记忆索引",
+				"",
+				"> 这是 sage-mem 的记忆索引骨架：每条记忆一行，链接到同目录下的一个 Markdown 文件。",
+				"> 索引由人（或 agent）手写维护，不是自动生成的；改写前建议先备份。",
+				"",
+				"## 活动记忆",
+				"",
+				"<!-- 一条记忆一行：「- [标题](文件名.md) — 一句话描述」 -->",
+				"",
+				"## 四类记忆",
+				"",
+				"- `user_*`：关于用户的事实与偏好",
+				"- `feedback_*`：用户给的工作方式指导",
+				"- `project_*`：进行中的工作与状态",
+				"- `reference_*`：外部信息在哪找",
+				"",
+			].join("\n");
+
+			function createIndexSkeleton() {
+				setError(null);
+				setNotice("");
+				if (!remote || typeof remote.readRaw !== "function" || typeof remote.writeRaw !== "function") {
+					setError("宿主侧还没有 readRaw / writeRaw 接口（插件版本较旧）");
+					return;
+				}
+				setBusy(true);
+				// 先读再写：**已有索引绝不覆盖**。readRaw 对不存在的文件会 reject，正好当探针。
+				remote.readRaw("MEMORY.md").then(function () {
+					setBusy(false);
+					setNotice("MEMORY.md 已经存在，没有改动它。");
+				}, function () {
+					return remote.writeRaw("MEMORY.md", INDEX_SKELETON).then(function (res) {
+						const out = unwrap(res);
+						setBusy(false);
+						if (out && out.ok === false) { setError(out.error || "建立索引骨架失败"); return; }
+						setNotice("已建立 MEMORY.md 索引骨架。");
+						load();
+					});
+				}).catch(function (e) {
+					setBusy(false);
+					setError(String((e && e.message) || e));
+				});
+			}
+
 			function openMemoryFolder() {
 				setError(null);
 				if (!remote || typeof remote.openMemoryDir !== "function") {
@@ -4597,7 +4645,7 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 			// 「文件列表」这一屏：状态筛选决定看哪一批，灰色卡片与留痕块自带「退役」语义。
 			// banner 只在**专门看归档**时出现，切到全部时不重复说一遍。
 			const filesView = h(FilesView, {
-				loading: loading, totalCount: totalCount, openAdd: openAdd,
+				loading: loading, totalCount: totalCount, openAdd: openAdd, createIndexSkeleton: createIndexSkeleton,
 				statusFilter: statusFilter, setStatusFilter: setStatusFilter,
 				items: items, archiveItems: archiveItems, filtered: filtered,
 				setTypeFilter: setTypeFilter, setTagFilter: setTagFilter, setQuery: setQuery,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sage-mem",
   "description": "Cross-session memory for DeepSeek Harness — plain markdown files, no database, no worker.",
-  "version": "1.6.0",
+  "version": "1.6.2",
   "type": "module",
   "main": "lib/index.js",
   "exports": {
@@ -47,7 +47,8 @@
         "0.1.7-rc.1": "compatible",
         "0.1.7-rc.2": "compatible",
         "0.2.0-rc.1": "compatible",
-        "0.2.0-rc.2": "compatible"
+        "0.2.0-rc.2": "compatible",
+        "0.2.1-rc.1": "compatible"
       }
     }
   },