sage-mem 1.1.0 → 1.2.0

package/README.md

@@ -492,6 +492,14 @@ memory/ directory (markdown files, 4 types)
 
 No worker, no SQLite, no HTTP port, no long-running process.
 
+Module boundaries (since 1.2.0):
+
+- `lib/index.js` — the **composition root** plus the three gateways. The typert manifest pins `sourceLocation` to this file, so the gateway classes stay here (moving them would be a contract drift)
+- `lib/recall/` — the injection chain: selection (`select`) / rendering and budget (`compose`) / text (`text`) / session state (`state`)
+- `lib/assembly/` — the four mounts: autodream / retrieval tools / observation / write gate
+- `lib/memory/` — pure memory-layer functions and file operations; `lib/autodream/` — the autodream engine
+- Dependency direction: `memory` never imports `autodream`, `recall` depends only on `memory`, `assembly` never imports the composition root (`test/structure-test.mjs` turns red if that changes)
+
 ## Contributing
 
 ```bash

package/README.zh.md

@@ -496,6 +496,14 @@ memory/ 目录（markdown 文件，4 类）
 
 没有 worker、没有 SQLite、没有 HTTP 端口、没有常驻进程。
 
+模块边界（1.2.0 起）：
+
+- `lib/index.js` —— **组合根** + 三个 Gateway。typert manifest 的 `sourceLocation` 钉在这个文件上，所以 Gateway 类不搬走（搬 = 契约漂移）
+- `lib/recall/` —— 注入链：选材（`select`）/ 渲染与预算（`compose`）/ 文本（`text`）/ 会话状态（`state`）
+- `lib/assembly/` —— 四块挂载：autodream / 检索工具 / 观测 / 写入门
+- `lib/memory/` —— 记忆层的纯函数与文件操作；`lib/autodream/` —— 自动做梦引擎
+- 依赖方向：`memory` 不认识 `autodream`，`recall` 只依赖 `memory`，`assembly` 不反向依赖组合根（`test/structure-test.mjs` 会红）
+
 ## 参与开发
 
 ```bash

package/lib/assembly/autodream-mount.js

@@ -0,0 +1,24 @@
+/**
+ * autodream 的挂载（1.2.0 从 `MemoryGateway` 构造函数原样搬出）。
+ *
+ * 整个包在 try 里：autodream 起不来（比如 timer 服务缺失、状态目录没权限）
+ * 不该把 sage-mem 最核心的那件事——「记忆按问题注入」——一起拖死。
+ * 这是本插件唯一一处「降级而不是失败」的设计，理由就在这里。
+ */
+import { warnLog } from '../memory/util.js'
+
+/** @param {object} ctx @param {{AutodreamEngine:Function, AutodreamGateway:Function, memoryDir:string, sessionsRoot:string, reservedFiles:string[]}} deps */
+export function mountAutodream(ctx, { AutodreamEngine, AutodreamGateway, memoryDir, sessionsRoot, reservedFiles }) {
+  try {
+    const engine = new AutodreamEngine(ctx, { memoryDir, sessionsRoot, reservedFiles })
+    new AutodreamGateway(ctx, engine)
+    engine.start()
+    // 卸载时把定时器与锁收干净。effect 拿不到就交给 unref 兜底（不阻止进程退出）。
+    if (typeof ctx.effect === 'function') ctx.effect(() => () => engine.dispose())
+  } catch (err) {
+    warnLog(ctx, `autodream 初始化失败（记忆本体不受影响）：${err?.message ?? err}`)
+    // 异常路径额外打一行到 stderr：warnLog 走 ctx.logger，某些启动阶段它还没接上，
+    // 而「autodream 静默不工作」正是最难查的那种故障（曾为此排查很久）。
+    console.error('[sage-mem] autodream init failed:', err && err.stack ? err.stack : err)
+  }
+}

package/lib/assembly/index.js

@@ -0,0 +1,13 @@
+/**
+ * 组合根的四块挂载（1.2.0 的模块边界）。
+ *
+ * 每块一个文件、一个 `mountXxx(ctx, …)`：组合根的构造函数只负责按顺序调用它们。
+ * 顺序是语义的一部分（autodream → 工具 → 观测 → 写门），所以这里按同一顺序再导出。
+ *
+ * ⚠️ `mountWriteGate` 必须**同步**调用（注册窗口在 fs 就绪之前就关），
+ * 这条约束写在 `write-gate-mount.js` 头注里，并由 `write-gate-wiring-test.mjs` 第 7 组看着。
+ */
+export { mountAutodream } from './autodream-mount.js'
+export { mountMemoryTools } from './tools-mount.js'
+export { mountObserve } from './observe-mount.js'
+export { mountWriteGate } from './write-gate-mount.js'

package/lib/assembly/observe-mount.js

