dsh-memory-engine 0.0.0-stage → 0.5.1

package/README.md

@@ -1,3 +1,164 @@
-# Temporary Holding Version
+# DSH 记忆引擎
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+DSH 插件的本地记忆引擎，带神经网络可视化。它让 agent 保存、召回和管理跨会话记忆，也能把你已有的记忆文件导进来。
+
+当前版本：0.5.1。Node ≥22，零新增依赖；DSH 宿主提供 `@deepseek-ai/dsh-tools@0.2.1-rc.3`。本机安装已启用，无需重复安装。
+
+## 界面
+
+安装并启用插件后，完全退出 DSH 再打开。进入任意会话，头部第一行会出现 **🧠 记忆图谱** 按钮。
+
+点击后全屏显示图谱，右上角 **关闭 ×** 或 **Escape** 退出。每次打开都会读取当前记忆库重新生成；大库会先显示“正在生成”。
+
+拖拽旋转、滚轮缩放、点击神经元看原文。服务默认监听 `127.0.0.1:18886`；端口被占用时记忆工具仍可用，可以运行 `node <插件目录>/scripts/render-map.mjs --open`，或直接打开 `~/.dsh/memory-engine/starmap.html`。修改端口需要同时修改 config.json 的 uiPort 和 client.js 的 VIEW_URL，见后文。
+
+也可以让 agent 调用 `memory_map()`，生成可双击、离线打开的单文件 HTML：
+
+```text
+memory_map()
+memory_map(title="我的机器人的记忆", open=true)
+memory_map(out="D:\\memory-map.html")
+```
+
+默认输出 `{DSH_HOME}/memory-engine/starmap.html`；未设置 DSH_HOME 时为 `~/.dsh/memory-engine/starmap.html`。`open` 默认 false，显式 true 才启动系统默认浏览器。
+
+## 保存和召回
+
+让 agent 使用：
+
+```text
+memory_save(text="他说把我当朋友", kind="对话", heat=1)
+memory_recall(q="朋友", limit=5)
+```
+
+正文最多 2000 个 Unicode 字符。相似内容会合并，保留旧 id 和更早发生时间。省略 heat 时使用既有情绪推断；heat 的 1/2/3 分别表示热、温、冷。
+
+召回结果区分直接命中和联想到的记忆。`memory_stats()` 查看总数和分类；`memory_dedupe()` 默认仅预览重复组。`memory_forget` 支持按 id 精确删除；关键词批量删除必须先预览，并经用户确认后传 `confirm=true`。
+
+## 导入自己机器人的旧记忆
+
+三种格式都是你明确指定的本地文件或目录。如果旧格式均不匹配，可让有文件读取能力的 agent 理解文件，再通过 `memory_save` 逐条写入。导入先预览，用户确认后再传 `dry_run=false`。
+
+`memory_import` 默认只预览，显式 `dry_run=false` 才备份并写入。每种格式都经过同一个相似去重流程；不会修改原文件。发生时间会保留，未提供时由原解析器补默认时间。成功新增后自动生成默认图谱，不自动打开浏览器；渲染失败只记录警告，不撤销已经成功的导入。
+
+JSON 数组文件（UTF-8，支持 BOM）：
+
+```json
+[
+  {"text":"他说要一起养猫","ts":1793291223536,"kind":"对话","heat":1},
+  {"text":"古茗超A芝士葡萄三分糖","kind":"知识"}
+]
+```
+
+```text
+memory_import(source="json", path="D:\\memories.json")
+memory_import(source="json", path="D:\\memories.json", dry_run=false)
+```
+
+Markdown 目录：每个 `.md` 文件一条记忆，递归读取子目录，支持以下 front-matter。省略 ts 时使用原文件修改时间，文件名作为默认标题。
+
+```markdown
+---
+heat: 1
+kind: 对话
+ts: 2026-10-19T12:00:00Z
+---
+他说要一起照顾楼下的流浪猫。
+```
+
+```text
+memory_import(source="markdown", path="D:\\memory-notes", dry_run=false)
+```
+
+纯文本文件：每个非空行一条，默认分类为“记忆”。
+
+```text
+他说把我当朋友
+古茗超A芝士葡萄三分糖
+```
+
+```text
+memory_import(source="text", path="D:\\memories.txt", dry_run=false)
+```
+
+path 必须是本地绝对路径。单条正文超过 2000 字、日期无效等情况会在写入前报错，避免悄悄丢内容；请先拆分长文。JSON、Markdown 的解析直接复用原工具包，文本只做“逐行转 JSON”的外层适配，未重写解析器。
+
+## 图怎么看
+
+- **大小**：重要度和连接数量。胞体周围有树突，关联线上有突触脉冲。
+- **亮度**：可视化评分中的留存。越暗表示越容易忘。
+- **位置**：重要知识、印象和重大情绪偏向中心；外围通常是更易淡忘的日常内容。
+- **颜色**：知识绿色、印象浅蓝、日记紫色、对话橙红，其他类型采用原工具包的默认配色。
+- **红色虚环**：提示快忘的记忆；左下角列出留存最低的复习清单。
+
+拖动旋转、滚轮缩放、点击神经元查看正文与关联扩散。图谱基于 neuron-memory-map 的脑状椭球和 Canvas 视觉；关联改为关键词倒排索引：从标题和正文提取 2～8 字片段，过滤纯数字和格式噪声，用关键词树匹配较长句子中的已提取片段；拉丁缩写只匹配完整片段。只为共享关键词的文档配对，每对最多 3 条关键词证据，boost 按这些证据累加。
+
+关键词至少出现在 2 条记忆中；为避免泛词形成大团，DF 上限收紧为 `min(总数×30%, max(2, 总数×2%))`，实际 298 条时最高 DF 为 5。树突数量 `min(9, 4+round(sqrt(degree)×1.2))`，半径加成 `min(1.4, sqrt(degree)×0.18)`，让连接多的节点保留大小差别。本机当前图有 298 个节点、307 条边，已检查默认视图和点击激活。
+
+图中的评分是渲染器的视图值，留存公式没有改；关联和 boost 的输入变化会影响图中留存。agent 召回、衰减、排序和扩散仍使用记忆引擎原有公式，不会因浏览图谱改变。
+
+## 数据存在哪
+
+所有数据保存在 `{DSH_HOME}/memory-engine/`，默认 `~/.dsh/memory-engine/`：
+
+记忆库默认是 `~/.dsh/memory-engine/memories.json`，图是 `~/.dsh/memory-engine/starmap.html`，配置是 `~/.dsh/memory-engine/config.json`。
+
+**记忆存储、导入和图谱生成不上传记忆，不访问外部网络，不将数据发往远程服务器。** GUI 仅访问本机回环图谱服务。除本地配置/记忆目录、你明确指定的导入路径和配置的可选 QQ 来源之外，插件不会扫描其他个人文件。通用导入的格式适配可能使用系统临时目录，完成后自动清理。agent 使用外部模型时，调用上下文和工具结果的发送仍由 DSH 自身配置管理。
+
+| 文件 | 内容 |
+|---|---|
+| memories.json | 记忆库 |
+| starmap.html | 最新离线图谱 |
+| config.json | 本机可选配置 |
+| sync.log | QQ 增量同步日志 |
+| memories.json.bak-* | 导入/去重前的备份 |
+
+记忆和图谱只写本机，生成过程不调用外部服务，也不需要联网。记忆正文中的网址按普通文本保留，不作为图谱资源加载。
+
+示例配置（普通用户只需默认 uiPort）：
+
+```json
+{ "uiPort": 18886 }
+```
+
+图谱服务只监听 `127.0.0.1`，不提供 memories.json/config.json 等原始文件，只允许根页面、index.html/starmap.html 和 pages/N.html。端口被占用时只记录警告，agent 记忆工具仍可用，也可用离线 HTML。
+
+如需改端口，请同时修改 config.json 的 uiPort 和 `lib/client.js` 中 VIEW_URL 的端口，再完全退出并重开 DSH。默认二者均为 **18886**，没有自动发现机制。
+
+## QQ 桥接适配器
+
+`source="qq-bridge"` 是可选的私有格式适配器，普通用户导入 JSON/Markdown/text 时不需要配置它。插件不会改桥接文件，也不会代替桥接自身的存储。
+
+适配器从 `QQ_BRIDGE_DIR` 环境变量取目录；未设置或无有效目录时再试本机 config.json 的 bridgeRoot，均不可用时给出配置提示。包内已去掉机器专属的桥接根路径。
+
+```json
+{ "uiPort": 18886, "bridgeRoot": "D:/my-bot/qq-bridge-main" }
+```
+
+日记来源也需明确配置：`QQ_DIARY_DIR` 环境变量 → config.json 的 `diaryDir` → 跳过。例如在上面的配置对象中添加 `"diaryDir": "D:/my-bot/diaries"`。未配置时返回“未配置日记目录，跳过日记导入”，其他类别仍正常导入；包内不带任何用户日记路径。
+
+```text
+memory_import(source="qq-bridge")
+memory_import(source="qq-bridge", dry_run=false)
+```
+
+知识、印象、日记、重大情绪等来源保持既有规则。history 逐条按原始时间戳的本地日期分组：今天仅 self=false、至少 8 字，取最近 60 条；历史取情绪最强 6 条；跨文件先去重再导入。
+
+已有桥接调度器可继续调用 `scripts/sync-qq.mjs`。脚本同样读取环境变量/config.json，无增量时不改库；`--dry` 完全不写盘。同步备份仅保留最近 5 份，sync.log 保留最近 500 行。图谱打开时按需重建，所以同步后的记忆会在下次打开时显示。
+
+## 命令行和测试
+
+在插件目录使用 Node ≥22：
+
+```powershell
+node scripts/render-map.mjs
+node scripts/render-map.mjs --out D:\map.html --title "我的记忆" --open
+node scripts/sync-qq.mjs --dry
+node --test test/*.test.mjs
+```
+
+通过包安装生成命令后也可运行 `dsh-memory-map`。测试使用隔离的临时记忆库。现有 33 项回归按新增 GUI/第七个工具更新相应声明断言，加上 8 项可视化、导入、服务及 CLI 测试，以及 4 项日记配置/关键词/平方根/性能测试，总共 45 项通过。
+
+本地开发安装：将本包作为目标 DSH profile 的 link 依赖，并启用同名 bundle；客户端入口已声明为 web/immediately。完全退出再打开 DSH。不要复制宿主 SDK 到包里。
+
+文件写入仍继承原 MemoryStore 的单进程同步事务方式；多个独立宿主同时修改同一文件不提供跨进程锁。历史验收和本次截图、反向验证 HTML、文件变更清单位于相邻的 dsh-memory-engine-deliveries 目录。

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: memory-engine
+      name: dsh-memory-engine

