sage-mem 2.1.17 → 2.1.18

package/README.md

@@ -12,7 +12,7 @@
 
 **Cross-session memory for DeepSeek Harness — plain markdown files, no database, no worker.**
 
-**Current release: `2.1.17`** — 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
+**Current release: `2.1.18`** — 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.

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.
 
-**当前发布版本：`2.1.17`** —— 顶部 npm 徽章是动态权威。**契约基线：`1.0.0`** —— 第一个稳定版，公开承诺、能力边界与「明确做不到」的清单冻结在
+**当前发布版本：`2.1.18`** —— 顶部 npm 徽章是动态权威。**契约基线：`1.0.0`** —— 第一个稳定版，公开承诺、能力边界与「明确做不到」的清单冻结在
 [契约冻结](https://github.com/gezi-wen/sage-mem/blob/main/docs/1.0.0-contract.md)。
 
 如果它对你有用，给个 Star 是最直接的反馈。

package/lib/autodream/audit.js

@@ -2,13 +2,16 @@
  * sage-mem autodream — 记忆目录审计（七查）。
  *
  * 审计清单内置在 host 侧，让 autodream 每次跑完都能自证
- * 没把记忆改坏（七项，外加「读不动」单列一类）：
- *   1. 索引悬空 —— MEMORY.md 指向不存在的文件
+ * 没把记忆改坏（七项，外加「读不动」「归档残留」「索引大小写冲突」各单列一类）：
+ *   1. 索引悬空 —— 索引指向不存在的文件
  *   2. 漏索引   —— 存在但没进索引的记忆文件
  *   3. type 与前缀不一致（分类看 type，前缀骗不了它）
  *   4. CRLF     —— 「某个 Windows 编辑器碰过」的可疑信号
  *   5. 双链断链 —— [[目标]] 找不到对应文件或 frontmatter name
  *   6. 未加引号值里的「空格+#」—— 会被 YAML 当注释吞掉，解析不报错但描述残缺
+ *   7. 索引大小写冲突 —— 同一目录同时存在 MEMORY.md / memory.md 等多个变体
+ *      （只在大小写敏感的卷上可能出现）：读哪一个都不算错，**歧义本身**要报。
+ *      索引的识别一律走 `memory/index-file.js`，不在本模块写死文件名。
  *
  * **归档区（`archive/`）不是审计对象**，只贡献「名字池」：正文里指向已归档记忆的
  * `[[链接]]` 单列成 `archivedLinks`（提示），**不计入 problems** —— 归档是「静默失效
@@ -24,14 +27,12 @@
 import { readdir, readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { hasFrontmatter, parseFrontmatter } from '../memory/frontmatter.js'
+import { isIndexName, resolveIndexNames } from '../memory/index-file.js'
 import { parseValidityTime } from '../memory/validity.js'
 import { SESSION_LOG_KEY, isPlainMdName } from '../shared/md-name.js'
 import { ARCHIVE_DIR_NAME, inspectMemoryEntry } from '../memory/scan.js'
 import { warnLog } from '../memory/util.js'
 
-/** 索引文件名。它本身不是一条记忆，是索引。 */
-const INDEX_FILE = 'MEMORY.md'
-
 /**
  * 归档 / 恢复中途崩溃留下的**私有名残留**：`a.md.archiving-<hex>` / `a.md.restoring-<hex>`。
  *
@@ -55,7 +56,7 @@ const STRAY_RE = /\.(?:archiving|restoring)-[0-9a-f]+$/i
  * ⚠️ 别和 `lib/memory/config.js` 的 `NON_ENTRY_FILES` 混为一谈 —— **同名不同义**：
  * 那个管「列不列进设置页 / 星图 / 检索」，这个管「审计读不读」。它们的差集就是
  * **索引 `MEMORY.md`**：它**要**被读（要当链接来源、要查行尾与链接），只是
- * **不是一条记忆** —— 见下面 `f !== INDEX_FILE` 那两处。
+ * **不是一条记忆** —— 见下面 `isIndexName` 那几处。
  */
 const AUDIT_SKIP_FILES = new Set([SESSION_LOG_KEY])
 
@@ -123,8 +124,14 @@ export function indexTargets(indexText) {
 /**
  * 扫一个目录下的记忆文件（不含子目录 —— 归档区就该扫不到），
  * 外加归档区的**名字池**（只有名字，不做检查）。
+ *
+ * 索引的识别与读取**不在这里写死文件名**：走 `memory/index-file.js` 的
+ * `resolveIndexNames`（大小写不敏感、多个变体时给出冲突列表），与「恢复归档时补索引」
+ * 等入口同一套规则。外部审查 Q17 的根因就是这里原先硬编码 `MEMORY.md`。
+ *
  * @param {string} dir
- * @returns {Promise<{files: string[], all: string[], skipped: number, indexText: string, archiveKeys: Set<string>, archiveCount: number}>}
+ * @returns {Promise<{files: string[], all: string[], skipped: number, indexText: string,
+ *   indexFile: string|null, indexVariants: string[], archiveKeys: Set<string>, archiveCount: number}>}
  */
 async function readDirSnapshot(dir) {
   let entries
@@ -132,6 +139,12 @@ async function readDirSnapshot(dir) {
   const all = entries
     .filter((e) => e.isFile() && e.name.toLowerCase().endsWith('.md'))
     .map((e) => e.name)
+  /**
+   * 索引的**实际磁盘名**：大小写不敏感地定位（与 `index-file.js` 同一套规则）。
+   * 同时拿到全部大小写变体 —— 多个变体只在大小写敏感的卷上可能同时存在，
+   * 那时目录本身有歧义，报出来而不是静默挑一个。
+   */
+  const index = resolveIndexNames(entries.filter((e) => e.isFile()).map((e) => e.name))
   const files = []
   for (const f of all) {
     if (AUDIT_SKIP_FILES.has(f.toLowerCase())) continue
@@ -150,10 +163,12 @@ async function readDirSnapshot(dir) {
     files.push(f)
   }
   let indexText = ''
-  try {
-    indexText = await readFile(join(dir, INDEX_FILE), 'utf8')
-  } catch (err) {
-    if (err?.code !== 'ENOENT') throw err
+  if (index.name !== null) {
+    try {
+      indexText = await readFile(join(dir, index.name), 'utf8')
+    } catch (err) {
+      if (err?.code !== 'ENOENT') throw err
+    }
   }
   // 归档区：文件名、去掉 .md 的名字、以及 frontmatter 里的 `name`。
   // 内容读不动只少一个名字，绝不让整场审计失败 —— 归档区本来就不是被审对象。
@@ -176,7 +191,17 @@ async function readDirSnapshot(dir) {
   } catch (err) {
     if (err?.code !== 'ENOENT') throw err
   }
-  return { files, all, skipped: all.length - files.length, indexText, archiveKeys, archiveCount }
+  return {
+    files,
+    all,
+    skipped: all.length - files.length,
+    indexText,
+    // 实际读取的索引名（null = 没有索引），以及全部大小写变体（>1 = 冲突）。
+    indexFile: index.name,
+    indexVariants: index.variants,
+    archiveKeys,
+    archiveCount,
+  }
 }
 
 /**
@@ -213,12 +238,21 @@ function stripCode(raw) {
  * @param {{nowMs?: number}} [opts] — `nowMs` 只用于「未来 `invalid_at`」那条提示：
  *   审计本身要读盘（不纯），但同一条规律仍然成立 —— 判定依赖的时钟必须能由调用方钉住，
  *   否则夹具没法写出「未来」这种确定性场景（R3）。不传才用当下。
- * @returns {Promise<object>} 结构化审计结果（problems 是六项之和）
+ * @returns {Promise<object>} 结构化审计结果（problems 是所有计分项之和）
  */
 export async function auditMemoryDir(dir, opts = {}) {
-  const { files, all, skipped, indexText, archiveKeys, archiveCount } = await readDirSnapshot(dir)
+  const { files, all, skipped, indexText, indexFile, indexVariants, archiveKeys, archiveCount } =
+    await readDirSnapshot(dir)
   const nowMs = Number.isFinite(opts?.nowMs) ? opts.nowMs : Date.now()
-  const entries = files.filter((f) => f !== INDEX_FILE)
+  // 索引本身不是一条记忆：大小写归一后排除（`memory.md` / `MEMORY.MD` 一样排除）。
+  const entries = files.filter((f) => !isIndexName(f))
+  /**
+   * 索引的大小写变体同时存在 = 目录本身有歧义（只在大小写敏感卷上可能）。
+   *
+   * 定位规则会优先读规范名，但**另一份文件仍在磁盘上**：用户改了它不会生效。
+   * 这必须单独报出来让人删掉多余的，而不是静默挑一个（Q17）。
+   */
+  const indexConflicts = indexVariants.length > 1 ? indexVariants.map((file) => ({ file })) : []
 
   const targets = indexTargets(indexText)
   const targetSet = new Set(targets.map((t) => t.toLowerCase()))
@@ -293,24 +327,25 @@ export async function auditMemoryDir(dir, opts = {}) {
     const fmMatch = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/)
     if (!fmMatch) {
       /**
-       * 索引 `MEMORY.md` 是**纯清单、不是一条记忆**（见 `lib/memory/config.js` 的
-       * `NON_ENTRY_FILES` 说明），不要求 frontmatter。报它等于给每一个健康的记忆库挂一盏常驻红灯。
+       * 索引（`MEMORY.md`，**大小写不敏感**：memory.md / MEMORY.MD 等同）是
+       * **纯清单、不是一条记忆**（见 `lib/memory/config.js` 的 `NON_ENTRY_FILES` 说明），
+       * 不要求 frontmatter。报它等于给每一个健康的记忆库挂一盏常驻红灯。
        */
-      if (f !== INDEX_FILE) noFrontmatter.push(f)
+      if (!isIndexName(f)) noFrontmatter.push(f)
     } else {
       const meta = parseFrontmatterLite(raw)
       const prefix = f.split('_')[0]
       const effective = meta.type || 'reference'
       /**
-       * ⚠️ **索引同样豁免「type 与前缀」这条**，与上面 `f !== INDEX_FILE` 是同一个理由。
+       * ⚠️ **索引同样豁免「type 与前缀」这条**，与上面 `!isIndexName(f)` 是同一个理由。
        *
-       * `MEMORY.md` 没有下划线，`f.split('_')[0]` 得到的就是整个 `MEMORY.md`；而历史版本的
+       * 索引名没有下划线，`f.split('_')[0]` 得到的就是整个文件名；而历史版本的
        * `write_memory` 硬要求内容以 frontmatter 开头，模型只好给索引补一个 `type: reference`
        * —— 于是**每一个健康的记忆库都常驻一条**「type=reference 前缀=MEMORY.md」，把
        * `problems` 这个唯一健康数字变成恒大于 0 的噪音（外部报告 2026-10-25 抓到）。
        * 索引不是一条记忆，它没有「前缀」可言，这条检查对它不成立。
        */
-      if (f !== INDEX_FILE && effective !== prefix) {
+      if (!isIndexName(f) && effective !== prefix) {
         typeMismatch.push({ file: f, type: meta.type || '(缺失)', prefix, effective })
       }
       for (const line of fmMatch[1].split(/\r?\n/)) {
@@ -383,6 +418,7 @@ export async function auditMemoryDir(dir, opts = {}) {
   const problems =
     dangling.length +
     unlisted.length +
+    indexConflicts.length +
     typeMismatch.length +
     crlf.length +
     brokenLinks.length +
@@ -397,8 +433,12 @@ export async function auditMemoryDir(dir, opts = {}) {
     skipped,
     archivedCount: archiveCount,
     indexEntries: targets.length,
+    // 实际读取的索引名（null = 没有索引）：大小写不敏感地定位，不用猜盘上是哪一种写法。
+    indexFile,
     dangling: dangling.map((file) => ({ file })),
     unlisted: unlisted.map((file) => ({ file })),
+    // 同一目录存在多个大小写变体（只在大小写敏感卷上可能）—— 单列一类、计入 problems。
+    indexConflicts,
     typeMismatch,
     crlf: crlf.map((file) => ({ file })),
     brokenLinks,
@@ -432,6 +472,8 @@ export function formatAudit(report, limit = 12) {
   }
   section('索引悬空', report.dangling, (r) => r.file)
   section('漏索引', report.unlisted, (r) => r.file)
+  // 多个大小写变体各自都可能是「用户以为的那份索引」：两边都列出来，让他删掉多余的。
+  section('索引大小写冲突（同一目录存在多个变体，请只保留一个）', report.indexConflicts ?? [], (r) => r.file)
   section('type 与前缀不一致', report.typeMismatch, (r) => `${r.file} type=${r.type} 前缀=${r.prefix}`)
   section('CRLF', report.crlf, (r) => r.file)
   section('双链断链', report.brokenLinks, (r) => `${r.file} -> [[${r.target}]]`)

package/lib/memory/index-file.js

@@ -50,13 +50,43 @@ async function readIndexText(indexPath) {
   }
 }
 
+/** 索引的规范文件名。大小写敏感卷上同时存在多个变体时，优先读它（与文档写法一致）。 */
+export const CANONICAL_INDEX_NAME = 'MEMORY.md'
+
+/**
+ * 这个名字算不算索引（大小写不敏感）——**唯一**判据，与 `findIndexFile` 同一套。
+ *
+ * 为什么单列出来：体检（`autodream/audit.js`）原先硬编码 `MEMORY.md`，排除索引时
+ * 又用精确字符串比较，于是索引合法地叫 `memory.md` 时，体检把索引本身报成
+ * 「漏索引 + 无 frontmatter」（外部审查 Q17）。所有「这是不是索引」的判断都走这里。
+ */
+export function isIndexName(name) {
+  return nameKey(name) === INDEX_KEY
+}
+
+/**
+ * 从一组目录项名里定位索引：返回**全部大小写变体**与「该读哪一个」。
+ *
+ * 多个变体只可能在大小写敏感的卷上同时存在（NTFS 默认做不到同一目录两份）。
+ * 这里优先规范名 `MEMORY.md`，否则按字典序取第一个 —— 保证同一目录每次挑同一个；
+ * 同时把变体列表交出去，让调用方**明确报冲突**，而不是静默挑一个（Q17）。
+ *
+ * @param {string[]} names
+ * @returns {{name: string|null, variants: string[]}}
+ */
+export function resolveIndexNames(names) {
+  const variants = (Array.isArray(names) ? names : []).filter((n) => isIndexName(n)).sort()
+  if (variants.length === 0) return { name: null, variants }
+  return { name: variants.includes(CANONICAL_INDEX_NAME) ? CANONICAL_INDEX_NAME : variants[0], variants }
+}
+
 /**
  * 索引文件的**磁盘真名**（大小写不敏感地找）。
  * 不假设盘上是 `MEMORY.md` —— 系统盘是 Windows、用户可能就写成了小写。
  */
 export async function findIndexFile(memoryDir) {
   const names = await readdir(memoryDir).catch(() => [])
-  return names.find((n) => nameKey(n) === INDEX_KEY) ?? null
+  return resolveIndexNames(names).name
 }
 
 /** 索引里有没有指向该文件的条目（`](file.md)` 或 `](file.md#L12)`，大小写不敏感）。 */

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": "2.1.17",
+  "version": "2.1.18",
   "type": "module",
   "main": "lib/index.js",
   "icon": "./icon.png",