dsh-memory-engine 0.5.4 → 0.5.6

package/README.md

@@ -10,6 +10,8 @@ DSH 插件的本地记忆引擎，带神经网络可视化。它让 agent 保存
 
 点击后全屏显示图谱，右上角 **关闭 ×** 或 **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：
@@ -86,6 +88,10 @@ memory_recall(q="朋友", limit=5)
 
 召回结果区分直接命中和联想到的记忆。`memory_stats()` 查看总数和分类；`memory_dedupe()` 默认仅预览重复组。`memory_forget` 支持按 id 精确删除；关键词批量删除必须先预览，并经用户确认后传 `confirm=true`。
 
+**检索是按字面词匹配，不做语义理解。** 库里写的是「古茗」，`memory_recall(q="奶茶")` 就查不到——必须先有「奶茶」这两个字。想覆盖这种情况，存记忆时把常见说法一起写进去（例如「阿木喝奶茶只点古茗的超A芝士葡萄」）。
+
+**联想到的记忆**来自关键词共享：两条记忆提到同一个词，就会被连起来，查其中一条时另一条一起返回。它不是推理，是顺着关联往外摸。扩散默认一跳（`hops=1`），邻居要留存 > 0.4 才会被带出来。
+
 ## 导入自己机器人的旧记忆
 
 三种格式都是你明确指定的本地文件或目录。如果旧格式均不匹配，可让有文件读取能力的 agent 理解文件，再通过 `memory_save` 逐条写入。导入先预览，用户确认后再传 `dry_run=false`。

package/lib/index.js

