@modusensus/dsh-mneme 0.1.0

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

package/lib/tools.js

@@ -0,0 +1,221 @@
+import { defineTool } from "@deepseek-ai/dsh-tools";
+
+const TEXT_OUTPUT = (text) => [{ type: "text", text }];
+
+// Wire shape emitted by service.toApiList: shared by memory_search and
+// memory_list so their output schemas always declare every key the runtime
+// value carries (additionalProperties: false would reject undeclared keys).
+const MEMORY_ITEM_SCHEMA = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    id: { type: "string", required: true },
+    type: { type: "string", required: true },
+    title: { type: "string", required: true },
+    content: { type: "string", required: true },
+    tags: { type: "array", items: { type: "string" } },
+    importance: { type: "integer", required: true },
+    source: { type: "string" },
+    created_at: { type: "string", required: true },
+    updated_at: { type: "string", required: true }
+  }
+};
+
+export function createTools(ctx, service, config) {
+  const tools = [
+    defineTool({
+      name: "memory_save",
+      description:
+        "Persist one memory entry for future sessions (user preferences, project state, decisions). " +
+        "Call this when the user states a durable preference, a project decision is made, or a lesson is learned. " +
+        "Merges into an existing entry of the same type when the title matches.",
+      parameters: {
+        type: { type: "string", required: true, enum: ["preference", "project", "decision", "history"], description: "preference=user profile; project=project knowledge/state; decision=key decision; history=conversation summary" },
+        title: { type: "string", required: true, description: "Short unique title" },
+        content: { type: "string", required: true, description: "Memory body" },
+        tags: { type: "array", items: { type: "string" }, description: "Optional tags" },
+        importance: { type: "integer", description: "1-5; >= threshold auto-injects into future sessions" },
+        source: { type: "string", description: "Optional provenance" }
+      },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            action: { type: "string", required: true, enum: ["created", "merged"] },
+            id: { type: "string", required: true }
+          }
+        },
+        render: (_args, value) => TEXT_OUTPUT(`memory ${value.action}: ${value.id}`)
+      },
+      async execute(args) {
+        const { action, memory } = service.saveWithDedupe({
+          type: args.type,
+          title: args.title,
+          content: args.content,
+          tags: args.tags ?? [],
+          importance: args.importance ?? 3,
+          source: args.source ?? "tool"
+        });
+        return { action, id: memory.id };
+      }
+    }),
+
+    defineTool({
+      name: "memory_search",
+      description: "Full-text search the cross-session memory store. Use when you need past context: how a problem was solved, user preferences, project decisions. Returns matching entries with source and timestamps.",
+      parameters: {
+        query: { type: "string", required: true, description: "Search text; substring match over title/content/tags" },
+        limit: { type: "integer", description: "Max results (default 20)" }
+      },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            items: {
+              type: "array", required: true,
+              items: MEMORY_ITEM_SCHEMA
+            }
+          }
+        },
+        render: (_args, value) => TEXT_OUTPUT(`Found ${value.items.length} memory entr${value.items.length === 1 ? "y" : "ies"}.`)
+      },
+      async execute(args) {
+        const rows = service.toApiList(service.search(args.query, { limit: args.limit ?? 20 }));
+        return { items: rows };
+      }
+    }),
+
+    defineTool({
+      name: "memory_list",
+      description: "List memory entries by type, high-importance first, then newest, paginated.",
+      parameters: {
+        type: { type: "string", enum: ["preference", "project", "decision", "history"], description: "Filter by type; omit for all" },
+        limit: { type: "integer", description: "Page size (default 50)" },
+        offset: { type: "integer", description: "Page offset (default 0)" }
+      },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            items: {
+              type: "array", required: true,
+              items: MEMORY_ITEM_SCHEMA
+            },
+            total: { type: "integer", required: true }
+          }
+        },
+        render: (_args, value) => TEXT_OUTPUT(`${value.items.length} memory entries (of ${value.total}).`)
+      },
+      async execute(args) {
+        const rows = service.toApiList(service.list({ type: args.type, limit: args.limit ?? 50, offset: args.offset ?? 0 }));
+        return { items: rows, total: service.count(args.type) };
+      }
+    }),
+
+    defineTool({
+      name: "memory_update",
+      description: "Modify an existing memory entry (title, content, type, tags, importance).",
+      parameters: {
+        id: { type: "string", required: true, description: "Memory id" },
+        title: { type: "string" },
+        content: { type: "string" },
+        type: { type: "string", enum: ["preference", "project", "decision", "history"] },
+        tags: { type: "array", items: { type: "string" } },
+        importance: { type: "integer", description: "1-5" }
+      },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            memory: {
+              type: "object",
+              additionalProperties: false,
+              properties: {
+                id: { type: "string", required: true },
+                title: { type: "string", required: true },
+                content: { type: "string", required: true }
+              }
+            }
+          }
+        },
+        render: (_args, value) => TEXT_OUTPUT(`Updated memory ${value.memory.id}: ${value.memory.title}`)
+      },
+      async execute(args) {
+        const memory = service.update(args.id, {
+          title: args.title,
+          content: args.content,
+          type: args.type,
+          tags: args.tags,
+          importance: args.importance
+        });
+        return { memory: { id: memory.id, title: memory.title, content: memory.content } };
+      }
+    }),
+
+    defineTool({
+      name: "memory_delete",
+      description: "Permanently delete a memory entry.",
+      parameters: {
+        id: { type: "string", required: true }
+      },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: { deleted: { type: "boolean", required: true } }
+        },
+        render: (_args, value) => TEXT_OUTPUT(value.deleted ? "Memory deleted." : "Memory not found.")
+      },
+      async execute(args) {
+        const existed = service.getById(args.id) !== undefined;
+        if (existed) service.remove(args.id);
+        return { deleted: existed };
+      }
+    }),
+
+    defineTool({
+      name: "memory_forget",
+      description:
+        "Stop a memory from being auto-injected and from appearing in searches and lists without deleting it. " +
+        "The entry stays in storage; pass forgotten: false to restore it.",
+      parameters: {
+        id: { type: "string", required: true },
+        forgotten: { type: "boolean", description: "Suppress (true, default) or restore (false) the entry's visibility" }
+      },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            memory: {
+              type: "object",
+              additionalProperties: false,
+              properties: {
+                id: { type: "string", required: true },
+                forgotten: { type: "boolean", required: true }
+              }
+            }
+          }
+        },
+        render: (_args, value) => TEXT_OUTPUT(`Memory ${value.memory.id} injection ${value.memory.forgotten ? "suppressed" : "restored"}.`)
+      },
+      async execute(args) {
+        if (service.getById(args.id) === undefined) {
+          throw new Error("memory not found");
+        }
+        const memory = service.setForget(args.id, args.forgotten ?? true);
+        return { memory: { id: memory.id, forgotten: memory.forgotten } };
+      }
+    })
+  ];
+
+  for (const tool of tools) {
+    ctx.tools.register(tool);
+  }
+
+  return tools;
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@modusensus/dsh-mneme",
+  "description": "Cross-session memory plugin for DeepSeek Harness with autoDream consolidation: SQLite+FTS5 store, Markdown mirrors, 6 model tools, automatic injection, session summarization, and a Web GUI panel",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": {
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "default": "./lib/client.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": ["lib", "src"],
+  "dsh": {
+    "client": {
+      "inject": ["slots", "locale", "layout", "connection"],
+      "platform": "web"
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.0-rc.6",
+    "@deepseek-ai/schemastery": "^3.18.1"
+  }
+}