sage-mem 0.8.0 → 0.9.1

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/scan.js

@@ -1,5 +1,13 @@
 /**
- * sage-mem 记忆层 —— 目录扫描：读回全部记忆文件，以及星图要的轻量元数据。
+ * sage-mem 记忆层 —— 目录扫描 + 归档区的读写形状。
+ *
+ * 归档区（`memory/archive/`）**不参与检索**：`scanMemoryFiles` 只扫根目录 ——
+ * 这就是「归档 = 静默失效且可回退」的语义，不是漏扫。归档只在两个地方现身：
+ * 星图（`scanStars(ctx, true)`）与归档列表（`scanArchived`）—— 让**用户**看得见，
+ * 而不是让**模型**想起来。
+ *
+ * 归档留痕写在文件自己的 frontmatter 里（`archived_at` / `archived_reason`）：
+ * 文件可能被手工搬来搬去，随文件走的元数据才不会与文件脱节。
  */
 
 import { MEMORY_DIR } from './config.js'
@@ -9,6 +17,101 @@ import { warnLog } from './util.js'
 import { readFile, readdir, stat } from 'node:fs/promises'
 import { join } from 'node:path'
 
+/** 归档区目录名。与 autodream 工具里的 ARCHIVE_DIR 同名同义（同一个目录）。 */
+export const ARCHIVE_DIR_NAME = 'archive'
+
+/** 归档区绝对路径。文件名不变，只换目录。 */
+export const MEMORY_ARCHIVE_DIR = join(MEMORY_DIR, ARCHIVE_DIR_NAME)
+
+/** 本地时间 `YYYY-MM-DD HH:mm` —— 归档留痕是给人看的，不用 ISO / UTC。 */
+export function localStamp(ms = Date.now()) {
+  const d = new Date(ms)
+  const p = (n) => String(n).padStart(2, '0')
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`
+}
+
+/**
+ * 把一个值写成 YAML 标量。
+ *
+ * 三层处理，少一层就是一个「不报错、值悄悄变形」的陷阱：
+ *   1. **换行折成一个空格**（有意的规范化，不是截断）：裸写出去的话，后半行会变成
+ *      **另一个 YAML 键**（`理由\narchived_reason: 假的` 会写出两个 `archived_reason`），
+ *      或者让 `---` 提前闭合 frontmatter；而 YAML 的多行引号标量读回来又会把换行折成
+ *      空格 —— 两种含糊都不如显式折叠。带过换行的值额外加引号，让读者看得出这行被
+ *      规范化过。
+ *   2. `: `（冒号+空格 → 被当成嵌套映射）与 ` #`（空格+井号 → 后半句被当注释吞掉）
+ *      必须给整值加单引号。
+ *   3. 空值写 `''`（裸写会变 YAML null）。
+ * 单引号按 YAML 规矩翻倍转义。`reason` 来自用户输入，指望人「别写冒号、别写换行」不现实。
+ */
+export function yamlScalar(value) {
+  const raw = String(value ?? '')
+  const hadNewline = /[\r\n]/.test(raw)
+  const s = raw.replace(/[\r\n]+/g, ' ').trim()
+  if (s === '') return "''"
+  if (hadNewline || /:(?:\s|$)| #/.test(s) || /^[-?#&*!|>%@`{}[\],'"]/.test(s)) {
+    return `'${s.replace(/'/g, "''")}'`
+  }
+  return s
+}
+
+/** frontmatter 块（含两侧 `---`）的匹配；没有 frontmatter 返回 null。 */
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---/
+
+/** 文件用的是哪种换行：回写沿用原风格，别把用户文件的 CRLF 悄悄换成 LF。 */
+const eolOf = (content) => (content.includes('\r\n') ? '\r\n' : '\n')
+
+/** 剥掉 YAML 标量两侧的引号（单引号的 `''` 还原成一个 `'`）。 */
+function unquoteYaml(raw) {
+  const s = String(raw ?? '').trim()
+  if (s.length >= 2 && s.startsWith("'") && s.endsWith("'")) return s.slice(1, -1).replace(/''/g, "'")
+  if (s.length >= 2 && s.startsWith('"') && s.endsWith('"')) return s.slice(1, -1).replace(/\\"/g, '"')
+  return s
+}
+
+/** 读 frontmatter 里的归档留痕。没有 frontmatter / 没有这两个字段都回空串。 */
+export function readArchivedMeta(content) {
+  const m = String(content ?? '').match(FRONTMATTER_RE)
+  if (!m) return { archivedAt: '', archivedReason: '' }
+  const grab = (key) => {
+    const hit = m[1].match(new RegExp(`^${key}:[ \\t]*(.*?)[ \\t\\r]*$`, 'm'))
+    return hit ? unquoteYaml(hit[1]) : ''
+  }
+  return { archivedAt: grab('archived_at'), archivedReason: grab('archived_reason') }
+}
+
+/** 去掉归档留痕两行（恢复时用）。没有 frontmatter 就原样返回。 */
+export function stripArchiveMeta(content) {
+  const src = String(content ?? '')
+  const m = src.match(FRONTMATTER_RE)
+  if (!m) return src
+  const eol = eolOf(src)
+  const body = m[1]
+    .split(/\r?\n/)
+    .filter((line) => !/^[ \t]*archived_(at|reason)[ \t]*:/.test(line))
+  const block = ['---', ...body, '---'].join(eol)
+  return block + src.slice(m.index + m[0].length)
+}
+
+/**
+ * 写入归档留痕：`archived_at` + `archived_reason` 插在 frontmatter 末尾。
+ *
+ * 已经是归档态的文件再归档没有意义（上层会先拒绝），所以这里只做 upsert：
+ * 先剥掉旧的两行再插，免得同一份文件里出现两个 `archived_at`。
+ * 没有 frontmatter 的文件补一个最小块 —— 归档信息必须有地方放。
+ */
+export function addArchiveMeta(content, reason, at) {
+  const src = String(content ?? '')
+  const eol = eolOf(src)
+  const lines = [`archived_at: ${yamlScalar(at)}`, `archived_reason: ${yamlScalar(reason)}`]
+  const stripped = stripArchiveMeta(src)
+  const m = stripped.match(FRONTMATTER_RE)
+  if (!m) return ['---', ...lines, '---', '', stripped].join(eol)
+  const block = m[0].split(/\r?\n/)
+  block.splice(block.length - 1, 0, ...lines)
+  return stripped.slice(0, m.index) + block.join(eol) + stripped.slice(m.index + m[0].length)
+}
+
 /** 扫 memory 目录，读回全部记忆文件（跳过索引与子目录），并解析 frontmatter 摘要。 */
 export async function scanMemoryFiles(ctx, sessionId) {
   try {
@@ -55,13 +158,13 @@ export function extractTitle(content) {
   return h1 ? h1[1].trim() : ''
 }
 
-/** 扫记忆目录，读全部 .md（跳过索引与 session-log），带体积与修改时间。 */
-export async function scanStars(ctx) {
+/** 扫一个目录，读回星图要的轻量元数据（正文 + 体积 + 修改时间）。 */
+async function readStarDir(dir, ctx) {
   let entries
   try {
-    entries = await readdir(MEMORY_DIR, { withFileTypes: true })
+    entries = await readdir(dir, { withFileTypes: true })
   } catch (err) {
-    if (err?.code !== 'ENOENT') warnLog(ctx, `cannot scan ${MEMORY_DIR}: ${err?.message ?? err}`)
+    if (err?.code !== 'ENOENT') warnLog(ctx, `cannot scan ${dir}: ${err?.message ?? err}`)
     return []
   }
   const names = entries
@@ -69,13 +172,33 @@ export async function scanStars(ctx) {
     .map(e => e.name)
   const loaded = await Promise.all(names.map(async (name) => {
     try {
-      const full = join(MEMORY_DIR, name)
+      const full = join(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}`)
+      if (err?.code !== 'ENOENT') warnLog(ctx, `cannot read ${full}: ${err?.message ?? err}`)
       return null
     }
   }))
   return loaded.filter(Boolean)
 }
+
+/**
+ * 扫归档区 `memory/archive/`。返回形状与 `readStarDir` 一致（多了 `archived: true`）。
+ * 归档区不存在是正常状态（没人归档过）→ 空数组，不是错误。
+ */
+export async function scanArchived(ctx) {
+  const rows = await readStarDir(MEMORY_ARCHIVE_DIR, ctx)
+  return rows.map(f => ({ ...f, archived: true }))
+}
+
+/**
+ * 扫记忆目录，读全部 .md（跳过索引与 session-log），带体积与修改时间。
+ *
+ * @param {boolean} [includeArchived] — 带上归档区的条目（默认不带：星图默认只看活着的）
+ */
+export async function scanStars(ctx, includeArchived = false) {
+  const active = (await readStarDir(MEMORY_DIR, ctx)).map(f => ({ ...f, archived: false }))
+  if (includeArchived !== true) return active
+  return [...active, ...(await scanArchived(ctx))]
+}