@modusensus/dsh-mneme 0.1.0

package/src/api.js

@@ -0,0 +1,59 @@
+import { URL } from "node:url";
+
+function sendJson(res, status, payload) {
+  res.writeHead(status, { "Content-Type": "application/json; charset=utf-8" });
+  res.end(JSON.stringify(payload));
+}
+
+export function createApi(ctx, service) {
+  const disposers = [];
+
+  // /api/dsh-mneme prefix fallback → 404 JSON for unknown sub-paths
+  disposers.push(ctx.webServer.register({
+    kind: "prefix",
+    path: "/api/dsh-mneme",
+    handler(req, res) {
+      sendJson(res, 404, { error: "not-found" });
+    }
+  }));
+
+  disposers.push(ctx.webServer.register({
+    kind: "exact",
+    path: "/api/dsh-mneme/list",
+    handler(req, res) {
+      try {
+        const url = new URL(req.url, "http://localhost");
+        const type = url.searchParams.get("type") ?? undefined;
+        const limit = Number(url.searchParams.get("limit") ?? 50);
+        const offset = Number(url.searchParams.get("offset") ?? 0);
+        const items = service.toApiList(service.list({ type, limit, offset }));
+        sendJson(res, 200, { items, total: service.count(type) });
+      } catch {
+        sendJson(res, 500, { error: "internal" });
+      }
+    }
+  }));
+
+  disposers.push(ctx.webServer.register({
+    kind: "exact",
+    path: "/api/dsh-mneme/search",
+    handler(req, res) {
+      try {
+        const url = new URL(req.url, "http://localhost");
+        const q = url.searchParams.get("q") ?? "";
+        const limit = Number(url.searchParams.get("limit") ?? 20);
+        const items = service.toApiList(service.search(q, { limit }));
+        sendJson(res, 200, { items });
+      } catch {
+        sendJson(res, 500, { error: "internal" });
+      }
+    }
+  }));
+
+  return {
+    routes: 3,
+    dispose: () => {
+      for (const dispose of disposers) dispose();
+    }
+  };
+}

package/src/config.js

@@ -0,0 +1,15 @@
+import z from "@deepseek-ai/schemastery";
+
+export const Config = z.object({
+  memoryDir: z.string().default("~/.dsh/memory"),
+  autoInject: z.boolean().default(true),
+  autoSummarize: z.boolean().default(true),
+  maxInjectedItems: z.natural().min(1).max(20).default(5),
+  importanceThreshold: z.natural().min(1).max(5).default(3),
+  autoDream: z.boolean().default(true),
+  dreamThresholdCount: z.natural().min(1).max(1000).default(10),
+  dreamThresholdChars: z.natural().min(100).max(100000).default(5000),
+  dreamDelayMs: z.natural().min(0).max(60000).default(2000),
+  dreamProvider: z.string(),
+  dreamModel: z.string()
+});

package/src/dream/decisions.js