@@ -0,0 +1,37 @@
+/**
+ * 「模型自己翻了记忆目录」的观测挂载（1.2.0 从构造函数原样搬出）。
+ *
+ * 宿主的 `tools/result` 把**每一次**工具调用的 `exec`（含 name / arguments）交给我们，
+ * 于是「模型用内置 read/grep 读了哪份记忆」第一次变得可观测 —— 此前台账只记得下
+ * 「插件注入了什么」，记不下「模型主动翻了什么」。
+ *
+ * 三条纪律：
+ *   1. **只记能可靠判定的**（`observe.js` 认 read/grep/glob 的路径参数；`pwsh` 一律不认，
+ *      那是**已知观测盲区** —— 不许把「看不到」说成「没读」）。
+ *   2. **按 session × 文件去重**：翻页（read 的 offset 不同）不刷计数，那是同一个动作。
+ *   3. **失败绝不影响任何东西**：观测是副产品，它的问题不许冒泡到工具调用链上。
+ */
+import { accessEventKey, classifyToolExecution, createDeduper } from '../memory/observe.js'
+import { recordRead } from '../memory/access.js'
+
+export function mountObserve(ctx, memoryDir) {
+  const observedReads = createDeduper()
+  try {
+    ctx.on('tools/result', (exec) => {
+      try {
+        const cls = classifyToolExecution(exec?.name, exec?.arguments, memoryDir)
+        if (cls.kind !== 'active_read' || !cls.file) return
+        const key = accessEventKey({
+          sessionId: exec?.agent?.id ?? '',
+          file: cls.file,
+          // revision 要读盘才算得出，这里拿不到 —— 所以去重粒度是「session × 文件」。
+          // 写明这条口径，免得以后有人以为它按内容去重。
+          revision: '',
+          kind: cls.kind,
+        })
+        if (!key || !observedReads.shouldCount(key)) return
+        recordRead(cls.file, '')
+      } catch { /* 观测失败静默：它不该有任何存在感 */ }
+    })
+  } catch { /* 老宿主没有这个事件：不影响注入 */ }
+}

package/lib/assembly/tools-mount.js

@@ -0,0 +1,44 @@
+/**
+ * 检索工具（`search_memory` / `read_memory`）的挂载（1.2.0 从构造函数原样搬出）。
+ *
+ * 工具是否注册成功。拿不到宿主的 `tools` 服务时为 false —— 状态卡据此换文案：
+ * 有工具就教它「用 search_memory 搜」，没有就退回「直接读记忆目录」。
+ *
+ * 为什么是个可变量：注册是**异步就绪**的（`ctx.inject` 要等依赖服务上线），而注入链
+ * 每步都跑 —— 前几步可能还没就绪、后几步才就绪，这是正常的。
+ * 因此返回 `{ ready: () => boolean }` 而不是一个布尔值：值拷贝会让注入链永远读到 false。
+ *
+ * ⚠️ **用 `ctx.inject` 挂子 fiber，绝不给本类加 `static inject = ['tools']`。**
+ * 理由（`docs/decisions.md` D5，有官方依据）：`inject` 是**硬依赖** —— 声明了它的插件
+ * 要等依赖就绪才会被加载。宿主没有 `tools` 服务时，整个 sage-mem 会一直待机，
+ * **记忆注入跟着一起消失**。而工具只是锦上添花，不值得拿核心功能去换。
+ * `ctx.inject` 只让这个子回调等依赖就绪，主插件照常工作；依赖永远不来就只有它不生效。
+ *
+ * 另一条实测事实（`docs/host-facts.md`）：不声明 inject 时 `ctx.get('tools')` 只给
+ * `undefined`（那一刻服务还没被提供，而插件不会重跑），所以「先探测再注册」在这里
+ * 是行不通的 —— 必须走 `ctx.inject`。
+ */
+import { createMemoryTools } from '../tools/memory-tools.js'
+import { warnLog } from '../memory/util.js'
+
+export function mountMemoryTools(ctx) {
+  const state = { ready: false }
+  try {
+    if (typeof ctx.inject === 'function') {
+      ctx.inject(['tools'], (inner) => {
+        try {
+          const { searchMemory, readMemory } = createMemoryTools(ctx)
+          inner.tools.register(searchMemory)
+          inner.tools.register(readMemory)
+          state.ready = true
+        } catch (err) {
+          // 注册失败 ≠ 注入失败。出声一次，然后什么也不做。
+          warnLog(ctx, `检索工具注册失败（记忆注入不受影响）：${err?.message ?? err}`)
+        }
+      })
+    }
+  } catch (err) {
+    warnLog(ctx, `检索工具挂载失败（记忆注入不受影响）：${err?.message ?? err}`)
+  }
+  return { ready: () => state.ready }
+}

package/lib/assembly/write-gate-mount.js

