dsh-memory-github 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # 更新日志
 
+## 0.3.0 — 2026-10-25
+
+参考同类插件（dsh-prime-memory、meow-memory、@try-works/dsh-memory、@modusensus/dsh-mneme 等
+百余个生态作品）后补齐的「记忆全生命周期」能力。仍然零依赖、纯 Markdown + git。
+
+### 新增
+
+- **`memory_update`**：改已有归档的 title / tags / content，刷新 `updated` 并自动提交推送。
+- **`memory_forget`**：`archive`（移到 `notes/archive/`，可回滚）或 `delete`（直接删文件）。
+- **`memory_stats`**：条数、总大小、标签分布、核心记忆长度、后端信息、最近更新时间。
+- **`memory_history`**：GitHub 后端的提交历史，可追溯某条记忆何时被哪个工具写进来。
+- **`recentLimit`**：每轮在系统提示末尾注入最近 N 条归档的 id / 标题 / 标签（默认关）。
+  竞品普遍靠「自动召回」提升命中率；这个是最便宜的近似做法，不引入数据库。
+- **查重提示**：`memory_write` 写入前与已有归档做词袋 Jaccard 比较（≥45%），
+  命中就在返回里提示「考虑用 `memory_update`」，减少同一件事写两遍。可用 `dedupeHint: false` 关闭。
+
+### 改进
+
+- `findNote` 现在支持三种定位方式：id 精确 / id 前缀 / **标题** / id 含该 slug，
+  并且多处命中时明确列出候选，不再直接报"找不到"。
+- 只读模式（`role: child`）下新增的两个读工具 `memory_stats`、`memory_history` 也可用。
+
+### 测试
+
+- 冒烟测试从 42 条扩到 **63 条**（覆盖 update / forget / stats / history / recentLimit / 查重）。
+
 ## 0.2.0 — 2026-10-25
 
 ### 新增

package/README.md

@@ -113,13 +113,24 @@ dsh plugin --profile desktop add link:/path/to/dsh-memory-github
 
 | 工具 | 作用 |
 |---|---|
-| `memory_write` | 保存一条归档记忆（title / content / tags），立刻进索引 |
+| `memory_write` | 保存一条归档记忆（title / content / tags），立刻进索引；写入前会做**相似度查重** |
+| `memory_update` | 改已有归档的 title / tags / content，刷新 `updated` |
+| `memory_forget` | `archive`（移到 `notes/archive/` 可回滚）或 `delete` |
 | `memory_core` | 编辑 `MEMORY.md`：`append` / `replace` / `remove` 某个分节 |
 | `memory_search` | 按关键词检索（标题权重 6、标签 3、正文按出现次数），返回摘要 |
 | `memory_read` | 按 id 读全文，支持唯一前缀 |
 | `memory_list` | 列出归档（新→旧），可按标签过滤 |
+| `memory_stats` | 条数、总大小、标签分布、核心记忆长度、后端与最近更新 |
+| `memory_history` | 提交历史（GitHub 后端），追溯某条记忆是何时被哪个工具写进来的 |
 | `memory_sync` | `status` / `pull` / `push`，GitHub 后端专用 |
 
+**查重**：`memory_write` 会把新内容与已有归档做词袋相似度比较（Jaccard ≥ 45% 视为高度相似），
+命中时在返回里提示「考虑改用 `memory_update`」。关掉：`dedupeHint: false`。
+
+**最近归档注入**：`recentLimit: 5` 会在每轮系统提示末尾附上最近 5 条归档的 id/标题/标签，
+让模型"看得见目录"，召回率比纯靠 `memory_search` 高。默认关闭（`0`）。
+
+
 模型侧的使用约定由插件注入的系统提示承载：核心记忆里写"永远要记住的"，
 归档里写"以后可能用得上、但不用每轮都占上下文的"。
 

package/lib/index.js

@@ -12,7 +12,7 @@
  *   - readOnly=true 时只注册读工具，适合"手机写入、电脑只读"这类分工
  */
 import {
-  existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync,
+  existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync,
 } from 'node:fs';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
