@modusensus/dsh-mneme 0.6.0 → 0.6.5

package/lib/store.js

@@ -1,5 +1,6 @@
 import { DatabaseSync } from "node:sqlite";
 import { randomUUID } from "node:crypto";
+import { sanitizeTags } from "./parser/tag.js";
 
 const SCHEMA = `
 CREATE TABLE IF NOT EXISTS memories (
@@ -552,6 +553,17 @@ export function createStore(path) {
   db.exec("PRAGMA journal_mode = WAL;");
   db.exec(SCHEMA);
 
+  // Wiki-link dedup (v0.6.1): a (from_entity, to_entity) pair is unique only for
+  // relation_type='links_to'. This is a PARTIAL index scoped to links_to, so the
+  // append-only semantics of all other relation types (uses/depends_on/part_of/
+  // related_to/supersedes — the extractor and autoDream write these per-run
+  // without global dedup, and supersedes rows carry distinct metadata like
+  // attr_key/old_value) are preserved. Idempotent (IF NOT EXISTS), atomic, and
+  // race-safe. Legacy DBs have no links_to rows yet, so the index builds cleanly
+  // everywhere and never breaks plugin startup (a full-table UNIQUE index would
+  // fail on legacy duplicates).
+  db.exec("CREATE UNIQUE INDEX IF NOT EXISTS idx_relations_wikilink ON entity_relations(from_entity, to_entity, relation_type) WHERE relation_type = 'links_to'");
+
   // Schema migrations for legacy databases (idempotent). Each ADD COLUMN is
   // also race-safe: two concurrently-opening processes can both pass the
   // PRAGMA table_info check before either ALTERs, so the ALTER itself is
@@ -652,6 +664,19 @@ export function createStore(path) {
     return toRow(row);
   }
 
+  /**
+   * Case-insensitive exact title lookup (v0.6.1 wiki-link). COLLATE NOCASE
+   * folds ASCII case (CJK titles are inherently case-free, so they match
+   * verbatim). Returns the first matching memory or undefined. Best-effort —
+   * used by wiki-link target resolution and the read APIs.
+   */
+  function findByTitle(title) {
+    if (typeof title !== "string" || !title.trim()) return undefined;
+    return toRow(db.prepare(
+      "SELECT * FROM memories WHERE title = ? COLLATE NOCASE LIMIT 1"
+    ).get(title.trim()));
+  }
+
   function save(memory) {
     const id = memory.id ?? randomUUID();
     const type = memory.type;
@@ -1660,9 +1685,168 @@ export function createStore(path) {
     return memories;
   }
 
+  // --- tag storage (v0.6.2) ------------------------------------------------
+  // Tags ride the snapshot-style entity_attrs table (attr_key='tags'), so one
+  // memory has exactly one live tags row; setMemoryTags invalidates any prior
+  // live row and inserts a fresh one (idempotent overwrite). entity_id is the
+  // memory id itself (the memory is its own tag entity), memory_id is kept so
+  // the existing memory-scoped attr queries (getAttrsByMemory / findMemoriesByAttr)
+  // and the bulk tag map all work without a special path.
+
+  /** Normalize an arbitrary tags input to a deduplicated string array.
+   *  Delegates to parser/tag.js sanitizeTags (shared validation with parseTags
+   *  and the autoDream tag-extractor): strips a leading `#`, trims, drops
+   *  non-strings/blanks/over-long/illegal-char tags. Kept as a thin alias so
+   *  the tag write path validates identically to the parser path. */
+  function normalizeTags(tags) {
+    return sanitizeTags(tags);
+  }
+
+  /**
+   * Set (overwrite) the live tag set for a memory. Exactly one tags row stays
+   * live per memory: any prior live row is invalidated first, then one fresh
+   * row is written (no-op when tags is empty — the invalidated row is removed
+   * so "clear tags" = no live row). Returns the stored tag array.
+   */
+  function setMemoryTags(memoryId, tags) {
+    const arr = normalizeTags(tags);
+    const now = nowIso();
+    // Atomic: the invalidation and the fresh row must land together, so a
+    // mid-write crash never leaves the old live row gone without a replacement.
+    // SAVEPOINT (not BEGIN) so this nests safely inside service.transaction().
+    db.exec("SAVEPOINT set_memory_tags");
+    try {
+      db.prepare(
+        `UPDATE entity_attrs SET valid_until = ?
+         WHERE attr_key = 'tags' AND memory_id = ? AND valid_until IS NULL`
+      ).run(now, memoryId);
+      if (arr.length) {
+        const id = randomUUID();
+        db.prepare(
+          `INSERT INTO entity_attrs (id, entity_id, attr_key, attr_value, memory_id, valid_from, valid_until, confidence, source)
+           VALUES (?, ?, 'tags', ?, ?, ?, NULL, 1.0, 'manual')`
+        ).run(id, memoryId, JSON.stringify(arr), memoryId, now);
+      }
+      db.exec("RELEASE set_memory_tags");
+    } catch (e) {
+      db.exec("ROLLBACK TO set_memory_tags");
+      db.exec("RELEASE set_memory_tags");
+      throw e;
+    }
+    return arr;
+  }
+
+  /** Live tags for a memory ([] when none / unknown). */
+  function getMemoryTags(memoryId) {
+    const row = db.prepare(
+      `SELECT attr_value FROM entity_attrs
+       WHERE attr_key = 'tags' AND memory_id = ? AND valid_until IS NULL
+       ORDER BY valid_from DESC LIMIT 1`
+    ).get(memoryId);
+    if (!row) return [];
+    try {
+      const arr = JSON.parse(row.attr_value);
+      return Array.isArray(arr) ? arr : [];
+    } catch {
+      return [];
+    }
+  }
+
+  /** Bulk live-tags lookup for mirror rendering. Returns Map<memoryId, string[]>. */
+  function getMemoryTagsMap(ids) {
+    const out = new Map();
+    const list = (Array.isArray(ids) ? ids : []).filter(Boolean);
+    for (let i = 0; i < list.length; i += 100) {
+      const chunk = list.slice(i, i + 100);
+      const rows = db.prepare(
+        `SELECT memory_id, attr_value FROM entity_attrs
+         WHERE attr_key = 'tags' AND valid_until IS NULL
+           AND memory_id IN (${chunk.map(() => "?").join(",")})`
+      ).all(...chunk);
+      for (const row of rows) {
+        try {
+          const arr = JSON.parse(row.attr_value);
+          if (Array.isArray(arr) && arr.length) out.set(row.memory_id, arr);
+        } catch { /* corrupt row: skip */ }
+      }
+    }
+    return out;
+  }
+
+  /**
+   * Memories carrying a live tags row that contains EVERY requested tag
+   * (AND semantics for a multi-tag query). attr_value is a JSON array, so the
+   * match uses quoted `"tag"` substrings — `tag:lin` never collides with
+   * `linux` because JSON array elements are quote-delimited. Only live rows
+   * (valid_until IS NULL) with a memory reference participate; each memory
+   * appears once.
+   */
+  function findMemoriesByTags(tags) {
+    const list = normalizeTags(tags);
+    if (!list.length) return [];
+    const where = list.map(() => `attr_value LIKE ? ESCAPE '\\'`).join(" AND ");
+    const params = list.map((t) => `%"${escapeLike(t)}"%`);
+    const rows = db.prepare(
+      `SELECT DISTINCT memory_id FROM entity_attrs
+       WHERE attr_key = 'tags' AND valid_until IS NULL
+         AND memory_id IS NOT NULL AND memory_id != ''
+         AND (${where})`
+    ).all(...params);
+    // Same live-memory filter as getDirectory/store.search: forgotten/archived/
+    // session-disposed memories are invisible to `tag:` recall.
+    const stmt = db.prepare(
+      "SELECT * FROM memories WHERE id = ? AND forgotten = 0 AND archived = 0 AND session_disposed_at IS NULL"
+    );
+    const memories = [];
+    for (const { memory_id } of rows) {
+      const row = stmt.get(memory_id);
+      if (row) memories.push(toRow(row));
+    }
+    return memories;
+  }
+
+  /**
+   * Directory view (v0.6.3): group live memories by their entity_attrs-backed
+   * tag set. A memory carrying N tags appears under all N tag folders; a memory
+   * with no live tags lands in `untagged`. Only live rows participate —
+   * forgotten, archived and session-disposed memories are excluded. Groups are
+   * ordered by tag (locale-aware), group members and untagged follow the
+   * canonical memory order (importance DESC, updated_at DESC, id).
+   * @returns {{groups: {tag: string, memories: object[]}[], untagged: object[]}}
+   */
+  function getDirectory() {
+    const rows = db.prepare(
+      `SELECT * FROM memories
+       WHERE forgotten = 0 AND archived = 0 AND session_disposed_at IS NULL
+       ORDER BY importance DESC, updated_at DESC, id`
+    ).all();
+    const memories = rows.map(toRow);
+    const tagMap = getMemoryTagsMap(memories.map((m) => m.id));
+    const byTag = new Map(); // tag -> memory[]
+    const untagged = [];
+    for (const m of memories) {
+      const tags = tagMap.get(m.id);
+      if (!tags || tags.length === 0) {
+        untagged.push(m);
+        continue;
+      }
+      for (const tag of tags) {
+        if (!byTag.has(tag)) byTag.set(tag, []);
+        byTag.get(tag).push(m);
+      }
+    }
+    const groups = [...byTag.entries()]
+      .sort((a, b) => a[0].localeCompare(b[0]))
+      .map(([tag, ms]) => ({ tag, memories: ms }));
+    return { groups, untagged };
+  }
+
   /**
    * Record a typed relation between two entities. metadata (optional) is a
-   * free-form JSON blob describing the relation. Relations are append-only.
+   * free-form JSON blob describing the relation. Relations are append-only —
+   * callers that need idempotency (e.g. wiki-links, via saveWikiLinks) guard
+   * with their own existence check plus the partial links_to unique index
+   * (idx_relations_wikilink) as a race backstop.
    */
   function saveRelation({ from_entity, to_entity, relation_type, memory_id, metadata }) {
     const id = randomUUID();
@@ -1676,7 +1860,56 @@ export function createStore(path) {
       `INSERT INTO entity_relations (id, from_entity, to_entity, relation_type, memory_id, created_at, metadata)
        VALUES (?, ?, ?, ?, ?, ?, ?)`
     ).run(id, from_entity, to_entity, relation_type, memory_id ?? null, now, metaStr);
-    return toRelation(db.prepare("SELECT * FROM entity_relations WHERE id = ?").get(id));
+    return toRelation(db.prepare(
+      "SELECT * FROM entity_relations WHERE from_entity = ? AND to_entity = ? AND relation_type = ? LIMIT 1"
+    ).get(from_entity, to_entity, relation_type));
+  }
+
+  /**
+   * Record wiki-link relations (v0.6.1). For each target title, resolve the
+   * target memory (case-insensitive title match via findByTitle) and write a
+   * links_to relation:
+   *   from_entity = source memory title, to_entity = canonical target memory
+   *   title, relation_type = 'links_to', memory_id = source memory id.
+   * Using the canonical resolved title keeps the graph case-consistent
+   * ([[beta]] and [[Beta]] collapse onto the same to_entity), so backlink
+   * lookups never fight the way a target was typed.
+   * Fail-safe: a target with no matching memory is skipped (never an error).
+   * Idempotent: an already-existing triple is a silent no-op (existence check
+   * here + the idx_relations_wikilink partial unique index as a race backstop),
+   * so `saved` only counts newly written relations. Returns { saved, skipped }.
+   */
+  function saveWikiLinks({ memoryId, title, targets }) {
+    const saved = [];
+    const skipped = [];
+    const seen = new Set(); // canonical (lowercased) targets already handled
+    const existsStmt = db.prepare(
+      "SELECT id FROM entity_relations WHERE from_entity = ? AND to_entity = ? AND relation_type = ?"
+    );
+    const list = Array.isArray(targets)
+      ? targets.filter((t) => typeof t === "string" && t.trim())
+      : [];
+    for (const raw of list) {
+      const target = raw.trim();
+      const key = target.toLowerCase();
+      if (seen.has(key)) continue; // dedupe within a single call (case-insensitive)
+      seen.add(key);
+      const targetMem = findByTitle(target);
+      if (!targetMem) {
+        skipped.push(target); // 目标不存在 → 跳过（Fail-safe）
+        continue;
+      }
+      const toEntity = targetMem.title;
+      if (existsStmt.get(title, toEntity, "links_to")) continue; // already linked → no-op
+      saved.push(saveRelation({
+        from_entity: title,
+        to_entity: toEntity,
+        relation_type: "links_to",
+        memory_id: memoryId,
+        metadata: { target_memory_id: targetMem.id }
+      }));
+    }
+    return { saved, skipped };
   }
 
   /**
@@ -1979,7 +2212,14 @@ export function createStore(path) {
     getAttrHistory,
     getAttrsByMemory,
     findMemoriesByAttr,
+    setMemoryTags,
+    getMemoryTags,
+    getMemoryTagsMap,
+    findMemoriesByTags,
+    getDirectory,
     saveRelation,
+    saveWikiLinks,
+    findByTitle,
     migrateAttrsToMemory,
     getRelations,
     setMirrorState,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@modusensus/dsh-mneme",
   "description": "Cross-session memory plugin for DeepSeek Harness with autoDream consolidation: SQLite store, Markdown mirrors, 7 model tools, automatic injection, session summarization, user profile/rules, custom slash commands, vector (semantic) search, and a Web GUI panel",
-  "version": "0.6.0",
+  "version": "0.6.5",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/api.js

@@ -422,6 +422,107 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
     }
   });
 
+  // --- wiki-link back links (v0.6.1) --------------------------------------
+  // Read-only like the graph endpoints, so it stays open when apiToken is set.
+  // GET /api/dsh-mneme/wikilinks/backlinks?id=<memoryId> → memories whose
+  // content carries a [[wiki-link]] resolving to the given memory.
+  register({
+    kind: "exact",
+    path: "/api/dsh-mneme/wikilinks/backlinks",
+    handler(req, res) {
+      try {
+        const url = new URL(req.url, "http://localhost");
+        const id = (url.searchParams.get("id") ?? "").trim();
+        if (!id) {
+          sendJson(res, 400, { error: "missing-id" });
+          return;
+        }
+        const memory = service.getById?.(id) ?? null;
+        const backlinks = (service.getBacklinks?.(id) ?? []).map(({ source, relation }) => ({
+          id: source.id,
+          title: source.title,
+          type: source.type,
+          created_at: relation.created_at
+        }));
+        sendJson(res, 200, {
+          memoryId: id,
+          memory: memory ? { id: memory.id, title: memory.title, type: memory.type } : null,
+          backlinks
+        });
+      } catch {
+        sendJson(res, 500, { error: "internal" });
+      }
+    }
+  });
+
+  // --- wiki-link forward links (v0.6.1) -----------------------------------
+  // GET /api/dsh-mneme/wikilinks/forward?id=<memoryId> → memories the given
+  // memory explicitly links to. Unresolved target titles surface with id:null.
+  register({
+    kind: "exact",
+    path: "/api/dsh-mneme/wikilinks/forward",
+    handler(req, res) {
+      try {
+        const url = new URL(req.url, "http://localhost");
+        const id = (url.searchParams.get("id") ?? "").trim();
+        if (!id) {
+          sendJson(res, 400, { error: "missing-id" });
+          return;
+        }
+        const memory = service.getById?.(id) ?? null;
+        const links = (service.getForwardLinks?.(id) ?? []).map(({ target, relation }) => ({
+          id: target?.id ?? null,
+          title: target?.title ?? relation.to_entity,
+          type: target?.type ?? null,
+          created_at: relation.created_at
+        }));
+        sendJson(res, 200, {
+          memoryId: id,
+          memory: memory ? { id: memory.id, title: memory.title, type: memory.type } : null,
+          links
+        });
+      } catch {
+        sendJson(res, 500, { error: "internal" });
+      }
+    }
+  });
+
+  // --- wiki-link resolve (v0.6.1) -----------------------------------------
+  // GET /api/dsh-mneme/wikilinks/resolve?title=<title> → case-insensitive exact
+  // title match against the memories table (the resolution used when writing
+  // links_to relations). 404 when no memory matches.
+  register({
+    kind: "exact",
+    path: "/api/dsh-mneme/wikilinks/resolve",
+    handler(req, res) {
+      try {
+        const url = new URL(req.url, "http://localhost");
+        const title = (url.searchParams.get("title") ?? "").trim();
+        if (!title) {
+          sendJson(res, 400, { error: "missing-title" });
+          return;
+        }
+        const memory = service.resolveWikiLink?.(title) ?? null;
+        if (!memory) {
+          sendJson(res, 404, { error: "memory-not-found", title });
+          return;
+        }
+        // Note: no `source` field — it may carry file paths/internal host info
+        // and this endpoint is read-only without auth when apiToken is set.
+        sendJson(res, 200, {
+          title,
+          memory: {
+            id: memory.id,
+            title: memory.title,
+            type: memory.type
+          }
+        });
+      } catch {
+        sendJson(res, 500, { error: "internal" });
+      }
+    }
+  });
+
   // --- health: mirror sync state (F-NEW-03 / v0.3.6) ---
   // Auth-gated; only returns a sanitized error code (never raw last_error which
   // may leak paths/token-like strings/internal hosts). On state read failure it
@@ -507,8 +608,84 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
     }
   });
 
+  // --- memory tags (v0.6.2) ------------------------------------------------
+  // GET  /api/dsh-mneme/memory/tags?id=<memoryId> → live entity_attrs-backed
+  //       tag set for one memory plus the manualTagEnabled gate (so the panel
+  //       can hide tag editing when the manual path is off). Read-only, stays
+  //       open when apiToken is set (like list/search/semantic).
+  // POST /api/dsh-mneme/memory/tags { id, tags } → overwrite the live tag set
+  //       via service.setMemoryTags (manualTagEnabled gate); 409 when the gate
+  //       is closed. Auth-gated like the other write endpoints.
+  register({
+    kind: "exact",
+    path: "/api/dsh-mneme/memory/tags",
+    handler(req, res) {
+      try {
+        if (req.method === "POST" || req.method === "PUT") {
+          if (!requireAuth(req, res, apiToken)) return;
+          return readBody(req).then((text) => {
+            const body = parseBody(text);
+            const id = typeof body.id === "string" ? body.id.trim() : "";
+            if (!id) {
+              sendJson(res, 400, { error: "missing-id" });
+              return;
+            }
+            const memory = service.getById?.(id) ?? null;
+            if (!memory) {
+              sendJson(res, 404, { error: "memory-not-found" });
+              return;
+            }
+            const result = service.setMemoryTags(id, Array.isArray(body.tags) ? body.tags : []);
+            if (result?.ok === false) {
+              sendJson(res, 409, { error: result.error || "tags-disabled" });
+              return;
+            }
+            sendJson(res, 200, { ok: true, memoryId: id, tags: result?.tags ?? [] });
+          });
+        }
+        const url = new URL(req.url, "http://localhost");
+        const id = (url.searchParams.get("id") ?? "").trim();
+        if (!id) {
+          sendJson(res, 400, { error: "missing-id" });
+          return;
+        }
+        const memory = service.getById?.(id) ?? null;
+        if (!memory) {
+          sendJson(res, 404, { error: "memory-not-found" });
+          return;
+        }
+        const tags = service.getMemoryTags?.(id) ?? [];
+        sendJson(res, 200, {
+          memoryId: id,
+          tags: Array.isArray(tags) ? tags : [],
+          manualTagEnabled: service.manualTagEnabled?.() ?? true
+        });
+      } catch {
+        sendJson(res, 500, { error: "internal" });
+      }
+    }
+  });
+
+  // --- directory view (v0.6.3) ---------------------------------------------
+  // GET /api/dsh-mneme/directory → memories grouped by tag as
+  // { groups: [{ tag, memories: [...] }], untagged: [...] }. Live-only
+  // (forgotten/archived/session-disposed excluded), groups tag-sorted, members
+  // importance+updated DESC. Read-only, stays open when apiToken is set.
+  register({
+    kind: "exact",
+    path: "/api/dsh-mneme/directory",
+    handler(req, res) {
+      try {
+        const dir = service.getDirectory?.() ?? { groups: [], untagged: [] };
+        sendJson(res, 200, dir);
+      } catch {
+        sendJson(res, 500, { error: "internal" });
+      }
+    }
+  });
+
   return {
-    routes: 11,
+    routes: 19,
     dispose: () => {
       for (const dispose of disposers) dispose();
     }

package/src/config.js

@@ -166,6 +166,33 @@ export const Config = z.object({
   // Prefix/semantic search over entity names (used by recall).
   entitySearchEnabled: z.boolean().default(true),
 
+  // --- wiki-link: explicit cross-memory [[links]] (v0.6.1) ----------------
+  // Opt-in, off by default. When enabled, saveWithDedupe/update fire-and-forget
+  // a wiki-link resolution pass: [[target]] / [[显示|target]] markers in a
+  // memory's content become links_to relations in entity_relations (idempotent,
+  // deduped by the unique relation index). The storage layer + read APIs
+  // (getBacklinks/getForwardLinks/resolveWikiLink) are always available
+  // regardless of this flag.
+  wikiLinkEnabled: z.boolean().default(false),
+
+  // --- tag system (v0.6.2) ---------------------------------------------------
+  // Opt-in: when autoTagEnabled is true, a light LLM pass runs after each
+  // autoDream consolidation and extracts 1-3 tags per retained memory
+  // (autoTagMaxPerRun bounds how many memories are tagged per run). The tag
+  // storage layer (store.setMemoryTags/getMemoryTags + tag: search + mirror
+  // `#tag` line) is always available regardless of this flag.
+  autoTagEnabled: z.boolean().default(false),
+  autoTagMaxPerRun: z.natural().min(1).max(100).default(10),
+  // Manual tagging (service.setMemoryTags / memory tools) is on by default;
+  // set false to disable the manual write path too.
+  manualTagEnabled: z.boolean().default(true),
+
+  // --- tag-weighted re-rank (v0.6.4) -------------------------------------
+  // Opt-in: boost candidates whose tags overlap the query/session tags.
+  tagBoostEnabled: z.boolean().default(false),
+  tagBoostFactor: z.number().min(1).max(2).default(1.15),
+  sessionTagBoostFactor: z.number().min(1).max(2).default(1.08),
+
   // --- sleep mode: idle-triggered deep maintenance (v0.4.0) ---------------
   // Opt-in, off by default. Unlike autoDream (threshold-triggered, lightweight)
   // sleep fires when the store has been quiet for sleepIdleMinutes and deep-

package/src/dream/tag-extractor.js

@@ -0,0 +1,149 @@
+// v0.6.2 auto-tag: a lightweight LLM pass that runs after an autoDream
+// consolidation and extracts 1-3 tags per retained memory. Opt-in via
+// config.autoTagEnabled (default false); autoTagMaxPerRun (default 10) bounds
+// how many memories are tagged per run.
+//
+// Design notes:
+//   - ONE batched LLM call per run (the consolidation route is reused). Each
+//     memory is a prompt line; the model replies with a JSON array of
+//     {"id","tags"} entries — the per-memory contract is `{"tags":[...]}`.
+//   - Fail-safe everywhere: a missing route / aborted stream / unparseable
+//     JSON / unknown id / illegal tag are all skipped, never thrown. Tagging
+//     must never degrade the consolidation run it rides on.
+//   - The actual writes go through service.applyMemoryTags inside a
+//     service.transaction, so the mirror re-renders exactly once per pass and
+//     the write hooks fire once (never per memory).
+import { sanitizeTags, MAX_TAG_LENGTH } from "../parser/tag.js";
+
+const TAG_PROMPT = `你是记忆库标签助手。下面是保留的记忆条目（id、标题、内容）。
+对每条记忆提取 1-3 个中文或英文标签，用于检索分类。
+标签规则：
+- 只允许字符：字母、数字、下划线、中文、连字符（如：linux、考研、deepseek-r1）
+- 标签长度 ≤ ${MAX_TAG_LENGTH} 字符
+- 宁缺毋滥：提取最核心的 1-3 个，不要凑数
+- 不要输出内容里没有依据的标签
+只输出一个 JSON 数组，每项形如 { "id": "<记忆id>", "tags": ["标签1", "标签2"] }。
+不要输出其他文字。`;
+
+/** Same stream consumption contract as dream.js. Returns accumulated text or
+ *  undefined when the stream aborted/errored. */
+async function streamText(ctx, options) {
+  if (!ctx?.llm?.stream) return undefined;
+  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;
+}
+
+/** Pull the outermost JSON array out of a model reply (same tolerant contract
+ *  as sleep.js parseJsonArray): find the first `[` … last `]` and parse. */
+function parseJsonArray(text) {
+  if (typeof text !== "string") return undefined;
+  const start = text.indexOf("[");
+  const end = text.lastIndexOf("]");
+  if (start === -1 || end <= start) return undefined;
+  try {
+    const parsed = JSON.parse(text.slice(start, end + 1));
+    return Array.isArray(parsed) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Resolve the LLM route for the tag pass: the caller-provided consolidation
+ *  route first, then dreamProvider/dreamModel. Falls through to undefined. */
+function resolveTagRoute(route, config, logger) {
+  if (route?.provider && route?.model) return route;
+  if (config?.dreamProvider && config?.dreamModel) return { provider: config.dreamProvider, model: config.dreamModel };
+  logger?.warn?.("dsh-mneme auto-tag: no llm route available");
+  return undefined;
+}
+
+/**
+ * Run the auto-tag pass over retained memories.
+ * @param {object} opts
+ * @param {object} opts.ctx        — { llm, logger }
+ * @param {object} opts.service    — service handle (all/transaction/applyMemoryTags)
+ * @param {object} opts.config     — plugin config (autoTagMaxPerRun, dreamProvider…)
+ * @param {object} [opts.route]    — already-resolved consolidation route
+ * @returns {Promise<{ok: boolean, tagged: number, skipped: number, failed: number, skippedBy: boolean}>}
+ */
+export async function runAutoTag({ ctx, service, config, route }) {
+  const logger = ctx?.logger;
+  const maxPerRun = Number.isInteger(config?.autoTagMaxPerRun) && config.autoTagMaxPerRun > 0
+    ? config.autoTagMaxPerRun
+    : 10;
+  // Retained = post-consolidation active memories, newest first, capped.
+  const memories = service.all()
+    .filter((m) => !m.forgotten && !m.archived && !m.session_disposed_at && m.type !== "summary")
+    .sort((a, b) => {
+      const ta = String(a.updated_at ?? "");
+      const tb = String(b.updated_at ?? "");
+      if (ta < tb) return 1;
+      if (ta > tb) return -1;
+      return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+    })
+    .slice(0, Math.max(1, maxPerRun));
+  if (!memories.length) return { ok: true, tagged: 0, skipped: 0, failed: 0, skippedBy: "empty" };
+  const tagRoute = resolveTagRoute(route, config, logger);
+  if (!tagRoute) return { ok: false, tagged: 0, skipped: memories.length, failed: 0, skippedBy: "no-route" };
+
+  const listText = memories
+    .map((m) => `id=${m.id} | title=${m.title} | content=${m.content}`)
+    .join("\n");
+  const text = await streamText(ctx, {
+    provider: tagRoute.provider,
+    model: tagRoute.model,
+    purpose: "compaction",
+    maxTokens: Math.min(2048, config?.dreamMaxTokens ?? 2048),
+    messages: [
+      { role: "system", content: [{ type: "text", text: TAG_PROMPT }] },
+      { role: "user", content: [{ type: "text", text: listText }] }
+    ]
+  });
+  if (text === undefined) return { ok: false, tagged: 0, skipped: memories.length, failed: 0, skippedBy: "llm-failed" };
+
+  const entries = parseJsonArray(text);
+  if (!entries) {
+    logger?.warn?.("dsh-mneme auto-tag: no json array in llm output");
+    return { ok: false, tagged: 0, skipped: memories.length, failed: 0, skippedBy: "bad-json" };
+  }
+
+  // Validate ids against the candidate set (unknown ids are ignored, never
+  // written — a stray id could otherwise tag an unrelated memory).
+  const candidateIds = new Set(memories.map((m) => m.id));
+  const toWrite = [];
+  let skipped = 0;
+  let failed = 0;
+  const seenIds = new Set();
+  for (const entry of entries) {
+    if (!entry || typeof entry !== "object") { failed++; continue; }
+    const id = typeof entry.id === "string" ? entry.id : undefined;
+    if (!id || !candidateIds.has(id)) { failed++; continue; }
+    if (seenIds.has(id)) continue; // first entry per id wins
+    seenIds.add(id);
+    // Reuse the shared sanitizer: strip, ≤20 chars, drop illegal, dedupe.
+    const tags = sanitizeTags(entry.tags);
+    if (!tags.length) { skipped++; continue; }
+    toWrite.push({ id, tags });
+  }
+
+  // Write the whole batch under one transaction: mirror re-renders once.
+  let tagged = 0;
+  try {
+    service.transaction(() => {
+      for (const { id, tags } of toWrite) {
+        service.applyMemoryTags(id, tags);
+        tagged++;
+      }
+    });
+  } catch (error) {
+    logger?.warn?.(`dsh-mneme auto-tag: write failed: ${String(error)}`);
+    return { ok: false, tagged, skipped, failed, skippedBy: "write-failed" };
+  }
+  return { ok: true, tagged, skipped, failed, skippedBy: false };
+}