sage-mem 2.1.16 → 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.16`** — 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.16`** —— 顶部 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/lib/memory/scan.js

@@ -354,8 +354,26 @@ export async function scanMemoryFiles(ctx, sessionId) {
   return scanMemoryDir(ctx, sessionId, MEMORY_DIR)
 }
 
+/**
+ * 同 `scanMemoryFiles`，但把「扫描到底完整不完整」一并带出来（外部审查 2026-10-31，Q14）。
+ *
+ * 返回 `{files, complete, errors, skipped, missing}`：
+ *   - `complete === false` → **目录级**读取失败（ENOTDIR / EACCES / 盘掉线…）：`files` 为空，
+ *     但上层**绝不能**当成「空目录、没有命中」；`errors` 是 `{code, message}` 列表。
+ *   - `missing === true` → 目录不存在（全新安装还没建过记忆）：合法空库，不是故障。
+ *   - `skipped` → 目录列得出来、但单条目被读取闸门跳过的份数（链接 / 超限 / 保留名别名 /
+ *     读失败），与目录级失败分开统计。
+ *
+ * 旧签名 `scanMemoryFiles` / `scanMemoryDir` 仍返回数组（调用点太多，不一次性改爆）。
+ */
+export async function scanMemoryFilesDetailed(ctx, sessionId) {
+  return scanMemoryDirDetailed(ctx, sessionId, MEMORY_DIR)
+}
+
 /**
  * 同 `scanMemoryFiles`，但目录可显式给（缓存按目录分账；测试用它证明两个目录不互相污染）。
+ * 返回值额外带扫描完整性（见 `scanMemoryFilesDetailed`）；缓存只在**扫描完整**时落，
+ * 免得把一次失败存成「目录是空的」。
  *
  * 失效判据**两层**，缺一不可：
  *   1. **主判据 —— watcher 代次**：目录里发生过事件就重扫。它也是「只改内容、不改名」这类
@@ -373,7 +391,7 @@ export async function scanMemoryFiles(ctx, sessionId) {
  * watcher 不可用（起不来 / 报错）时**一律全扫**，与加缓存之前逐字一致 —— 拿不到失效信号
  * 就不许缓存，这是这条优化的安全底线。
  */
