sage-mem 0.8.0 → 0.9.1

package/README.md

@@ -41,6 +41,34 @@ sage-mem 换一条路：**每条记忆就是一个 Markdown 文件**。用编辑
 
 *记忆星图：每颗星是一条记忆 —— 颜色对应类型、大小对应体积、亮度对应新鲜度，底部是四类计数与库总体积。画布上只画关系与分布；悬停或点开某颗星时才会显示那一条的文件名。*
 
+## 界面预览
+
+下面每张图都是**从仓库里的界面代码渲染出来的**（同一份 CSS、同一棵组件树，数据是演示用的假数据，不是真实记忆目录）。
+
+![文件列表：每条记忆一个 Markdown 文件，灰底的是已归档](https://raw.githubusercontent.com/gezi-wen/sage-mem/main/docs/images/files-list.png)
+
+*文件列表 —— 头部带常显「体检 N 个问题」与「待重启生效」，不用点开就知道该不该处理；灰底条目是已归档，随时可以恢复。*
+
+![工具抽屉：体检 / 归档候选 / 保留名编辑，关着时零占位](https://raw.githubusercontent.com/gezi-wen/sage-mem/main/docs/images/tools-drawer.png)
+
+*工具抽屉 —— 关着时只占一个按钮，展开后三项各带状态：体检 4 个问题 / 归档候选 2 条 / 保留名 3 个。*
+
+![体检：硬问题按类报红分节，「指向已归档」只作提示](https://raw.githubusercontent.com/gezi-wen/sage-mem/main/docs/images/audit.png)
+
+*体检 —— 索引悬空、漏索引、断链这类硬问题按类报红；「指向已归档」只作提示、不计入问题，也不提供一键修补按钮（改哪条由你决定）。*
+
+![归档候选：每条写清「为什么建议归档」，确认后才执行](https://raw.githubusercontent.com/gezi-wen/sage-mem/main/docs/images/archive-candidates.png)
+
+*归档候选 —— 每条都写清「为什么建议归档」（闲置天数 vs 该类型阈值），逐条或全选后确认才动文件；归档是把文件移进 `archive/`，不删除。*
+
+![记忆星图：暗星是已归档的记忆，可查看归档时间与理由](https://raw.githubusercontent.com/gezi-wen/sage-mem/main/docs/images/starmap-archive.png)
+
+*记忆星图 —— 暗星是已归档的记忆；点开看归档时间、理由与「恢复到活动记忆」。*
+
+![自动做梦 · 设置：运行 / 设置 / 记录 二级分组，参数两列并写清「当前 → 重启后」](https://raw.githubusercontent.com/gezi-wen/sage-mem/main/docs/images/autodream-settings.png)
+
+*自动做梦 · 设置 —— 运行 / 设置 / 记录 二级分组；五个注入参数两列排开，并写清「当前生效」与「重启后」，不会让人误以为改完立刻生效。*
+
 ## 快速开始
 
 需要 DSH `0.1.2-rc.1` 或更高（见[兼容性](#dsh-兼容性)），Node.js `>= 18`。

package/lib/autodream/config.js

@@ -22,6 +22,19 @@ export const DEFAULT_CONFIG = {
   maxSnapshotKeep: 5,
   /** 回滚按钮的默认范围：files = 只恢复该次运行动过的文件；all = 整目录恢复到该时点。 */
   rollbackScope: 'files',
+  /**
+   * 归档策略：off = 什么都不做；report = 只把候选写进报告（**默认，一个文件都不动**）；
+   * auto = 运行末尾真的把候选移进 `archive/`（只移不删）。
+   * 默认最保守：归档是不可逆的退役动作，先让人看见清单，再决定要不要自动。
+   */
+  autoArchive: 'report',
+  /**
+   * 自动归档阈值（天，按类型差异化）。feedback 没有阈值 —— 它**永不进候选**。
+   * 保守默认：project 90 / reference 180 / user 365。
+   */
+  archiveAfterDaysProject: 90,
+  archiveAfterDaysReference: 180,
+  archiveAfterDaysUser: 365,
 }
 
 /**

package/lib/autodream/engine.js

@@ -37,6 +37,9 @@ import { auditMemoryDir } from '../autodream-audit.js'
 import { autodreamToolSchemas, createToolRunner } from '../autodream-tools.js'
 import { CONFIG_VERSION, DEFAULT_CONFIG, DEFAULT_TOKEN_BUDGET, FAILURE_BACKOFF_MS, FEATURE_DIR, LEGACY_SNAPSHOT_DIR, LEGACY_STATE_FILE, SCHEDULE_INTERVAL_MS, STARTUP_CHECK_DELAY_MS, STATE_DIR } from './config.js'
 import { countSessionsSince, newRunId, stampHuman } from './util.js'
+import { flushAccess, pickArchiveCandidates, readAccessLedger } from '../memory/access.js'
+import { archiveMemory } from '../memory/archive.js'
+import { scanMemoryFiles } from '../memory/scan.js'
 import { dirname, join } from 'node:path'
 
 import * as gateMod from './gate.js'
@@ -147,6 +150,13 @@ export class AutodreamEngine {
 
     await this.load()
     const cfg = this.state.config
+    // 台账先落盘：这趟整理看到的「上次被注入」必须是新的，否则阈值按旧数据算。
+    // flushAccess 自己吞掉失败 —— 台账写不进去不该拦住一趟整理。
+    // 台账先落盘：这趟整理看到的「上次被注入」必须是新的，否则阈值按旧数据算。
+    // flushAccess 自己吞掉失败 —— 台账写不进去不该拦住一趟整理。
+    // ⚠️ 必须传 this.memoryDir：台账的键要跟**这个**记忆目录对表（引擎的目录可以是任意路径，
+    // 拿模块常量会把别的目录的键当成死的清掉）。
+    await flushAccess(this.memoryDir)
     const startedAt = Date.now()
     const runId = newRunId(startedAt)
 
@@ -244,6 +254,11 @@ export class AutodreamEngine {
         sessionCount,
       })
 
+      // 归档策略：在运行末尾、**审计之前**做 —— 归档过的东西要出现在「运行后」的审计里
+      // （指向它的 [[链接]] 会从「断链」变成「指向已归档」的提示）。
+      this.phase = '归档候选'
+      const policy = await this.archivePolicyPass(cfg)
+
       this.phase = '运行后审计'
       const auditAfter = await auditMemoryDir(this.memoryDir)
 
@@ -270,8 +285,15 @@ export class AutodreamEngine {
         auditBefore,
         auditAfter,
         finalText: result.finalText,
+        archiveMode: policy.mode,
+        archiveRequested: policy.requested,
+        archiveCandidates: policy.candidates,
+        archivedByPolicy: policy.archived,
+        archiveDegraded: policy.degraded,
       })
 
+      // 报告里的「改动的文件」要把策略归档也算上 —— 它们确实被移走了，漏掉就是报告在说谎。
+      const policyTouched = policy.archived.filter((a) => a.ok).map((a) => `${a.file} → archive/`)
       const report = await this.writeReport({
         runId,
         startedAt,
@@ -285,7 +307,7 @@ export class AutodreamEngine {
         hoursSince,
         sessionCount,
         snapshot,
-        touched: result.touched,
+        touched: [...result.touched, ...policyTouched],
         auditBefore,
         auditAfter,
         finalText: result.finalText,
@@ -293,6 +315,11 @@ export class AutodreamEngine {
         tokensIn: result.tokensIn,
         tokensOut: result.tokensOut,
         declarationMarkdown: declaration.markdown,
+        archiveMode: policy.mode,
+        archiveRequested: policy.requested,
+        archiveCandidates: policy.candidates,
+        archivedByPolicy: policy.archived,
+        archiveDegraded: policy.degraded,
       })
 
       this.state.lastRunAt = Date.now()
@@ -387,6 +414,56 @@ export class AutodreamEngine {
     }
   }
 
+  // ────────────────────────────── 归档策略 ──────────────────────────────
+
+  /**
+   * 自动归档一趟（**确定性，不调模型**）。
+   *
+   * 三档：`off` 什么也不做；`report` 只把候选交回上层写进报告（一个文件都不动）；
+   * `auto` 在运行末尾真的把候选移进 `archive/`（只移不删）。
+   *
+   * ⚠️ **`apply: false` 是用户可见的绝对承诺**（「只读模式……不可能改到任何文件」）：
+   * `auto` 遇到只读一律**降级为报告**并在报告里明说，绝不绕过那条承诺。
+   *
+   * 归档动作调 `memory/archive.js` 的共享实现 —— 与手动 remote、`archive_memory` 工具
+   * 是同一份代码，三条入口不可能再漂移出两种行为。
+   */
+  async archivePolicyPass(cfg) {
+    const requested = cfg.autoArchive === 'auto' ? 'auto' : cfg.autoArchive === 'off' ? 'off' : 'report'
+    if (requested === 'off') return { mode: 'off', requested, candidates: [], archived: [], degraded: '' }
+    const [ledger, memoryFiles] = await Promise.all([readAccessLedger(), scanMemoryFiles(this.ctx, '')])
+    const candidates = pickArchiveCandidates(memoryFiles, ledger, {
+      thresholds: {
+        project: cfg.archiveAfterDaysProject,
+        reference: cfg.archiveAfterDaysReference,
+        user: cfg.archiveAfterDaysUser,
+      },
+    })
+    if (requested === 'auto' && !cfg.apply) {
+      return {
+        mode: 'report',
+        requested,
+        candidates,
+        archived: [],
+        degraded: 'autoArchive 已设为 auto，但自动做梦处于只读模式，本轮只出报告（一个文件都没动）',
+      }
+    }
+    if (requested !== 'auto' || candidates.length === 0) {
+      return { mode: requested, requested, candidates, archived: [], degraded: '' }
+    }
+    const archived = []
+    for (const c of candidates) {
+      const reason = `自动归档：${c.type} 类，超过 ${c.limit} 天未被注入`
+      const res = await archiveMemory(this.memoryDir, c.file, reason)
+      archived.push({
+        file: c.file,
+        ok: res.ok === true,
+        message: res.ok ? `已归档 ${res.file}（原因：${res.archivedReason}）` : res.error,
+      })
+    }
+    return { mode: 'auto', requested, candidates, archived, degraded: '' }
+  }
+
   // ────────────────────────────── 调度 ──────────────────────────────
 
   /**

package/lib/autodream/report.js

@@ -43,6 +43,16 @@ export async function writeDeclaration(payload) {
     changes: payload.changes,
     warnings: payload.warnings,
     notes: payload.notes ?? [],
+    // 自动归档策略那一段：候选清单是**确定性算出来的**（访问台账 → updated → mtime），
+    // 与模型的判断无关。report 模式下这里就是全部动作（一个文件都不动）。
+    archive: {
+      mode: payload.archiveMode ?? 'off',
+      requested: payload.archiveRequested ?? payload.archiveMode ?? 'off',
+      candidates: payload.archiveCandidates ?? [],
+      archived: payload.archivedByPolicy ?? [],
+      // 降级说明（例如 auto 撞上只读模式）：非空就是「配置想要的没做成，原因在这儿」。
+      degraded: payload.archiveDegraded ?? '',
+    },
     report: payload.report ?? null,
     finalText: payload.finalText ?? '',
     rolledBackAt: 0,
@@ -101,6 +111,25 @@ export function renderDeclaration(m, headingLevel = 1) {
       )
     }
   }
+  if (m.archive && m.archive.mode !== 'off' && (m.archive.candidates.length || m.archive.degraded)) {
+    lines.push(`${H}# 自动归档候选（策略：${m.archive.mode}）`, '')
+    // 降级必须**明说**：用户设了 auto 却什么都没动，原因不写在报告里就等于静默失灵。
+    if (m.archive.degraded) lines.push(`> ⚠ ${m.archive.degraded}`, '')
+    if (m.archive.mode === 'auto') {
+      const done = m.archive.archived.filter((a) => a.ok).length
+      lines.push(`- 已移入 \`archive/\`：${done} / ${m.archive.archived.length} 条（只移不删）`)
+    } else {
+      lines.push('- **本次只出清单，没有移动任何文件**（策略 `report`；想自动跑请把 `autoArchive` 改成 `auto`）')
+    }
+    lines.push('')
+    if (m.archive.candidates.length) {
+      lines.push('| 文件 | 类型 | 闲置 | 阈值 | 说明 |', '|---|---|---|---|---|')
+      for (const c of m.archive.candidates) {
+        lines.push(`| \`${c.file}\` | ${c.type} | ${c.days} 天 | ${c.limit} 天 | ${c.reason} |`)
+      }
+      lines.push('')
+    }
+  }
   if (m.warnings?.length) {
     lines.push(`${H}# 未能落地的改动（这些改动没有发生）`, '')
     for (const w of m.warnings) lines.push(`- ${w}`)

package/lib/autodream/settings.js

@@ -84,6 +84,8 @@ export async function setConfig(patch) {
   if (typeof p.apply === 'boolean') c.apply = p.apply
   if (p.source === 'memory' || p.source === 'memory+sessions') c.source = p.source
   if (p.rollbackScope === 'files' || p.rollbackScope === 'all') c.rollbackScope = p.rollbackScope
+  // 归档策略三档：与上面 trigger / rollbackScope 同一套写法 —— 非法值不写入，保留原值。
+  if (p.autoArchive === 'off' || p.autoArchive === 'report' || p.autoArchive === 'auto') c.autoArchive = p.autoArchive
   if (p.minHours !== undefined) c.minHours = clampNum(Number(p.minHours), 1, 720, DEFAULT_CONFIG.minHours)
   if (p.minSessions !== undefined) c.minSessions = Math.round(clampNum(Number(p.minSessions), 1, 200, DEFAULT_CONFIG.minSessions))
   if (p.maxSteps !== undefined) c.maxSteps = Math.round(clampNum(Number(p.maxSteps), 1, 80, DEFAULT_CONFIG.maxSteps))

package/lib/autodream-audit.js

@@ -10,6 +10,10 @@
  *   5. 双链断链 —— [[目标]] 找不到对应文件或 frontmatter name
  *   6. 未加引号值里的「空格+#」—— 会被 YAML 当注释吞掉，解析不报错但描述残缺
  *
+ * **归档区（`archive/`）不是审计对象**，只贡献「名字池」：正文里指向已归档记忆的
+ * `[[链接]]` 单列成 `archivedLinks`（提示），**不计入 problems** —— 归档是「静默失效
+ * 且可回退」，不是删除。不这么分，归档越多假红灯越多。
+ *
  * **纯只读**：不修任何东西。修哪条、怎么修，由 autodream agent 或人决定。
  *
  * 这一份解析是 sage-mem 宿主侧 parseFrontmatter 的同源精简版，故意不共用：
@@ -24,14 +28,20 @@ import { join } from 'node:path'
 const INDEX_FILE = 'MEMORY.md'
 
 /**
- * 非记忆条目：不是四类记忆、也不该套「type 与前缀一致」这条规则。
+ * 审计**整个跳过**的文件（不读、不当被审对象）。
+ *
+ * session-log.md 是追加型流水，逐会话的账本而不是一条记忆；它没有
+ * `user_/feedback_/project_/reference_` 前缀，扫进来只会白白读一大坨再报假问题。
  *
- * session-log.md 是追加型流水，逐会话的账本而不是一条记忆；
- * 它没有 `user_/feedback_/project_/reference_` 前缀，扫进来只会白白读一大坨
- * 再报一条假问题（实测：报出 `session-log.md type=reference`）。
- * 同理 MEMORY.md 是索引本身，只作为链接来源读，不作为被审对象。
+ * ⚠️ 别和 `lib/memory/config.js` 的 `NON_ENTRY_FILES` 混为一谈 —— **同名不同义**：
+ * 那个管「列不列进设置页 / 星图 / 检索」，这个管「审计读不读」。它们的差集就是
+ * **索引 `MEMORY.md`**：它**要**被读（要当链接来源、要查行尾与链接），只是
+ * **不是一条记忆** —— 见下面 `f !== INDEX_FILE` 那两处。
  */
-const NON_ENTRY_FILES = new Set(['session-log.md'])
+const AUDIT_SKIP_FILES = new Set(['session-log.md'])
+
+/** 归档区目录名（与 autodream-tools.js 的 ARCHIVE_DIR、宿主侧 memory/scan.js 同名）。 */
+const ARCHIVE_DIR = 'archive'
 
 /** YAML 行形态：`key: value`（顶层键，不含缩进的嵌套行）。 */
 const YAML_LEAF_RE = /^[A-Za-z0-9_.-]+:\s*(.*)$/
@@ -77,9 +87,10 @@ export function indexTargets(indexText) {
 }
 
 /**
- * 扫一个目录下的记忆文件（不含子目录 —— 归档区就该扫不到）。
+ * 扫一个目录下的记忆文件（不含子目录 —— 归档区就该扫不到），
+ * 外加归档区的**名字池**（只有名字，不做检查）。
  * @param {string} dir
- * @returns {Promise<{files: string[], indexText: string}>}
+ * @returns {Promise<{files: string[], all: string[], skipped: number, indexText: string, archiveKeys: Set<string>, archiveCount: number}>}
  */
 async function readDirSnapshot(dir) {
   let entries
@@ -87,14 +98,35 @@ async function readDirSnapshot(dir) {
   const all = entries
     .filter((e) => e.isFile() && e.name.toLowerCase().endsWith('.md'))
     .map((e) => e.name)
-  const files = all.filter((f) => !NON_ENTRY_FILES.has(f.toLowerCase()))
+  const files = all.filter((f) => !AUDIT_SKIP_FILES.has(f.toLowerCase()))
   let indexText = ''
   try {
     indexText = await readFile(join(dir, INDEX_FILE), 'utf8')
   } catch (err) {
     if (err?.code !== 'ENOENT') throw err
   }
-  return { files, all, skipped: all.length - files.length, indexText }
+  // 归档区：文件名、去掉 .md 的名字、以及 frontmatter 里的 `name`。
+  // 内容读不动只少一个名字，绝不让整场审计失败 —— 归档区本来就不是被审对象。
+  const archiveKeys = new Set()
+  let archiveCount = 0
+  try {
+    const archived = await readdir(join(dir, ARCHIVE_DIR), { withFileTypes: true })
+    for (const e of archived) {
+      if (!e.isFile() || !e.name.toLowerCase().endsWith('.md')) continue
+      archiveCount++
+      archiveKeys.add(e.name)
+      archiveKeys.add(e.name.replace(/\.md$/i, ''))
+      try {
+        const meta = parseFrontmatterLite(await readFile(join(dir, ARCHIVE_DIR, e.name), 'utf8'))
+        if (meta.name) archiveKeys.add(meta.name.trim())
+      } catch {
+        /* 读不动：名字池少一条而已 */
+      }
+    }
+  } catch (err) {
+    if (err?.code !== 'ENOENT') throw err
+  }
+  return { files, all, skipped: all.length - files.length, indexText, archiveKeys, archiveCount }
 }
 
 /**
@@ -103,7 +135,7 @@ async function readDirSnapshot(dir) {
  * @returns {Promise<object>} 结构化审计结果（problems 是六项之和）
  */
 export async function auditMemoryDir(dir) {
-  const { files, all, skipped, indexText } = await readDirSnapshot(dir)
+  const { files, all, skipped, indexText, archiveKeys, archiveCount } = await readDirSnapshot(dir)
   const entries = files.filter((f) => f !== INDEX_FILE)
 
   const targets = indexTargets(indexText)
@@ -119,6 +151,7 @@ export async function auditMemoryDir(dir) {
   const crlf = []
   const hashHazards = []
   const brokenLinks = []
+  const archivedLinks = []
   const noFrontmatter = []
   const linkKeys = new Set()
 
@@ -145,13 +178,28 @@ export async function auditMemoryDir(dir) {
   }
   for (const f of readable) linkKeys.add(f)
   for (const f of readable) linkKeys.add(f.replace(/\.md$/, ''))
+  /**
+   * ⚠️ 链接目标池还必须含**非条目文件**（`session-log.md` / `MEMORY.md`）。
+   *
+   * 它们不在 `readable` 里（不参与检索），但 `[[session-log]]` 指向的是**真实存在的文件** ——
+   * 只因它不参与检索就报成断链，是假阳性。这与上面 `dangling` 用 `allSet` 而非 `files`
+   * 判定悬空是同一个理由，别只在一处想到。（2026-10-09 实测：健康记忆库被报 1 条假断链）
+   */
+  for (const f of all) {
+    linkKeys.add(f)
+    linkKeys.add(f.replace(/\.md$/i, ''))
+  }
 
   for (const f of readable) {
     const raw = contents.get(f)
     if (raw.includes('\r')) crlf.push(f)
     const fmMatch = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/)
     if (!fmMatch) {
-      noFrontmatter.push(f)
+      /**
+       * 索引 `MEMORY.md` 是**纯清单、不是一条记忆**（见 `lib/memory/config.js` 的
+       * `NON_ENTRY_FILES` 说明），不要求 frontmatter。报它等于给每一个健康的记忆库挂一盏常驻红灯。
+       */
+      if (f !== INDEX_FILE) noFrontmatter.push(f)
     } else {
       const meta = parseFrontmatterLite(raw)
       const prefix = f.split('_')[0]
@@ -166,9 +214,22 @@ export async function auditMemoryDir(dir) {
         }
       }
     }
-    for (const m of raw.matchAll(/\[\[([^\]]+)\]\]/g)) {
+    /**
+     * ⚠️ 只在**非代码**文本里找双链。
+     *
+     * `` `[[双链]]` `` 写在行内代码或围栏代码块里，是在**讲链接语法本身**，不是一条链接。
+     * 直接在原文上 `matchAll` 会把它报成断链（2026-10-09 实测的假阳性）。
+     */
+    const prose = raw.replace(/```[\s\S]*?```/g, '').replace(/`+[^`]*`+/g, '')
+    for (const m of prose.matchAll(/\[\[([^\]]+)\]\]/g)) {
       const target = m[1].trim()
-      if (!linkKeys.has(target)) brokenLinks.push({ file: f, target })
+      if (linkKeys.has(target)) continue
+      // 指向归档区的链接：单列提示、不计问题 —— 归档不是删除，目标还在库里躺着。
+      if (archiveKeys.has(target)) {
+        archivedLinks.push({ file: f, target })
+        continue
+      }
+      brokenLinks.push({ file: f, target })
     }
   }
 
@@ -186,12 +247,15 @@ export async function auditMemoryDir(dir) {
     dir,
     fileCount: entries.length,
     skipped,
+    archivedCount: archiveCount,
     indexEntries: targets.length,
     dangling: dangling.map((file) => ({ file })),
     unlisted: unlisted.map((file) => ({ file })),
     typeMismatch,
     crlf: crlf.map((file) => ({ file })),
     brokenLinks,
+    // 指向归档的链接是提示，**不进 problems**（见文件头那段）。
+    archivedLinks,
     hashHazards,
     noFrontmatter: noFrontmatter.map((file) => ({ file })),
     unreadable: unreadable.map((file) => ({ file })),
@@ -220,6 +284,8 @@ export function formatAudit(report, limit = 12) {
   section('type 与前缀不一致', report.typeMismatch, (r) => `${r.file} type=${r.type} 前缀=${r.prefix}`)
   section('CRLF', report.crlf, (r) => r.file)
   section('双链断链', report.brokenLinks, (r) => `${r.file} -> [[${r.target}]]`)
+  // 指向归档单列且写明「不计问题」：否则模型会去「修」一条本来正确的链接。
+  section('指向已归档（提示，不计入问题）', report.archivedLinks ?? [], (r) => `${r.file} -> [[${r.target}]]`)
   section('未加引号的「空格+#」', report.hashHazards, (r) => `${r.file} :: ${r.line}`)
   section('无 frontmatter', report.noFrontmatter, (r) => r.file)
   // 读不动的单列，且排最后：它不是「这条记忆写错了」，是「我没读到它」——

package/lib/autodream-tools.js

@@ -24,10 +24,11 @@
  * `write_memory` 的 frontmatter 规范都沿用 sage-mem 的既有约定，不另造一套。
  */
 
-import { readFile, readdir, writeFile, rename, stat, mkdir } from 'node:fs/promises'
+import { readFile, readdir, writeFile, stat } from 'node:fs/promises'
 import { join, basename } from 'node:path'
 import { createHash } from 'node:crypto'
 import { auditMemoryDir, formatAudit, parseFrontmatterLite } from './autodream-audit.js'
+import { archiveMemory } from './memory/archive.js'
 
 /** 单次 read_memory 返回的正文上限（字符）。超过就截断并明确告诉模型。 */
 const READ_LIMIT = 20000
@@ -35,8 +36,6 @@ const READ_LIMIT = 20000
 const LIST_DESC_CHARS = 70
 /** search_sessions 单次返回上限（字符）。 */
 const SEARCH_LIMIT = 8000
-/** 归档区目录名（相对 memory 根）。 */
-const ARCHIVE_DIR = 'archive'
 /** 索引文件名：它在列表里要单独标注，免得模型当成一条普通记忆去改。 */
 const INDEX_FILE = 'memory.md'
 /**
@@ -467,20 +466,20 @@ export function createToolRunner(opts) {
             const validated = safeMemoryPath(memoryDir, a.file)
             if (!validated) return `错误：文件名不合法：${String(a.file)}`
             const full = join(memoryDir, await resolveRealName(memoryDir, basename(validated)))
+            // reason 必填这条语义由**工具自己**守（模型必须为不可逆动作说清为什么）；
+            // 落盘动作则交给 memory/archive.js —— 与手动 remote、自动策略共用同一份。
             const reason = typeof a.reason === 'string' ? a.reason.trim() : ''
             if (reason.length < MIN_REASON_CHARS) {
               warnings.push(`拒绝对 ${basename(full)} 的归档：模型没给 reason（或太短）`)
               return '错误：archive_memory 必须给 reason —— 一句话说明为什么这条该退役。请带上 reason 重发。'
             }
-            const exists = await stat(full).catch(() => null)
-            if (!exists) return `错误：没有这个文件：${basename(full)}`
-            const archiveDir = join(memoryDir, ARCHIVE_DIR)
-            await mkdir(archiveDir, { recursive: true })
-            const target = join(archiveDir, basename(full))
-            const clash = await stat(target).catch(() => null)
-            if (clash) return `错误：archive/ 里已有同名文件（${basename(full)}），请先人工处理，避免覆盖。`
             const before = await fileFingerprint(full)
-            await rename(full, target)
+            const res = await archiveMemory(memoryDir, basename(full), reason)
+            if (!res.ok) {
+              if (res.code === 'not-found') return `错误：没有这个文件：${basename(full)}`
+              if (res.code === 'exists') return `错误：archive/ 里已有同名文件（${basename(full)}），请先人工处理，避免覆盖。`
+              return `错误：${String(res.error).replace(/^sage-mem: /, '')}`
+            }
             changeRecord('archive', basename(full), reason, before, { exist: false, bytes: 0, sha256: null })
             touched.push(`${basename(full)} → archive/`)
             listCache = null