sage-mem 0.7.2 → 0.9.0

package/lib/memory/retrieval.js

@@ -0,0 +1,86 @@
+/**
+ * sage-mem 记忆层 —— 检索：双字打分、名额裁剪、baseline 排序、新鲜度换算。
+ */
+
+import { MAX_BASELINE, MAX_RESULTS } from './config.js'
+
+/** 提取消息文本，兼容 content 为字符串或 text-block 数组两种形态。 */
+export function extractText(content) {
+  if (typeof content === 'string') return content.trim()
+  if (!Array.isArray(content)) return ''
+  return content
+    .filter(b => b && b.type === 'text' && typeof b.text === 'string')
+    .map(b => b.text)
+    .join('\n')
+    .trim()
+}
+
+/** 提取双字（2-gram）集合，中英文数字通用。 */
+export function bigrams(s) {
+  const clean = String(s).toLowerCase().replace(/[^\p{L}\p{N}]+/gu, '')
+  const set = new Set()
+  for (let i = 0; i < clean.length - 1; i++) set.add(clean.slice(i, i + 2))
+  return set
+}
+
+/** query 的双字在 text 中的覆盖率（0~1），作为相关性得分。 */
+export function score(query, text) {
+  const q = bigrams(query)
+  if (q.size === 0) return 0
+  const t = bigrams(text)
+  let hit = 0
+  for (const g of q) if (t.has(g)) hit++
+  return hit / q.size
+}
+
+/**
+ * 相关性打分只用 frontmatter 的 description + 文件名，不扫全文。
+ *
+ * 旧版拿 query 的双字去全文里找，得分是「覆盖率」，分母是 query，不惩罚
+ * 文件长度 —— 越长的记忆越容易蒙中。实测：长记忆在全文匹配下对任何问题都能
+ * 蒙中足量双字组，连寒暄问句都能注入上千 token；而真正该命中的那条反被
+ * 挤掉。description 是「一句话说清这条是什么」的精准摘要，用它当检索
+ * 信号，噪音大幅下降。
+ */
+export function selectRelevant(query, files) {
+  return files
+    .map(f => {
+      // 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)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, MAX_RESULTS)
+}
+
+/**
+ * 选 baseline 条目：按显式 `baselinePriority` 排，不按文件名。
+ *
+ * 文件名排序等于让 `feedback_*` 无条件压过 `user_*`，与「哪条更该出现在每场
+ * 会话开头」毫无关系。没写这个字段的老条目一律算 0，行为与从前一致。
+ */
+export 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)
+}
+
+/**
+ * 一条记忆「多久以前写下的」（整数天；null = 无从判断）。
+ *
+ * **优先 frontmatter 的 `updated`，缺失才回落文件 mtime —— 顺序不能反。**
+ * 文件系统时间会被复制、checkout、备份还原整批改掉，它表示的是「这个文件什么时候
+ * 被动过」，不是「这条记忆什么时候写的」。手写的时间戳才是权威。
+ *
+ * 未来日期（时钟偏差 / 手写错）一律当 0：宁可标「今天」也不要标负数。
+ */
+export function ageDays(f, nowMs) {
+  const fromMeta = Date.parse(f?.updated || '')
+  const base = Number.isFinite(fromMeta) ? fromMeta : (Number.isFinite(f?.mtimeMs) ? f.mtimeMs : NaN)
+  if (!Number.isFinite(base)) return null
+  const days = Math.floor((nowMs - base) / 86400000)
+  return days > 0 ? days : 0
+}

package/lib/memory/scan.js