@@ -0,0 +1,92 @@
+/**
+ * 写入门（版本守卫）的挂载（1.2.0 从构造函数原样搬出）。
+ *
+ * 实测（`scripts/events-probe.mjs`，本机 headless，2026-10-15）：这两个事件**只对
+ * 「工具发起」的写入**触发 —— 模型调内置 `write` / `edit` 打到记忆文件时会走这里；
+ * 而**插件自己**调 `ctx.fs.writeText` 时一次都不发（实测 0 次），那条路由调用方自己传
+ * `expected`（见 `lib/autodream/tools.js` 的 `writeMemoryText`）。
+ * 监听器**不需要声明 inject** 也能收到，所以这里不挂子 fiber。
+ *
+ * 它买到的东西：**模型的 `write` 没法在一个记忆文件被改过之后静默覆盖它** ——
+ * 守卫过不了，宿主会以 `FS_STALE_VERSION` 明确拒绝（实测确实会被拒）。
+ * 这属于「把静默的坏结果变成显式的失败」，不是「阻止写入」：这个事件**没有拒绝动作**，
+ * 我们也不发明一个（见 write-gate.js 的头注释）。
+ *
+ * 单槽纪律：返回 `undefined` 才是「不管」。目录外**必须**返回 undefined，否则会占掉槽位、
+ * 影响整块盘的写入（write-gate.js 的 `outside_memory` 判在 `caller_wins` 之前正是为此）。
+ *
+ * ⚠️⚠️ **本函数必须在 `apply()` 里被直接调用，绝不能挪进 `ctx.inject(['fs'], …)`，也不能给
+ * 插件加 `static inject = ['fs']`。** 这不是风格偏好，是实测出来的硬约束：
+ * 这两个事件有一个**注册窗口**，窗口在 fs 服务就绪**之前**就关了。
+ *   不 inject、apply 里直接挂     → 收到 1 次 ✅
+ *   顶层 `inject:['fs']`           → **0 次**
+ *   顶层 `inject:['tokenMeter']`   → **0 次**（与 fs 无关，是时机问题）
+ *   `ctx.inject(['fs'], sub)` 子 fiber → **0 次**
+ *   不 inject、但 apply 之后 2.5 秒再挂 → **0 次**（晚挂收不到）
+ * 证据：`scripts/host-facts-probe.mjs` 的七组对照 + `docs/host-facts.md` 3.3 节。
+ * 之所以特别标注：**按 D5 的规范直觉（可选服务要用 ctx.inject 挂子 fiber）改这里，
+ * 会让写门静默失效** —— 编译得过、测试可能也过，只是永远不触发。
+ * 而我们**不需要** inject：实测不声明 inject 时，处理器**内部** `ctx.get('fs')` 照样拿得到服务
+ * （`{hasFs:true, hasStat:true}`），取版本就靠它。
+ */
+import { memoryPathOf } from '../memory/paths.js'
+import { decideEditGuard, decideWriteIntent } from '../memory/write-gate.js'
+
+/**
+ * 探目标的当前版本。**区分「不存在」与「不知道」**。
+ *
+ * 这个区分不是洁癖：`!!info` 会把「拿不到 fs 服务」也写成 `exists:false`，判定表据此给
+ * `createIfAbsent` —— 而目标**其实是存在的**记忆文件时，那是一次**误拦**（写入必然失败，
+ * 模型收到一句看不懂的错误）。拿不准就不干涉，比猜一个安全。
+ */
+function makeProbeTarget(ctx) {
+  return async (target) => {
+    try {
+      const fs = typeof ctx.get === 'function' ? ctx.get('fs') : undefined
+      if (!fs || typeof fs.stat !== 'function' || !target) return { known: false }
+      const info = await fs.stat(target)
+      return { known: true, exists: !!info, version: info?.version ?? null }
+    } catch {
+      return { known: false }
+    }
+  }
+}
+
+export function mountWriteGate(ctx, memoryDir) {
+  const probeTarget = makeProbeTarget(ctx)
+  try {
+    if (typeof ctx.on === 'function') {
+      // 公共骨架：**先判位置、再决定要不要碰链子**。
+      //
+      // ⚠️ 三条纪律（都是踩出来的）：
+      //   1. **目录外连 `next()` 都不调**。宿主对**任何**工具写入都发这个事件（实测：写一个
+      //      临时文件也发），无条件调 next() + stat 等于给整个系统的每次写文件都加一次系统调用，
+      //      而我们本来就什么都不该做。直接 `return next()` 把决策权原样交出去。
+      //   2. **一旦调了 `next()`，就必须把它给的东西交回去**。`next()` 返回的是下游（或调用方
+      //      自己）已经做出的决定；此时再 `return undefined` 会把这个决定**丢掉** ——
+      //      我们本想「不干涉」，实际却比干涉还糟。
+      //   3. **探不到版本就不碰**（见 probeTarget）：把「不知道」当「不存在」会误拦真实存在的文件。
+      const gateEvent = (decide) => async (target, actor, next) => {
+        try {
+          const memoryPath = memoryPathOf(target?.displayPath, memoryDir)
+          if (!memoryPath.ok) return typeof next === 'function' ? next() : undefined
+          const caller = typeof next === 'function' ? await next() : undefined
+          const probed = await probeTarget(target)
+          if (!probed.known) return caller
+          const chosen = decide({
+            memoryPath,
+            exists: probed.exists,
+            version: probed.version,
+            caller,
+          })
+          // 我们给出决定就用我们的；决定不了（undefined）就把 `caller` 原样交回去，不吞。
+          return chosen === undefined ? caller : chosen
+        } catch {
+          return undefined /* 写门在宿主的写入链路上：抛出去会把一次正常写入炸掉 */
+        }
+      }
+      ctx.on('fs/write-intent', gateEvent((facts) => decideWriteIntent(facts).intent))
+      ctx.on('fs/edit-intent', gateEvent((facts) => decideEditGuard(facts).guard))
+    }
+  } catch { /* 老宿主没有这两个事件：写入按宿主默认语义走 */ }
+}