@@ -0,0 +1,121 @@
+const ACTIONS = new Set(["keep", "merge", "archive", "conflict"]);
+
+/**
+ * Validate a dream decision list against a snapshot of eligible memories.
+ * @param decisions - LLM-produced decision list.
+ * @param snapshot - Map<id, memory> of eligible (non-archived, non-summary) entries.
+ * @returns {{ok: boolean, errors: string[]}}
+ */
+export function validateDecisions(decisions, snapshot) {
+  const errors = [];
+  if (!Array.isArray(decisions) || decisions.length === 0) {
+    return { ok: false, errors: ["decision list must be a non-empty array"] };
+  }
+  const claimed = new Set();
+  for (const [index, d] of decisions.entries()) {
+    const at = `decision[${index}]`;
+    if (!d || typeof d !== "object" || !ACTIONS.has(d.action)) {
+      errors.push(`${at}: invalid action ${JSON.stringify(d?.action)}`);
+      continue;
+    }
+    const ids = d.action === "conflict" ? [d.winner, d.loser] : (d.ids ?? []);
+    if (d.action === "conflict") {
+      if (!d.winner || !d.loser || d.winner === d.loser) {
+        errors.push(`${at}: conflict needs distinct winner and loser`);
+        continue;
+      }
+    } else if (!Array.isArray(d.ids) || d.ids.length === 0) {
+      errors.push(`${at}: ${d.action} needs non-empty ids`);
+      continue;
+    }
+    for (const id of ids) {
+      const mem = snapshot.get(id);
+      if (!mem) {
+        errors.push(`${at}: unknown id ${JSON.stringify(id)}`);
+      } else if (mem.archived || mem.type === "summary") {
+        errors.push(`${at}: id ${JSON.stringify(id)} is archived or summary (not eligible)`);
+      }
+      if (claimed.has(id)) {
+        errors.push(`${at}: id ${JSON.stringify(id)} claimed by multiple decisions`);
+      }
+      claimed.add(id);
+    }
+    if (d.action === "merge") {
+      if (!d.keepSource || !d.ids.includes(d.keepSource)) {
+        errors.push(`${at}: merge keepSource must be one of ids`);
+      }
+      if (typeof d.title !== "string" || !d.title.trim() || typeof d.content !== "string" || !d.content.trim()) {
+        errors.push(`${at}: merge needs non-empty title and content`);
+      }
+      if (d.importance !== undefined && (!Number.isInteger(d.importance) || d.importance < 1 || d.importance > 5)) {
+        errors.push(`${at}: merge importance must be an integer 1-5 when provided`);
+      }
+      // Merging across types would blur preference/project/decision boundaries
+      // in the injected context; the snapshot carries each entry's type.
+      const mergeTypes = new Set(d.ids.map((id) => snapshot.get(id)?.type));
+      if (mergeTypes.size > 1) {
+        errors.push(`${at}: merge ids span multiple types (${[...mergeTypes].join(", ")})`);
+      }
+    }
+  }
+  // Every snapshot id must appear in at least one decision
+  for (const id of snapshot.keys()) {
+    if (!claimed.has(id)) errors.push(`memory ${JSON.stringify(id)} missing from decisions`);
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+/**
+ * Apply a validated decision list to the service. Caller must validate first.
+ *
+ * Note: merge is intentionally non-atomic — the keeper is updated before the
+ * other sources are archived, so a failure between the two never loses content.
+ *
+ * @param decisions - validated decision list.
+ * @param service - memory service (saveWithDedupe/getById/update/setArchived).
+ * @param logger - optional logger ({ warn }); per-decision failures are logged.
+ * @returns number of applied decisions (archive counts each archived memory as one).
+ */
+export function applyDecisions(decisions, service, logger = null) {
+  let applied = 0;
+  for (const [i, d] of decisions.entries()) {
+    try {
+      if (d.action === "keep") continue;
+      if (d.action === "archive") {
+        for (const id of d.ids) {
+          const mem = service.getById(id);
+          if (mem && !mem.archived) { service.setArchived(id, true); applied++; }
+        }
+      } else if (d.action === "merge") {
+        const keeper = service.getById(d.keepSource);
+        if (!keeper || keeper.archived) continue;
+        service.update(d.keepSource, {
+          title: d.title,
+          content: d.content,
+          importance: d.importance ?? Math.max(keeper.importance, ...d.ids.map((id) => service.getById(id)?.importance ?? 1))
+        });
+        for (const id of d.ids) {
+          if (id !== d.keepSource) {
+            const mem = service.getById(id);
+            if (mem && !mem.archived) { service.setArchived(id, true); }
+          }
+        }
+        applied++;
+      } else if (d.action === "conflict") {
+        const winner = service.getById(d.winner);
+        const loser = service.getById(d.loser);
+        if (!winner || !loser) continue;
+        service.update(d.winner, {
+          content: `${winner.content}\n\n（已否决旧信息：${[...loser.content].slice(0, 100).join("")}）`
+        });
+        service.setArchived(d.loser, true);
+        applied++;
+      }
+    } catch (error) {
+      // Skip individual bad decision; never corrupt the store. The optional
+      // logger makes the failure visible instead of failing silently.
+      logger?.warn?.(`dsh-mneme dream: failed to apply ${d.action} at index ${i}: ${error.message}`);
+    }
+  }
+  return applied;
+}

package/src/dream.js

@@ -0,0 +1,205 @@
+import { validateDecisions, applyDecisions } from "./dream/decisions.js";
+export { validateDecisions, applyDecisions };
+
+const SUMMARY_PROMPT = `你是记忆库摘要助手。根据整理后的记忆，生成一段 150-200 字的记忆库总览，覆盖：用户偏好、活跃项目、关键决策。之后作为会话上下文注入。只输出摘要文本，不要其他内容。`;
+
+const CONSOLIDATION_PROMPT = `你是记忆库整理助手。下面是全部记忆条目（id、类型、标题、内容、重要性、更新时间）。
+请执行记忆巩固（consolidation）：
+1. 识别主题相近的条目 → 输出 merge（合并为更精炼的摘要，保留信息最完整的 id 作为 keepSource）
+2. 识别重复/过时信息 → 输出 archive
+3. 识别内容矛盾的条目 → 输出 conflict（根据时间新旧、来源完整性、信息具体程度判断 winner/loser）
+4. 无问题的条目 → 输出 keep
+
+规则：
+- 每条记忆至少出现在一个决策中
+- merge 的 keepSource 必须是 ids 之一
+- 仅合并同类型条目（type 相同）
+- 不要编造 ids；只使用提供的 id
+- 重要性 1-5，合并后取最高
+- 只输出 JSON 数组，不要其他文字`;
+
+function totalChars(memories) {
+  return memories.reduce((sum, m) => sum + (m.title?.length ?? 0) + (m.content?.length ?? 0), 0);
+}
+
+/**
+ * Consume an LLM stream and return the accumulated text. Direct text-delta
+ * accumulation covers both the real protocol ({type:"text-delta", index, text})
+ * and looser test doubles ({type:"text-delta", text}); a terminal error/abort
+ * surfaces as undefined. The caller decides how to treat an empty result.
+ */
+async function streamText(ctx, options) {
+  let text = "";
+  for await (const chunk of ctx.llm.stream(options)) {
+    if (chunk.type === "text-delta" && typeof chunk.text === "string") text += chunk.text;
+    if (chunk.type === "finish" && (chunk.reason?.kind === "error" || chunk.reason?.kind === "aborted")) {
+      return undefined;
+    }
+  }
+  return text;
+}
+
+/**
+ * Resolve the LLM route: agent default model (deployment) first, plugin config
+ * (dreamProvider/dreamModel) as fallback. Falls through to undefined when no
+ * route exists — runDream then fails safe. Fallback is logged so a silent
+ * route switch is observable.
+ */
+function resolveRoute(ctx, config, logger) {
+  try {
+    const sel = ctx.agentDefaultModel?.currentSelection?.();
+    if (sel?.provider && sel?.model) return { provider: sel.provider, model: sel.model };
+    logger?.warn?.("dsh-mneme dream: agentDefaultModel unavailable, falling back to config route");
+  } catch (error) {
+    logger?.warn?.(`dsh-mneme dream: agentDefaultModel lookup failed, falling back to config route: ${String(error)}`);
+  }
+  if (config.dreamProvider && config.dreamModel) return { provider: config.dreamProvider, model: config.dreamModel };
+  return undefined;
+}
+
+export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChars = 5000, delayMs = 2000, logger }) {
+  let pendingTimer = null;
+  let running = false;
+  let disposed = false;
+  let baseline = { count: 0, chars: 0 };
+
+  function shouldTrigger(service) {
+    const memories = service.all().filter((m) => !m.archived && m.type !== "summary");
+    const count = memories.length;
+    const chars = totalChars(memories);
+    const overBase = count >= baseline.count + thresholdCount || chars >= baseline.chars + thresholdChars;
+    const overAbs = count >= thresholdCount || chars >= thresholdChars;
+    return { trigger: overAbs && overBase, count, chars };
+  }
+
+  function maybeSchedule(service) {
+    if (disposed || running || pendingTimer) return false;
+    const { trigger, count, chars } = shouldTrigger(service);
+    if (!trigger) return false;
+    pendingTimer = setTimeout(() => {
+      pendingTimer = null;
+      running = true;
+      // Defer the onRun invocation so a synchronous throw cannot escape the
+      // timer callback (which would crash the process) and skip the teardown.
+      // Errors are logged, never swallowed silently.
+      Promise.resolve()
+        .then(() => (onRun ? onRun() : Promise.resolve({ ok: true, skipped: true })))
+        .then((result) => {
+          // Refresh the baseline only for a successful run (design §5.3: an
+          // LLM failure must not move the baseline, so the next write can
+          // immediately re-trigger a retry). A `{ok:false}` result or a throw
+          // keeps the old baseline. A run that reports nothing is treated as
+          // completed without failure (no-op hooks / minimal test doubles).
+          if (result && result.ok) {
+            try {
+              baseline = shouldTrigger(service);
+            } catch (error) {
+              // Store closed mid-flight: keep the last known baseline.
+              logger?.warn?.(`dsh-mneme dream: baseline refresh failed: ${String(error)}`);
+            }
+          }
+        })
+        .catch((error) => {
+          logger?.warn?.(`dsh-mneme dream: run failed: ${error?.message ?? error}`);
+          // Failed runs do not refresh the baseline.
+        })
+        .finally(() => {
+          running = false;
+        });
+    }, delayMs);
+    return true;
+  }
+
+  function dispose() {
+    disposed = true;
+    if (pendingTimer) { clearTimeout(pendingTimer); pendingTimer = null; }
+    // An in-flight run is left to complete naturally: its LLM calls are
+    // already paid for and aborting would discard the work. The caller is
+    // responsible for closing the store only after the run has finished.
+  }
+
+  async function runDream(ctx, service, config) {
+    const logger = ctx.logger;
+    const memories = service.all().filter((m) => !m.archived && m.type !== "summary");
+    if (memories.length === 0) return { ok: true, applied: 0, skipped: true, summary: false };
+    const snapshot = new Map(memories.map((m) => [m.id, m]));
+    const route = resolveRoute(ctx, config, logger);
+    if (!route) {
+      logger?.warn?.("dsh-mneme dream: no llm route available");
+      return { ok: false, error: "no llm route", summary: false };
+    }
+
+    const listText = [...snapshot.values()].map((m) =>
+      `id=${m.id} | type=${m.type} | importance=${m.importance} | updated=${m.updated_at} | title=${m.title} | content=${m.content}`
+    ).join("\n");
+
+    let decisionText;
+    try {
+      decisionText = await streamText(ctx, {
+        provider: route.provider,
+        model: route.model,
+        purpose: "compaction",
+        maxTokens: config.dreamMaxTokens ?? 4096,
+        messages: [
+          { role: "system", content: [{ type: "text", text: CONSOLIDATION_PROMPT }] },
+          { role: "user", content: [{ type: "text", text: listText }] }
+        ]
+      });
+    } catch (error) {
+      logger?.warn?.(`dsh-mneme dream: consolidation llm call failed: ${String(error)}`);
+      return { ok: false, error: "llm failed", summary: false };
+    }
+    if (decisionText === undefined) {
+      logger?.warn?.("dsh-mneme dream: consolidation llm stream aborted or errored");
+      return { ok: false, error: "llm failed", summary: false };
+    }
+
+    let decisions;
+    try {
+      const start = decisionText.indexOf("[");
+      const end = decisionText.lastIndexOf("]");
+      if (start === -1 || end <= start) {
+        logger?.warn?.("dsh-mneme dream: no json array in llm output");
+        return { ok: false, error: "no json array in llm output", summary: false };
+      }
+      decisions = JSON.parse(decisionText.slice(start, end + 1));
+    } catch {
+      logger?.warn?.("dsh-mneme dream: invalid decisions json");
+      return { ok: false, error: "invalid decisions json", summary: false };
+    }
+    const { ok, errors } = validateDecisions(decisions, snapshot);
+    if (!ok) {
+      logger?.warn?.(`dsh-mneme dream: invalid decisions: ${errors.join("; ")}`);
+      return { ok: false, error: `invalid decisions: ${errors.length} errors`, summary: false };
+    }
+
+    const applied = applyDecisions(decisions, service, logger);
+
+    // Summary generation (second LLM call). A throwing stream is reported as
+    // a failed run; summary:false marks a run that produced no summary.
+    let summaryText;
+    try {
+      summaryText = await streamText(ctx, {
+        provider: route.provider,
+        model: route.model,
+        purpose: "compaction",
+        maxTokens: config.dreamMaxTokens ?? 2048,
+        messages: [
+          { role: "system", content: [{ type: "text", text: SUMMARY_PROMPT }] },
+          { role: "user", content: [{ type: "text", text: service.all().filter((m) => !m.archived && m.type !== "summary").map((m) => `- ${m.title}: ${m.content}`).join("\n") }] }
+        ]
+      });
+    } catch (error) {
+      logger?.warn?.(`dsh-mneme dream: summary llm call failed: ${String(error)}`);
+      return { ok: false, error: "llm failed", summary: false };
+    }
+    let summaryStored = false;
+    if (summaryText !== undefined && summaryText.trim()) {
+      service.saveWithDedupe({ type: "summary", title: "记忆库总览", content: summaryText.trim(), importance: 5, source: "dream" });
+      summaryStored = true;
+    }
+    return { ok: true, applied, summary: summaryStored };
+  }
+
+  return { maybeSchedule, runDream, dispose };
+}