@@ -0,0 +1,204 @@
+/**
+ * sage-mem 记忆层 —— 目录扫描 + 归档区的读写形状。
+ *
+ * 归档区（`memory/archive/`）**不参与检索**：`scanMemoryFiles` 只扫根目录 ——
+ * 这就是「归档 = 静默失效且可回退」的语义，不是漏扫。归档只在两个地方现身：
+ * 星图（`scanStars(ctx, true)`）与归档列表（`scanArchived`）—— 让**用户**看得见，
+ * 而不是让**模型**想起来。
+ *
+ * 归档留痕写在文件自己的 frontmatter 里（`archived_at` / `archived_reason`）：
+ * 文件可能被手工搬来搬去，随文件走的元数据才不会与文件脱节。
+ */
+
+import { MEMORY_DIR } from './config.js'
+import { parseBaseline, parseFrontmatter } from './frontmatter.js'
+import { isMemoryEntry } from './naming.js'
+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 {
+    const entries = await readdir(MEMORY_DIR, { withFileTypes: true })
+    const names = entries
+      .filter(e => e.isFile() && isMemoryEntry(e.name))
+      .map(e => e.name)
+    const loaded = await Promise.all(names.map(async (name) => {
+      try {
+        const full = join(MEMORY_DIR, name)
+        // stat 与 readFile 并行 —— 多要一个 mtime 不该变成串行两跳。
+        const [content, info] = await Promise.all([readFile(full, 'utf8'), stat(full)])
+        const meta = parseFrontmatter(content)
+        return {
+          file: name,
+          content,
+          description: meta.description || '',
+          aliases: meta.aliases || [],
+          baseline: parseBaseline(content),
+          baselinePriority: meta.baselinePriority || 0,
+          // 新鲜度的两个来源：frontmatter 的 updated（权威）与文件 mtime（退路）。
+          updated: meta.updated || '',
+          mtimeMs: info.mtimeMs,
+        }
+      } catch (err) {
+        // 只有 ENOENT 是正常状态（扫到读之间被删）。其余——权限错、编码坏、盘掉线——
+        // 一律出声：这里的静默化就是把「记忆不再注入」变成无声事故的那一手。
+        if (err?.code !== 'ENOENT') warnLog(ctx, `cannot read ${name}: ${err?.message ?? err}`, sessionId)
+        return null
+      }
+    }))
+    return loaded.filter(Boolean)
+  } catch (err) {
+    if (err?.code !== 'ENOENT') warnLog(ctx, `cannot scan ${MEMORY_DIR}: ${err?.message ?? err}`, sessionId)
+    return []
+  }
+}
+
+/** 提取正文第一个 `# ` 标题作为展示标题。 */
+export function extractTitle(content) {
+  const m = content.match(/^---\r?\n[\s\S]*?\r?\n---/)
+  const body = m ? content.slice(m[0].length) : content
+  const h1 = body.match(/^#\s+(.+)$/m)
+  return h1 ? h1[1].trim() : ''
+}
+
+/** 扫一个目录，读回星图要的轻量元数据（正文 + 体积 + 修改时间）。 */
+async function readStarDir(dir, ctx) {
+  let entries
+  try {
+    entries = await readdir(dir, { withFileTypes: true })
+  } catch (err) {
+    if (err?.code !== 'ENOENT') warnLog(ctx, `cannot scan ${dir}: ${err?.message ?? err}`)
+    return []
+  }
+  const names = entries
+    .filter(e => e.isFile() && isMemoryEntry(e.name))
+    .map(e => e.name)
+  const loaded = await Promise.all(names.map(async (name) => {
+    try {
+      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 ${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))]
+}

package/lib/memory/util.js

@@ -0,0 +1,37 @@
+/**
+ * sage-mem 记忆层 —— 通用小工具：统一日志出口与原子写。
+ */
+
+import { rename, unlink, writeFile } from 'node:fs/promises'
+
+/**
+ * 统一告警出口。所有非 ENOENT 的失败都必须落到日志，绝不静默
+ * （历史坑见 assemble 监听器里那段注释：表现是「插件在、记忆不再注入」，日志一字没有）。
+ * @param ctx — 插件上下文，取 ctx.logger.warn
+ * @param msg — 消息正文，调用方负责带上文件名 / 目录名
+ * @param sessionId — 可选 session id，有就带
+ */
+export function warnLog(ctx, msg, sessionId) {
+  const line = `sage-mem: ${msg}${sessionId ? ` (session ${sessionId})` : ''}`
+  if (ctx?.logger?.warn) ctx.logger.warn(line)
+  else console.warn(line)
+}
+
+/**
+ * 原子写：先写同目录临时文件，再 rename 覆盖目标。
+ *
+ * 直写的风险是崩在中途（断电、进程被杀、磁盘满）留下半截文件 —— frontmatter
+ * 缺半边，这条记忆从此解析不出来、检索不到，而文件看上去还在。
+ * 同卷 rename 是原子的：读方要么看到旧全文、要么看到新全文，不存在中间态。
+ * 任何一步失败都不碰目标文件，临时文件收尾清掉。
+ */
+export async function writeFileAtomic(target, content) {
+  const tmp = `${target}.${process.pid}.tmp`
+  try {
+    await writeFile(tmp, content, 'utf8')
+    await rename(tmp, target)
+  } finally {
+    // rename 成功后 tmp 已不存在（ENOENT），失败时把它清掉不留垃圾。
+    await unlink(tmp).catch(() => {})
+  }
+}