@modusensus/dsh-mneme 0.8.3 → 0.8.4

package/src/mirror.js

@@ -1,198 +1,198 @@
-import { mkdirSync, readFileSync, writeFileSync, existsSync, rmSync } from "node:fs";
-import { createHash } from "node:crypto";
-import { join } from "node:path";
-import { STR, langOf } from "./lang.js";
-
-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, language = "zh") {
-  // last-rendered digest baseline: sha256(title \x00 content). service.js
-  // compares the file hash against this to tell "untouched by a human" (machine
-  // write wins) apart from a real human edit, so a not-yet-re-rendered store
-  // update is not misread as a concurrent human edit.
-  const digest = createHash("sha256")
-    .update(`${m.title}\x00${m.content}`)
-    .digest("hex");
-  const lines = [];
-  lines.push(`## ${esc(m.title)}`);
-  lines.push("");
-  lines.push(`- **ID**: \`${m.id}\``);
-  const ML = STR.mirrorLabel[language];
-  lines.push(`- **${ML.type}**: ${m.type}`);
-  lines.push(`- **${ML.importance}**: ${m.importance}`);
-  lines.push(`- **${ML.tags}**: ${m.tags.map((t) => `\`${esc(t)}\``).join(" ")}`);
-  lines.push(`- **${ML.updated}**: ${m.updated_at}`);
-  if (m.source) lines.push(`- **${ML.source}**: ${esc(m.source)}`);
-  lines.push("");
-  lines.push(`<!-- mirror-digest: ${digest} -->`);
-  lines.push(m.content);
-  lines.push("");
-  lines.push("---");
-  lines.push("");
-  return lines.join("\n");
-}
-
-/**
- * Render one type's memories into exactly the mirror-file text (header +
- * per-memory blocks, updated_at DESC like sync). sync() writes this to disk;
- * the /export endpoint returns the same text, so an exported markdown is
- * byte-compatible with a mirror file and can be fed straight back through
- * parseHumanEdits → mergeHumanEdits. Unknown type → undefined.
- */
-export function renderMirrorText(type, memories, language = "zh") {
-  const name = TYPE_FILE[type];
-  if (!name) return undefined;
-  const items = (memories ?? [])
-    .slice()
-    .sort((a, b) => (a.updated_at < b.updated_at ? 1 : -1));
-  const header = STR.mirrorHeader[language](name);
-  const body = items.map((m) => renderMemory(m, language)).join("\n");
-  return header + body;
-}
-
-/**
- * Parse mirror text back into {id, title, content} entries for human edits.
- * Pure text-in/edits-out core: readHumanEdits feeds it mirror file contents
- * and the /import endpoint feeds it user-pasted markdown, so both paths share
- * one parsing implementation (行为一致是硬约束——import 必须能吃回 export 与
- * 磁盘镜像)。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 text). 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.
- */
-export function parseHumanEdits(text) {
-  // CRLF 归一化（readHumanEdits 原有的读取侧处理移入纯函数，Windows 手工编辑
-  // 的文件与导入文本都能正确解析）。
-  const normalized = String(text ?? "").replace(/\r\n/g, "\n");
-  const edits = [];
-  // 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 = [...normalized.matchAll(/^- \*\*ID\*\*: `([^`]+)`\n- \*\*(?:类型|Type)\*\*:/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 : normalized.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 = [...normalized.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 = normalized
-      .slice(blockStart, blockEnd)
-      .replace(/^- \*\*ID\*\*: `[^`]+`\n?/, "")
-      .replace(/^(- \*\*(?:类型|重要性|标签|更新时间|来源|Type|Importance|Tags|Updated|Source)\*\*:.*\n?)+/, "")
-      .replace(/^<!-- mirror-digest: [a-f0-9]+ -->\n?/m, "");
-    const separators = [...body.matchAll(/^---\s*$/gm)];
-    const lastSep = separators[separators.length - 1];
-    if (lastSep) body = body.slice(0, lastSep.index);
-    body = body.trim();
-
-    // The machine-written "更新时间" line records the store's updated_at at
-    // render time — the version token for detecting a concurrent store write
-    // during a three-way merge of human edits (see service.syncMirror).
-    const block = normalized.slice(blockStart, blockEnd);
-    const updatedMatch = block.match(/- \*\*(?:更新时间|Updated)\*\*: ([^\n]+)/);
-    const digestMatch = block.match(/<!-- mirror-digest: ([a-f0-9]+) -->/);
-    edits.push({
-      id: anchor[1],
-      title: titleMatch ? unescape(titleMatch[1]).trim() : undefined,
-      content: body,
-      updated_at: updatedMatch ? updatedMatch[1].trim() : undefined,
-      digest: digestMatch ? digestMatch[1] : undefined
-    });
-
-    const lineEnd = normalized.indexOf("\n", blockStart);
-    prevEnd = lineEnd === -1 ? normalized.length : lineEnd + 1;
-  }
-  return edits;
-}
-
-export function createMirror(dir, language = "zh") {
-  mkdirSync(dir, { recursive: true });
-
-  function filePath(type) {
-    const name = TYPE_FILE[type];
-    return name ? join(dir, name) : undefined;
-  }
-
-  /**
-   * Read the mirror files and parse them back into human edits. The pure
-   * parsing logic lives in the exported parseHumanEdits (shared with /import);
-   * this wrapper only owns the "read file → text" side.
-   */
-  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;
-      edits.push(...parseHumanEdits(readFileSync(file, "utf8")));
-    }
-    return edits;
-  }
-
-  function sync(memories) {
-    const byType = {};
-    for (const m of memories) {
-      (byType[m.type] ??= []).push(m);
-    }
-    // Per-type physical outcomes (audit peer D): a failed write for one type
-    // must not abort the whole render. Each type is written (or pruned) in its
-    // own try/catch and the result reported so the caller can persist per-type
-    // committed/failed receipts — a file that was already written is a real
-    // physical commit even when a sibling type errors.
-    const results = {};
-    for (const type of Object.keys(TYPE_FILE)) {
-      try {
-        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 });
-        } else {
-          // 渲染走 renderMirrorText（与 /export 共用同一条渲染路径），磁盘镜像
-          // 与导出文本永远同构。
-          writeFileSync(file, renderMirrorText(type, items, language), "utf8");
-        }
-        results[type] = { ok: true };
-      } catch (error) {
-        results[type] = { ok: false, error: error?.message ?? String(error) };
-      }
-    }
-    return results;
-  }
-
-  return { filePath, sync, readHumanEdits };
-}
+import { mkdirSync, readFileSync, writeFileSync, existsSync, rmSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { STR, langOf } from "./lang.js";
+
+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, language = "zh") {
+  // last-rendered digest baseline: sha256(title \x00 content). service.js
+  // compares the file hash against this to tell "untouched by a human" (machine
+  // write wins) apart from a real human edit, so a not-yet-re-rendered store
+  // update is not misread as a concurrent human edit.
+  const digest = createHash("sha256")
+    .update(`${m.title}\x00${m.content}`)
+    .digest("hex");
+  const lines = [];
+  lines.push(`## ${esc(m.title)}`);
+  lines.push("");
+  lines.push(`- **ID**: \`${m.id}\``);
+  const ML = STR.mirrorLabel[language];
+  lines.push(`- **${ML.type}**: ${m.type}`);
+  lines.push(`- **${ML.importance}**: ${m.importance}`);
+  lines.push(`- **${ML.tags}**: ${m.tags.map((t) => `\`${esc(t)}\``).join(" ")}`);
+  lines.push(`- **${ML.updated}**: ${m.updated_at}`);
+  if (m.source) lines.push(`- **${ML.source}**: ${esc(m.source)}`);
+  lines.push("");
+  lines.push(`<!-- mirror-digest: ${digest} -->`);
+  lines.push(m.content);
+  lines.push("");
+  lines.push("---");
+  lines.push("");
+  return lines.join("\n");
+}
+
+/**
+ * Render one type's memories into exactly the mirror-file text (header +
+ * per-memory blocks, updated_at DESC like sync). sync() writes this to disk;
+ * the /export endpoint returns the same text, so an exported markdown is
+ * byte-compatible with a mirror file and can be fed straight back through
+ * parseHumanEdits → mergeHumanEdits. Unknown type → undefined.
+ */
+export function renderMirrorText(type, memories, language = "zh") {
+  const name = TYPE_FILE[type];
+  if (!name) return undefined;
+  const items = (memories ?? [])
+    .slice()
+    .sort((a, b) => (a.updated_at < b.updated_at ? 1 : -1));
+  const header = STR.mirrorHeader[language](name);
+  const body = items.map((m) => renderMemory(m, language)).join("\n");
+  return header + body;
+}
+
+/**
+ * Parse mirror text back into {id, title, content} entries for human edits.
+ * Pure text-in/edits-out core: readHumanEdits feeds it mirror file contents
+ * and the /import endpoint feeds it user-pasted markdown, so both paths share
+ * one parsing implementation (行为一致是硬约束——import 必须能吃回 export 与
+ * 磁盘镜像)。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 text). 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.
+ */
+export function parseHumanEdits(text) {
+  // CRLF 归一化（readHumanEdits 原有的读取侧处理移入纯函数，Windows 手工编辑
+  // 的文件与导入文本都能正确解析）。
+  const normalized = String(text ?? "").replace(/\r\n/g, "\n");
+  const edits = [];
+  // 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 = [...normalized.matchAll(/^- \*\*ID\*\*: `([^`]+)`\n- \*\*(?:类型|Type)\*\*:/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 : normalized.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 = [...normalized.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 = normalized
+      .slice(blockStart, blockEnd)
+      .replace(/^- \*\*ID\*\*: `[^`]+`\n?/, "")
+      .replace(/^(- \*\*(?:类型|重要性|标签|更新时间|来源|Type|Importance|Tags|Updated|Source)\*\*:.*\n?)+/, "")
+      .replace(/^<!-- mirror-digest: [a-f0-9]+ -->\n?/m, "");
+    const separators = [...body.matchAll(/^---\s*$/gm)];
+    const lastSep = separators[separators.length - 1];
+    if (lastSep) body = body.slice(0, lastSep.index);
+    body = body.trim();
+
+    // The machine-written "更新时间" line records the store's updated_at at
+    // render time — the version token for detecting a concurrent store write
+    // during a three-way merge of human edits (see service.syncMirror).
+    const block = normalized.slice(blockStart, blockEnd);
+    const updatedMatch = block.match(/- \*\*(?:更新时间|Updated)\*\*: ([^\n]+)/);
+    const digestMatch = block.match(/<!-- mirror-digest: ([a-f0-9]+) -->/);
+    edits.push({
+      id: anchor[1],
+      title: titleMatch ? unescape(titleMatch[1]).trim() : undefined,
+      content: body,
+      updated_at: updatedMatch ? updatedMatch[1].trim() : undefined,
+      digest: digestMatch ? digestMatch[1] : undefined
+    });
+
+    const lineEnd = normalized.indexOf("\n", blockStart);
+    prevEnd = lineEnd === -1 ? normalized.length : lineEnd + 1;
+  }
+  return edits;
+}
+
+export function createMirror(dir, language = "zh") {
+  mkdirSync(dir, { recursive: true });
+
+  function filePath(type) {
+    const name = TYPE_FILE[type];
+    return name ? join(dir, name) : undefined;
+  }
+
+  /**
+   * Read the mirror files and parse them back into human edits. The pure
+   * parsing logic lives in the exported parseHumanEdits (shared with /import);
+   * this wrapper only owns the "read file → text" side.
+   */
+  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;
+      edits.push(...parseHumanEdits(readFileSync(file, "utf8")));
+    }
+    return edits;
+  }
+
+  function sync(memories) {
+    const byType = {};
+    for (const m of memories) {
+      (byType[m.type] ??= []).push(m);
+    }
+    // Per-type physical outcomes (audit peer D): a failed write for one type
+    // must not abort the whole render. Each type is written (or pruned) in its
+    // own try/catch and the result reported so the caller can persist per-type
+    // committed/failed receipts — a file that was already written is a real
+    // physical commit even when a sibling type errors.
+    const results = {};
+    for (const type of Object.keys(TYPE_FILE)) {
+      try {
+        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 });
+        } else {
+          // 渲染走 renderMirrorText（与 /export 共用同一条渲染路径），磁盘镜像
+          // 与导出文本永远同构。
+          writeFileSync(file, renderMirrorText(type, items, language), "utf8");
+        }
+        results[type] = { ok: true };
+      } catch (error) {
+        results[type] = { ok: false, error: error?.message ?? String(error) };
+      }
+    }
+    return results;
+  }
+
+  return { filePath, sync, readHumanEdits };
+}

package/src/quality-filter.js

@@ -1,126 +1,126 @@
-// Rule-based memory quality filter (Bug7). Pure + total: no shared state, no
-// async, no external calls, so it can be unit-tested in isolation and wired
-// into the writer without any I/O or store access.
-//
-// evaluateMemoryQuality scores a memory 0-100 and tags low-value signals. The
-// writer then decides (config.memoryQualityFilter):
-//   score >= degradeThreshold (60)     → stored normally
-//   archiveThreshold (30) <= score < 60 → quality_score persisted; the
-//     injection sort re-ranks by importance * quality_score/100 (degraded)
-//   score < archiveThreshold (30)      → archived + tagged low_quality (still
-//     recallable via explicit search, just never auto-injected)
-//
-// Signals and their deductions from the base 100:
-//   meta                meta-memory vocabulary (the memory talks about the
-//                       memory system itself, not the user's world)    −45
-//   self_referential    title/content mentions its own type label      −15
-//   short_content       content shorter than minContentLength          −80
-//   repetitive          dedup ratio (unique chars / total) < 0.3       −50
-//   duplicate           bigram similarity to a recent memory > 0.85    −80
-//
-// The meta signal alone lands a well-formed memory in the degraded band
-// (30..60) — it is still stored and searchable, just demoted in injection.
-// Reaching the archive band (< 30) needs a degenerate body (short, repetitive
-// or near-duplicated) or stacked signals.
-
-export const META_MEMORY_RE =
-  /记忆|mneme|recall|inject|上下文|token|prompt|系统指令|作为AI|作为助手|我需要记住|总结一下刚才/;
-
-// Own-type labels, used for self-reference detection (the English type value
-// the AI writers emit plus the Chinese equivalent a human would type).
-const TYPE_LABELS = {
-  preference: ["preference", "偏好"],
-  project: ["project", "项目"],
-  decision: ["decision", "决策", "决定"],
-  history: ["history", "历史", "事件"],
-  summary: ["summary", "总结", "摘要", "总览"],
-  pattern: ["pattern", "模式", "规律"],
-  rejected_solution: ["rejected_solution", "被否决", "废弃方案"],
-  pitfall: ["pitfall", "踩坑"],
-  constraint: ["constraint", "约束"]
-};
-
-/** Normalized bigram-overlap similarity in [0,1]; 0 for tiny/empty inputs. */
-export function textSimilarity(a, b) {
-  const bigrams = (s) => {
-    const set = new Set();
-    const t = String(s).replace(/\s+/g, "");
-    for (let i = 0; i < t.length - 1; i++) set.add(t.slice(i, i + 2));
-    return set;
-  };
-  const A = bigrams(a);
-  const B = bigrams(b);
-  if (!A.size || !B.size) return 0;
-  let inter = 0;
-  for (const g of A) if (B.has(g)) inter++;
-  return inter / Math.min(A.size, B.size);
-}
-
-/** Fraction of characters that are unique (dedup ratio in [0,1]). */
-export function dedupRatio(text) {
-  const t = String(text);
-  if (!t.length) return 0;
-  return new Set(t).size / t.length;
-}
-
-/**
- * Score a memory's quality. `recentContents` (optional) is the list of recent
- * memory contents used for near-duplicate detection; when omitted the duplicate
- * signal is skipped. Never throws: every input is coerced defensively.
- * @param {object} memory  { type, title, content }
- * @param {object} [options]
- * @param {number} [options.minContentLength=10]
- * @param {string[]} [options.recentContents]  up to ~20 recent contents
- * @returns {{score: number, tags: string[], reason: string}}
- */
-export function evaluateMemoryQuality(memory, options = {}) {
-  const minContentLength = options.minContentLength ?? 10;
-  const recentContents = Array.isArray(options.recentContents) ? options.recentContents : [];
-  const title = String(memory?.title ?? "");
-  const content = String(memory?.content ?? "");
-  const text = `${title}\n${content}`;
-  const trimmed = content.trim();
-  const tags = [];
-  const reasons = [];
-  let score = 100;
-
-  if (META_MEMORY_RE.test(text)) {
-    score -= 45;
-    tags.push("meta");
-    reasons.push("meta-memory vocabulary");
-  }
-
-  const labels = TYPE_LABELS[memory?.type];
-  if (labels && labels.some((l) => text.includes(l))) {
-    score -= 15;
-    tags.push("self_referential");
-    reasons.push("mentions its own type");
-  }
-
-  if (minContentLength > 0 && trimmed.length < minContentLength) {
-    score -= 80;
-    tags.push("short_content");
-    reasons.push(`content shorter than ${minContentLength} chars`);
-  }
-
-  if (trimmed.length > 0 && dedupRatio(trimmed) < 0.3) {
-    score -= 50;
-    tags.push("repetitive");
-    reasons.push("repetitive content");
-  }
-
-  if (recentContents.length > 0 && trimmed.length > 0) {
-    for (const other of recentContents) {
-      if (textSimilarity(trimmed, other) > 0.85) {
-        score -= 80;
-        tags.push("duplicate");
-        reasons.push("near-duplicate of a recent memory");
-        break;
-      }
-    }
-  }
-
-  score = Math.max(0, Math.min(100, Math.round(score)));
-  if (score < 30) tags.push("low_quality");
-  return { score, tags: [...new Set(tags)], reason: reasons.length ? reasons.join("; ") : "ok" };
-}
+// Rule-based memory quality filter (Bug7). Pure + total: no shared state, no
+// async, no external calls, so it can be unit-tested in isolation and wired
+// into the writer without any I/O or store access.
+//
+// evaluateMemoryQuality scores a memory 0-100 and tags low-value signals. The
+// writer then decides (config.memoryQualityFilter):
+//   score >= degradeThreshold (60)     → stored normally
+//   archiveThreshold (30) <= score < 60 → quality_score persisted; the
+//     injection sort re-ranks by importance * quality_score/100 (degraded)
+//   score < archiveThreshold (30)      → archived + tagged low_quality (still
+//     recallable via explicit search, just never auto-injected)
+//
+// Signals and their deductions from the base 100:
+//   meta                meta-memory vocabulary (the memory talks about the
+//                       memory system itself, not the user's world)    −45
+//   self_referential    title/content mentions its own type label      −15
+//   short_content       content shorter than minContentLength          −80
+//   repetitive          dedup ratio (unique chars / total) < 0.3       −50
+//   duplicate           bigram similarity to a recent memory > 0.85    −80
+//
+// The meta signal alone lands a well-formed memory in the degraded band
+// (30..60) — it is still stored and searchable, just demoted in injection.
+// Reaching the archive band (< 30) needs a degenerate body (short, repetitive
+// or near-duplicated) or stacked signals.
+
+export const META_MEMORY_RE =
+  /记忆|mneme|recall|inject|上下文|token|prompt|系统指令|作为AI|作为助手|我需要记住|总结一下刚才/;
+
+// Own-type labels, used for self-reference detection (the English type value
+// the AI writers emit plus the Chinese equivalent a human would type).
+const TYPE_LABELS = {
+  preference: ["preference", "偏好"],
+  project: ["project", "项目"],
+  decision: ["decision", "决策", "决定"],
+  history: ["history", "历史", "事件"],
+  summary: ["summary", "总结", "摘要", "总览"],
+  pattern: ["pattern", "模式", "规律"],
+  rejected_solution: ["rejected_solution", "被否决", "废弃方案"],
+  pitfall: ["pitfall", "踩坑"],
+  constraint: ["constraint", "约束"]
+};
+
+/** Normalized bigram-overlap similarity in [0,1]; 0 for tiny/empty inputs. */
+export function textSimilarity(a, b) {
+  const bigrams = (s) => {
+    const set = new Set();
+    const t = String(s).replace(/\s+/g, "");
+    for (let i = 0; i < t.length - 1; i++) set.add(t.slice(i, i + 2));
+    return set;
+  };
+  const A = bigrams(a);
+  const B = bigrams(b);
+  if (!A.size || !B.size) return 0;
+  let inter = 0;
+  for (const g of A) if (B.has(g)) inter++;
+  return inter / Math.min(A.size, B.size);
+}
+
+/** Fraction of characters that are unique (dedup ratio in [0,1]). */
+export function dedupRatio(text) {
+  const t = String(text);
+  if (!t.length) return 0;
+  return new Set(t).size / t.length;
+}
+
+/**
+ * Score a memory's quality. `recentContents` (optional) is the list of recent
+ * memory contents used for near-duplicate detection; when omitted the duplicate
+ * signal is skipped. Never throws: every input is coerced defensively.
+ * @param {object} memory  { type, title, content }
+ * @param {object} [options]
+ * @param {number} [options.minContentLength=10]
+ * @param {string[]} [options.recentContents]  up to ~20 recent contents
+ * @returns {{score: number, tags: string[], reason: string}}
+ */
+export function evaluateMemoryQuality(memory, options = {}) {
+  const minContentLength = options.minContentLength ?? 10;
+  const recentContents = Array.isArray(options.recentContents) ? options.recentContents : [];
+  const title = String(memory?.title ?? "");
+  const content = String(memory?.content ?? "");
+  const text = `${title}\n${content}`;
+  const trimmed = content.trim();
+  const tags = [];
+  const reasons = [];
+  let score = 100;
+
+  if (META_MEMORY_RE.test(text)) {
+    score -= 45;
+    tags.push("meta");
+    reasons.push("meta-memory vocabulary");
+  }
+
+  const labels = TYPE_LABELS[memory?.type];
+  if (labels && labels.some((l) => text.includes(l))) {
+    score -= 15;
+    tags.push("self_referential");
+    reasons.push("mentions its own type");
+  }
+
+  if (minContentLength > 0 && trimmed.length < minContentLength) {
+    score -= 80;
+    tags.push("short_content");
+    reasons.push(`content shorter than ${minContentLength} chars`);
+  }
+
+  if (trimmed.length > 0 && dedupRatio(trimmed) < 0.3) {
+    score -= 50;
+    tags.push("repetitive");
+    reasons.push("repetitive content");
+  }
+
+  if (recentContents.length > 0 && trimmed.length > 0) {
+    for (const other of recentContents) {
+      if (textSimilarity(trimmed, other) > 0.85) {
+        score -= 80;
+        tags.push("duplicate");
+        reasons.push("near-duplicate of a recent memory");
+        break;
+      }
+    }
+  }
+
+  score = Math.max(0, Math.min(100, Math.round(score)));
+  if (score < 30) tags.push("low_quality");
+  return { score, tags: [...new Set(tags)], reason: reasons.length ? reasons.join("; ") : "ok" };
+}