@@ -26,7 +26,9 @@ export function createTools(defineTool, store = new MemoryStore(), { map = gener
   return [
     defineTool({
       name: 'memory_save',
-      description: '把值得记住的事保存到跨会话的本地记忆。与 QQ 桥接记忆独立。重复正文自动合并。',
+      description: '把值得记住的事保存到跨会话的本地记忆。与 QQ 桥接记忆独立。重复正文自动合并。'
+        + '该存：对方的称呼/偏好/忌讳/习惯、答应过的事、情绪特别重的瞬间、新学到的知识、当天小结。'
+        + '不该存：寒暄、重复内容、纯事务性对话。一天三五条足够，存前可先用 memory_recall 查重。',
       parameters: {
         text: { type: 'string', required: true, description: '记忆正文，最多 2000 字' },
         kind: { type: 'string', description: '分类，默认对话；可用知识/印象/日记/对话/事件或自定义' },
@@ -135,10 +137,18 @@ export function createTools(defineTool, store = new MemoryStore(), { map = gener
       async execute() {
         const stats = store.stats();
         const kinds = Object.entries(stats.kinds).map(([kind, count]) => `${kind} ${count}`).join(' / ');
-        return `记忆引擎状态\n- 总条数：${stats.total}${kinds ? `（${kinds}）` : ''}\n`
+        const body = `记忆引擎状态\n- 总条数：${stats.total}${kinds ? `（${kinds}）` : ''}\n`
           + `- 快忘了的（留存<0.3）：${stats.fading} 条\n`
           + `- 最老：${stats.oldest === null ? '暂无' : `${new Date(stats.oldest).toISOString().slice(0, 10)}（${stats.ageDays} 天前）`}\n`
           + `- 存储：${stats.file}（${(stats.bytes / 1024).toFixed(1)} KB）`;
+        // 库是空的时，替 agent 把「接下来该做什么」说出来（见 README「装完是空库」）。
+        if (stats.total === 0) {
+          return body + '\n\n记忆库还是空的。插件不会自己读聊天记录，记忆要靠两件事之一进来：\n'
+            + '① 在提示词里告诉 agent 该记什么，聊天时就调 memory_save（推荐）\n'
+            + '② 用 memory_import 把旧记忆导进来（支持 json / markdown / text）\n'
+            + '建议主动把这两条简短告诉主人，并提醒他点开图谱可以看到上手引导页。';
+        }
+        return body;
       },
     }),
   ];

package/lib/serve.js

@@ -8,6 +8,86 @@ export const DEFAULT_UI_PORT = 18886;
 const pending = '<!doctype html><html lang="zh-CN"><meta charset="utf-8"><meta http-equiv="refresh" content="1"><title>记忆图谱生成中</title><body style="background:#03060c;color:#d8e9f8;font:16px system-ui;padding:40px">正在生成记忆图谱，请稍候……</body></html>';
 const escapeBridge = '<script>window.addEventListener("keydown",function(e){if(e.key==="Escape")parent.postMessage({type:"dsh-memory-engine-close"},"*")});</script>';
 
+// 空库时的上手引导页。
+// 为什么要有这一页：新装用户点开图谱看到的是一片黑，只会以为插件坏了。
+// 这个页面在他最想用的那一刻告诉他「为什么是空的、两件事怎么做」。
+const ONBOARD_PROMPT = [
+  '聊天时遇到这些，用 memory_save 记下来：',
+  '  · 对方的称呼、偏好、忌讳、习惯（kind="印象"，who 填对方名字）',
+  '  · 答应过的事、约定、承诺（kind="对话"）',
+  '  · 情绪特别重的瞬间（kind="事件"，heat=1）',
+  '  · 新学到的知识、名词、梗的解释（kind="知识"）',
+  '  · 每天结束时，用一两句写当天小结（kind="日记"）',
+  '',
+  '不用每条都记。一天三五条就够，宁可少存也别灌水。',
+  '存之前先 memory_recall 查一下，避免重复。',
+].join('\n');
+
+const onboard = `<!doctype html><html lang="zh-CN"><head><meta charset="utf-8">
+<title>还没有记忆</title>
+<style>
+  :root{color-scheme:dark}
+  *{box-sizing:border-box}
+  body{margin:0;min-height:100vh;background:radial-gradient(ellipse at 50% 0%,#0b1a2e 0%,#03060c 60%);
+    color:#dbeaf8;font:15px/1.75 "Microsoft YaHei",system-ui,sans-serif;display:flex;align-items:center;justify-content:center;padding:32px}
+  .card{width:min(760px,100%)}
+  h1{font-size:26px;margin:0 0 6px;font-weight:600;letter-spacing:.5px}
+  .sub{color:#7f9dbb;margin:0 0 26px;font-size:14px}
+  .step{border-left:3px solid #1f4d73;padding:2px 0 2px 16px;margin:0 0 24px}
+  .step h2{font-size:16px;margin:0 0 8px;color:#9fd0f5;font-weight:600}
+  .step p{margin:0 0 10px;color:#b6cde2;font-size:14px}
+  pre{background:#07121f;border:1px solid #17324b;border-radius:8px;padding:14px;overflow:auto;
+    font:13px/1.7 ui-monospace,Consolas,monospace;color:#b9d8f2;margin:0 0 10px;white-space:pre-wrap}
+  button{background:#123a5c;color:#cfe9ff;border:1px solid #2a6698;border-radius:7px;
+    padding:8px 16px;font:14px "Microsoft YaHei",system-ui;cursor:pointer}
+  button:hover{background:#17496f}
+  button:active{transform:translateY(1px)}
+  code{background:#0d1e30;border-radius:4px;padding:1px 5px;color:#8fd0ff;font-size:13px}
+  .foot{color:#5f7a93;font-size:13px;margin-top:8px}
+</style></head><body><div class="card">
+  <h1>记忆库还是空的</h1>
+  <p class="sub">插件不会自己读你的聊天记录。记忆要靠下面两件事之一进来。</p>
+
+  <div class="step">
+    <h2>① 让它边聊边记（推荐）</h2>
+    <p>把这段加进 agent 的提示词或角色卡里：</p>
+    <pre id="prompt">${ONBOARD_PROMPT.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')}</pre>
+    <button id="copy">复制这段提示词</button>
+  </div>
+
+  <div class="step">
+    <h2>② 或者把旧记忆导进来</h2>
+    <p>让 agent 调用 <code>memory_import</code>，支持三种格式：</p>
+    <pre>memory_import(source="json", path="D:\\\\bot\\\\memories.json")
+memory_import(source="markdown", path="D:\\\\bot\\\\notes")
+memory_import(source="text", path="D:\\\\bot\\\\memories.txt")</pre>
+    <p class="foot">会先预览「能新增多少条、多少条重复被跳过」，确认后再写。</p>
+  </div>
+
+  <div class="step">
+    <h2>③ 然后就有图了</h2>
+    <p>有了几条记忆之后，回到这个按钮，就能看到神经网络。</p>
+    <p class="foot">记忆只存在本机 <code>~/.dsh/memory-engine/</code>，不上传、不联网。</p>
+  </div>
+</div>
+<script>
+  var btn = document.getElementById('copy');
+  btn.addEventListener('click', function () {
+    var text = document.getElementById('prompt').textContent;
+    var done = function () { btn.textContent = '已复制 ✓'; setTimeout(function () { btn.textContent = '复制这段提示词'; }, 1800); };
+    if (navigator.clipboard && navigator.clipboard.writeText) {
+      navigator.clipboard.writeText(text).then(done, fallback);
+    } else { fallback(); }
+    function fallback() {
+      var area = document.createElement('textarea');
+      area.value = text; document.body.appendChild(area); area.select();
+      try { document.execCommand('copy'); done(); } catch (e) { btn.textContent = '请手动选中复制'; }
+      document.body.removeChild(area);
+    }
+  });
+</script>
+</body></html>`;
+
 export async function startMapServer({ store, port, warn = () => {} }) {
   const directory = path.dirname(store.file);
   const config = readConfig(path.dirname(directory));
@@ -27,6 +107,10 @@ export async function startMapServer({ store, port, warn = () => {} }) {
       const rootPage = ['/', '/index.html', '/starmap.html'].includes(url.pathname);
       if (!rootPage && !/^\/pages\/[1-9]\d*\.html$/u.test(url.pathname)) return reply(404);
       if (rootPage) {
+        // 空库直接返回上手引导页：不要让人对着黑屏猜「是不是坏了」
+        let rows = [];
+        try { rows = store.read(); } catch (error) { warn(`记忆库读取失败：${error.message}`); }
+        if (!Array.isArray(rows) || rows.length === 0) return reply(200, onboard + escapeBridge);
         let signature = 'empty';
         try { const info = fs.statSync(store.file); signature = `${info.mtimeMs}:${info.size}`; }
         catch (error) { if (error.code !== 'ENOENT') throw error; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-memory-engine",
-  "version": "0.5.4",
+  "version": "0.5.6",
   "description": "Local DSH memory engine with neuron network visualization and private file import",
   "keywords": [
     "dsh",