@modusensus/dsh-mneme 0.1.0

package/lib/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/lib/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/lib/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/lib/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 };
+}

package/lib/service.js

@@ -0,0 +1,157 @@
+const INJECT_TYPES = new Set(["preference", "project", "decision", "summary"]);
+
+export function createService({ store, mirror, config, onWrite }) {
+  // Optional dream scheduler hook, installed via setDreamHook after creation
+  // (the scheduler holds a reference back to the service, so it cannot be
+  // passed in the constructor). Fired on the same write events as onWrite.
+  let dreamHook = null;
+
+  /**
+   * Fire-and-forget write notification; errors are swallowed to keep write
+   * paths clean. The store mutation has already committed, so a throwing
+   * subscriber must not surface as a write failure. Archive/forget flags are
+   * state toggles, not content writes, so they never notify.
+   */
+  function notifyWrite() {
+    if (onWrite) {
+      try { onWrite(); } catch { /* ignore */ }
+    }
+    if (dreamHook) {
+      try { dreamHook(); } catch { /* ignore */ }
+    }
+  }
+
+  /**
+   * Save a memory, merging into an existing one when title matches within the same type.
+   * @returns {{action: "created"|"merged", memory: object}}
+   */
+  function saveWithDedupe(memory) {
+    const existing = store
+      .list({ type: memory.type, limit: 100 })
+      .find((m) => m.title.trim() === String(memory.title).trim());
+    if (existing) {
+      const merged = store.update(existing.id, {
+        content: memory.content ?? existing.content,
+        importance: memory.importance ?? existing.importance,
+        tags: memory.tags ?? existing.tags,
+        title: memory.title ?? existing.title
+      });
+      syncMirror();
+      notifyWrite();
+      return { action: "merged", memory: merged };
+    }
+    const created = store.save({
+      type: memory.type,
+      title: memory.title,
+      content: memory.content,
+      tags: memory.tags ?? [],
+      importance: memory.importance ?? 3,
+      source: memory.source ?? "manual"
+    });
+    syncMirror();
+    notifyWrite();
+    return { action: "created", memory: created };
+  }
+
+  /**
+   * Candidate memories for automatic context injection:
+   * summaries first, then all preferences, then non-forgotten items with
+   * importance >= threshold. History is never auto-injected. Archived entries
+   * are excluded (store.list already filters them by default; the extra
+   * !m.archived check is kept as double insurance).
+   */
+  function injectCandidates({ maxItems = 5, threshold = 3 } = {}) {
+    const items = store.list({ limit: 200, includeForgotten: false })
+      .filter((m) => !m.archived && INJECT_TYPES.has(m.type) && !m.forgotten &&
+        (m.type === "summary" || m.type === "preference" || m.importance >= threshold))
+      .sort((a, b) => {
+        const pa = a.type === "summary" ? 0 : a.type === "preference" ? 1 : 2;
+        const pb = b.type === "summary" ? 0 : b.type === "preference" ? 1 : 2;
+        return pa - pb || b.importance - a.importance;
+      });
+    return items.slice(0, maxItems);
+  }
+
+  /**
+   * Merge human edits parsed from a mirror file back into the store.
+   * Only content/title are taken; structure fields stay machine-owned.
+   */
+  function mergeHumanEdits(type, edits) {
+    let applied = 0;
+    for (const edit of edits) {
+      if (!edit.id) continue; // corrupt/malformed edit: skip it, keep merging the rest
+      const existing = store.getById(edit.id);
+      if (!existing || existing.type !== type) continue;
+      const patch = {};
+      if (typeof edit.title === "string" && edit.title.trim()) patch.title = edit.title.trim();
+      if (typeof edit.content === "string" && edit.content.trim()) patch.content = edit.content.trim();
+      if (Object.keys(patch).length) {
+        store.update(edit.id, patch);
+        applied++;
+      }
+    }
+    if (applied) {
+      syncMirror();
+      notifyWrite();
+    }
+    return applied;
+  }
+
+  function toApiList(rows) {
+    return rows.map((m) => ({
+      id: m.id,
+      type: m.type,
+      title: m.title,
+      content: m.content,
+      tags: m.tags,
+      importance: m.importance,
+      source: m.source,
+      created_at: m.created_at,
+      updated_at: m.updated_at
+    }));
+  }
+
+  /**
+   * Re-render the human-editable mirror after any store mutation. Only
+   * non-forgotten memories are mirrored: forgotten entries must not reach the
+   * human-editable file (a human "edit" could otherwise resurrect them).
+   */
+  function syncMirror() {
+    if (mirror) mirror.sync(store.list({ limit: 500, includeForgotten: false }));
+  }
+
+  return {
+    saveWithDedupe,
+    injectCandidates,
+    mergeHumanEdits,
+    toApiList,
+    setDreamHook(fn) { dreamHook = fn; },
+    // passthroughs used by tools and api layers; mutations keep the mirror in sync
+    search: (q, o) => store.search(q, o),
+    list: (o) => store.list(o),
+    all: () => store.all(),
+    count: (type) => store.count(type),
+    getById: (id) => store.getById(id),
+    remove: (id) => {
+      store.remove(id);
+      syncMirror();
+      notifyWrite();
+    },
+    update: (id, p) => {
+      const updated = store.update(id, p);
+      syncMirror();
+      notifyWrite();
+      return updated;
+    },
+    setForget: (id, f) => {
+      const updated = store.setForget(id, f);
+      syncMirror();
+      return updated;
+    },
+    setArchived: (id, f) => {
+      const updated = store.setArchived(id, f);
+      syncMirror();
+      return updated;
+    }
+  };
+}