-export async function scanMemoryDir(ctx, sessionId, dir = MEMORY_DIR) {
+export async function scanMemoryDirDetailed(ctx, sessionId, dir = MEMORY_DIR) {
   const st = scanStateOf(dir)
   // ── 命中检查：代次 + 文件名集合，两道都对上才算「目录真的没变」──
   if (st.watcher.ok && st.entry) {
@@ -386,7 +404,15 @@ export async function scanMemoryDir(ctx, sessionId, dir = MEMORY_DIR) {
        */
       if (names && namesKeyOf(names) === st.entry.namesKey && st.generation === g0) {
         // 还一个新数组：缓存是共享的，调用方就地排序 / splice 不该改到别人的那一份。
-        return st.entry.files.slice()
+        return {
+          files: st.entry.files.slice(),
+          complete: true,
+          missing: false,
+          errors: [],
+          skipped: st.entry.skipped ?? 0,
+          namesKey: st.entry.namesKey,
+          cached: true,
+        }
       }
     }
   }
@@ -405,32 +431,59 @@ export async function scanMemoryDir(ctx, sessionId, dir = MEMORY_DIR) {
     st.watcher.dispose()
     st.watcher = null
   }
-  if (st.watcher && st.watcher.ok && scanned.namesKey !== null && gStart === gEnd) {
-    st.entry = { generation: gEnd, namesKey: scanned.namesKey, files: scanned.files }
+  if (st.watcher && st.watcher.ok && scanned.complete !== false && scanned.namesKey !== null && gStart === gEnd) {
+    st.entry = { generation: gEnd, namesKey: scanned.namesKey, files: scanned.files, skipped: scanned.skipped }
   }
   // 也还新数组：上面刚把同一份引用存进了缓存，交出去就等于把缓存的所有权给了调用方。
-  return scanned.files.slice()
+  return { ...scanned, files: scanned.files.slice() }
+}
+
+/** 兼容旧签名：只要文件数组（要分辨「空库 vs 读不了」用 `scanMemoryDirDetailed`）。 */
+export async function scanMemoryDir(ctx, sessionId, dir = MEMORY_DIR) {
+  return (await scanMemoryDirDetailed(ctx, sessionId, dir)).files
 }
 
 /**
- * 真的走一遍磁盘。返回 `{files, namesKey}`。
+ * 真的走一遍磁盘。返回 `{files, namesKey, complete, missing, errors, skipped}`。
  *
- * `namesKey === null` 表示目录根本没列出来（不存在 / 无权限）→ 这一轮**不落缓存**：
+ * `namesKey === null` 表示目录根本没列出来 → 这一轮**不落缓存**：
  * 把一次失败当成「目录是空的」存下来，会让之后每一次读取都命中这份假结果。
+ * `complete === false` 是**目录级**失败（ENOTDIR / EACCES…）；`missing === true` 是目录不存在，
+ * 属于合法空库 —— 两者刻意分开，上层据此决定「说空库」还是「说检索不可用」。
  */
 async function fullScanMemoryDir(ctx, sessionId, dir) {
   try {
-    const entries = await readdir(dir, { withFileTypes: true })
+    let entries
+    try {
+      entries = await readdir(dir, { withFileTypes: true })
+    } catch (err) {
+      // 目录级 I/O 失败（ENOTDIR / EACCES / 盘掉线…）与「目录还没建过」必须分开：
+      // 前者要带 complete=false 让上层说「检索不可用」，后者是合法空库。
+      const code = String(err?.code ?? '')
+      if (code === 'ENOENT') return { files: [], namesKey: null, complete: true, missing: true, errors: [], skipped: 0 }
+      warnLog(ctx, `cannot scan ${dir}: ${err?.message ?? err}`, sessionId)
+      return {
+        files: [],
+        namesKey: null,
+        complete: false,
+        missing: false,
+        errors: [{ code, message: String(err?.message ?? err) }],
+        skipped: 0,
+      }
+    }
     // 目录名集合的指纹：作为缓存的**兜底判据**（watcher 漏掉增 / 删 / 改名时的第二道闸）。
     const namesKey = namesKeyOf(entries.map(e => e.name))
     /** 保留名的文件身份：8.3 短名与硬链接都得靠它才认得出（名字文本上它们毫无关系）。 */
     const reservedIds = await reservedIdentitySet(dir)
+    /** 目录列得出来、但单个条目没读成 / 被策略跳过的份数（与目录级失败分开统计）。 */
+    let skipped = 0
     /**
      * 链接条目在 `isFile()` 这一步就被滤掉了（`readdir` 的 Dirent 报的是链接本身），
      * 也就是说**闸门根本没机会看到它们** —— 不在这里出声，用户只会看到「这条记忆不见了」。
      */
     for (const e of entries) {
       if (e.isSymbolicLink() && /\.md$/i.test(e.name)) {
+        skipped += 1
         warnLog(ctx, `skip ${e.name}: 是指向别处的符号链接 / 目录联接`, sessionId)
       }
     }
@@ -447,6 +500,7 @@ async function fullScanMemoryDir(ctx, sessionId, dir) {
        * 文本上毫无关系，inode 却是同一个。不按身份拦，索引就会以普通记忆的身份被读进上下文。
        */
       if (gate.ok && gate.id && reservedIds.has(gate.id)) {
+        skipped += 1
         warnLog(ctx, `skip ${name}: 这是某个保留名（索引 / 流水）的另一个名字，不当记忆读`, sessionId)
         return null
       }
@@ -455,6 +509,7 @@ async function fullScanMemoryDir(ctx, sessionId, dir) {
         warnLog(ctx, `note ${name}: 有 ${gate.links} 个硬链接名，内容可能被记忆目录之外改到`, sessionId)
       }
       if (!gate.ok) {
+        skipped += 1
         warnLog(ctx, `skip ${name}: ${gate.error}`, sessionId)
         return null
       }
@@ -487,14 +542,24 @@ async function fullScanMemoryDir(ctx, sessionId, dir) {
       } catch (err) {
         // 只有 ENOENT 是正常状态（扫到读之间被删）。其余——权限错、编码坏、盘掉线——
         // 一律出声：这里的静默化就是把「记忆不再注入」变成无声事故的那一手。
+        skipped += 1
         if (err?.code !== 'ENOENT') warnLog(ctx, `cannot read ${name}: ${err?.message ?? err}`, sessionId)
         return null
       }
     }))
-    return { files: loaded.filter(Boolean), namesKey }
+    return { files: loaded.filter(Boolean), namesKey, complete: true, missing: false, errors: [], skipped }
   } catch (err) {
-    if (err?.code !== 'ENOENT') warnLog(ctx, `cannot scan ${dir}: ${err?.message ?? err}`, sessionId)
-    return { files: [], namesKey: null }
+    // 兜底：扫描中途出现未预期异常时同样**不能**当空库 —— 带 complete=false 交给上层。
+    const code = String(err?.code ?? '')
+    warnLog(ctx, `cannot scan ${dir}: ${err?.message ?? err}`, sessionId)
+    return {
+      files: [],
+      namesKey: null,
+      complete: false,
+      missing: false,
+      errors: [{ code, message: String(err?.message ?? err) }],
+      skipped: 0,
+    }
   }
 }
 

