sage-mem 0.6.3 → 0.7.0

package/lib/index.js

@@ -6,7 +6,7 @@
  *   1. 按问题检索注入：system-prompt/assemble 时扫 memory 目录，按双字匹配
  *      选相关文件，读全文注入 system prompt，让 agent 第一轮就「想起」
  *   2. TypertRemoteService：给设置页「记忆管理」提供文件列表/读/写/删
- *   3. dream（做梦）：可选的记忆整理，见 lib/dream.js
+ *   3. autodream（自动做梦）：可选的记忆整理，见 lib/autodream.js
  *
  * 写入靠 AGENTS.md 的「记忆使用」规则引导 agent 自己判断 + 用文件工具写
  * memory 目录——透明、可检查、防膨胀。无 worker、无 SQLite、无端口。
@@ -17,54 +17,94 @@
 import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol'
 import { homedir } from 'node:os'
 import { readFile, readdir, writeFile, rename, unlink, stat } from 'node:fs/promises'
-import { join, basename } from 'node:path'
-import { DreamEngine } from './dream.js'
+import { readFileSync } from 'node:fs'
+import { join, basename, dirname } from 'node:path'
+import { AutodreamEngine } from './autodream.js'
 
 const MEMORY_DIR = process.env.SAGE_MEM_DIR || join(homedir(), '.sage-mem', 'memory')
 /**
- * DSH 会话记录根目录。dream 的门控靠它数「上次整理之后有几个会话更新」，
+ * DSH 会话记录根目录。autodream 的门控靠它数「上次整理之后有几个会话更新」，
  * `memory+sessions` 输入源下也会在里面做定向搜索。取不到就是空串，
  * 门控会退化成「会话数 0 → 不触发」，而不是报错。
  */
 const SESSIONS_ROOT = process.env.DSH_HOME ? join(process.env.DSH_HOME, 'sessions') : ''
-const MAX_RESULTS = 5
-const MAX_CHARS_PER_FILE = 1500
-const MAX_BASELINE = 5
+
+/** 读一个整数型环境变量并在范围内收敛；取不到或非法就用默认值。 */
+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（2026-10-01）：**记忆条数 ÷ 注入名额 ≈ 命中率上限**，名额 5 时那个上限低到
+ * 的根因就在这个比值上。名额翻倍是提升召回最直接的一手，代价是每轮多约 7.5K
+ * 字符的上下文。**这个数字该由实测决定**，所以留了 SAGE_MEM_MAX_RESULTS 覆写口
+ * （比较两档的命中率与 token 账单，别拍脑袋）。
+ */
+const MAX_RESULTS = envInt('SAGE_MEM_MAX_RESULTS', 10, 1, 30)
+
+/** 单条记忆注入的字符上限。 */
+const MAX_CHARS_PER_FILE = envInt('SAGE_MEM_MAX_CHARS', 1500, 200, 20000)
+
+/**
+ * baseline 名额。
+ *
+ * baseline 条目通常不多，卡在 5 只会让靠后的条目永不出现——
+ * 而 baseline 恰恰是短问题、恢复会话时唯一的兜底。现在放到 8，
+ * 排序见下面「按显式优先级排，不按文件名」那段。
+ */
+const MAX_BASELINE = envInt('SAGE_MEM_MAX_BASELINE', 8, 1, 50)
 
 /**
- * 保留名：设置页的写/删方法一律不得触碰。
+ * 结构性保留名：设置页的写/删方法一律不得触碰。
  *
- * 列进来的两类文件：
- *   1. MEMORY.md / session-log.md —— 不是记忆条目：不进检索、不进星图、不出现在
- *      设置页列表里，它们是索引与追加型流水（session-log.md 已 130+ KB）。
- *      「+ 添加记忆」表单里手打这两个名字就能整份覆盖，而这个表单是照
- *      buildFrontmatter() 重建 frontmatter 的，原有内容一个字都留不下。
- *   2. project_heartscape.md / project_self-cognition.md —— 人格连续性的手写载体
- *      （AGENTS.md 指定的落盘目标），单副本、纯人工维护；表单写还会把
- *      frontmatter 里的 originSessionId / birthday 等字段一并抹掉。
+ * 只列**结构决定必须保护**的两个：
+ *   1. `MEMORY.md` —— 索引。它被整份覆盖就等于索引没了（「+ 添加记忆」表单是照
+ *      buildFrontmatter() 重建 frontmatter 的，原有内容一个字都留不下）。
+ *   2. `session-log.md` —— 追加型流水，体量最大，同样经不起一份重建。
  *
- * 判定依据是「丢了能不能从别处重建」：memory 目录**不在任何版本控制下**
- * （该目录里没有 .git，`git rev-parse` 直接报 not a git repository），
- * deleteFile 是 unlink、没有回收站，所以宁严勿松。
- * 这几个文件要改，用文件工具直接编辑。
+ * ⚠️ **除了这两个，别把任何具体记忆的文件名写死在这里。**
+ * 「哪几条记忆特别要紧」是**使用者的私事**——把它编进随包发布的代码，等于把作者的
+ * 记忆主题发给每一个装这个插件的人。
+ * 用户自己的保护名单放在 `<状态根>/reserved.json`（JSON 字符串数组），见下。
  *
  * ⚠️ 全部小写存放，比较一律走 nameKey()（NTFS 不区分大小写，集合里放 'MEMORY.md'
  * 而拿 'memory.md' 去 has() 是查不到的 —— 曾经就是这个漏洞：表单里填 memory.md
- * 就能整份覆盖 19 KB 的索引，deleteFile 还能不可逆删掉它）。
+ * 就能整份覆盖索引，deleteFile 还能不可逆删掉它）。
  */
