sage-mem 0.7.2 → 0.9.0

package/lib/memory/access.js

@@ -0,0 +1,220 @@
+/**
+ * sage-mem 记忆层 —— 访问台账 + 自动归档候选。
+ *
+ * 台账 = `<状态根>/access.json`：`{ "<文件名>": <最近一次被注入的毫秒时间戳> }`。
+ *
+ * ⚠️ **只写状态目录，绝不往记忆文件里写 `last_accessed`。** 往记忆文件写等于在读路径上
+ * 写盘：只读模式、并发、mtime 抖动全会出问题 —— 而读路径必须无副作用。
+ *
+ * 它同时是「自动归档」那个 N 天阈值**唯一**的数据来源：没有台账，「多久没被用过」只能
+ * 看 frontmatter 的 updated 或文件 mtime，而这两个都不等于「没被用过」（手改一个字就刷新）。
+ *
+ * 候选计算是**纯确定性**的：不调模型、不看语义，只看「距上次被注入多少天」。
+ */
+
+import { MEMORY_DIR, STATE_ROOT } from './config.js'
+import { ARCHIVE_DIR_NAME } from './scan.js'
+import { isMemoryEntry } from './naming.js'
+import { parseFrontmatter } from './frontmatter.js'
+import { writeFileAtomic } from './util.js'
+import { mkdir, readFile, readdir } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+
+/** 台账文件：状态根下，与记忆文件分开。 */
+export const ACCESS_LEDGER_FILE = join(STATE_ROOT, 'access.json')
+
+/** 落盘节流：内存先累计，最多每 30 秒写一次盘。 */
+export const ACCESS_FLUSH_INTERVAL_MS = 30 * 1000
+
+/** 开了才出声：台账写不进去是**静默降级**，没有这个开关就查不出「为什么阈值算不准」。 */
+const DEBUG = process.env.SAGE_MEM_DEBUG === '1'
+
+/** 「永不自动归档」的类型：feedback 是用户给的做事方式，退役它等于把人的交代扔掉。 */
+export const NEVER_ARCHIVE_TYPES = new Set(['feedback'])
+
+/** 内存累计（尚未落盘）：文件名 → 时间戳，同名取最新。 */
+let pending = new Map()
+let flushTimer = null
+let lastFlushAt = 0
+
+/**
+ * 记一次「这些文件真的被注入了」。
+ *
+ * 只进内存，落盘交给节流器 —— 注入链每步都跑，每步落盘就是拿读路径的稳定性换数据。
+ * **同步、绝不抛**：台账是观测数据，它的问题不许升级成「记忆不再注入」。
+ */
+export function recordAccess(names, at = Date.now()) {
+  for (const n of names ?? []) {
+    if (typeof n === 'string' && n) pending.set(n, at)
+  }
+  scheduleFlush()
+}
+
+function scheduleFlush() {
+  if (flushTimer) return
+  const wait = Math.max(0, ACCESS_FLUSH_INTERVAL_MS - (Date.now() - lastFlushAt))
+  flushTimer = setTimeout(() => {
+    flushTimer = null
+    flushAccess().catch(() => {})
+  }, wait)
+  // 不阻止进程退出：这只是「顺带记一笔」的台账。
+  if (typeof flushTimer.unref === 'function') flushTimer.unref()
+}
+
+/** 读盘上的台账。读不到 / JSON 坏 / 不是对象 / 值不是有限数 → 一律当空台账。 */
+export async function readAccessLedger() {
+  try {
+    const parsed = JSON.parse(await readFile(ACCESS_LEDGER_FILE, 'utf8'))
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return {}
+    const out = {}
+    for (const [k, v] of Object.entries(parsed)) {
+      if (typeof k === 'string' && Number.isFinite(v)) out[k] = v
+    }
+    return out
+  } catch {
+    return {}
+  }
+}
+
+/**
+ * 当前**真实存在**的记忆文件名（根目录 + `archive/`）。
+ *
+ * 归档区的名字要算：归档的记忆将来可能被恢复，它「上次被注入」的时间仍然有意义。
+ * 返回 `null` = 「这次扫不动」→ 调用方**保留全部键**，绝不把一次读盘失败当成
+ * 「文件都没了」而清空台账。
+ *
+ * 两类 ENOENT 必须分开看：**`archive/` 的 ENOENT 是正常状态**（没人归档前它一直不存在），
+ * 而**记忆根目录的 ENOENT 不是** —— 那说明这个路径根本不是记忆目录，按「空」回收就是
+ * 一次静默的数据清空。详见下面的注释。
+ */
+async function currentMemoryNames(memoryDir) {
+  const out = new Set()
+  let unknown = false
+  const collect = async (dir) => {
+    const entries = await readdir(dir, { withFileTypes: true })
+    for (const e of entries) if (e.isFile() && isMemoryEntry(e.name)) out.add(e.name)
+  }
+  // 记忆根目录：**任何**读失败（含 ENOENT）都算「不知道」。
+  // 根目录不存在不等于「记忆都没了」，而是「这个路径根本不是记忆目录」——参数传错、
+  // 盘没挂上、目录被挪走。这时按「空」回收就是一次**静默的数据清空**：idleDays 会全体
+  // 回落到 updated/mtime，自动归档阈值从此算错，而且没有任何信号。
+  // 宁可留死键（下轮真扫到时自然会清），不可误清。
+  try {
+    await collect(memoryDir)
+  } catch {
+    unknown = true
+  }
+  // 归档区：ENOENT 是**正常状态**（没人归档前这个目录一直不存在）→ 算空；
+  // 其余读失败（权限、盘掉线、父路径不是目录）保留全部键。
+  try {
+    await collect(join(memoryDir, ARCHIVE_DIR_NAME))
+  } catch (err) {
+    if (err?.code !== 'ENOENT') unknown = true
+  }
+  return unknown ? null : out
+}
+
+/**
+ * 把内存里的增量并到盘上（合并写：同一文件只留最新时间戳），**落盘前顺手回收死键**。
+ *
+ * 台账没有别的回收物：记忆被归档 / 改名 / 删除之后，它再也不会被注入，那条时间戳
+ * 就永远烂在盘上 —— autodream 的状态有 pruneSnapshots，台账也得有对应物。
+ * 回收**只跟着真正的写盘一起做**（batch 非空）：一次纯粹的强刷不该去动一个没必要
+ * 动的文件，也避免「拿着别的记忆目录来刷」时误清。
+ *
+ * **强制 flush 的时机**：每次 autodream 运行前 —— 否则「这趟整理看到的台账」可能落后
+ * 若干步注入，阈值就会算偏。失败时把这一批放回内存，下次还有机会。
+ *
+ * @param {string} [memoryDir] — 记忆根目录（引擎必须传自己的，不许拿模块常量：它可能是别的目录）
+ */
+export async function flushAccess(memoryDir = MEMORY_DIR) {
+  if (pending.size === 0) return { ok: true, written: 0 }
+  const batch = pending
+  pending = new Map()
+  try {
+    const onDisk = await readAccessLedger()
+    for (const [name, at] of batch) {
+      if (!Number.isFinite(onDisk[name]) || at > onDisk[name]) onDisk[name] = at
+    }
+    const alive = await currentMemoryNames(memoryDir)
+    if (alive) {
+      for (const key of Object.keys(onDisk)) {
+        if (!alive.has(key)) delete onDisk[key]
+      }
+    }
+    // 状态目录是插件自己的地盘，缺了可以建（autodream 的配置也存在这儿）。
+    // 建不出来（只读、父路径不是目录）就走 catch 静默降级。
+    await mkdir(dirname(ACCESS_LEDGER_FILE), { recursive: true })
+    await writeFileAtomic(ACCESS_LEDGER_FILE, JSON.stringify(onDisk, null, 2))
+    lastFlushAt = Date.now()
+    return { ok: true, written: batch.size, reclaimed: alive ? true : false }
+  } catch (err) {
+    for (const [name, at] of batch) if (!pending.has(name)) pending.set(name, at)
+    // 静默降级：注入是插件最核心的事，台账写不进去不许把它拖下水。开了 DEBUG 才出声。
+    if (DEBUG) console.warn(`[sage-mem][debug] access ledger flush failed: ${err?.message ?? err}`)
+    return { ok: false, error: err?.message ?? String(err) }
+  }
+}
+
+/** 清掉内存里没落盘的增量（只给测试用：一次进程里想从头验节流）。 */
+export function __resetAccessPendingForTest() {
+  pending = new Map()
+  flushTimer = null
+  lastFlushAt = 0
+}
+
+/** 一条记忆的类型：frontmatter 的 `type` 优先，回落文件名前缀（`project_x.md` → `project`）。 */
+export function fileType(f) {
+  const fromMeta = f?.content ? parseFrontmatter(f.content).type : ''
+  return String(fromMeta || f?.type || f?.file || '').split('_')[0].toLowerCase()
+}
+
+/**
+ * 一条记忆「多久没被注入」（整数天；null = 无从判断）。
+ *
+ * 顺序不能反：**台账 → frontmatter 的 updated → 文件 mtime**。台账是「真的被用过」的
+ * 唯一证据；updated 是「人写过」；mtime 只是「文件被动过」——复制、checkout、备份还原
+ * 都会把它整批改掉。
+ */
+export function idleDays(f, ledger = {}, now = Date.now()) {
+  const seen = ledger?.[f?.file]
+  const fromMeta = Date.parse(f?.updated || '')
+  const base = Number.isFinite(seen)
+    ? seen
+    : (Number.isFinite(fromMeta) ? fromMeta : (Number.isFinite(f?.mtimeMs) ? f.mtimeMs : NaN))
+  if (!Number.isFinite(base)) return null
+  const days = Math.floor((now - base) / 86400000)
+  return days > 0 ? days : 0
+}
+
+/**
+ * 算自动归档候选（确定性，不调模型）。
+ *
+ * @param {Array} files — `scanMemoryFiles` 的结果（**只有根目录**，所以归档区天然不在内）
+ * @param {Object} ledger — 访问台账
+ * @param {{thresholds?: Object}} opts — 按类型的阈值（天）；缺阈值＝该类型永不候选
+ * @returns {Array<{file:string,type:string,days:number,limit:number,reason:string}>} 按闲置天数降序
+ */
+export function pickArchiveCandidates(files, ledger = {}, opts = {}, now = Date.now()) {
+  const thresholds = opts.thresholds ?? {}
+  const out = []
+  for (const f of files ?? []) {
+    if (!f?.file || f.archived === true) continue
+    const type = fileType(f)
+    if (NEVER_ARCHIVE_TYPES.has(type)) continue
+    // baseline 是「每场会话必读」的那几条：它们本来就不靠检索命中，闲置天数没有意义。
+    if (f.baseline === true) continue
+    const limit = Number(thresholds[type])
+    if (!Number.isFinite(limit) || limit <= 0) continue
+    const days = idleDays(f, ledger, now)
+    if (days === null || days < limit) continue
+    out.push({
+      file: f.file,
+      type,
+      days,
+      limit,
+      reason: `已 ${days} 天未被注入（${type} 阈值 ${limit} 天）`,
+    })
+  }
+  return out.sort((a, b) => b.days - a.days || a.file.localeCompare(b.file))
+}