package/lib/{autodream-audit.js → autodream/audit.js}

@@ -23,8 +23,8 @@
 
 import { readdir, readFile } from 'node:fs/promises'
 import { join } from 'node:path'
-import { ARCHIVE_DIR_NAME, inspectMemoryEntry } from './memory/scan.js'
-import { warnLog } from './memory/util.js'
+import { ARCHIVE_DIR_NAME, inspectMemoryEntry } from '../memory/scan.js'
+import { warnLog } from '../memory/util.js'
 
 /** 索引文件名。它本身不是一条记忆，是索引。 */
 const INDEX_FILE = 'MEMORY.md'

package/lib/autodream/engine.js

@@ -33,8 +33,8 @@
  * 这里保留**同名同签名**的方法，以 `.call(this, …)` 转发 —— 纯搬移、零行为变更。
  */
 
-import { auditMemoryDir } from '../autodream-audit.js'
-import { autodreamToolSchemas, createToolRunner } from '../autodream-tools.js'
+import { auditMemoryDir } from './audit.js'
+import { autodreamToolSchemas, createToolRunner } from './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, ledgerFileFor, pickArchiveCandidates, readAccessLedger } from '../memory/access.js'

package/lib/autodream/llm-loop.js

@@ -8,7 +8,7 @@
  * 之所以不用真正的子代理：见 engine.js 顶部第 2 条设计决定。
  */
 
-import { buildAutodreamSystemPrompt, buildAutodreamUserPrompt } from '../autodream-prompt.js'
+import { buildAutodreamSystemPrompt, buildAutodreamUserPrompt } from './prompt.js'
 import { randomUUID } from 'node:crypto'
 
 export class BlockAssembler {

package/lib/autodream/report.js

@@ -6,7 +6,7 @@
  * 与拆分前完全一致，没有引入任何模块级可变状态。
  */
 
-import { formatAudit } from '../autodream-audit.js'
+import { formatAudit } from './audit.js'
 import { LEGACY_REPORT_DIR, REPORT_DIR } from './config.js'
 import { OP_LABEL, formatDelta, readJson, safeName, stampHuman } from './util.js'
 import { mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises'

package/lib/{autodream-tools.js → autodream/tools.js}

@@ -27,14 +27,14 @@
 import { readFile, readdir, 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'
-import { MAX_FILE_BYTES, STATE_ROOT } from './memory/config.js'
-import { writeFileAtomic, warnLog } from './memory/util.js'
-import { buildConflict, writeConflict } from './memory/conflicts.js'
-import { memoryPathOf } from './memory/paths.js'
-import { decideWriteIntent } from './memory/write-gate.js'
-import { inspectMemoryEntry, reservedIdentitySet } from './memory/scan.js'
+import { auditMemoryDir, formatAudit, parseFrontmatterLite } from './audit.js'
+import { archiveMemory } from '../memory/archive.js'
+import { MAX_FILE_BYTES, STATE_ROOT } from '../memory/config.js'
+import { writeFileAtomic, warnLog } from '../memory/util.js'
+import { buildConflict, writeConflict } from '../memory/conflicts.js'
+import { memoryPathOf } from '../memory/paths.js'
+import { decideWriteIntent } from '../memory/write-gate.js'
+import { inspectMemoryEntry, reservedIdentitySet } from '../memory/scan.js'
 
 /** 单次 read_memory 返回的正文上限（字符）。超过就截断并明确告诉模型。 */
 const READ_LIMIT = 20000