@@ -34,6 +34,8 @@ const DEFAULTS = {
   pushOnTurnEnd: false,    // 每轮结束时若有未提交改动就推送
   remindEvery: 6,          // 每 N 条用户消息、且期间没动过记忆 → 提醒（0=关）
   staleMinutes: 0,         // 距上次同步超过 N 分钟 → 提醒（0=关）
+  recentLimit: 0,          // 每轮额外注入最近 N 条归档的标题与标签（0=关）
+  dedupeHint: true,        // 写入时检查是否与已有归档高度相似
   commitMessage: 'memory: {tool}',
   gitBin: 'git',
   authorName: 'dsh-memory',
@@ -179,6 +181,85 @@ function saveIndex(p, notes) {
   return sorted;
 }
 
+/** 按 id（或唯一前缀）找到一条归档。 */
+function findNote(p, want) {
+  const id = String(want ?? '').replace(/\.md$/, '').trim();
+  if (!id) return { error: 'id 不能为空。' };
+  const notes = loadIndex(p);
+  const exact = notes.find((n) => n.id === id);
+  if (exact) return { note: exact, notes };
+
+  // 依次尝试：id 前缀 / 标题（忽略大小写）/ id 后缀（用户常只给 slug）
+  const byPrefix = notes.filter((n) => n.id.startsWith(id));
+  if (byPrefix.length === 1) return { note: byPrefix[0], notes };
+  const lower = id.toLowerCase();
+  const byTitle = notes.filter((n) => String(n.title ?? '').toLowerCase() === lower);
+  if (byTitle.length === 1) return { note: byTitle[0], notes };
+  const bySuffix = notes.filter((n) => n.id.includes(`-${id}`));
+  if (bySuffix.length === 1) return { note: bySuffix[0], notes };
+
+  const candidates = [...byPrefix, ...byTitle, ...bySuffix].filter((n, i, arr) => arr.findIndex((x) => x.id === n.id) === i);
+  if (candidates.length > 1) {
+    return {
+      error: `「${id}」匹配到 ${candidates.length} 条，请给更长前缀或完整 id：\n`
+        + candidates.map((n) => `- ${n.id}  ${n.title}`).join('\n'),
+    };
+  }
+  return { error: `没有找到 id 为「${id}」的记忆。` };
+}
+
+/** 词袋：用于相似度判断（标题 / 标签 / 正文前 600 字）。 */
+function tokenSet(text) {
+  const set = new Set();
+  for (const tok of String(text ?? '').toLowerCase().split(/[^\p{L}\p{N}]+/u)) {
+    if (tok && tok.length > 1) set.add(tok);
+  }
+  return set;
+}
+
+function jaccard(a, b) {
+  if (!a.size || !b.size) return 0;
+  let inter = 0;
+  for (const x of a) if (b.has(x)) inter += 1;
+  return inter / (a.size + b.size - inter);
+}
+
+/** 写入前查重：返回最多 3 条高相似（Jaccard ≥ 0.45）的归档。 */
+function similarNotes(p, title, content) {
+  const mine = tokenSet(`${title} ${String(content ?? '').slice(0, 600)}`);
+  const hits = [];
+  for (const n of loadIndex(p)) {
+    // 只比正文，不要把 frontmatter 里的 id/时间戳算进相似度，否则会把相似度稀释掉
+    const parsed = parseNoteFile(readTextSafe(join(p.notes, `${n.id}.md`), ''));
+    const body = parsed.content ?? '';
+    const theirs = tokenSet(`${n.title} ${(n.tags ?? []).join(' ')} ${body.slice(0, 600)}`);
+    const score = jaccard(mine, theirs);
+    if (score >= 0.45) hits.push({ id: n.id, title: n.title, score });
+  }
+  hits.sort((a, b) => b.score - a.score);
+  return hits.slice(0, 3);
+}
+
+/** 把归档移到 notes/archive/（保留内容，可回滚）。 */
+function archiveNoteFile(p, id) {
+  const dir = join(p.notes, 'archive');
+  mkdirSync(dir, { recursive: true });
+  const from = join(p.notes, `${id}.md`);
+  const to = join(dir, `${id}.md`);
+  renameSync(from, to);
+  return to;
+}
+
+/** 最近 N 条归档的标题清单，用于注入系统提示。 */
+function recentSection(p, limit) {
+  const n = Number(limit);
+  if (!Number.isFinite(n) || n <= 0) return '';
+  const notes = loadIndex(p).slice(0, Math.floor(n));
+  if (!notes.length) return '';
+  const lines = notes.map((x) => `- \`${x.id}\` ${x.title}${(x.tags ?? []).length ? '  #' + x.tags.join(' #') : ''}`);
+  return ['', `### 最近归档（${notes.length} 条，细节用 memory_search）`, ...lines].join('\n');
+}
+
 // ---------------------------------------------------------------- core 记忆
 
 function coreLimit(config) {
@@ -495,7 +576,7 @@ export function apply(ctx, config0) {
     name: 'dsh-memory-github:core',
     order: 60,
     text: () => {
-      const base = coreSection(readCore(p), coreLimit(config));
+      const base = coreSection(readCore(p), coreLimit(config)) + recentSection(p, config.recentLimit);
       const stamp = activityStamp(p);
       if (stamp > syncState.lastActivity) {
         // 记忆被写过（本进程写的，或别的进程/设备同步下来的），计数归零
@@ -564,6 +645,9 @@ export function apply(ctx, config0) {
           ? args.tags.filter((t) => typeof t === 'string' && t.trim()).map((t) => t.trim())
           : [];
         try {
+          const dupes = config.dedupeHint === false
+            ? []
+            : similarNotes(p, title, content);
           return await enqueue(() => {
             ensureDirs(p);
             const notes = loadIndex(p);
@@ -576,7 +660,11 @@ export function apply(ctx, config0) {
             atomicWrite(join(p.notes, `${id}.md`), text);
             saveIndex(p, [meta, ...notes]);
             const sync = afterWrite('memory_write');
-            return `已保存 [${id}] ${title}${tags.length ? ' #' + tags.join(' #') : ''}。${sync}`;
+            const hint = dupes.length
+              ? '\n注意：和已有归档高度相似，考虑改用 memory_update：\n'
+                + dupes.map((d) => `- ${d.id}  ${d.title}（相似度 ${(d.score * 100).toFixed(0)}%）`).join('\n')
+              : '';
+            return `已保存 [${id}] ${title}${tags.length ? ' #' + tags.join(' #') : ''}。${sync}${hint}`;
           });
         } catch (e) {
           return errText(e);
@@ -699,6 +787,142 @@ export function apply(ctx, config0) {
         }
       },
     },
+    {
+      name: 'memory_update',
+      description: '修改一条已有归档记忆（title / tags / content 三选一或多选）。id 支持唯一前缀。修改后 updated 时间会刷新，GitHub 后端会自动提交推送。',
+      parameters: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          id: { type: 'string', description: '记忆 id，支持唯一前缀' },
+          title: { type: 'string', description: '新标题（可选）' },
+          content: { type: 'string', description: '新正文（可选，整体替换）' },
+          tags: { type: 'array', items: { type: 'string' }, description: '新标签列表（可选，整体替换）' },
+        },
+        required: ['id'],
+      },
+      output: outputText,
+      async execute(args) {
+        try {
+          return await enqueue(() => {
+            const found = findNote(p, args.id);
+            if (found.error) return found.error;
+            const note = found.note;
+            const file = join(p.notes, `${note.id}.md`);
+            const parsed = parseNoteFile(readTextSafe(file));
+            const oldContent = parsed.content ?? '';
+            const nextMeta = {
+              id: note.id,
+              title: typeof args.title === 'string' && args.title.trim() ? args.title.replace(/\s+/g, ' ').trim() : note.title,
+              tags: Array.isArray(args.tags)
+                ? args.tags.filter((t) => typeof t === 'string' && t.trim()).map((t) => t.trim())
+                : (note.tags ?? []),
+              created: note.created,
+              updated: new Date().toISOString(),
+            };
+            const nextContent = typeof args.content === 'string' ? args.content : oldContent;
+            if (!nextContent.trim()) return '更新失败：content 不能为空。';
+            const text = noteFileText(nextMeta, nextContent);
+            atomicWrite(file, text);
+            const notes = found.notes.map((n) => (n.id === note.id
+              ? { ...n, title: nextMeta.title, tags: nextMeta.tags, updated: nextMeta.updated, size: Buffer.byteLength(text) }
+              : n));
+            saveIndex(p, notes);
+            const sync = afterWrite('memory_update');
+            return `已更新 [${note.id}] ${nextMeta.title}。${sync}`;
+          });
+        } catch (e) {
+          return errText(e);
+        }
+      },
+    },
+    {
+      name: 'memory_forget',
+      description: '处理一条不再需要的归档记忆。mode=archive（默认）移到 notes/archive/ 保留可回滚；mode=delete 直接从 notes/ 删除文件。',
+      parameters: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          id: { type: 'string', description: '记忆 id，支持唯一前缀' },
+          mode: { type: 'string', enum: ['archive', 'delete'], description: '默认 archive' },
+        },
+        required: ['id'],
+      },
+      output: outputText,
+      async execute(args) {
+        try {
+          return await enqueue(() => {
+            const found = findNote(p, args.id);
+            if (found.error) return found.error;
+            const note = found.note;
+            const mode = args.mode === 'delete' ? 'delete' : 'archive';
+            const file = join(p.notes, `${note.id}.md`);
+            if (mode === 'delete') {
+              if (existsSync(file)) unlinkSync(file);
+            } else {
+              archiveNoteFile(p, note.id);
+            }
+            saveIndex(p, found.notes.filter((n) => n.id !== note.id));
+            const sync = afterWrite(`memory_forget:${mode}`);
+            return `已${mode === 'delete' ? '删除' : '归档'} [${note.id}] ${note.title}。${sync}`;
+          });
+        } catch (e) {
+          return errText(e);
+        }
+      },
+    },
+    {
+      name: 'memory_stats',
+      description: '记忆库概况：归档条数、总大小、标签分布、核心记忆长度、后端与最近更新时间。',
+      parameters: { type: 'object', additionalProperties: false, properties: {} },
+      output: outputText,
+      async execute() {
+        try {
+          const notes = loadIndex(p);
+          const tags = new Map();
+          let bytes = 0;
+          for (const n of notes) {
+            bytes += n.size ?? 0;
+            for (const t of n.tags ?? []) tags.set(t, (tags.get(t) ?? 0) + 1);
+          }
+          const core = readCore(p);
+          const lines = [
+            `目录：${p.dir}`,
+            `归档：${notes.length} 条，共 ${(bytes / 1024).toFixed(1)} KB`,
+            `核心记忆：${core.trim() ? `${core.length} 字符` : '空'}`,
+            `后端：${config.backend}${githubMode ? `（${config.remote || '未设 remote'} · ${config.branch}）` : ''}`,
+            `最近更新：${notes[0]?.updated ?? '—'}`,
+          ];
+          if (tags.size) {
+            lines.push(`标签：${[...tags.entries()].sort((a, b) => b[1] - a[1]).map(([t, c]) => `${t}(${c})`).join(' ')}`);
+          }
+          return lines.join('\n');
+        } catch (e) {
+          return errText(e);
+        }
+      },
+    },
+    {
+      name: 'memory_history',
+      description: '看记忆库的提交历史（仅 GitHub 后端）。返回最近若干次提交的 hash 与信息，用来追溯某条记忆是什么时候、被哪个工具写进来的。',
+      parameters: {
+        type: 'object',
+        additionalProperties: false,
+        properties: { limit: { type: 'integer', description: '条数，默认 10' } },
+      },
+      output: outputText,
+      async execute(args) {
+        if (!githubMode) return '当前是 local 后端，没有提交历史。';
+        try {
+          const n = Math.max(1, Math.min(Number(args.limit) || 10, 100));
+          const r = git(p, config, ['log', `-${n}`, '--pretty=format:%h  %ad  %s', '--date=short']);
+          if (r.status !== 0) return `读取历史失败：${(r.stderr || r.stdout || '').trim() || `exit ${r.status}`}`;
+          return (r.stdout || '').trim() || '还没有提交记录。';
+        } catch (e) {
+          return errText(e);
+        }
+      },
+    },
     {
       name: 'memory_sync',
       description: 'GitHub 后端专用：action=status 看仓库状态，pull 拉取远端，push 提交并推送本地改动。local 后端调用会提示未启用。',
@@ -744,7 +968,7 @@ export function apply(ctx, config0) {
     },
   ];
 
-  const WRITE_TOOLS = new Set(['memory_write', 'memory_core']);
+  const WRITE_TOOLS = new Set(['memory_write', 'memory_core', 'memory_update', 'memory_forget']);
   const registered = [];
   for (const def of defs) {
     if (readOnly && WRITE_TOOLS.has(def.name)) continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-memory-github",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Cross-session memory for DeepSeek Harness. Local memory store by default, optional GitHub-backed sync (git), with primary/child roles for multi-device setups.",
   "type": "module",
   "main": "lib/index.js",