package/lib/memory/archive.js

@@ -0,0 +1,91 @@
+/**
+ * sage-mem 记忆层 —— 归档的**唯一实现**。
+ *
+ * 归档有三条入口：手动 remote（`memory.archive`）、模型工具（autodream 的
+ * `archive_memory`）、自动归档策略。三处都调这里 —— 之前「手动写留痕、工具只 rename」
+ * 是两份实现，已经漂移过一次：自动归档收起来的记忆在面板上显示「时间未知 / 没写理由」，
+ * 而档案馆的意义恰恰是回答「它为什么被收起来」。
+ *
+ * 语义（A 阶段冻结、三条路径共用）：
+ *   - **只移不删**：文件进 `archive/`，名字不变；
+ *   - 移动前写 `archived_at`（本地时间 `YYYY-MM-DD HH:mm`）与 `archived_reason`；
+ *   - 拒绝一律返回 `{ ok:false, code, error }`，由调用方决定抛还是回 `{ ok:false }`。
+ *
+ * ⚠️ 记忆目录**必须由调用方传进来**：autodream 引擎的 memoryDir 可以是任意目录（测试里
+ * 就是临时目录），拿模块级常量会写错地方 —— 那是会碰到真实记忆的危险错误。
+ */
+
+import { ARCHIVE_DIR_NAME, addArchiveMeta, localStamp, stripArchiveMeta } from './scan.js'
+import { isReserved, nameKey, safeName } from './naming.js'
+import { writeFileAtomic } from './util.js'
+import { mkdir, readFile, stat, unlink } from 'node:fs/promises'
+import { join } from 'node:path'
+
+/** 归档区绝对路径（按调用方给的记忆目录算）。 */
+export const archiveDirOf = (memoryDir) => join(memoryDir, ARCHIVE_DIR_NAME)
+
+/** 名字闸门：保留名 → 非 .md / 带路径成分。返回 { ok:true, safe } 或 { ok:false, code, error }。 */
+function checkName(name, verb) {
+  if (isReserved(name)) {
+    return { ok: false, code: 'reserved', error: `sage-mem: reserved file, refusing to ${verb}: ${nameKey(name)}` }
+  }
+  const safe = safeName(name)
+  if (!safe) return { ok: false, code: 'invalid-name', error: `sage-mem: invalid file name: ${String(name)}` }
+  return { ok: true, safe }
+}
+
+/**
+ * 归档一条记忆：写留痕 + 移进 `archive/`（不删）。
+ *
+ * @param {string} memoryDir — 记忆根目录（调用方给，不许拿模块常量）
+ * @param {string} name — 文件名（根目录里必须已存在）
+ * @param {string} [reason] — 归档缘由；空/省略时写默认「手动归档」
+ * @param {string} [at] — 归档时间（默认本地时间 `YYYY-MM-DD HH:mm`）
+ * @returns {Promise<{ok:true,file:string,archivedReason:string}|{ok:false,code:string,error:string}>}
+ */
+export async function archiveMemory(memoryDir, name, reason, at = localStamp()) {
+  const gate = checkName(name, 'archive')
+  if (!gate.ok) return gate
+  const safe = gate.safe
+  const src = join(memoryDir, safe)
+  const dst = join(archiveDirOf(memoryDir), safe)
+  const info = await stat(src).catch(() => null)
+  // 根目录里没有 → 文件名写错，或者它已经是归档态（归档区那份不该再归档一次）。
+  if (!info?.isFile()) return { ok: false, code: 'not-found', error: `sage-mem: file not found: ${safe}` }
+  if (await stat(dst).catch(() => null)) {
+    // 归档区已有同名：不覆盖 —— 那份旧归档可能是用户想留的另一版。
+    return { ok: false, code: 'exists', error: `sage-mem: already archived: ${safe}` }
+  }
+  const content = await readFile(src, 'utf8')
+  // 空理由给默认值：手动 remote 允许省略（工具那侧自己会先挡掉空理由，那是它自己的语义）。
+  const why = String(reason ?? '').trim() || '手动归档'
+  const stamped = addArchiveMeta(content, why, at)
+  await mkdir(archiveDirOf(memoryDir), { recursive: true })
+  // 先落归档副本、再删原件：中途崩了最坏是两份都在（人工可收拾），不会一份都没有。
+  await writeFileAtomic(dst, stamped)
+  await unlink(src)
+  return { ok: true, file: safe, archivedReason: why }
+}
+
+/**
+ * 从归档区恢复：移回根目录并去掉两行留痕。
+ *
+ * 根目录已有同名时**拒绝**：根目录那份是正在用的记忆，归档这份只是退役版 ——
+ * 覆盖等于悄悄改掉一条活记忆。
+ */
+export async function restoreMemory(memoryDir, name) {
+  const gate = checkName(name, 'restore')
+  if (!gate.ok) return gate
+  const safe = gate.safe
+  const dst = join(memoryDir, safe)
+  const src = join(archiveDirOf(memoryDir), safe)
+  const info = await stat(src).catch(() => null)
+  if (!info?.isFile()) return { ok: false, code: 'not-archived', error: `sage-mem: not archived: ${safe}` }
+  if (await stat(dst).catch(() => null)) {
+    return { ok: false, code: 'target-exists', error: `sage-mem: already exists, refusing to overwrite: ${safe}` }
+  }
+  const content = await readFile(src, 'utf8')
+  await writeFileAtomic(dst, stripArchiveMeta(content))
+  await unlink(src)
+  return { ok: true, file: safe }
+}

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
+}