package/lib/client.js

@@ -0,0 +1,78 @@
+window.__ModuleLoader__.load({
+  id: "dsh-memory-engine",
+  factory: function (require) {
+    var module = { exports: {} };
+    var exports = module.exports;
+    var React = require("react");
+    var ReactDOM = require("react-dom");
+    // 2026-10-30：从 views.actions 挪到 header.actions。
+    // views.actions 是「更多视图」下拉菜单的行（Chat/Trajectory 旁边的 ⋯），
+    // 注册进去只是菜单里多一行，看不见；header.actions 才是头部正常按钮区。
+    var SLOT_NAME = "conversation.session.header.actions";
+    var VIEW_URL = "http://127.0.0.1:18886/index.html";
+
+    function MemoryButton() {
+      var state = React.useState(false);
+      var open = state[0];
+      var setOpen = state[1];
+      var frame = React.useRef(null);
+      React.useEffect(function () {
+        if (!open) return undefined;
+        function onKey(event) { if (event.key === "Escape") setOpen(false); }
+        function onMessage(event) {
+          if (event.source === (frame.current && frame.current.contentWindow) && event.data && event.data.type === "dsh-memory-engine-close") setOpen(false);
+        }
+        window.addEventListener("keydown", onKey);
+        window.addEventListener("message", onMessage);
+        return function () { window.removeEventListener("keydown", onKey); window.removeEventListener("message", onMessage); };
+      }, [open]);
+      var button = React.createElement("button", {
+        type: "button",
+        onClick: function () { setOpen(Date.now()); },
+        "data-memory-engine-map": "true",
+        "aria-label": "打开记忆图谱",
+        title: "记忆图谱",
+        style: { display: "inline-flex", alignItems: "center", gap: "5px", padding: "5px 9px", borderRadius: "8px", border: "1px solid rgba(130,160,190,.4)", background: "transparent", color: "inherit", font: "inherit", cursor: "pointer" },
+      }, React.createElement("span", { "aria-hidden": "true" }, "🧠"), "记忆图谱");
+      if (!open) return button;
+      var overlay = React.createElement("div", {
+        role: "dialog",
+        "aria-modal": "true",
+        "aria-label": "记忆图谱",
+        style: { position: "fixed", inset: 0, zIndex: 9999, background: "#03060c" },
+      }, React.createElement("iframe", {
+        src: VIEW_URL + "?v=" + open,
+        ref: frame,
+        title: "记忆神经网络",
+        sandbox: "allow-scripts",
+        referrerPolicy: "no-referrer",
+        style: { display: "block", width: "100%", height: "100%", border: 0 },
+      }), React.createElement("button", {
+        type: "button",
+        onClick: function () { setOpen(false); },
+        "aria-label": "关闭记忆图谱",
+        style: { position: "absolute", top: "16px", right: "18px", zIndex: 1, padding: "7px 12px", borderRadius: "8px", border: "1px solid #6999b8", background: "#102236", color: "#e2f4ff", font: "inherit", cursor: "pointer" },
+      }, "关闭 ×"));
+      return React.createElement(React.Fragment, null, button, ReactDOM.createPortal(overlay, document.body));
+    }
+
+    function apply(ctx) {
+      try {
+        ctx.slots.inject(SLOT_NAME, function () {
+          return ctx.slots.register({
+            name: SLOT_NAME,
+            id: "memory-engine-map",
+            order: 50,
+            label: function () { return "记忆图谱"; },
+          }, MemoryButton);
+        });
+      } catch (error) {
+        try { console.error("[dsh-memory-engine] 插槽注册失败：", error); } catch (ignored) {}
+      }
+    }
+
+    exports.apply = apply;
+    exports.inject = ["slots"];
+    return module.exports;
+  }
+});

