sage-mem 0.8.0 → 0.9.0

package/lib/index.js

@@ -15,15 +15,120 @@
  */
 
 import { AutodreamEngine } from './autodream.js'
-import { MAX_BASELINE, MAX_CHARS_PER_FILE, MAX_FILE_BYTES, MAX_RESULTS, MAX_SESSION_BYTES, MEMORY_DIR, RECALL_DISCIPLINE, RESERVED_FILES, SESSIONS_ROOT, STALE_DAYS } from './memory/config.js'
+import { auditMemoryDir } from './autodream-audit.js'
+import { DEFAULT_CONFIG } from './autodream/config.js'
+import { readJson } from './autodream/util.js'
+import { MAX_BASELINE, MAX_CHARS_PER_FILE, MAX_FILE_BYTES, MAX_RESULTS, MAX_SESSION_BYTES, MEMORY_DIR, RECALL_DISCIPLINE, RESERVED_FILES, SESSIONS_ROOT, STALE_DAYS, STATE_ROOT } from './memory/config.js'
 import { parseAliases, parseBaseline, parseBaselinePriority, parseFrontmatter, parseTags } from './memory/frontmatter.js'
 import { isReserved, nameKey, safeName } from './memory/naming.js'
 import { ageDays, bigrams, extractText, score, selectBaseline, selectRelevant } from './memory/retrieval.js'
-import { extractTitle, scanMemoryFiles, scanStars } from './memory/scan.js'
+import { MEMORY_ARCHIVE_DIR, addArchiveMeta, extractTitle, readArchivedMeta, scanArchived, scanMemoryFiles, scanStars } from './memory/scan.js'
+import { archiveMemory, restoreMemory } from './memory/archive.js'
+import { flushAccess, pickArchiveCandidates, readAccessLedger, recordAccess } from './memory/access.js'
 import { warnLog, writeFileAtomic } from './memory/util.js'
 import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol'