package/lib/tools/memory-tools.js

@@ -18,7 +18,7 @@
 
 import { DEFAULT_MAX_BYTES, MAX_MAX_BYTES, readSlice } from '../memory/reader.js'
 import { DEFAULT_LIMIT, MAX_LIMIT, retrieve } from '../memory/search.js'
-import { scanMemoryFiles } from '../memory/scan.js'
+import { scanMemoryFilesDetailed } from '../memory/scan.js'
 import { parseFrontmatter } from '../memory/frontmatter.js'
 import { describeValidity } from '../memory/validity.js'
 
@@ -37,6 +37,10 @@ function renderSearchResult(args, value) {
   const cov = v.coverage ?? {}
   const head = [
     `检索面：${v.scope ?? 'all'}；扫了 ${cov.searched ?? 0} 份记忆（切出 ${cov.chunks ?? 0} 个段落）`,
+    // 目录不存在 = 还没建过记忆（合法空库），说出来，别让「空」被读成「扫过且没有」。
+    cov.missingDir ? '；记忆目录还不存在（可能还没建过任何记忆）' : '',
+    // 单条目被闸门跳过（链接 / 超限 / 保留名别名 / 读失败）：与「目录级读不了」分开报。
+    cov.skippedFiles ? `；有 ${cov.skippedFiles} 份被读取闸门跳过（链接 / 超限 / 读不了）` : '',
     cov.skipped ? `；有 ${cov.skipped} 份没读成` : '',
     cov.filteredBelowFloor ? `；另有 ${cov.filteredBelowFloor} 段因相关性不够被滤掉` : '',
     `。`,
@@ -118,7 +122,22 @@ export function createMemoryTools(ctx) {
       const query = String(args?.query ?? '').trim()
       if (!query) return { ok: false, error: 'query 不能为空' }
       try {
-        const files = await scanMemoryFiles(ctx, exec?.agent?.id ?? '')
+        /**
+         * 用 Detailed 入口（外部审查 2026-10-31，Q14）：目录级失败（ENOTDIR / EACCES…）
+         * 以前被 `scanMemoryDir` 降级成空数组，工具照样回 `ok:true` + `complete:true`，
+         * 「读不了记忆」就被渲染成「记忆里没有」。现在把「检索不可用」单独带出去。
+         */
+        const scan = await scanMemoryFilesDetailed(ctx, exec?.agent?.id ?? '')
+        if (scan.complete === false) {
+          const detail = (scan.errors ?? []).map((e) => `${e.code ? `${e.code}: ` : ''}${e.message}`).join('；') || '目录读取失败'
+          return {
+            ok: false,
+            code: 'memory_unavailable',
+            error: `记忆目录读不了（${detail}）。这是「检索不可用」，不代表记忆里没有匹配项 —— 换个时间重试，或检查记忆目录是否存在、是否是个目录。`,
+            coverage: { searched: 0, complete: false, errors: scan.errors ?? [] },
+          }
+        }
+        const files = scan.files
         const result = retrieve({ query, files, scope: args?.scope, limit: args?.limit, cursor: args?.cursor })
         // 2.0.0：把每条命中对应的失效信息带出去（D29 Q3）。检索本身**不过滤**失效记忆 ——
         // 问历史时旧口径是证据；过滤掉才是丢信息。模型靠这里的标记判断「这是不是现状」。
@@ -135,6 +154,11 @@ export function createMemoryTools(ctx) {
             if (v.expired) extra.expired = true
             return Object.keys(extra).length ? { ...h, ...extra } : h
           })
+          // 扫描层的「单条目被跳过」与目录级失败分开报（Q14）：坏一份 ≠ 整库读不了。
+          if (result.coverage && typeof result.coverage === 'object') {
+            result.coverage.skippedFiles = scan.skipped ?? 0
+            if (scan.missing) result.coverage.missingDir = true
+          }
         }
         return result
       } catch (err) {

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