sage-mem 2.1.16 → 2.1.17

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

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