-import { readFile, unlink, writeFile } from 'node:fs/promises'
-import { join } from 'node:path'
+import { mkdir, readFile, stat, unlink, writeFile } from 'node:fs/promises'
+import { basename, join } from 'node:path'
+
+/**
+ * `SAGE_MEM_DEBUG=1` 才出声的注入链调试出口。
+ *
+ * 一行结构化 JSON：候选数 / 命中数 / 逐条得分 / 入选与真注入的文件名 / 注入字符数 /
+ * 被会话预算挡掉几条。它回答的是「这条记忆为什么没被召回」——一个光看上下文永远查不出的问题。
+ *
+ * ⚠️ **不开时零输出、零额外开销**：常量的读取只在模块加载时发生一次；调用点整个包在
+ * `if (DEBUG_RECALL)` 里，连 payload 对象都不会被构造出来。
+ */
+const DEBUG_RECALL = process.env.SAGE_MEM_DEBUG === '1'
+
+function debugRecall(payload) {
+  if (!DEBUG_RECALL) return
+  console.log(`[sage-mem] recall ${JSON.stringify(payload)}`)
+}
+
+/**
+ * 面板可改的 5 项注入上限 —— 与 `memory/config.js` 里的 `SAGE_MEM_*` 一一对应。
+ * 边界值照抄那边的 envInt 调用（lo/hi 不许在这里另立一套）。
+ */
+const LIMIT_SPECS = {
+  maxResults: { env: 'SAGE_MEM_MAX_RESULTS', dflt: 10, lo: 1, hi: 30 },
+  maxChars: { env: 'SAGE_MEM_MAX_CHARS', dflt: 1500, lo: 200, hi: 20000 },
+  maxBaseline: { env: 'SAGE_MEM_MAX_BASELINE', dflt: 8, lo: 1, hi: 50 },
+  maxSessionBytes: { env: 'SAGE_MEM_MAX_SESSION_BYTES', dflt: 60 * 1024, lo: 4096, hi: 512 * 1024 },
+  staleDays: { env: 'SAGE_MEM_STALE_DAYS', dflt: 1, lo: 0, hi: 365 },
+}
+
+/** 面板设置的落点：状态根下（与 autodream 的配置、台账同级）。 */
+const SETTINGS_FILE = join(STATE_ROOT, 'settings.json')
+const RESERVED_FILE = join(STATE_ROOT, 'reserved.json')
+
+/**
+ * `writeRaw` 的体积上限（4 MB）。
+ *
+ * ⚠️ **故意不复用 `MAX_FILE_BYTES`（512 KB）**：保留名里就有 `session-log.md` 这种追加型
+ * 流水，它天然长得比单条记忆大得多（实测已 > 512 KB）。沿用小上限 = 用户永远存不回去。
+ */
+const MAX_RAW_BYTES = 4 * 1024 * 1024
+
+/** 整数收敛（与 config.js 的 envInt 同一套语义）：非有限数回落默认，越界夹到边界。 */
+const clampInt = (v, spec) => (Number.isFinite(v) ? Math.max(spec.lo, Math.min(spec.hi, Math.round(v))) : spec.dflt)
+
+/** 读 `<状态根>/settings.json`；缺失、坏 JSON、不是对象都当「没设置」。 */
+async function readSettingsFile() {
+  try {
+    const parsed = JSON.parse(await readFile(SETTINGS_FILE, 'utf8'))
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null
+  } catch {
+    return null
+  }
+}
+
+/** 待生效的 5 项上限：`settings.json` > 环境变量 > 内置默认。 */
+function pendingLimits(fileObj) {
+  const out = {}
+  const saved = fileObj?.limits && typeof fileObj.limits === 'object' ? fileObj.limits : {}
+  for (const [key, spec] of Object.entries(LIMIT_SPECS)) {
+    const fromFile = Number(saved[key])
+    if (Number.isFinite(fromFile)) {
+      out[key] = clampInt(fromFile, spec)
+      continue
+    }
+    const raw = process.env[spec.env]
+    out[key] = clampInt(raw === undefined || raw === '' ? NaN : Number(raw), spec)
+  }
+  return out
+}
+
+/** 读 `<状态根>/reserved.json`（用户声明的保护名单）。**保留原始大小写**，好让 get 读回一致。 */
+async function readReservedFile() {
+  try {
+    const arr = JSON.parse(await readFile(RESERVED_FILE, 'utf8'))
+    if (!Array.isArray(arr)) return []
+    return arr
+      .map((s) => String(s).trim())
+      .filter((s) => s.endsWith('.md') && !s.includes('/') && !s.includes('\\') && !s.startsWith('..'))
+  } catch {
+    return []
+  }
+}
+
+/**
+ * 原样读写用的名字校验：只要求「单段、`.md`」。
+ *
+ * ⚠️ **故意不走 `safeName`**：那个函数把 `MEMORY.md` / `session-log.md` 当非记忆条目排除，
+ * 而它们恰恰是 `readRaw` / `writeRaw` 的目标。这里只防路径成分与扩展名。
+ */
+function rawName(raw) {
+  const s = typeof raw === 'string' ? raw : ''
+  if (!s || basename(s) !== s) return null
+  return /\.md$/i.test(s) ? s : null
+}
+
+/** autodream 的实际配置（缺文件/坏文件回落默认值）—— 面板要显示真实策略，不能显示想象。 */
+async function autodreamConfigSnapshot() {
+  const parsed = await readJson(join(STATE_ROOT, 'autodream.json'))
+  return { ...DEFAULT_CONFIG, ...(parsed?.config ?? {}) }
+}
 
 /**
  * 手动 @Remote marker 注册（Node 24 不解析装饰器语法，手写 decorator context）。
@@ -177,7 +282,10 @@ export class MemoryGateway extends TypertRemoteService {
           relevant.forEach(take)
         }
 
-        if (picked.length === 0) return assembled
+        if (picked.length === 0) {
+          if (DEBUG_RECALL) debugRecall({ scanned: files.length, hits: relevant.length, scores: [], picked: [], injected: [], chars: 0, skippedByBudget: 0 })
+          return assembled
+        }
 
         // ── 单会话累计预算 ──
         // 账记在 session id 上；消息条数变小 = 压缩/清空发生过 → 账本归零（见上面
@@ -189,6 +297,7 @@ export class MemoryGateway extends TypertRemoteService {
         const nowMs = Date.now()
 
         const parts = []
+        const injectedFiles = []
         let skippedForBudget = 0
         for (const f of picked) {
           const body = f.content.length > MAX_CHARS_PER_FILE
@@ -201,11 +310,26 @@ export class MemoryGateway extends TypertRemoteService {
           if (usedBytes + size > MAX_SESSION_BYTES) { skippedForBudget++; continue }
           usedBytes += size
           parts.push(part)
+          injectedFiles.push(f.file)
         }
 
+        // 进上下文的这些才算「被用过」—— 台账是自动归档阈值的唯一数据源，记错一步阈值就偏。
+        // recordAccess 同步、绝不抛：台账的问题不许升级成注入失败。
+        recordAccess(injectedFiles, nowMs)
+
         // 被预算挡掉了全部条目 —— 一个字都不注。本会话已经注进去的那批还在上下文里，
         // 每步再塞一条「预算已满」只是白花 token；真压缩过之后账本会自己归零。
-        if (parts.length === 0) return assembled
+        // 这条早退也要出声：一条都没注进去，正是最需要解释的那种情况。
+        if (parts.length === 0) {
+          if (DEBUG_RECALL) {
+            debugRecall({
+              scanned: files.length, hits: relevant.length,
+              scores: relevant.map(f => [f.file, Number(f.score.toFixed(4))]),
+              picked: picked.map(f => f.file), injected: [], chars: usedBytes, skippedByBudget: skippedForBudget,
+            })
+          }
+          return assembled
+        }
 
         injectLedger.set(ledgerKey, { bytes: usedBytes, messageCount: messages.length })
         if (injectLedger.size > INJECT_LEDGER_MAX) {
@@ -219,6 +343,18 @@ export class MemoryGateway extends TypertRemoteService {
           (skippedForBudget > 0 ? `；因预算省略 ${skippedForBudget} 条，需要时直接用文件工具读 ${MEMORY_DIR}` : '') +
           '）'
 
+        if (DEBUG_RECALL) {
+          debugRecall({
+            scanned: files.length,
+            hits: relevant.length,
+            scores: relevant.map(f => [f.file, Number(f.score.toFixed(4))]),
+            picked: picked.map(f => f.file),
+            injected: injectedFiles,
+            chars: usedBytes,
+            skippedByBudget: skippedForBudget,
+          })
+        }
+
         return {
           ...assembled,
           contexts: [...(assembled.contexts ?? []), {
@@ -299,35 +435,324 @@ export class MemoryGateway extends TypertRemoteService {
     await unlink(join(MEMORY_DIR, safe))
     return { ok: true }
   }
+
+  /**
+   * 归档一条记忆：把文件移进 `memory/archive/`（**不删**），并在 frontmatter 里留下
+   * `archived_at` / `archived_reason`。
+   *
+   * 语义是「静默失效且可回退」：归档区不参与检索（见 memory/scan.js 的 scanMemoryFiles），
+   * 但列表与星图都看得见它，也能一键恢复 —— 所以这里只是移动 + 打标，绝不 unlink。
+   *
+   * 真正的实现在 `memory/archive.js`：autodream 的 `archive_memory` 工具与自动归档策略
+   * 走的是同一份 —— 三条入口只许有一种行为。
+   *
+   * 拒绝一律返回 `{ ok: false, error }`（不是抛）：面板按 ok 判定，抛出去只会变成
+   * 一句没有上下文的报错。
+   */
+  async archive(name, reason) {
+    const res = await archiveMemory(MEMORY_DIR, name, reason)
+    return res.ok ? { ok: true, file: res.file } : { ok: false, error: res.error }
+  }
+
+  /**
+   * 从归档区恢复一条记忆：移回根目录，并去掉 `archived_at` / `archived_reason` 两行。
+   * 同样委托给 `memory/archive.js`（判断与拒绝矩阵只有一份）。
+   */
+  async restore(name) {
+    const res = await restoreMemory(MEMORY_DIR, name)
+    return res.ok ? { ok: true, file: res.file } : { ok: false, error: res.error }
+  }
+
+  /**
+   * 列出归档区的全部记忆（面板的「已归档」区）。
+   *
+   * 与 `listFiles()` 分开、形状也不同：`listFiles` 只列活动记忆、多一个字段都会破坏
+   * 界面与断言依赖的形状；归档条目额外带 `archivedAt` / `archivedReason`。
+   * 旧版 autodream 工具直接移文件、不写留痕，所以这两个字段可能是空串。
+   */
+  async listArchived() {
+    const files = await scanArchived(this.ctx)
+    const out = files.map(f => {
+      const meta = parseFrontmatter(f.content)
+      const archived = readArchivedMeta(f.content)
+      return {
+        file: f.name,
+        type: meta.type || 'reference',
+        description: meta.description || '',
+        size: f.content.length,
+        tags: meta.tags,
+        archivedAt: archived.archivedAt,
+        archivedReason: archived.archivedReason,
+      }
+    })
+    return { count: out.length, files: out }
+  }
+
+  /**
+   * 读一份**已归档**记忆的全文。
+   *
+   * 归档不是删除，正文就该和活跃记忆一样能看能改（使用者的要求）。名字仍然只走
+   * `safeName`：调用方永远不许自己拼路径，归档区也只认 `memory/archive/` 这一层。
+   */
+  async readArchived(name) {
+    const safe = safeName(name)
+    if (!safe) throw new Error('sage-mem: invalid file name')
+    const full = join(MEMORY_ARCHIVE_DIR, safe)
+    const info = await stat(full).catch(() => null)
+    // 找不到就抛：与 readFile 一致。静默返回空串会让面板显示一个「空的记忆」，
+    // 而用户改完一存 —— 就把一条真实内容顶掉了。
+    if (!info?.isFile()) throw new Error(`sage-mem: archived file not found: ${safe}`)
+    const content = await readFile(full, 'utf8')
+    return { name: safe, content }
+  }
+
+  /**
+   * 写一份**已归档**记忆的正文（覆盖整份文件，形状与 `writeFile` 一致）。
+   *
+   * 三道闸照抄 writeFile：名字先过 safeName、内容必须是字符串、体积上限，最后原子写。
+   * 额外一条：**盘上那份的归档留痕（`archived_at` / `archived_reason`）不许因为改正文而丢**。
+   * 调用方若交回一份连留痕都没有的内容（「重建 frontmatter」式编辑器就是这样），
+   * 这里按盘上原来的值补回去 —— 归档凭据不该依赖调用方是否体贴。
+   */
+  async writeArchived(name, content) {
+    if (isReserved(name)) {
+      return { ok: false, file: nameKey(name), error: `sage-mem: reserved file, edit it with the file tools: ${nameKey(name)}` }
+    }
+    const safe = safeName(name)
+    if (!safe) throw new Error('sage-mem: invalid file name')
+    const full = join(MEMORY_ARCHIVE_DIR, safe)
+    const info = await stat(full).catch(() => null)
+    // 只改归档区里**已经存在**的文件：这条 remote 不是「把任意文件写进归档区」的后门。
+    if (!info?.isFile()) return { ok: false, file: safe, error: `sage-mem: archived file not found: ${safe}` }
+    if (typeof content !== 'string') {
+      return { ok: false, file: safe, error: `sage-mem: content must be a string, got ${typeof content}` }
+    }
+    const bytes = Buffer.byteLength(content, 'utf8')
+    if (bytes > MAX_FILE_BYTES) {
+      return { ok: false, file: safe, error: `sage-mem: content too large (${bytes} bytes > ${MAX_FILE_BYTES})` }
+    }
+    const given = readArchivedMeta(content)
+    let toWrite = content
+    if (!given.archivedAt && !given.archivedReason) {
+      const onDisk = readArchivedMeta(await readFile(full, 'utf8'))
+      if (onDisk.archivedAt || onDisk.archivedReason) {
+        toWrite = addArchiveMeta(content, onDisk.archivedReason, onDisk.archivedAt)
+      }
+    }
+    await writeFileAtomic(full, toWrite)
+    return { ok: true, file: safe }
+  }
+
+  /**
+   * 记忆目录体检：结构化审计结果。
+   *
+   * **直接透出 `auditMemoryDir` 的返回**，不另写一套检查 —— 面板上的「问题」与 autodream
+   * 报告里的必须是同一份判断，否则用户与模型看到的健康状况会互相打架。只读。
+   */
+  async audit() {
+    return auditMemoryDir(MEMORY_DIR)
+  }
+
+  /**
+   * 自动归档候选 + 当前策略与阈值（面板「执行归档」前先看清单）。
+   *
+   * 复用 `memory/access.js` 的台账与候选计算，与 autodream 引擎跑的是同一份逻辑。
+   * 先强制 flush 台账：面板看到的候选不能比引擎少（内存里还压着的那批注入必须算进去）。
+   */
+  async archiveCandidates() {
+    await flushAccess(MEMORY_DIR)
+    const [ledger, files] = await Promise.all([readAccessLedger(), scanMemoryFiles(this.ctx, '')])
+    const cfg = await autodreamConfigSnapshot()
+    const thresholds = {
+      project: cfg.archiveAfterDaysProject,
+      reference: cfg.archiveAfterDaysReference,
+      user: cfg.archiveAfterDaysUser,
+    }
+    const candidates = pickArchiveCandidates(files, ledger, { thresholds })
+    return { count: candidates.length, candidates, autoArchive: cfg.autoArchive, thresholds }
+  }
+
+  /**
+   * 面板上的注入设置（5 项上限 + 保留名保护名单）。
+   *
+   * ⚠️ **这 5 个常量是模块加载时读的**：面板改完要**重启 DSH** 才生效。所以这里同时给出
+   * 「当前生效值」`limits` 与「待生效值」`pendingLimits`，外加 `restartRequired` ——
+   * 界面才能诚实地说「改好了，重启后生效」，而不是让用户以为立刻生效又看不到变化。
+   */
+  async getSettings() {
+    const file = await readSettingsFile()
+    const limits = {
+      maxResults: MAX_RESULTS,
+      maxChars: MAX_CHARS_PER_FILE,
+      maxBaseline: MAX_BASELINE,
+      maxSessionBytes: MAX_SESSION_BYTES,
+      staleDays: STALE_DAYS,
+    }
+    const pending = pendingLimits(file)
+    const reservedExtra = await readReservedFile()
+    // 模块加载时那份「用户声明的保护名」（RESERVED_FILES 里抠掉两个内置名）
+    const activeExtra = [...RESERVED_FILES].filter((n) => n !== 'memory.md' && n !== 'session-log.md')
+    const norm = (list) => JSON.stringify([...list].map((s) => String(s).toLowerCase()).sort())
+    const restartRequired =
+      JSON.stringify(limits) !== JSON.stringify(pending) || norm(activeExtra) !== norm(reservedExtra)
+    return {
+      limits,
+      pendingLimits: pending,
+      restartRequired,
+      // 生效的保护名单（含两个内置名）+ 用户声明的那部分原文（面板编辑的是后者）
+      reserved: [...new Set(['memory.md', 'session-log.md', ...reservedExtra.map((s) => s.toLowerCase())])],
+      reservedExtra,
+    }
+  }
+
+  /**
+   * 改设置：5 项上限落 `<状态根>/settings.json`，保护名单落 `<状态根>/reserved.json`。
+   *
+   * 校验**先全部过一遍再写盘**：任何一个值非法就整体 `{ ok:false }`，绝不写半份。
+   * 越界不是「夹到边界」（那是环境变量的宽容语义）—— 面板上手输的数字越界是笔误，
+   * 静默改成别的值比报错更让人困惑。
+   */
+  async setSettings(patch) {
+    const p = patch && typeof patch === 'object' && !Array.isArray(patch) ? patch : {}
+    const limitsPatch = p.limits && typeof p.limits === 'object' && !Array.isArray(p.limits) ? p.limits : null
+    const nextLimits = {}
+    if (limitsPatch) {
+      for (const [key, value] of Object.entries(limitsPatch)) {
+        const spec = LIMIT_SPECS[key]
+        if (!spec) return { ok: false, error: `sage-mem: unknown setting: ${key}` }
+        if (typeof value !== 'number' || !Number.isFinite(value)) {
+          return { ok: false, error: `sage-mem: ${key} must be a number, got ${typeof value}` }
+        }
+        const rounded = Math.round(value)
+        if (rounded < spec.lo || rounded > spec.hi) {
+          return { ok: false, error: `sage-mem: ${key} must be an integer in [${spec.lo}, ${spec.hi}], got ${value}` }
+        }
+        nextLimits[key] = rounded
+      }
+    }
+    let nextReserved = null
+    if (p.reserved !== undefined) {
+      if (!Array.isArray(p.reserved)) return { ok: false, error: 'sage-mem: reserved must be an array of file names' }
+      const cleaned = []
+      for (const item of p.reserved) {
+        const s = String(item ?? '').trim()
+        if (!s || !s.endsWith('.md') || s.includes('/') || s.includes('\\') || s.startsWith('..')) {
+          return { ok: false, error: `sage-mem: invalid reserved file name: ${String(item)}` }
+        }
+        if (!cleaned.includes(s)) cleaned.push(s)
+      }
+      nextReserved = cleaned
+    }
+    if (!limitsPatch && nextReserved === null) return { ok: false, error: 'sage-mem: empty patch' }
+
+    await mkdir(STATE_ROOT, { recursive: true })
+    if (limitsPatch) {
+      const current = await readSettingsFile()
+      const merged = { ...(current?.limits ?? {}), ...nextLimits }
+      await writeFileAtomic(SETTINGS_FILE, JSON.stringify({ limits: merged, updatedAt: Date.now() }, null, 2))
+    }
+    if (nextReserved !== null) {
+      await writeFileAtomic(RESERVED_FILE, `${JSON.stringify(nextReserved, null, 2)}\n`)
+    }
+    // 写盘即提示重启：这些值在模块加载时就固化了，不重启它一定还没生效。
+    return { ok: true, settings: await this.getSettings(), restartRequired: true }
+  }
+
+  /**
+   * 原样读保留名文件（`MEMORY.md` / `session-log.md` / 用户声明的保护名）。
+   *
+   * **不解析、不重建**：索引与流水是纯文本，面板拿到什么就显示什么。
+   */
+  async readRaw(name) {
+    if (!isReserved(name)) {
+      return { ok: false, error: `sage-mem: ${String(name)} is not a reserved file; normal memories use the memory form or readFile` }
+    }
+    const safe = rawName(name)
+    if (!safe) return { ok: false, error: `sage-mem: invalid file name: ${String(name)}` }
+    // 读不到就抛（与 readFile 一致）：静默返回空串会让面板显示一份「空的索引」，
+    // 用户一存就把真索引顶掉。
+    const content = await readFile(join(MEMORY_DIR, safe), 'utf8')
+    return { name: safe, content }
+  }
+
+  /**
+   * 原样写保留名文件：**逐字节照写，绝不重建 frontmatter**。
+   *
+   * 这就是 2026-09-25 那次 P0 数据丢失事故（表单重建 frontmatter 把 baseline /
+   * node_type / originSessionId 全抹掉）的解药：索引与流水只许原样进出。
+   */
+  async writeRaw(name, content) {
+    if (!isReserved(name)) {
+      return { ok: false, error: `sage-mem: ${String(name)} is not a reserved file; normal memories use the memory form or writeFile` }
+    }
+    const safe = rawName(name)
+    if (!safe) return { ok: false, error: `sage-mem: invalid file name: ${String(name)}` }
+    if (typeof content !== 'string') {
+      return { ok: false, file: safe, error: `sage-mem: content must be a string, got ${typeof content}` }
+    }
+    const bytes = Buffer.byteLength(content, 'utf8')
+    // ⚠️ 与 writeFile 的 512 KB 上限**不是同一个数**：流水天然更大（见 MAX_RAW_BYTES 的注释）。
+    if (bytes > MAX_RAW_BYTES) {
+      return {
+        ok: false,
+        file: safe,
+        error: `sage-mem: content too large (${bytes} bytes > ${MAX_RAW_BYTES / (1024 * 1024)} MB raw limit)`,
+      }
+    }
+    await writeFileAtomic(join(MEMORY_DIR, safe), content)
+    return { ok: true, file: safe }
+  }
 }
 
 markRemote(MemoryGateway, 'listFiles', 'listFiles')
 markRemote(MemoryGateway, 'readFile', 'readFile')
 markRemote(MemoryGateway, 'writeFile', 'writeFile')
 markRemote(MemoryGateway, 'deleteFile', 'deleteFile')