-const RESERVED_FILES = new Set([
-  'memory.md',
-  'session-log.md',
-  'project_heartscape.md',
-  'project_self-cognition.md',
-])
+const STATE_ROOT = process.env.SAGE_MEM_STATE_DIR || join(dirname(MEMORY_DIR), '.sage-mem')
+
+/**
+ * 读使用者自己声明的额外保护名单：`<状态根>/reserved.json`，形如 `["a.md","b.md"]`。
+ *
+ * 读不到、JSON 坏、不是数组 —— 一律当空数组返回。**一份可选的保护名单，
+ * 绝不该有能力让插件加载失败。**
+ */
+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 []
+  }
+}
+
+const RESERVED_FILES = new Set(['memory.md', 'session-log.md', ...readExtraReserved()])
 
 /**
  * 非记忆条目：不参与检索 / 不进星图 / 不出现在设置页列表里，读写也一律不通。
  *
  * 是 RESERVED_FILES 的子集，区别在「列不列出来」：MEMORY.md 是索引、
- * session-log.md 是追加型流水（已 390+ KB），两者都不是一条记忆；
- * 而 project_heartscape.md / project_self-cognition.md 是正常记忆条目
+ * session-log.md 是追加型流水，两者都不是一条记忆；
+ * 而使用者手写维护的重要记忆是正常记忆条目（它们该被检索到）。
  * （要出现在列表与星图里、要能读），只是不许从表单写/删。
  */
 const NON_ENTRY_FILES = new Set([
@@ -74,7 +114,7 @@ const NON_ENTRY_FILES = new Set([
 
 /**
  * 单文件体积上限（字节）。定 512 KB 的理由：
- *   - 当前 memory 目录最大的一条正文 19 KB（project_guikit.md），索引与流水都排除在外，
+ *   - 单条正文通常在几十 KB 以内，索引与流水都排除在外，
  *     512 KB 是它的 26 倍，任何正常记忆都够用；
  *   - 记忆是要塞进 system prompt 的，一条 512 KB 的记忆本身就等于把上下文撑爆——
  *     到这个量级基本可以判定是写错了目标（比如把日志、代码贴进来）。
@@ -139,7 +179,9 @@ async function scanMemoryFiles(ctx, sessionId) {
           file: name,
           content,
           description: meta.description || '',
+          aliases: meta.aliases || [],
           baseline: parseBaseline(content),
+          baselinePriority: meta.baselinePriority || 0,
         }
       } catch (err) {
         // 只有 ENOENT 是正常状态（扫到读之间被删）。其余——权限错、编码坏、盘掉线——
@@ -159,16 +201,17 @@ async function scanMemoryFiles(ctx, sessionId) {
  * 相关性打分只用 frontmatter 的 description + 文件名，不扫全文。
  *
  * 旧版拿 query 的双字去全文里找，得分是「覆盖率」，分母是 query，不惩罚
- * 文件长度 —— 越长的记忆越容易蒙中。实测 8 个典型问题：project_heartscape
- * (5.9KB) 与 project_self-cognition (6.8KB) 命中 7 个，连「今天天气不错」都
- * 注入 2300 token；而「论文写得怎么样了」该命中的 project_position-paper
- * 反被挤掉。description 是「一句话说清这条是什么」的精准摘要，用它当检索
+ * 文件长度 —— 越长的记忆越容易蒙中。实测：长记忆在全文匹配下对任何问题都能
+ * 蒙中足量双字组，连寒暄问句都能注入上千 token；而真正该命中的那条反被
+ * 挤掉。description 是「一句话说清这条是什么」的精准摘要，用它当检索
  * 信号，噪音大幅下降。
  */
 function selectRelevant(query, files) {
   return files
     .map(f => {
-      const hay = f.description + ' ' + f.file.replace(/\.md$/, '').replace(/[_-]/g, ' ')
+      // 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)
@@ -176,6 +219,19 @@ function selectRelevant(query, files) {
     .slice(0, MAX_RESULTS)
 }
 
+/**
+ * 选 baseline 条目：按显式 `baselinePriority` 排，不按文件名。
+ *
+ * 文件名排序等于让 `feedback_*` 无条件压过 `user_*`，与「哪条更该出现在每场
+ * 会话开头」毫无关系。没写这个字段的老条目一律算 0，行为与从前一致。
+ */
+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)
+}
+
 /**
  * 解析 frontmatter 的 `tags`（自定义标签，用于列表页筛选）。
  *
@@ -208,9 +264,9 @@ function parseFrontmatter(content) {
   // 换行必须容忍 CRLF：任何用 Windows 编辑器碰过一次的文件都会被换成 \r\n，
   // 而旧版这里写的是 /^---\n/ —— 匹配失败 → description/type 全空 →
   // 「baseline 走 parseBaseline 那条带 \r?\n 的正则照旧命中，但这条记忆永远检索不到」，
-  // 症状极具欺骗性。:123 的 parseBaseline 与 :277 的 extractTitle 早已是 \r?\n。
+  // 症状极具欺骗性。下文定义的 parseBaseline 与 extractTitle 早已是 \r?\n。
   const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---/)
-  if (!m) return { name: '', description: '', type: '', tags: [] }
+  if (!m) return { name: '', description: '', type: '', tags: [], aliases: [], baselinePriority: 0 }
   const body = m[1]
   const grab = (key) => {
     // [ \t] / [ \t\r] 而不是 \s：\s 会连 CRLF 的 \r 一起吃进捕获组，值尾留一个 \r
@@ -224,7 +280,52 @@ function parseFrontmatter(content) {
     const nested = body.match(/^metadata:\s*\r?\n(?:\s+[^\r\n]+\r?\n)*?\s+type:\s*(\S+)/m)
     if (nested) type = nested[1]
   }
-  return { name: grab('name'), description: grab('description'), type, tags: parseTags(body) }
+  return {
+    name: grab('name'),
+    description: grab('description'),
+    type,
+    tags: parseTags(body),
+    aliases: parseAliases(body),
+    baselinePriority: parseBaselinePriority(body),
+  }
+}
+
+/**
+ * 解析 frontmatter 的 `aliases`（别称 / 同义词 / 我可能用的另一种叫法）。
+ *
+ * 为什么要有它：检索是**词面重合**的，不是语义的——问「我有什么待办」而文件里
+ * 写的是「代办清单」，差一个字就完全不命中。`description` 回答「我会怎么问它」，
+ * `aliases` 补上「我还可能怎么问」。写法与 tags 完全一致（flow / block / 逗号串三种都收），
+ * 免得手写时「时灵时不灵」。
+ */
+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，
+ * 于是没写这个字段的老条目行为不变。
+ */
+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` 标记：会话第一回合无条件注入。 */
@@ -286,7 +387,7 @@ function isMemoryEntry(name) {
  *
  * MemoryGateway.readFile / StarmapGateway.readFile 都走这里，不再各写一套
  * —— 旧版 starmap 那套内联校验只排除了 'MEMORY.md'（大小写敏感）且**完全不排除
- * session-log.md**，于是 `starmap.readFile('session-log.md')` 能把 390+ KB 的流水
+ * session-log.md**，于是 `starmap.readFile('session-log.md')` 能把整份流水
  * 整个拉进浏览器。
  *
  * 不复用 nameKey 的原因：这里要保留磁盘上的原始大小写（返回值直接 join 进路径）。
@@ -325,22 +426,26 @@ export class MemoryGateway extends TypertRemoteService {
     // 一并挂载星图 remote（同一记忆目录，纯只读）—— starmap.* 服务
     new StarmapGateway(ctx)
 
-    // dream（夜间记忆整理）：引擎 + remote 面 + 自动触发的定时器。
+    // autodream（夜间记忆整理）：引擎 + remote 面 + 自动触发的定时器。
     //
-    // 整个包在 try 里：dream 起不来（比如 timer 服务缺失、状态目录没权限）
+    // 整个包在 try 里：autodream 起不来（比如 timer 服务缺失、状态目录没权限）
     // 不该把 sage-mem 最核心的那件事——「记忆按问题注入」——一起拖死。
     // 这是本插件唯一一处「降级而不是失败」的设计，理由就在这里。
     try {
-      const engine = new DreamEngine(ctx, { memoryDir: MEMORY_DIR, sessionsRoot: SESSIONS_ROOT })
-      new DreamGateway(ctx, engine)
+      const engine = new AutodreamEngine(ctx, {
+        memoryDir: MEMORY_DIR,
+        sessionsRoot: SESSIONS_ROOT,
+        reservedFiles: [...RESERVED_FILES],
+      })
+      new AutodreamGateway(ctx, engine)
       engine.start()
       // 卸载时把定时器与锁收干净。effect 拿不到就交给 unref 兜底（不阻止进程退出）。
       if (typeof ctx.effect === 'function') ctx.effect(() => () => engine.dispose())
     } catch (err) {
-      warnLog(ctx, `dream 初始化失败（记忆本体不受影响）：${err?.message ?? err}`)
+      warnLog(ctx, `autodream 初始化失败（记忆本体不受影响）：${err?.message ?? err}`)
       // 异常路径额外打一行到 stderr：warnLog 走 ctx.logger，某些启动阶段它还没接上，
-      // 而「dream 静默不工作」正是最难查的那种故障（2026-09-27 为此绕了一大圈）。
-      console.error('[sage-mem] dream init failed:', err && err.stack ? err.stack : err)
+      // 而「autodream 静默不工作」正是最难查的那种故障（2026-09-27 为此绕了一大圈）。
+      console.error('[sage-mem] autodream init failed:', err && err.stack ? err.stack : err)
     }
 
     // 同一轮对话里问题不变、注入内容也不变，但 DSH 每一步都会往 session 追加
@@ -398,7 +503,7 @@ export class MemoryGateway extends TypertRemoteService {
         // baseline：每个会话注入一次，**不看消息条数**。
         //
         // 旧写法 `if (userMessages.length === 0)` 依赖一个真实存在的时序：assemble
-        // 触发时当前这条用户消息还没写进 session。已在 DSH 检出里核实为真 ——
+        // 触发时当前这条用户消息还没写进 session。已在 DSH 0.1.7-rc.1 上核实为真 ——
         //   dsh-agent-loop/lib/index.js:906  const claimed = this.inbox.claim(...)   // 只从 pending 队列取走
         //   dsh-agent-loop/lib/index.js:907  await this.loopCtx.systemPrompt.assemble(...)  // ← 本监听器在这里跑
         //   dsh-agent-loop/lib/index.js:1046 this.session.append("user/message", ...)  // 落 session 在 preStep 之后
@@ -410,10 +515,7 @@ export class MemoryGateway extends TypertRemoteService {
         let baselineTaken = 0
         const baselineKey = session.id ? session.id : session
         if (!baselineInjected.has(baselineKey)) {
-          files
-            .filter(f => f.baseline)
-            .sort((a, b) => a.file.localeCompare(b.file))
-            .slice(0, MAX_BASELINE)
+          selectBaseline(files)
             .forEach(f => {
               const before = picked.length
               take(f)
@@ -610,14 +712,14 @@ markRemote(StarmapGateway, 'listStars', 'listStars')
 markRemote(StarmapGateway, 'readFile', 'readFile')
 
 /**
- * dream 的 remote 面：设置页「做梦」标签页唯一的数据通道。
+ * autodream 的 remote 面：设置页「自动做梦」标签页唯一的数据通道。
  *
- * 这一层刻意很薄——全部判断（门控、模式、白名单）都在 DreamEngine 里，
- * 这里只负责把 ctx 里的引擎接到 typert 的调用表上。想看行为就读 dream.js。
+ * 这一层刻意很薄——全部判断（门控、模式、白名单）都在 AutodreamEngine 里，
+ * 这里只负责把 ctx 里的引擎接到 typert 的调用表上。想看行为就读 autodream.js。
  */
-export class DreamGateway extends TypertRemoteService {
+export class AutodreamGateway extends TypertRemoteService {
   constructor(ctx, engine) {
-    super(ctx, 'dream')
+    super(ctx, 'autodream')
     this.engine = engine
   }
 
@@ -641,14 +743,15 @@ export class DreamGateway extends TypertRemoteService {
    *
    * force 默认为 true —— 人点了按钮，就不该再被「还没到 24 小时」挡回来。
    *
-   * **故意不 await**：一趟 dream 可能跑几分钟（多轮模型调用 + 工具），
+   * **故意不 await**：一趟 autodream 可能跑几分钟（多轮模型调用 + 工具），
    * remote 调用挂在那儿等会直接撞上前端超时，界面上表现为「点了没反应」。
    * 所以这里只负责点火，进度与结果都从 status() 轮询 —— run() 自己会把
    * lastResult 落盘，界面刷新几次就能看到。
    */
-  async runNow(force) {
-    if (this.engine.running) return { ok: false, error: '已有一趟 dream 在跑' }
-    this.engine.run({ reason: '设置页手动触发', force: force !== false }).catch(() => {})
+  async runNow(opts) {
+    if (this.engine.running) return { ok: false, error: '已有一趟 autodream 在跑' }
+    const reason = typeof opts?.reason === 'string' && opts.reason.trim() ? opts.reason.trim().slice(0, 120) : '设置页手动触发'
+    this.engine.run({ reason, force: true }).catch(() => {})
     return { ok: true }
   }
 
@@ -666,14 +769,63 @@ export class DreamGateway extends TypertRemoteService {
   async listSnapshots() {
     return this.engine.listSnapshots()
   }
+
+  /** 运行记录列表（面板的「整理声明」区）。 */
+  async listRuns(opts) {
+    return this.engine.listRuns(opts?.limit)
+  }
+
+  /** 读某次运行的完整整理声明（人读 markdown + 机读 manifest）。 */
+  async readDeclaration(opts) {
+    return this.engine.readDeclaration(opts?.runId)
+  }
+
+  /**
+   * 回滚到某个回滚点。
+   *
+   * 与 runNow 相反，这里**必须 await**：回滚是几十毫秒级的文件操作，
+   * 而「点完按钮不知道到底滚没滚」正是回滚这种动作最不能接受的体验。
+   */
+  async rollback(opts) {
+    return this.engine.rollback({ snapshotId: opts?.snapshotId, scope: opts?.scope })
+  }
+
+  /** 可选的整理模型路线（设置面板的模型下拉）。 */
+  async listModels() {
+    return this.engine.listModels()
+  }
 }
 
-markRemote(DreamGateway, 'getConfig', 'getConfig')
-markRemote(DreamGateway, 'setConfig', 'setConfig')
-markRemote(DreamGateway, 'status', 'status')
-markRemote(DreamGateway, 'runNow', 'runNow')
-markRemote(DreamGateway, 'listReports', 'listReports')
-markRemote(DreamGateway, 'readReport', 'readReport')
-markRemote(DreamGateway, 'listSnapshots', 'listSnapshots')
+markRemote(AutodreamGateway, 'getConfig', 'getConfig')
+markRemote(AutodreamGateway, 'setConfig', 'setConfig')
+markRemote(AutodreamGateway, 'status', 'status')
+markRemote(AutodreamGateway, 'runNow', 'runNow')
+markRemote(AutodreamGateway, 'listReports', 'listReports')
+markRemote(AutodreamGateway, 'readReport', 'readReport')
+markRemote(AutodreamGateway, 'listSnapshots', 'listSnapshots')
+markRemote(AutodreamGateway, 'listRuns', 'listRuns')
+markRemote(AutodreamGateway, 'readDeclaration', 'readDeclaration')
+markRemote(AutodreamGateway, 'rollback', 'rollback')
+markRemote(AutodreamGateway, 'listModels', 'listModels')
 
 export default MemoryGateway
+
+/**
+ * **仅供测试**的只读出口。
+ *
+ * 检索这条链（frontmatter 解析 → 双字打分 → 名额裁剪）没有任何对外可见的调用面：
+ * 想验证「写了 aliases 之后换个说法能不能命中」，否则只能起一个真的 DSH 端到端跑一遍。
+ * 把这些纯函数露出来是为了能写断言，**不是给外部用的 API**，别依赖。
+ */
+export const __testables = {
+  bigrams,
+  score,
+  parseFrontmatter,
+  parseAliases,
+  parseBaselinePriority,
+  parseBaseline,
+  parseTags,
+  selectRelevant,
+  selectBaseline,
+  limits: { MAX_RESULTS, MAX_CHARS_PER_FILE, MAX_BASELINE },
+}