sage-mem 0.7.2 → 0.8.0

package/lib/memory/config.js

@@ -0,0 +1,151 @@
+/**
+ * sage-mem 记忆层 —— 目录位置、各项上限与引用纪律。
+ *
+ * 记忆目录 / 状态根怎么定、注入条数与体积上限是多少、`reserved.json` 保护名单怎么读，
+ * 全在这儿。常量值与拆分前逐字一致。
+ */
+
+import { readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+export const MEMORY_DIR = process.env.SAGE_MEM_DIR || join(homedir(), '.sage-mem', 'memory')
+/**
+ * DSH 会话记录根目录。autodream 的门控靠它数「上次整理之后有几个会话更新」，
+ * `memory+sessions` 输入源下也会在里面做定向搜索。取不到就是空串，
+ * 门控会退化成「会话数 0 → 不触发」，而不是报错。
+ */
+export const SESSIONS_ROOT = process.env.DSH_HOME ? join(process.env.DSH_HOME, 'sessions') : ''
+
+/** 读一个整数型环境变量并在范围内收敛；取不到或非法就用默认值。 */
+export function envInt(name, dflt, lo, hi) {
+  const raw = process.env[name]
+  if (raw === undefined || raw === '') return dflt
+  const n = Number(raw)
+  if (!Number.isFinite(n)) return dflt
+  return Math.max(lo, Math.min(hi, Math.round(n)))
+}
+
+/**
+ * 一次注入最多带几条记忆。
+ *
+ * 5 → 10：**记忆条数 ÷ 注入名额 ≈ 命中率上限**，名额 5 时那个上限低到
+ * 的根因就在这个比值上。名额翻倍是提升召回最直接的一手，代价是每轮多约 7.5K
+ * 字符的上下文。**这个数字该由实测决定**，所以留了 SAGE_MEM_MAX_RESULTS 覆写口
+ * （比较两档的命中率与 token 账单，别拍脑袋）。
+ */
+export const MAX_RESULTS = envInt('SAGE_MEM_MAX_RESULTS', 10, 1, 30)
+
+/** 单条记忆注入的字符上限。 */
+export const MAX_CHARS_PER_FILE = envInt('SAGE_MEM_MAX_CHARS', 1500, 200, 20000)
+
+/**
+ * baseline 名额。
+ *
+ * baseline 条目通常不多，卡在 5 只会让靠后的条目永不出现——
+ * 而 baseline 恰恰是短问题、恢复会话时唯一的兜底。现在放到 8，
+ * 排序见下面「按显式优先级排，不按文件名」那段。
+ */
+export const MAX_BASELINE = envInt('SAGE_MEM_MAX_BASELINE', 8, 1, 50)
+
+/**
+ * 单会话累计注入字节上限 —— 到顶以后这个会话就不再注入新的记忆。
+ *
+ * 为什么要有：条数上限（MAX_RESULTS）管的是「一次」注入多少，管不了「一场会话注
+ * 多少次」。长会话里问题一直在换、检索签名一直在变，于是走一步注一批，累积没有
+ * 上限 —— 实测某个高重合的短问题一次就注 7,700 字符，八次就到 60 KB。
+ * Claude Code 有同一层闸门（`MAX_SESSION_BYTES = 60 * 1024`，到顶**彻底停止**预取），
+ * 本插件此前只有单条上限、没有会话上限。
+ *
+ * 60 KB 是与 CC 对齐的起点、不是实测出来的数字 —— 留了 SAGE_MEM_MAX_SESSION_BYTES
+ * 覆写口，量过再定。
+ */
+export const MAX_SESSION_BYTES = envInt('SAGE_MEM_MAX_SESSION_BYTES', 60 * 1024, 4096, 512 * 1024)
+
+/**
+ * 注入文本里标「保存于 N 天前」的门槛（天）。超了才标；0 = 每条都标。
+ *
+ * 为什么用「N 天前」而不是日期：模型不擅长日期算术，绝对时间戳几乎不触发陈旧
+ * 推理，相对天数才会。为什么需要它：陈旧记忆被当事实引用时，「引用」这个动作
+ * 本身会让它显得更权威、而不是更可疑。
+ */
+export const STALE_DAYS = envInt('SAGE_MEM_STALE_DAYS', 1, 0, 365)
+
+/**
+ * 注入文本开头的引用纪律 —— **必须独立成节，不能压成一条 bullet**。
+ *
+ * Claude Code 对这条做过 A/B：同一句内容埋成 bullet 命中 0/3，独立成节 3/3，
+ * 连标题措辞都验过。原因很实在：陈旧记忆被当事实引用时，「引用」这个动作本身
+ * 会让它显得更权威而不是更可疑 —— 规矩得在**读这批内容之前**先立。
+ *
+ * 每次注入都带（约 150 字符），不按会话只带一次：它约束的是「这一批」怎么用，
+ * 与批次绑定比与会话绑定更不容易失效。
+ */
+export const RECALL_DISCIPLINE = [
+  '> **引用纪律**：以下是过去某一刻写下的记录，不是当前事实。',
+  '> 提到文件路径先确认存在，提到函数 / 配置项先 grep，要据此动手前先核实当前代码。',
+  '> 标了「保存于 N 天前」的尤其注意：其中的 `文件:行号` 很可能已经过期。',
+  '> 「记忆里写着 X 存在」不等于「X 现在存在」。',
+].join('\n')
+
+/**
+ * 结构性保留名：设置页的写/删方法一律不得触碰。
+ *
+ * 只列**结构决定必须保护**的两个：
+ *   1. `MEMORY.md` —— 索引。它被整份覆盖就等于索引没了（「+ 添加记忆」表单是照
+ *      buildFrontmatter() 重建 frontmatter 的，原有内容一个字都留不下）。
+ *   2. `session-log.md` —— 追加型流水，体量最大，同样经不起一份重建。
+ *
+ * ⚠️ **除了这两个，别把任何具体记忆的文件名写死在这里。**
+ * 「哪几条记忆特别要紧」是**使用者的私事**——把它编进随包发布的代码，等于把作者的
+ * 记忆主题发给每一个装这个插件的人。
+ * 用户自己的保护名单放在 `<状态根>/reserved.json`（JSON 字符串数组），见下。
+ *
+ * ⚠️ 全部小写存放，比较一律走 nameKey()（NTFS 不区分大小写，集合里放 'MEMORY.md'
+ * 而拿 'memory.md' 去 has() 是查不到的 —— 曾经就是这个漏洞：表单里填 memory.md
+ * 就能整份覆盖索引，deleteFile 还能不可逆删掉它）。
+ */
+export const STATE_ROOT = process.env.SAGE_MEM_STATE_DIR || join(dirname(MEMORY_DIR), '.sage-mem')
+
+/**
+ * 读使用者自己声明的额外保护名单：`<状态根>/reserved.json`，形如 `["a.md","b.md"]`。
+ *
+ * 读不到、JSON 坏、不是数组 —— 一律当空数组返回。**一份可选的保护名单，
+ * 绝不该有能力让插件加载失败。**
+ */
+export function readExtraReserved() {
+  try {
+    const arr = JSON.parse(readFileSync(join(STATE_ROOT, 'reserved.json'), 'utf8'))
+    if (!Array.isArray(arr)) return []
+    return arr
+      .map((s) => String(s).trim().toLowerCase())
+      .filter((s) => s.endsWith('.md') && !s.includes('/') && !s.includes('\\') && !s.startsWith('..'))
+  } catch {
+    return []
+  }
+}
+
+export const RESERVED_FILES = new Set(['memory.md', 'session-log.md', ...readExtraReserved()])
+
+/**
+ * 非记忆条目：不参与检索 / 不进星图 / 不出现在设置页列表里，读写也一律不通。
+ *
+ * 是 RESERVED_FILES 的子集，区别在「列不列出来」：MEMORY.md 是索引、
+ * session-log.md 是追加型流水，两者都不是一条记忆；
+ * 而使用者手写维护的重要记忆是正常记忆条目（它们该被检索到）。
+ * （要出现在列表与星图里、要能读），只是不许从表单写/删。
+ */
+export const NON_ENTRY_FILES = new Set([
+  'memory.md',
+  'session-log.md',
+])
+
+/**
+ * 单文件体积上限（字节）。定 512 KB 的理由：
+ *   - 单条正文通常在几十 KB 以内，索引与流水都排除在外，
+ *     512 KB 是它的 26 倍，任何正常记忆都够用；
+ *   - 记忆是要塞进 system prompt 的，一条 512 KB 的记忆本身就等于把上下文撑爆——
+ *     到这个量级基本可以判定是写错了目标（比如把日志、代码贴进来）。
+ * 与 lib/typert.host.js 的 fileContentSchema.max(512 * 1024) 保持一致。
+ */
+export const MAX_FILE_BYTES = 512 * 1024

package/lib/memory/frontmatter.js

@@ -0,0 +1,117 @@
+/**
+ * sage-mem 记忆层 —— frontmatter 解析全家（tags / aliases / baseline / 摘要字段）。
+ */
+
+/**
+ * 解析 frontmatter 的 `tags`（自定义标签，用于列表页筛选）。
+ *
+ * 三种写法都收 —— 手写记忆时这三种都会自然出现，只认一种就等于「标签时灵时不灵」：
+ *   tags: [a, b]           （YAML flow）
+ *   tags:\n  - a\n  - b    （YAML block）
+ *   tags: a, b             （松散的逗号串）
+ *
+ * 上限 20 个、每个 40 字符：标签是给人点着筛的，超过这个量级已经不是标签，
+ * 而是一句话被塞进了 tags 字段。
+ */
+export function parseTags(body) {
+  const clean = (arr) =>
+    arr
+      .map((s) => String(s).trim().replace(/^["']|["']$/g, '').trim())
+      .filter(Boolean)
+      .slice(0, 20)
+      .map((s) => s.slice(0, 40))
+  const flow = body.match(/^tags:[ \t]*\[([^\]]*)\]/m)
+  if (flow) return clean(flow[1].split(','))
+  const block = body.match(/^tags:[ \t]*\r?\n((?:[ \t]+-[^\r\n]*\r?\n?)+)/m)
+  if (block) return clean(block[1].split(/\r?\n/).map((l) => l.replace(/^[ \t]*-[ \t]*/, '')))
+  const inline = body.match(/^tags:[ \t]*(.+?)[ \t\r]*$/m)
+  if (inline && inline[1].trim()) return clean(inline[1].split(','))
+  return []
+}
+
+/** 解析 frontmatter 的 name/description/type（兼容顶层与 metadata 嵌套两种 type）。 */
+export function parseFrontmatter(content) {
+  // 换行必须容忍 CRLF：任何用 Windows 编辑器碰过一次的文件都会被换成 \r\n，
+  // 而旧版这里写的是 /^---\n/ —— 匹配失败 → description/type 全空 →
+  // 「baseline 走 parseBaseline 那条带 \r?\n 的正则照旧命中，但这条记忆永远检索不到」，
+  // 症状极具欺骗性。下文定义的 parseBaseline 与 extractTitle 早已是 \r?\n。
+  const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---/)
+  if (!m) return { name: '', description: '', type: '', tags: [], aliases: [], updated: '', baselinePriority: 0 }
+  const body = m[1]
+  const grab = (key) => {
+    // [ \t] / [ \t\r] 而不是 \s：\s 会连 CRLF 的 \r 一起吃进捕获组，值尾留一个 \r
+    // 会让下面的引号剥离（["']$）失配，description 尾巴上挂一个残引号。
+    const hit = body.match(new RegExp(`^${key}:[ \\t]*(.+?)[ \\t\\r]*$`, 'm'))
+    if (!hit) return ''
+    return hit[1].replace(/^["']|["']$/g, '').trim()
+  }
+  let type = grab('type')
+  if (!type) {
+    const nested = body.match(/^metadata:\s*\r?\n(?:\s+[^\r\n]+\r?\n)*?\s+type:\s*(\S+)/m)
+    if (nested) type = nested[1]
+  }
+  // `updated` 踩的是与 `type` 同一个坑：它通常写在 `metadata:` 嵌套块里（缩进两格），
+  // 顶层 `^updated:` 抓不到 —— 于是「明明写了日期却永远显示不出来」。
+  // 抓不到就回落文件 mtime（见 ageDays）：手写时间戳是权威的，文件系统时间只是退路。
+  let updated = grab('updated')
+  if (!updated) {
+    const nestedUpdated = body.match(/^metadata:\s*\r?\n(?:\s+[^\r\n]+\r?\n)*?\s+updated:\s*(\S+)/m)
+    if (nestedUpdated) updated = nestedUpdated[1]
+  }
+  return {
+    name: grab('name'),
+    description: grab('description'),
+    type,
+    tags: parseTags(body),
+    aliases: parseAliases(body),
+    updated,
+    baselinePriority: parseBaselinePriority(body),
+  }
+}
+
+/**
+ * 解析 frontmatter 的 `aliases`（别称 / 同义词 / 我可能用的另一种叫法）。
+ *
+ * 为什么要有它：检索是**词面重合**的，不是语义的——问「我有什么待办」而文件里
+ * 写的是「代办清单」，差一个字就完全不命中。`description` 回答「我会怎么问它」，
+ * `aliases` 补上「我还可能怎么问」。写法与 tags 完全一致（flow / block / 逗号串三种都收），
+ * 免得手写时「时灵时不灵」。
+ */
+export function parseAliases(body) {
+  const clean = (arr) =>
+    arr
+      .map((s) => String(s).trim().replace(/^["']|["']$/g, '').trim())
+      .filter(Boolean)
+      .slice(0, 24)
+      .map((s) => s.slice(0, 60))
+  const flow = body.match(/^aliases:[ \t]*\[([^\]]*)\]/m)
+  if (flow) return clean(flow[1].split(','))
+  const block = body.match(/^aliases:[ \t]*\r?\n((?:[ \t]+-[^\r\n]*\r?\n?)+)/m)
+  if (block) return clean(block[1].split(/\r?\n/).map((l) => l.replace(/^[ \t]*-[ \t]*/, '')))
+  const inline = body.match(/^aliases:[ \t]*(.+?)[ \t\r]*$/m)
+  if (inline && inline[1].trim()) return clean(inline[1].split(','))
+  return []
+}
+
+/**
+ * 解析 frontmatter 的 `baselinePriority`（数字，越大越先注入）。
+ *
+ * 旧版 baseline 是 `MAX_BASELINE = 5` + **按文件名排序**——`feedback_*` 永远排在
+ * `user_*` 前面，与「哪条真的更该在每场会话开头出现」毫无关系。缺失当 0，
+ * 于是没写这个字段的老条目行为不变。
+ */
+export function parseBaselinePriority(body) {
+  const hit = body.match(/^baselinePriority:[ \t]*(.+?)[ \t\r]*$/m)
+  if (!hit) return 0
+  const n = Number(hit[1].replace(/^["']|["']$/g, '').trim())
+  return Number.isFinite(n) ? n : 0
+}
+
+/** 解析 frontmatter 的 `baseline` 标记：会话第一回合无条件注入。 */
+export function parseBaseline(content) {
+  const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---/)
+  if (!m) return false
+  const hit = m[1].match(/^baseline:\s*(.+)$/m)
+  if (!hit) return false
+  return /^(true|yes|1)$/i.test(hit[1].replace(/^["']|["']$/g, '').trim())
+}

package/lib/memory/naming.js

@@ -0,0 +1,54 @@
+/**
+ * sage-mem 记忆层 —— 文件名归一与保留名判定（**唯一**的名字比较基准）。
+ */
+
+import { NON_ENTRY_FILES, RESERVED_FILES } from './config.js'
+import { basename } from 'node:path'
+
+/**
+ * 文件名归一：只取单段文件名再小写。
+ *
+ * 这是**唯一**的名字比较基准（保留名、非条目名、扫描过滤全走它）。
+ * 不能直接用原始字符串比：NTFS 不区分大小写，`memory.md` 与 `MEMORY.md`
+ * 是同一个文件；`basename` 还顺手挡掉 `..\..\MEMORY.md` 这类带目录成分的输入。
+ */
+export function nameKey(raw) {
+  return basename(String(raw ?? '')).toLowerCase()
+}
+
+/** 是否是保留名（写/删一律拒绝）。大小写不敏感。 */
+export function isReserved(raw) {
+  return RESERVED_FILES.has(nameKey(raw))
+}
+
+/** 是否是非记忆条目（索引与流水）：列出/检索/星图/读写全部排除。大小写不敏感。 */
+export function isNonEntry(raw) {
+  return NON_ENTRY_FILES.has(nameKey(raw))
+}
+
+/** 目录扫描过滤：这个名字算不算一条记忆条目。 */
+export function isMemoryEntry(name) {
+  return /\.md$/i.test(String(name ?? '')) && !isNonEntry(name)
+}
+
+/**
+ * 唯一的路径校验函数（防穿越 + 扩展名 + 排除非记忆条目）。
+ *
+ * MemoryGateway.readFile / StarmapGateway.readFile 都走这里，不再各写一套
+ * —— 旧版 starmap 那套内联校验只排除了 'MEMORY.md'（大小写敏感）且**完全不排除
+ * session-log.md**，于是 `starmap.readFile('session-log.md')` 能把整份流水
+ * 整个拉进浏览器。
+ *
+ * 不复用 nameKey 的原因：这里要保留磁盘上的原始大小写（返回值直接 join 进路径）。
+ * @param raw — 调用方传来的文件名（任意值）
+ * @returns 通过校验的原始文件名；非法返回 null
+ */
+export function safeName(raw) {
+  if (typeof raw !== 'string' || raw === '') return null
+  // basename 与原文不一致＝含目录成分。旧版是「悄悄取 basename 继续」，
+  // 与 starmap 那套（要求 safe === raw）行为不一致；现在统一为拒绝。
+  if (basename(raw) !== raw) return null
+  if (!/\.md$/i.test(raw)) return null
+  if (isNonEntry(raw)) return null
+  return raw
+}

package/lib/memory/retrieval.js

@@ -0,0 +1,86 @@
+/**
+ * sage-mem 记忆层 —— 检索：双字打分、名额裁剪、baseline 排序、新鲜度换算。
+ */
+
+import { MAX_BASELINE, MAX_RESULTS } from './config.js'
+
+/** 提取消息文本，兼容 content 为字符串或 text-block 数组两种形态。 */
+export function extractText(content) {
+  if (typeof content === 'string') return content.trim()
+  if (!Array.isArray(content)) return ''
+  return content
+    .filter(b => b && b.type === 'text' && typeof b.text === 'string')
+    .map(b => b.text)
+    .join('\n')
+    .trim()
+}
+
+/** 提取双字（2-gram）集合，中英文数字通用。 */
+export function bigrams(s) {
+  const clean = String(s).toLowerCase().replace(/[^\p{L}\p{N}]+/gu, '')
+  const set = new Set()
+  for (let i = 0; i < clean.length - 1; i++) set.add(clean.slice(i, i + 2))
+  return set
+}
+
+/** query 的双字在 text 中的覆盖率（0~1），作为相关性得分。 */
+export function score(query, text) {
+  const q = bigrams(query)
+  if (q.size === 0) return 0
+  const t = bigrams(text)
+  let hit = 0
+  for (const g of q) if (t.has(g)) hit++
+  return hit / q.size
+}
+
+/**
+ * 相关性打分只用 frontmatter 的 description + 文件名，不扫全文。
+ *
+ * 旧版拿 query 的双字去全文里找，得分是「覆盖率」，分母是 query，不惩罚
+ * 文件长度 —— 越长的记忆越容易蒙中。实测：长记忆在全文匹配下对任何问题都能
+ * 蒙中足量双字组，连寒暄问句都能注入上千 token；而真正该命中的那条反被
+ * 挤掉。description 是「一句话说清这条是什么」的精准摘要，用它当检索
+ * 信号，噪音大幅下降。
+ */
+export function selectRelevant(query, files) {
+  return files
+    .map(f => {
+      // aliases 一并进检索面：它是专门为「换个说法也能命中」准备的字段。
+      const aliasText = Array.isArray(f.aliases) && f.aliases.length ? ' ' + f.aliases.join(' ') : ''
+      const hay = f.description + aliasText + ' ' + f.file.replace(/\.md$/, '').replace(/[_-]/g, ' ')
+      return { ...f, score: score(query, hay) }
+    })
+    .filter(f => f.score > 0)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, MAX_RESULTS)
+}
+
+/**
+ * 选 baseline 条目：按显式 `baselinePriority` 排，不按文件名。
+ *
+ * 文件名排序等于让 `feedback_*` 无条件压过 `user_*`，与「哪条更该出现在每场
+ * 会话开头」毫无关系。没写这个字段的老条目一律算 0，行为与从前一致。
+ */
+export function selectBaseline(files) {
+  return files
+    .filter(f => f.baseline)
+    .sort((a, b) => (b.baselinePriority || 0) - (a.baselinePriority || 0) || a.file.localeCompare(b.file))
+    .slice(0, MAX_BASELINE)
+}
+
+/**
+ * 一条记忆「多久以前写下的」（整数天；null = 无从判断）。
+ *
+ * **优先 frontmatter 的 `updated`，缺失才回落文件 mtime —— 顺序不能反。**
+ * 文件系统时间会被复制、checkout、备份还原整批改掉，它表示的是「这个文件什么时候
+ * 被动过」，不是「这条记忆什么时候写的」。手写的时间戳才是权威。
+ *
+ * 未来日期（时钟偏差 / 手写错）一律当 0：宁可标「今天」也不要标负数。
+ */
+export function ageDays(f, nowMs) {
+  const fromMeta = Date.parse(f?.updated || '')
+  const base = Number.isFinite(fromMeta) ? fromMeta : (Number.isFinite(f?.mtimeMs) ? f.mtimeMs : NaN)
+  if (!Number.isFinite(base)) return null
+  const days = Math.floor((nowMs - base) / 86400000)
+  return days > 0 ? days : 0
+}

package/lib/memory/scan.js

@@ -0,0 +1,81 @@
+/**
+ * sage-mem 记忆层 —— 目录扫描：读回全部记忆文件，以及星图要的轻量元数据。
+ */
+
+import { MEMORY_DIR } from './config.js'
+import { parseBaseline, parseFrontmatter } from './frontmatter.js'
+import { isMemoryEntry } from './naming.js'
+import { warnLog } from './util.js'
+import { readFile, readdir, stat } from 'node:fs/promises'
+import { join } from 'node:path'
+
+/** 扫 memory 目录，读回全部记忆文件（跳过索引与子目录），并解析 frontmatter 摘要。 */
+export async function scanMemoryFiles(ctx, sessionId) {
+  try {
+    const entries = await readdir(MEMORY_DIR, { withFileTypes: true })
+    const names = entries
+      .filter(e => e.isFile() && isMemoryEntry(e.name))
+      .map(e => e.name)
+    const loaded = await Promise.all(names.map(async (name) => {
+      try {
+        const full = join(MEMORY_DIR, name)
+        // stat 与 readFile 并行 —— 多要一个 mtime 不该变成串行两跳。
+        const [content, info] = await Promise.all([readFile(full, 'utf8'), stat(full)])
+        const meta = parseFrontmatter(content)
+        return {
+          file: name,
+          content,
+          description: meta.description || '',
+          aliases: meta.aliases || [],
+          baseline: parseBaseline(content),
+          baselinePriority: meta.baselinePriority || 0,
+          // 新鲜度的两个来源：frontmatter 的 updated（权威）与文件 mtime（退路）。
+          updated: meta.updated || '',
+          mtimeMs: info.mtimeMs,
+        }
+      } catch (err) {
+        // 只有 ENOENT 是正常状态（扫到读之间被删）。其余——权限错、编码坏、盘掉线——
+        // 一律出声：这里的静默化就是把「记忆不再注入」变成无声事故的那一手。
+        if (err?.code !== 'ENOENT') warnLog(ctx, `cannot read ${name}: ${err?.message ?? err}`, sessionId)
+        return null
+      }
+    }))
+    return loaded.filter(Boolean)
+  } catch (err) {
+    if (err?.code !== 'ENOENT') warnLog(ctx, `cannot scan ${MEMORY_DIR}: ${err?.message ?? err}`, sessionId)
+    return []
+  }
+}
+
+/** 提取正文第一个 `# ` 标题作为展示标题。 */
+export function extractTitle(content) {
+  const m = content.match(/^---\r?\n[\s\S]*?\r?\n---/)
+  const body = m ? content.slice(m[0].length) : content
+  const h1 = body.match(/^#\s+(.+)$/m)
+  return h1 ? h1[1].trim() : ''
+}
+
+/** 扫记忆目录，读全部 .md（跳过索引与 session-log），带体积与修改时间。 */
+export async function scanStars(ctx) {
+  let entries
+  try {
+    entries = await readdir(MEMORY_DIR, { withFileTypes: true })
+  } catch (err) {
+    if (err?.code !== 'ENOENT') warnLog(ctx, `cannot scan ${MEMORY_DIR}: ${err?.message ?? err}`)
+    return []
+  }
+  const names = entries
+    .filter(e => e.isFile() && isMemoryEntry(e.name))
+    .map(e => e.name)
+  const loaded = await Promise.all(names.map(async (name) => {
+    try {
+      const full = join(MEMORY_DIR, name)
+      const [content, info] = await Promise.all([readFile(full, 'utf8'), stat(full)])
+      return { name, content, bytes: info.size, mtimeMs: info.mtimeMs }
+    } catch (err) {
+      if (err?.code !== 'ENOENT') warnLog(ctx, `cannot read ${name}: ${err?.message ?? err}`)
+      return null
+    }
+  }))
+  return loaded.filter(Boolean)
+}

package/lib/memory/util.js

@@ -0,0 +1,37 @@
+/**
+ * sage-mem 记忆层 —— 通用小工具：统一日志出口与原子写。
+ */
+
+import { rename, unlink, writeFile } from 'node:fs/promises'
+
+/**
+ * 统一告警出口。所有非 ENOENT 的失败都必须落到日志，绝不静默
+ * （历史坑见 assemble 监听器里那段注释：表现是「插件在、记忆不再注入」，日志一字没有）。
+ * @param ctx — 插件上下文，取 ctx.logger.warn
+ * @param msg — 消息正文，调用方负责带上文件名 / 目录名
+ * @param sessionId — 可选 session id，有就带
+ */
+export function warnLog(ctx, msg, sessionId) {
+  const line = `sage-mem: ${msg}${sessionId ? ` (session ${sessionId})` : ''}`
+  if (ctx?.logger?.warn) ctx.logger.warn(line)
+  else console.warn(line)
+}
+
+/**
+ * 原子写：先写同目录临时文件，再 rename 覆盖目标。
+ *
+ * 直写的风险是崩在中途（断电、进程被杀、磁盘满）留下半截文件 —— frontmatter
+ * 缺半边，这条记忆从此解析不出来、检索不到，而文件看上去还在。
+ * 同卷 rename 是原子的：读方要么看到旧全文、要么看到新全文，不存在中间态。
+ * 任何一步失败都不碰目标文件，临时文件收尾清掉。
+ */
+export async function writeFileAtomic(target, content) {
+  const tmp = `${target}.${process.pid}.tmp`
+  try {
+    await writeFile(tmp, content, 'utf8')
+    await rename(tmp, target)
+  } finally {
+    // rename 成功后 tmp 已不存在（ENOENT），失败时把它清掉不留垃圾。
+    await unlink(tmp).catch(() => {})
+  }
+}