+markRemote(MemoryGateway, 'archive', 'archive')
+markRemote(MemoryGateway, 'restore', 'restore')
+markRemote(MemoryGateway, 'listArchived', 'listArchived')
+markRemote(MemoryGateway, 'readArchived', 'readArchived')
+markRemote(MemoryGateway, 'writeArchived', 'writeArchived')
+markRemote(MemoryGateway, 'audit', 'audit')
+markRemote(MemoryGateway, 'archiveCandidates', 'archiveCandidates')
+markRemote(MemoryGateway, 'getSettings', 'getSettings')
+markRemote(MemoryGateway, 'setSettings', 'setSettings')
+markRemote(MemoryGateway, 'readRaw', 'readRaw')
+markRemote(MemoryGateway, 'writeRaw', 'writeRaw')
 
 /**
  * 记忆星图（宿主侧）—— 只读扫描记忆目录，把每条记忆解析成一颗「星」。
  * 通过 TypertRemoteService 暴露两个 remote 方法给界面侧：
- *   - starmap.listStars()  全部星（元数据，不含正文）
- *   - starmap.readFile(n)  单条记忆全文（文件名白名单校验）
+ *   - starmap.listStars(includeArchived)  全部星（元数据，不含正文）
+ *   - starmap.readFile(n)                 单条记忆全文（文件名白名单校验）
  */
 export class StarmapGateway extends TypertRemoteService {
   constructor(ctx) { super(ctx, 'starmap') }
 
-  async listStars() {
-    const files = await scanStars(this.ctx)
+  /**
+   * @param {boolean} [includeArchived] — 连归档区一起给（默认 false：与从前一样只看活着的星）
+   */
+  async listStars(includeArchived) {
+    const files = await scanStars(this.ctx, includeArchived === true)
     const stars = files.map(f => {
       const meta = parseFrontmatter(f.content)
       const title = extractTitle(f.content)
-      return {
+      const star = {
         file: f.name,
         kind: meta.type || 'special',
         title: title || meta.name || (meta.description ? meta.description.slice(0, 24) : f.name.replace(/\.md$/, '')),
         desc: meta.description || '',
         bytes: f.bytes,
         mtimeMs: f.mtimeMs,
+        archived: f.archived === true,
+      }
+      // 归档留痕只对归档星有意义；活动星连键都不出现（保持与旧形状逐字段相同）。
+      if (star.archived) {
+        const a = readArchivedMeta(f.content)
+        star.archivedAt = a.archivedAt
+        star.archivedReason = a.archivedReason
       }
+      return star
     })
     return { count: stars.length, stars }
   }