package/src/index.js

@@ -0,0 +1,86 @@
+import { createStore } from "./store.js";
+import { createMirror, TYPE_FILE } from "./mirror.js";
+import { createService } from "./service.js";
+import { createTools } from "./tools.js";
+import { createInjector } from "./inject.js";
+import { createSummarizer } from "./summarize.js";
+import { createDreamScheduler } from "./dream.js";
+import { createApi } from "./api.js";
+import { Config } from "./config.js";
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+export const name = "dsh-mneme";
+export const inject = ["tools", "systemPrompt", "webServer", "llm", "agentDefaultModel"];
+export { Config };
+
+// Arrow (not function declaration): cordis 4 treats any apply with a
+// prototype as a class constructor (`new apply(...)`) and discards its return
+// value, so a `function apply` disposer would never run on unload. An arrow
+// has no prototype, is called normally, and its returned disposer is collected
+// and run by the fiber on unload.
+export const apply = (ctx, config) => {
+  const cfg = Config(config);
+
+  // Resolve memoryDir: expand leading "~"
+  const memoryDir = cfg.memoryDir.startsWith("~")
+    ? join(homedir(), cfg.memoryDir.slice(1))
+    : cfg.memoryDir;
+  mkdirSync(memoryDir, { recursive: true });
+
+  const store = createStore(join(memoryDir, "memory.db"));
+  const mirror = createMirror(memoryDir);
+  const service = createService({ store, mirror, config: cfg });
+
+  // Human edits in mirror files win on every sync; merge them back first.
+  // TYPE_FILE maps each memory type to its mirror filename.
+  for (const type of Object.keys(TYPE_FILE)) {
+    const edits = mirror.readHumanEdits(type);
+    if (edits.length) service.mergeHumanEdits(type, edits);
+  }
+
+  // Dream scheduler: automatic consolidation + summary runs, triggered by
+  // store growth. Writes through the service fire the dream hook, which asks
+  // the scheduler to (re)schedule a run once absolute and since-last-run
+  // thresholds are both exceeded. onRun is deferred through `dream` so the
+  // closure sees the assigned scheduler; the null guard keeps a run safe even
+  // if the hook fires before assignment or after dispose.
+  let dream = null;
+  if (cfg.autoDream) {
+    dream = createDreamScheduler({
+      thresholdCount: cfg.dreamThresholdCount,
+      thresholdChars: cfg.dreamThresholdChars,
+      delayMs: cfg.dreamDelayMs,
+      logger: ctx.logger,
+      onRun: () => (dream ? dream.runDream(ctx, service, cfg) : Promise.resolve({ ok: true, skipped: true }))
+    });
+    service.setDreamHook(() => dream.maybeSchedule(service));
+  }
+
+  const disposers = [];
+
+  ctx.inject(["systemPrompt"], (promptCtx) => {
+    if (cfg.autoInject) disposers.push(createInjector(promptCtx, service, cfg));
+  });
+
+  ctx.inject(["tools"], (toolsCtx) => {
+    disposers.push(createTools(toolsCtx, service, cfg));
+  });
+
+  const summarizer = createSummarizer(ctx, service, cfg);
+  disposers.push(summarizer.dispose);
+
+  if (ctx.webServer) {
+    const api = createApi(ctx, service);
+    disposers.push(api.dispose);
+  }
+
+  return () => {
+    for (const dispose of disposers) {
+      if (typeof dispose === "function") dispose();
+    }
+    if (dream) dream.dispose();
+    store.close();
+  };
+};

