@modusensus/dsh-mneme 0.1.0

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

package/src/store.js

@@ -0,0 +1,230 @@
+import { DatabaseSync } from "node:sqlite";
+import { randomUUID } from "node:crypto";
+
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS memories (
+  id          TEXT PRIMARY KEY,
+  type        TEXT NOT NULL,
+  title       TEXT NOT NULL,
+  content     TEXT NOT NULL,
+  tags        TEXT NOT NULL DEFAULT '[]',
+  importance  INTEGER NOT NULL DEFAULT 3,
+  forgotten   INTEGER NOT NULL DEFAULT 0,
+  archived    INTEGER NOT NULL DEFAULT 0,
+  source      TEXT,
+  created_at  TEXT NOT NULL,
+  updated_at  TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_memories_type ON memories(type);
+CREATE INDEX IF NOT EXISTS idx_memories_importance ON memories(importance);
+`;
+
+const TYPES = new Set(["preference", "project", "decision", "history", "summary"]);
+
+// Pure helpers: no shared module state.
+
+function sanitizePage(limit, offset, defaultLimit) {
+  const lim = Number.isInteger(limit) && limit > 0 ? limit : defaultLimit;
+  const off = Number.isInteger(offset) && offset > 0 ? offset : 0;
+  return { limit: lim, offset: off };
+}
+
+function escapeLike(q) {
+  return q.replace(/[\\%_]/g, (c) => `\\${c}`);
+}
+
+function parseTags(raw) {
+  try {
+    const arr = JSON.parse(raw);
+    return Array.isArray(arr) ? arr : [];
+  } catch {
+    return [];
+  }
+}
+
+function toRow(row) {
+  if (!row) return undefined;
+  return {
+    id: row.id,
+    type: row.type,
+    title: row.title,
+    content: row.content,
+    tags: parseTags(row.tags),
+    importance: row.importance,
+    forgotten: row.forgotten === 1,
+    archived: row.archived === 1,
+    source: row.source ?? undefined,
+    created_at: row.created_at,
+    updated_at: row.updated_at
+  };
+}
+
+export function createStore(path) {
+  const db = new DatabaseSync(path);
+  db.exec("PRAGMA journal_mode = WAL;");
+  db.exec(SCHEMA);
+
+  // Schema migration: add archived column to legacy databases (idempotent)
+  const columns = db.prepare("PRAGMA table_info(memories)").all().map((c) => c.name);
+  if (!columns.includes("archived")) {
+    db.exec("ALTER TABLE memories ADD COLUMN archived INTEGER NOT NULL DEFAULT 0");
+  }
+
+  // Per-instance monotonic timestamp guard: consecutive writes within the same
+  // millisecond must still produce strictly increasing timestamps (test asserts
+  // updated_at != created_at). State lives in the store closure, not module scope.
+  let lastTs = "";
+  function nowIso() {
+    let ts = new Date().toISOString();
+    if (lastTs && ts <= lastTs) {
+      const d = new Date(lastTs);
+      d.setMilliseconds(d.getMilliseconds() + 1);
+      ts = d.toISOString();
+    }
+    lastTs = ts;
+    return ts;
+  }
+
+  function count(type, { includeForgotten = false, includeArchived = false } = {}) {
+    const clauses = [];
+    const params = [];
+    if (type !== undefined) {
+      clauses.push("type = ?");
+      params.push(type);
+    }
+    if (!includeForgotten) {
+      clauses.push("forgotten = 0");
+    }
+    if (!includeArchived) {
+      clauses.push("archived = 0");
+    }
+    const where = clauses.length ? `WHERE ${clauses.join(" AND ")}` : "";
+    return db.prepare(`SELECT count(*) AS c FROM memories ${where}`).get(...params).c;
+  }
+
+  function getById(id) {
+    const row = db.prepare("SELECT * FROM memories WHERE id = ?").get(id);
+    return toRow(row);
+  }
+
+  function save(memory) {
+    const id = memory.id ?? randomUUID();
+    const type = memory.type;
+    if (!TYPES.has(type)) throw new Error(`invalid memory type: ${type}`);
+    if (memory.tags !== undefined && !Array.isArray(memory.tags)) {
+      throw new Error("tags must be an array");
+    }
+    const now = nowIso();
+    const tags = JSON.stringify(memory.tags ?? []);
+    const importance = Number.isInteger(memory.importance) ? memory.importance : 3;
+    db.prepare(
+      `INSERT INTO memories (id, type, title, content, tags, importance, forgotten, source, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, 0, ?, ?, ?)`
+    ).run(id, type, memory.title, memory.content, tags, importance, memory.source ?? null, now, now);
+    return getById(id);
+  }
+
+  function update(id, patch) {
+    const existing = getById(id);
+    if (!existing) throw new Error(`memory not found: ${id}`);
+    const type = patch.type ?? existing.type;
+    if (!TYPES.has(type)) throw new Error(`invalid memory type: ${type}`);
+    if (patch.tags !== undefined && !Array.isArray(patch.tags)) {
+      throw new Error("tags must be an array");
+    }
+    const now = nowIso();
+    db.prepare(
+      `UPDATE memories SET type=?, title=?, content=?, tags=?, importance=?, source=?, updated_at=? WHERE id=?`
+    ).run(
+      type,
+      patch.title ?? existing.title,
+      patch.content ?? existing.content,
+      JSON.stringify(patch.tags ?? existing.tags),
+      Number.isInteger(patch.importance) ? patch.importance : existing.importance,
+      patch.source !== undefined ? patch.source : (existing.source ?? null),
+      now,
+      id
+    );
+    return getById(id);
+  }
+
+  function remove(id) {
+    db.prepare("DELETE FROM memories WHERE id = ?").run(id);
+  }
+
+  function setForget(id, forgotten) {
+    db.prepare("UPDATE memories SET forgotten = ?, updated_at = ? WHERE id = ?")
+      .run(forgotten === true || forgotten === 1 ? 1 : 0, nowIso(), id);
+    return getById(id);
+  }
+
+  function setArchived(id, archived) {
+    db.prepare("UPDATE memories SET archived = ?, updated_at = ? WHERE id = ?")
+      .run(archived ? 1 : 0, nowIso(), id);
+    return getById(id);
+  }
+
+  function list({ type, limit = 50, offset = 0, includeForgotten = false, includeArchived = false } = {}) {
+    const clauses = [];
+    const params = [];
+    if (type) {
+      clauses.push("type = ?");
+      params.push(type);
+    }
+    if (!includeForgotten) {
+      clauses.push("forgotten = 0");
+    }
+    if (!includeArchived) {
+      clauses.push("archived = 0");
+    }
+    const { limit: lim, offset: off } = sanitizePage(limit, offset, 50);
+    const where = clauses.length ? `WHERE ${clauses.join(" AND ")}` : "";
+    const rows = db.prepare(
+      `SELECT * FROM memories ${where} ORDER BY importance DESC, updated_at DESC, id LIMIT ? OFFSET ?`
+    ).all(...params, lim, off);
+    return rows.map(toRow);
+  }
+
+  function all() {
+    const rows = db.prepare("SELECT * FROM memories ORDER BY updated_at DESC").all();
+    return rows.map(toRow);
+  }
+
+  function search(query, { limit = 20, includeArchived = false } = {}) {
+    const q = String(query).trim();
+    if (!q) return [];
+    // FTS5 over unicode61 (English + long phrases); LIKE fallback covers CJK substring.
+    // LIKE wildcards in the query are escaped so user input is matched literally.
+    const like = `%${escapeLike(q)}%`;
+    const { limit: lim } = sanitizePage(limit, 0, 20);
+    const archivedFilter = includeArchived ? "" : "archived = 0 AND ";
+    const rows = db.prepare(
+      `SELECT * FROM memories
+       WHERE ${archivedFilter}forgotten = 0 AND (title LIKE ? ESCAPE '\\' OR content LIKE ? ESCAPE '\\' OR tags LIKE ? ESCAPE '\\')
+       ORDER BY
+         CASE WHEN title LIKE ? ESCAPE '\\' THEN 0 ELSE 1 END,
+         importance DESC,
+         updated_at DESC,
+         id
+       LIMIT ?`
+    ).all(like, like, like, like, lim);
+    return rows.map(toRow);
+  }
+
+  return {
+    db,
+    count,
+    getById,
+    save,
+    update,
+    remove,
+    setForget,
+    setArchived,
+    list,
+    all,
+    search,
+    close() {
+      db.close();
+    }
+  };
+}

package/src/summarize.js

@@ -0,0 +1,171 @@
+import { BlockAssembler, createUserMessage } from "@deepseek-ai/dsh-llm";
+
+const SUMMARY_PROMPT = `你是记忆库提炼助手。根据下面的会话内容，提炼 2-3 条值得跨会话记住的记忆。
+只输出 JSON 数组，每项形如 {"type":"preference|project|decision|history","title":"简短标题","content":"一句话内容","importance":1-5}。
+不要输出任何其他文字。`;
+
+/** Extract a JSON array from LLM output that may contain prose around it. */
+export function parseSummaryJson(raw) {
+  const text = String(raw ?? "");
+  const start = text.indexOf("[");
+  const end = text.lastIndexOf("]");
+  if (start === -1 || end === -1 || end <= start) return [];
+  let arr;
+  try {
+    arr = JSON.parse(text.slice(start, end + 1));
+  } catch {
+    return [];
+  }
+  if (!Array.isArray(arr)) return [];
+  const VALID = new Set(["preference", "project", "decision", "history"]);
+  return arr.filter(
+    (item) =>
+      item &&
+      typeof item === "object" &&
+      VALID.has(item.type) &&
+      typeof item.title === "string" &&
+      item.title.trim() &&
+      typeof item.content === "string" &&
+      item.content.trim()
+  ).map((item) => ({
+    type: item.type,
+    title: item.title.trim(),
+    content: item.content.trim(),
+    importance: Number.isInteger(item.importance) ? Math.min(5, Math.max(1, item.importance)) : 3
+  }));
+}
+
+// The dsh-llm StreamChunk protocol BlockAssembler.push() consumes:
+// block-start {index, blockType}, text-delta {index, text},
+// block-end {index, block}, finish {reason}. Some consumers observe a
+// looser shape ({block} / {delta} / {kind}); normalize before pushing so
+// both real adapter streams and shape-tolerant test doubles assemble.
+const STREAM_CHUNK_TYPES = new Set([
+  "block-start",
+  "text-delta",
+  "reasoning-delta",
+  "tool-call-delta",
+  "block-end",
+  "usage",
+  "finish"
+]);
+
+function toProtocolChunk(chunk) {
+  switch (chunk.type) {
+    case "block-start":
+      return { type: "block-start", index: chunk.index ?? 0, blockType: chunk.blockType ?? chunk.block?.type ?? "text" };
+    case "text-delta":
+      return { type: "text-delta", index: chunk.index ?? 0, text: chunk.text ?? chunk.delta ?? "" };
+    case "reasoning-delta":
+      return { type: "reasoning-delta", index: chunk.index ?? 0, text: chunk.text ?? chunk.delta ?? "" };
+    case "block-end":
+      return { type: "block-end", index: chunk.index ?? 0, block: chunk.block ?? { type: "text" } };
+    case "finish":
+      return {
+        type: "finish",
+        reason: chunk.reason ?? { kind: chunk.kind === "error" ? "error" : "stop" },
+        replayState: chunk.replayState
+      };
+    default:
+      return chunk;
+  }
+}
+
+// Only direct human prompts are summarized: plugin-injected context
+// (AGENTS.md, skill bodies, file-change notices) and other machine-originated
+// events must not leak into the memory store. Events without a data payload
+// (minimal test doubles) pass the kind check and are handled by the content
+// check below.
+function collectMessages(session) {
+  const messages = [];
+  for (const event of session.events ?? []) {
+    const kind = event.data?.source?.kind;
+    if (event.type !== "user/message") continue;
+    if (kind !== undefined && kind !== "user") continue;
+    if (!event.data?.content?.length) continue; // nothing to summarize
+    messages.push(createUserMessage({ content: event.data.content }));
+  }
+  return messages.slice(-20);
+}
+
+export function createSummarizer(ctx, service, config) {
+  if (!config.autoSummarize) return { dispose: () => {} };
+
+  const inFlight = new Map();
+  let disposed = false;
+
+  async function summarize(session) {
+    if (disposed || inFlight.has(session.id)) return;
+    const controller = new AbortController();
+    inFlight.set(session.id, controller);
+    try {
+      const header = session.requestHeader?.()?.config;
+      const route = header?.provider && header?.model
+        ? { provider: header.provider, model: header.model }
+        : undefined;
+      if (!route) return;
+      const messages = collectMessages(session);
+      if (!messages.length) return;
+
+      const assembler = new BlockAssembler();
+      let text = "";
+      const options = {
+        provider: route.provider,
+        model: route.model,
+        purpose: "summarization",
+        messages: [
+          { role: "system", content: [{ type: "text", text: SUMMARY_PROMPT }] },
+          ...messages
+        ],
+        signal: controller.signal
+      };
+      for await (const chunk of ctx.llm.stream(options)) {
+        if (STREAM_CHUNK_TYPES.has(chunk.type)) assembler.push(toProtocolChunk(chunk));
+        if (chunk.type === "text-delta") {
+          text += chunk.text ?? chunk.delta ?? "";
+        }
+        if (chunk.type === "finish") {
+          const reasonKind = chunk.reason?.kind ?? chunk.kind;
+          if (reasonKind === "error" || reasonKind === "aborted") return;
+        }
+      }
+      // Direct delta accumulation is the primary extraction path (it works
+      // for real protocol chunks {index,text} and looser {delta} shapes
+      // alike); the assembler blocks are a fallback for streams that only
+      // deliver text inside block-end. This dsh-llm exposes no public
+      // no-arg assemble() — blocks() is the message-level API.
+      const blocks = assembler.blocks();
+      const assembledText = blocks
+        .filter((b) => b.type === "text")
+        .map((b) => b.text ?? "")
+        .join("");
+      const entries = parseSummaryJson(text || assembledText);
+      for (const entry of entries) {
+        service.saveWithDedupe({ ...entry, source: `session:${session.id}` });
+      }
+    } finally {
+      inFlight.delete(session.id);
+    }
+  }
+
+  const unsubscribe = ctx.on("session/event", (session, event) => {
+    if (disposed || event.type !== "turn/end") return;
+    // Return the summarization promise so awaiters observe the writes; the
+    // catch keeps listener dispatch from rejecting. Dispose-initiated aborts
+    // and external AbortErrors are silent.
+    return summarize(session).catch((error) => {
+      if (disposed || error?.name === "AbortError") return;
+      ctx.logger?.warn?.(`dsh-mneme: summarization failed: ${String(error)}`);
+    });
+  });
+
+  return {
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      unsubscribe?.();
+      for (const controller of inFlight.values()) controller.abort();
+      inFlight.clear();
+    }
+  };
+}