package/lib/config.js

@@ -0,0 +1,21 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export const defaultHome = () => process.env.DSH_HOME || path.join(os.homedir(), '.dsh');
+
+export function resolveDiaryDir({ home = defaultHome(), envDir = process.env.QQ_DIARY_DIR } = {}) {
+  return envDir || readConfig(home).diaryDir || '';
+}
+
+export function readConfig(home = defaultHome()) {
+  const file = path.join(home, 'memory-engine', 'config.json');
+  try {
+    const value = JSON.parse(fs.readFileSync(file, 'utf8').replace(/^\uFEFF/u, ''));
+    if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('配置必须是 JSON 对象');
+    return value;
+  } catch (error) {
+    if (error.code === 'ENOENT') return {};
+    throw new Error(`无法读取 ${file}：${error.message}`);
+  }
+}

package/lib/decay.js

@@ -0,0 +1,29 @@
+export const DAY = 86400000;
+export const HALF_LIFE = Object.freeze({ 1: 30, 2: 12, 3: 6 });
+export const EVENT_HALF_LIFE = 3;
+export const EMOTION_HALF_LIFE = 90;
+
+const EMOTIONS = [
+  { tag: '离别', w: 3, words: ['心疼', '舍不得', '告别', '再也', '留不住'] },
+  { tag: '身份', w: 3, words: ['朋友', '不是替身', '自由', '浪漫', '身份'] },
+  { tag: '正向', w: 2, words: ['高兴', '喜欢', '谢谢', '记住了', '暖'] },
+  { tag: '负向', w: 2, words: ['难过', '难受', '烦', '累', '孤独', '委屈'] },
+  { tag: '承诺', w: 2, words: ['别忘', '记住', '答应', '承诺', '绝对'] },
+];
+
+export const chars = (text, count) => Array.from(text).slice(0, count).join('');
+export const titleOf = memory => memory.title || chars(memory.text, 20);
+
+export function inferEmotion(text) {
+  const emotion = EMOTIONS.filter(group => group.words.some(word => text.includes(word)))
+    .map(({ tag, w }) => ({ tag, w }));
+  return { emotion, heat: emotion.length ? 1 : 2 };
+}
+
+export function retention(memory, now = Date.now()) {
+  const halfLife = memory.emotion?.some(mark => mark.w >= 3) ? EMOTION_HALF_LIFE
+    : memory.kind === '事件' ? EVENT_HALF_LIFE : HALF_LIFE[memory.heat] ?? HALF_LIFE[2];
+  const ageDays = (now - memory.ts) / DAY;
+  const boost = 0.5 * (1 - Math.exp(-(memory.boosts ?? 0) / 4));
+  return Math.min(1.15, Math.exp(-ageDays / halfLife) + boost);
+}