package/src/inject.js

@@ -0,0 +1,22 @@
+export function createInjector(ctx, service, config) {
+  const maxItems = config.maxInjectedItems ?? 5;
+  const threshold = config.importanceThreshold ?? 3;
+
+  function render(candidates) {
+    if (!candidates.length) return "";
+    const lines = ["[记忆库] 来自 dsh-mneme 的跨会话记忆（用户偏好与高优先级项目/决策）："];
+    for (const m of candidates) {
+      lines.push(`- [${m.type}] ${m.title}（重要性 ${m.importance}）：${m.content}`);
+    }
+    return lines.join("\n");
+  }
+
+  return ctx.systemPrompt.context({
+    name: "memory",
+    order: 90,
+    text: () => {
+      const candidates = service.injectCandidates({ maxItems, threshold });
+      return render(candidates);
+    }
+  });
+}

package/src/mirror.js

@@ -0,0 +1,131 @@
+import { mkdirSync, readFileSync, writeFileSync, existsSync, rmSync } from "node:fs";
+import { join } from "node:path";
+
+export const TYPE_FILE = {
+  preference: "preferences.md",
+  project: "projects.md",
+  decision: "decisions.md",
+  history: "history.md",
+  summary: "summary.md"
+};
+
+const ESCAPE = /([\\`*_[\]{}()#+.!|>~-])/g;
+const UNESCAPE = new RegExp("\\\\" + ESCAPE.source, "g");
+
+function esc(text) {
+  return String(text).replace(ESCAPE, "\\$1");
+}
+
+function unescape(text) {
+  return String(text).replace(UNESCAPE, "$1");
+}
+
+function renderMemory(m) {
+  const lines = [];
+  lines.push(`## ${esc(m.title)}`);
+  lines.push("");
+  lines.push(`- **ID**: \`${m.id}\``);
+  lines.push(`- **类型**: ${m.type}`);
+  lines.push(`- **重要性**: ${m.importance}`);
+  lines.push(`- **标签**: ${m.tags.map((t) => `\`${esc(t)}\``).join(" ")}`);
+  lines.push(`- **更新时间**: ${m.updated_at}`);
+  if (m.source) lines.push(`- **来源**: ${esc(m.source)}`);
+  lines.push("");
+  lines.push(m.content);
+  lines.push("");
+  lines.push("---");
+  lines.push("");
+  return lines.join("\n");
+}
+
+export function createMirror(dir) {
+  mkdirSync(dir, { recursive: true });
+
+  function filePath(type) {
+    const name = TYPE_FILE[type];
+    return name ? join(dir, name) : undefined;
+  }
+
+  /**
+   * Parse a mirror file back into {id, title, content} entries for human edits.
+   * Entries are anchored on "- **ID**: `...`" lines that are followed by the
+   * "- **类型**:" metadata line (structural entry head): each entry's block
+   * spans from its ID line up to the next ID line (or end of file). The block
+   * head (the ID line plus the generated metadata run) and the trailing
+   * structural "---" separator are stripped; everything in between is the entry
+   * body, so user content containing "---", metadata-like lines, or even a
+   * machine-format "- **ID**: `x`" line is preserved. The title is the "## "
+   * heading preceding the ID line.
+   */
+  function readHumanEdits(type = undefined) {
+    const types = type ? [type] : Object.keys(TYPE_FILE);
+    const edits = [];
+    for (const t of types) {
+      const file = filePath(t);
+      if (!file || !existsSync(file)) continue;
+      const text = readFileSync(file, "utf8").replace(/\r\n/g, "\n");
+      // Anchor on the ID line only when it is a structural entry head: the
+      // machine-rendered ID line is always followed by the "- **类型**:" line.
+      // A body line like "- **ID**: `x`" is not, so it never splits the block
+      // or produces a ghost entry.
+      const anchors = [...text.matchAll(/^- \*\*ID\*\*: `([^`]+)`\n- \*\*类型\*\*:/gm)];
+      let prevEnd = 0;
+      for (let i = 0; i < anchors.length; i++) {
+        const anchor = anchors[i];
+        const blockStart = anchor.index;
+        const blockEnd = i + 1 < anchors.length ? anchors[i + 1].index : text.length;
+
+        // Title: last "## " heading before this ID line (file header region /
+        // previous block tail). Body headings of earlier entries come before
+        // the structural "---" + "## " of this entry, so the last match wins.
+        const titleMatches = [...text.slice(prevEnd, blockStart).matchAll(/^## (.+)$/gm)];
+        const titleMatch = titleMatches[titleMatches.length - 1];
+
+        // Body: the ID line and the generated metadata run are structural head;
+        // everything after them up to the trailing "---" separator is the body.
+        let body = text
+          .slice(blockStart, blockEnd)
+          .replace(/^- \*\*ID\*\*: `[^`]+`\n?/, "")
+          .replace(/^(- \*\*(类型|重要性|标签|更新时间|来源)\*\*:.*\n?)+/, "");
+        const separators = [...body.matchAll(/^---\s*$/gm)];
+        const lastSep = separators[separators.length - 1];
+        if (lastSep) body = body.slice(0, lastSep.index);
+        body = body.trim();
+
+        edits.push({
+          id: anchor[1],
+          title: titleMatch ? unescape(titleMatch[1]).trim() : undefined,
+          content: body
+        });
+
+        const lineEnd = text.indexOf("\n", blockStart);
+        prevEnd = lineEnd === -1 ? text.length : lineEnd + 1;
+      }
+    }
+    return edits;
+  }
+
+  function sync(memories) {
+    const byType = {};
+    for (const m of memories) {
+      (byType[m.type] ??= []).push(m);
+    }
+    for (const type of Object.keys(TYPE_FILE)) {
+      const file = filePath(type);
+      const items = (byType[type] ?? [])
+        .slice()
+        .sort((a, b) => (a.updated_at < b.updated_at ? 1 : -1));
+      if (items.length === 0) {
+        // no memories of this type: drop any stale mirror file so deleted
+        // memories do not "resurrect" via readHumanEdits
+        rmSync(file, { force: true });
+        continue;
+      }
+      const header = `# ${TYPE_FILE[type]} — dsh-mneme 镜像\n\n<!-- 手工编辑此文件会被合并回记忆库（人工优先）。 -->\n\n`;
+      const body = items.map(renderMemory).join("\n");
+      writeFileSync(file, header + body, "utf8");
+    }
+  }
+
+  return { filePath, sync, readHumanEdits };
+}