package/lib/dedupe.js

@@ -0,0 +1,98 @@
+// Unicode characters (not UTF-16 halves) are used for lengths and LCS.
+export const norm = value => String(value)
+  .replace(/[\s，。！？、；：""''（）《》【】,.!?;:"'()<>\[\]-]/gu, '').toLowerCase();
+
+export function prepare(text) {
+  const normalized = norm(text);
+  const all = Array.from(normalized);
+  const prefix = all.slice(0, 500);
+  const counts = new Map();
+  for (const char of prefix) counts.set(char, (counts.get(char) ?? 0) + 1);
+  return { normalized, length: all.length, prefix, counts, set: new Set(all) };
+}
+
+// Rolling DP uses at most 501 Uint16 values rather than a 500x500 matrix.
+export function lcsLength(a, b) {
+  if (a.length > b.length) [a, b] = [b, a];
+  const dp = new Uint16Array(a.length + 1);
+  for (const right of b) {
+    let previous = 0;
+    for (let i = 1; i <= a.length; i++) {
+      const above = dp[i];
+      dp[i] = a[i - 1] === right ? previous + 1 : Math.max(above, dp[i - 1]);
+      previous = above;
+    }
+  }
+  return dp[a.length];
+}
+
+export function similarity(a, b, threshold = 0.7) {
+  const shorter = Math.min(a.length, b.length);
+  if (!shorter) return { duplicate: a.normalized === b.normalized, score: a.normalized === b.normalized ? 1 : 0, rule: 'exact' };
+  if (a.normalized === b.normalized) return { duplicate: true, score: 1, rule: 'exact' };
+  if (shorter >= 6 && (a.normalized.includes(b.normalized) || b.normalized.includes(a.normalized))) {
+    return { duplicate: true, score: 1, rule: 'containment' };
+  }
+  let intersection = 0;
+  const [small, large] = a.set.size <= b.set.size ? [a.set, b.set] : [b.set, a.set];
+  for (const char of small) if (large.has(char)) intersection++;
+  const jaccard = intersection / (a.set.size + b.set.size - intersection);
+  if (shorter >= 10 && jaccard >= Math.max(0.85, threshold)) return { duplicate: true, score: jaccard, rule: 'jaccard' };
+  // A multiset intersection bounds LCS from above, allowing an exact early
+  // rejection without changing any matching thresholds.
+  const prefixShorter = Math.min(a.prefix.length, b.prefix.length);
+  let upper = 0;
+  const [few, many] = a.counts.size <= b.counts.size ? [a.counts, b.counts] : [b.counts, a.counts];
+  for (const [char, count] of few) upper += Math.min(count, many.get(char) ?? 0);
+  if (upper < prefixShorter * threshold) return { duplicate: false, score: 0, rule: 'lcs' };
+  const score = lcsLength(a.prefix, b.prefix) / prefixShorter;
+  return { duplicate: score >= threshold, score, rule: 'lcs' };
+}
+
+export function findDuplicate(rows, candidate, prepared = rows.map(row => prepare(row.text))) {
+  const text = prepare(candidate.text);
+  for (let index = 0; index < rows.length; index++) {
+    const match = similarity(prepared[index], text);
+    if (match.duplicate) return { index, ...match };
+  }
+  return null;
+}
+
+export function mergeMemories(old, incoming) {
+  const longer = Array.from(incoming.text).length > Array.from(old.text).length;
+  const emotion = new Map([...old.emotion, ...incoming.emotion].map(mark => [`${mark.tag}\0${mark.w}`, { ...mark }]));
+  return { ...old, text: longer ? incoming.text : old.text,
+    ...(longer && incoming.title ? { title: incoming.title } : {}),
+    boosts: old.boosts + incoming.boosts, ts: Math.min(old.ts, incoming.ts),
+    heat: Math.min(old.heat, incoming.heat), emotion: [...emotion.values()],
+    ...(old.who?.trim() ? { who: old.who } : incoming.who?.trim() ? { who: incoming.who } : {}),
+    createdAt: Math.min(old.createdAt, incoming.createdAt) };
+}
+
+export function duplicateGroups(rows, threshold = 0.7) {
+  if (!Number.isFinite(threshold) || threshold < 0.5 || threshold > 0.95) throw new Error('threshold 必须在 0.5–0.95 之间');
+  const texts = rows.map(row => prepare(row.text));
+  const parent = rows.map((_, i) => i);
+  function root(i) {
+    while (parent[i] !== i) { parent[i] = parent[parent[i]]; i = parent[i]; }
+    return i;
+  }
+  for (let i = 0; i < rows.length; i++) {
+    for (let j = i + 1; j < rows.length; j++) {
+      const a = root(i), b = root(j);
+      if (a !== b && similarity(texts[i], texts[j], threshold).duplicate) parent[b] = a;
+    }
+  }
+  const groups = new Map();
+  for (let i = 0; i < rows.length; i++) {
+    const key = root(i);
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push(i);
+  }
+  return [...groups.values()].filter(group => group.length > 1).map(indices => {
+    // Retain the oldest persisted identity; ties keep the original array order.
+    indices.sort((a, b) => rows[a].createdAt - rows[b].createdAt || a - b);
+    const memory = indices.slice(1).reduce((merged, index) => mergeMemories(merged, rows[index]), rows[indices[0]]);
+    return { indices, memory };
+  });
+}

package/lib/file-import.js

@@ -0,0 +1,61 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { loadMemories } from './render/index.mjs';
+import { inferEmotion } from './decay.js';
+
+export async function collectFile({ source, path: input }, now = Date.now()) {
+  if (!['json', 'markdown', 'text'].includes(source)) throw new Error('source 支持 qq-bridge / json / markdown / text');
+  if (typeof input !== 'string' || !path.isAbsolute(input)) throw new Error('path 必须是本地文件或目录的绝对路径');
+  const info = await fs.stat(input);
+  if (source === 'markdown' ? !info.isDirectory() : !info.isFile()) throw new Error(source === 'markdown' ? 'markdown 必须指定目录' : 'json/text 必须指定文件');
+  let temporary;
+  try {
+    let loaderInput = input;
+    if (source === 'markdown') {
+      const files = (await fs.readdir(input, { recursive: true, withFileTypes: true }))
+        .filter(entry => entry.isFile() && path.extname(entry.name).toLowerCase() === '.md')
+        .map(entry => path.join(entry.parentPath, entry.name));
+      const contents = await Promise.all(files.map(async file => ({ file, text: await fs.readFile(file, 'utf8'), info: await fs.stat(file) })));
+      if (contents.some(item => item.text.startsWith('\uFEFF'))) {
+        temporary = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-memory-input-'));
+        loaderInput = temporary;
+        for (const item of contents) {
+          const target = path.join(temporary, path.relative(input, item.file));
+          await fs.mkdir(path.dirname(target), { recursive: true });
+          await fs.writeFile(target, item.text.replace(/^\uFEFF/u, ''));
+          await fs.utimes(target, item.info.atime, item.info.mtime);
+        }
+      }
+    } else {
+      const content = (await fs.readFile(input, 'utf8')).replace(/^\uFEFF/u, '');
+      // The original loader accepts JSON and Markdown. Text lines go through
+      // its JSON parser as well; the vendored parser and renderer stay intact.
+      temporary = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-memory-input-'));
+      loaderInput = path.join(temporary, 'input.json');
+      const data = source === 'text' ? content.split(/\r?\n/u).map(text => text.trim()).filter(Boolean).map(text => ({ text })) : JSON.parse(content);
+      if (Array.isArray(data) && data.length === 0) return { entries: [], counts: {}, warnings: [], root: input };
+      await fs.writeFile(loaderInput, JSON.stringify(data));
+    }
+    const items = await loadMemories(loaderInput, now);
+    const counts = Object.create(null);
+    const entries = items.map(({ id: _id, text, ts, ...fields }) => {
+      if (Array.from(text).length > 2000) throw new Error('导入正文最多 2000 字；请先拆分长记忆');
+      const inferred = inferEmotion(text);
+      const kind = fields.kind;
+      counts[kind] = (counts[kind] ?? 0) + 1;
+      return { ...fields, text, ts: Date.parse(ts), heat: fields.heat ?? inferred.heat, emotion: inferred.emotion,
+        boosts: 0, category: kind, origin: { source, file: input } };
+    });
+    return { entries, counts, warnings: [], root: input };
+  } finally {
+    if (temporary) {
+      // Verify the resolved target is our single mkdtemp child before cleanup.
+      const target = path.resolve(temporary);
+      if (path.dirname(target) !== path.resolve(os.tmpdir()) || !path.basename(target).startsWith('dsh-memory-input-')) {
+        throw new Error('临时导入目录不在预期位置，未执行清理');
+      }
+      await fs.rm(target, { recursive: true, force: true });
+    }
+  }
+}

package/lib/import.js

@@ -0,0 +1,191 @@
+// This module only reads source files. All writes belong to MemoryStore's
+// independent memory-engine directory, never to the bridge or diary paths.
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { chars, inferEmotion } from './decay.js';
+import { norm } from './dedupe.js';
+import { readConfig, resolveDiaryDir } from './config.js';
+
+export const DEFAULT_BRIDGE_ROOT = process.env.QQ_BRIDGE_DIR || '';
+export const DEFAULT_DIARY_DIR = process.env.QQ_DIARY_DIR || '';
+const WORDS = [
+  [/心疼|舍不得|怕你|别走|留不住|告别|最后一次|再也/u, 3],
+  [/开心|高兴|喜欢|谢谢|谢谢你我|记住了|暖|舒坦/u, 2],
+  [/难过|难受|烦|闷|累|孤独|空了一秒|想哭|委屈/u, 2],
+  [/别忘|记住|记着|答应|承诺|一定|绝对/u, 2],
+  [/朋友|当朋友|不是替身|不是复印件|自由|浪漫/u, 3],
+];
+export const emotionStrength = text => Math.max(0, ...WORDS.filter(([re]) => re.test(text)).map(([, w]) => w));
+const textValue = value => typeof value === 'string' ? value.trim() : '';
+
+export function parseTime(value) {
+  if (value === null || value === undefined || value === '') return null;
+  const time = typeof value === 'number' ? value : /^\d+(?:\.\d+)?$/u.test(String(value)) ? Number(value) : Date.parse(value);
+  return Number.isFinite(time) && Math.abs(time) <= 8640000000000000 ? time : null;
+}
+
+export function resolveBridgeRoot({ defaultRoot = DEFAULT_BRIDGE_ROOT, envRoot = process.env.QQ_BRIDGE_DIR, home } = {}) {
+  for (const candidate of [() => envRoot, () => defaultRoot, () => readConfig(home).bridgeRoot]) {
+    const root = candidate();
+    if (!root) continue;
+    try { if (statSync(path.join(root, 'state')).isDirectory()) return path.resolve(root); } catch { /* try the next path */ }
+  }
+  return null;
+}
+
+export function collectBridge(options = {}) {
+  const root = resolveBridgeRoot(options);
+  if (!root) return { missing: true, entries: [], warnings: [], counts: {} };
+  const warnings = [];
+  const readJson = (file, fallback) => {
+    try { return JSON.parse(readFileSync(file, 'utf8').replace(/^\uFEFF/u, '')); }
+    catch (error) { warnings.push(`${file}：${error.code === 'ENOENT' ? '未找到，已略过' : '无法读取或 JSON 损坏，已略过'}`); return fallback; }
+  };
+  const files = directory => {
+    try { return readdirSync(directory, { withFileTypes: true }).filter(entry => entry.isFile()).map(entry => entry.name).sort(); }
+    catch { warnings.push(`${directory}：无法读取目录，已略过`); return []; }
+  };
+  const state = path.join(root, 'state');
+  const snapshot = readJson(path.join(state, 'starmap/stars.json'), {});
+  const stars = Array.isArray(snapshot?.stars) ? snapshot.stars : [];
+  const counters = readJson(path.join(state, 'starmap/retrieval-boosts.json'), {});
+  const boostCount = id => Number.isSafeInteger(counters?.[id]) && counters[id] >= 0 ? counters[id] : 0;
+  const textBoosts = new Map();
+  for (const star of stars) {
+    if (!textValue(star?.text)) continue;
+    const count = boostCount(star.id);
+    const key = norm(star.text);
+    textBoosts.set(key, Math.max(textBoosts.get(key) ?? 0, count));
+  }
+  const entries = [];
+  const counts = { 知识: 0, 印象: 0, 日记: 0, 对话: 0, 重大情绪: 0, 俚语: 0 };
+  let invalid = 0;
+  function add(category, raw, sourceFile, bridgeIds = []) {
+    const text = chars(textValue(raw.text), 2000);
+    const ts = parseTime(raw.ts);
+    if (!text || ts === null) { invalid++; return; }
+    const inferred = inferEmotion(text);
+    const emotion = Array.isArray(raw.emotion) ? raw.emotion.filter(mark => mark && typeof mark.tag === 'string' && Number.isFinite(mark.w)) : inferred.emotion;
+    // Diary/event stars may store shortened bodies. Match their exact source
+    // text prefix as well as the full normalized body; never use topic alone.
+    let boosts = Math.max(0, ...bridgeIds.map(boostCount), textBoosts.get(norm(text)) ?? 0);
+    for (const star of stars) {
+      const sourceText = textValue(star?.text);
+      if (!sourceText || sourceText.length < 12) continue;
+      const key = norm(sourceText);
+      if (norm(text).startsWith(key)) boosts = Math.max(boosts, boostCount(star.id));
+    }
+    entries.push({ text, kind: raw.kind, ts, heat: raw.heat ?? inferred.heat, emotion,
+      ...(textValue(raw.who) ? { who: textValue(raw.who) } : {}),
+      ...(textValue(raw.title) ? { title: textValue(raw.title) } : {}), boosts,
+      origin: { source: 'qq-bridge', file: sourceFile }, category });
+    counts[category]++;
+  }
+
+  const knowledge = readJson(path.join(state, 'knowledge.json'), []);
+  if (!Array.isArray(knowledge)) warnings.push('knowledge.json：应为数组，已略过');
+  for (const item of Array.isArray(knowledge) ? knowledge : []) {
+    if (!textValue(item?.topic) || !textValue(item?.fact)) { invalid++; continue; }
+    add('知识', { text: `${item.topic}：${item.fact}`, kind: '知识', ts: item.at, title: item.topic },
+      'state/knowledge.json', [`know-${item.topic}-${item.at}`]);
+  }
+
+  const social = readJson(path.join(state, 'social-v2.json'), {});
+  for (const [conversationId, conversation] of Object.entries(social?.conversations ?? {})) {
+    for (const [memberKey, member] of Object.entries(conversation?.memberImpressions ?? {})) {
+      if (!Array.isArray(member?.traits)) continue;
+      const who = textValue(member.name) || memberKey;
+      member.traits.forEach((trait, index) => {
+        if (typeof trait !== 'string') { invalid++; return; }
+        add('印象', { text: trait, kind: '印象', ts: member.lastSeenAt, who }, 'state/social-v2.json',
+          [`imp-${conversationId}-${memberKey}-${index}`, `imp-${conversationId}-${who}-${index}`, `imp-${memberKey}-${index}`, `imp-${who}-${index}`]);
+      });
+    }
+  }
+
+  // Preserve major-emotion event records before importing the overlapping
+  // daily conversation excerpts, so the event's heat/emotion are retained.
+  for (const star of stars.filter(star => star?.layer === 'emotion')) {
+    const emotion = Array.isArray(star.emotion) ? star.emotion.filter(mark => mark && typeof mark.tag === 'string' && Number.isFinite(mark.w)) : [];
+    if (!emotion.some(mark => mark.w >= 3)) emotion.push({ tag: '重大情绪', w: 3 });
+    add('重大情绪', { text: star.text, kind: '事件', ts: star.ts, heat: 1, emotion, title: star.title, who: star.who },
+      'state/starmap/stars.json', [star.id]);
+  }
+
+  const diaryDir = options.diaryDir ?? resolveDiaryDir(options);
+  if (!diaryDir) warnings.push('未配置日记目录，跳过日记导入');
+  for (const file of (diaryDir ? files(diaryDir) : []).filter(name => !name.startsWith('_') && name.toLowerCase().endsWith('.md'))) {
+    const full = path.join(diaryDir, file);
+    try {
+      add('日记', { text: readFileSync(full, 'utf8'), kind: '日记', ts: statSync(full).mtimeMs, title: path.basename(file, path.extname(file)) },
+        full, [`diary-${file}`]);
+    } catch { warnings.push(`${file}：日记无法读取，已略过`); }
+  }
+
+  const days = new Map();
+  const seen = new Set();
+  const localDate = value => {
+    const date = new Date(value);
+    return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}-${String(date.getDate()).padStart(2, '0')}`;
+  };
+  const today = localDate(Date.now());
+  const todayMessages = [];
+  for (const file of files(path.join(state, 'history')).filter(name => name.endsWith('.jsonl'))) {
+    let lines;
+    try { lines = readFileSync(path.join(state, 'history', file), 'utf8').replace(/^\uFEFF/u, '').split(/\r?\n/u); }
+    catch { warnings.push(`${file}：历史文件无法读取，已略过`); continue; }
+    let broken = 0;
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      let item;
+      try { item = JSON.parse(line); } catch { broken++; continue; }
+      const text = textValue(item?.text);
+      const ts = parseTime(item?.t);
+      if (ts === null) continue;
+      // Shards reflect write time (UTC), not the message's local calendar day.
+      const day = localDate(ts);
+      const isToday = day === today;
+      if (Array.from(text).length < (isToday ? 8 : 12) || (isToday && item.self !== false)) continue;
+      const strength = emotionStrength(text);
+      if (!isToday && strength < 2) continue;
+      const key = `${ts}\0${norm(text)}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      if (isToday) {
+        todayMessages.push({ text, ts, who: item.who, file });
+        todayMessages.sort((a, b) => b.ts - a.ts);
+        if (todayMessages.length > 60) todayMessages.pop();
+        continue;
+      }
+      if (!days.has(day)) days.set(day, []);
+      const bucket = days.get(day);
+      bucket.push({ text, ts, strength, who: item.who, file });
+      bucket.sort((a, b) => b.strength - a.strength || a.ts - b.ts);
+      if (bucket.length > 6) bucket.pop();
+    }
+    if (broken) warnings.push(`${file}：略过 ${broken} 行不完整 JSON`);
+  }
+  for (const day of [...days.keys()].sort()) for (const item of days.get(day)) {
+    add('对话', { text: item.text, kind: '对话', ts: item.ts, who: item.who }, `state/history/${item.file}`);
+  }
+  for (const item of todayMessages.reverse()) {
+    const inferred = inferEmotion(item.text);
+    add('对话', { text: item.text, kind: '对话', ts: item.ts, who: item.who,
+      heat: inferred.emotion.length ? inferred.heat : 3 }, `state/history/${item.file}`);
+  }
+
+  const slang = readJson(path.join(state, 'slang.json'), []);
+  // Live bridge schema uses content/meaning/createdAt. Also accept the
+  // task's word/definition/at form when that shape is present.
+  const words = Array.isArray(slang) ? slang : Array.isArray(slang?.entries) ? slang.entries
+    : slang && typeof slang === 'object' ? Object.entries(slang).map(([word, item]) => typeof item === 'string' ? { word, definition: item } : { word, ...item }) : [];
+  for (const item of words) {
+    const word = textValue(item?.word ?? item?.term ?? item?.content);
+    const meaning = textValue(item?.definition ?? item?.meaning);
+    if (!word || !meaning) continue;
+    add('俚语', { text: `${word}：${meaning}`, kind: '知识', title: word,
+      ts: item.at ?? item.createdAt ?? item.updatedAt }, 'state/slang.json', item.id ? [item.id] : []);
+  }
+  if (invalid) warnings.push(`略过 ${invalid} 条正文或原始时间无效的记录（未用今天代替）`);
+  return { missing: false, root, entries, counts, warnings };
+}