@jacklika/dsh-memory-curator 0.1.0-alpha.1 → 0.1.0-alpha.11

package/README.md

@@ -4,7 +4,15 @@ Curator tools for the DSH memory vault. This package is a member of the `@jackli
 
 ## Tools
 
-- `memory_recall(query)` — Search the vault for prior notes before starting a task.
-- `memory_capture(title, summary, ...)` — Persist durable knowledge after significant work, with conflict detection and optional user approval.
+- `memory_recall(query)` — Search the vault for prior notes before starting a task. Returns `{ query, hits, total, truncated }`, where `total` is the vault-wide match count passed through from `wiki_search` and can exceed `hits.length` when either layer caps its results, and `truncated` is `true` whenever it did — recall reports its own 20-hit presentation cap, not only the search layer's — so a caller can tell "these are all the matches" from "there are more". Per-turn auto-capture notes from `memory-anchor` are hidden from the hit list and subtracted from `total`, so bookkeeping never crowds out curated knowledge; the match anchors on the notes namespace, so a curated note whose name merely shares the prefix is still returned.
+- `memory_capture(title, summary, ...)` — Persist durable knowledge after significant work, with conflict detection and optional user approval. Returns `{ written, id, mode, conflict, version, created?, updated?, committed? }`: `version` is the SHA-1 of the persisted note text, `created` is present on first capture, `updated` is present on appends, and `committed` is present when `memory-git` completed the commit.
+
+## Note ids
+
+When `id` is omitted, `memory_capture` derives it from the title: Unicode letters and digits are kept (NFC-normalized, lowercased) and every other run of characters becomes a single `-`, so CJK and other non-Latin titles stay readable and distinct. A title with no letters or digits at all falls back to `note-<12 hex chars of its sha256>`, so symbol-only captures never collapse into one shared file.
+
+## Overwriting a capture
+
+`mode: 'overwrite'` replaces the note body but merges its frontmatter: fields another writer recorded and the original `created` survive, `title` and `tags` come from this call, and `updated` is stamped. A first capture writes `created` only.
 
 See the Bundle documentation in `docs/usage.md` for configuration and workflow.

package/README.zh.md

@@ -4,7 +4,15 @@ DSH 记忆库的策展工具。本包是 `@jacklika/dsh-memory` Bundle 的成员
 
 ## 工具
 
-- `memory_recall(query)` — 在任务开始前搜索知识库中的相关笔记。
-- `memory_capture(title, summary, ...)` — 在有意义的任务结束后持久化知识，支持冲突检测与可选的用户审批。
+- `memory_recall(query)` — 在任务开始前搜索知识库中的相关笔记。返回 `{ query, hits, total, truncated }`，其中 `total` 是从 `wiki_search` 透传的全库命中数；任一层截断（搜索层上限或 recall 自身的 20 条展示上限）都会使 `total` 大于 `hits.length` 且 `truncated` 为 `true`——调用方因此能区分“这就是全部命中”与“还有更多”。`memory-anchor` 写入的逐回合自动入库笔记会从命中列表中隐藏，并从 `total` 中扣除，记账内容不会挤占策展知识；匹配锚定在策展区命名空间上，仅名字前缀相同的策展笔记仍会返回。
+- `memory_capture(title, summary, ...)` — 在有意义的任务结束后持久化知识，支持冲突检测与可选的用户审批。返回 `{ written, id, mode, conflict, version, created?, updated?, committed? }`：`version` 是持久化笔记文本的 SHA-1 指纹；首次入库返回 `created`；追加写入返回 `updated`；挂载 `memory-git` 完成提交时还会返回 `committed`。
+
+## 笔记 id
+
+省略 `id` 时，`memory_capture` 由标题推导笔记 id：保留 Unicode 字母与数字（先做 NFC 归一化并转小写），其余连续字符统一折叠为单个 `-`，因此中日韩等非拉丁标题依然可读且互不相同。完全不含字母与数字的标题退化为 `note-<标题 sha256 的前 12 位十六进制>`，纯符号标题的写入不会坍缩到同一个文件。
+
+## 覆盖式入库
+
+`mode: 'overwrite'` 替换笔记正文，但会合并既有 frontmatter：其他写入方记录的字段与原始 `created` 都保留，`title` 与 `tags` 以本次调用为准，并写入 `updated`。首次入库只写 `created`。
 
 配置与工作流请参阅 Bundle 文档 `docs/usage.zh.md`。

package/lib/index.js

@@ -7,10 +7,11 @@
  * shared curated zone.
  * @module @jacklika/dsh-memory-curator
  */
-import { randomUUID } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import z from '@deepseek-ai/schemastery';
 import { ToolCallId } from '@deepseek-ai/dsh-llm';
 import { defineTool } from '@deepseek-ai/dsh-tools';
+import { formatBeijingTime } from '@jacklika/dsh-memory-time';
 import yaml from 'js-yaml';
 /** Cordis plugin name used by loader diagnostics. */
 export const name = 'memory-curator';
@@ -22,18 +23,49 @@ export const Config = z.object({
     defaultScope: z.union(['shared', 'private']).default('shared'),
     notesDir: z.string().default('shared/notes'),
 });
-function normalizeTitle(title) {
-    return title.toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim();
+/**
+ * Fold a title to its comparison form: NFC, case-insensitive, every run of
+ * characters that are neither Unicode letters nor digits collapsed to one
+ * space. Keeping `\p{L}` means CJK and other non-Latin titles stay distinct
+ * instead of folding to the empty string they would all share.
+ */
+function foldTitle(title) {
+    return title.normalize('NFC').toLowerCase().replace(/[^\p{L}\p{N}]+/gu, ' ').trim();
+}
+const MAX_SLUG_LENGTH = 100;
+function hashTail(title, length = 12) {
+    return createHash('sha256').update(title.normalize('NFC')).digest('hex').slice(0, length);
 }
 function slugify(title) {
-    return title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+    let slug = foldTitle(title).replace(/ /g, '-');
+    // Emoji-only and punctuation-only titles fold to nothing; a stable content
+    // hash keeps them addressable and separate rather than sharing a bare ".md".
+    if (slug === '')
+        return `note-${hashTail(title)}`;
+    // Keep generated filenames bounded on all platforms. A long CJK title would
+    // otherwise create a very long filename; truncate and append a hash so the
+    // id remains deterministic and collision-resistant.
+    if (slug.length > MAX_SLUG_LENGTH) {
+        slug = `${slug.slice(0, 64)}-${hashTail(title)}`;
+    }
+    return slug;
 }
 function ensureMdExtension(id) {
     return id.endsWith('.md') ? id : `${id}.md`;
 }
+function isSafeNoteId(id) {
+    if (id === '' || id.startsWith('/') || id.startsWith('\\') || /^[A-Za-z]:/.test(id))
+        return false;
+    if (id.includes('\\'))
+        return false;
+    return !id.split('/').some(segment => segment === '..' || segment === '.');
+}
 function resolveNoteId(id, title, scope, notesDir) {
     if (id !== undefined && id !== '') {
         const withExt = ensureMdExtension(id);
+        if (!isSafeNoteId(withExt)) {
+            throw new Error(`memory-curator: invalid note id ${JSON.stringify(withExt)}: ids must be vault-relative paths without '..', '.', backslashes, leading slashes, or drive letters`);
+        }
         if (scope === 'private')
             return withExt;
         return withExt.startsWith('shared/') ? withExt : `${notesDir}/${withExt.replace(/^\//, '')}`;
@@ -65,16 +97,50 @@ async function callTool(ctx, exec, toolName, args) {
     return JSON.parse(textFromContent(result.content) || 'null');
 }
 function findConflicts(targetId, title, hits) {
-    const normalized = normalizeTitle(title);
+    const normalized = foldTitle(title);
+    const target = targetId.normalize('NFC').toLowerCase();
     return hits.filter(hit => {
-        if (hit.id.toLowerCase() === targetId.toLowerCase())
+        if (hit.id.normalize('NFC').toLowerCase() === target)
             return true;
-        return normalizeTitle(hit.title) === normalized;
+        // A title that folds to nothing carries no identity; matching it would make
+        // every untitled note a conflict with every other one.
+        return normalized !== '' && foldTitle(hit.title) === normalized;
     });
 }
 function dedupeHits(hits) {
     return [...new Map(hits.map(hit => [hit.id, hit])).values()];
 }
+/**
+ * Frontmatter for a capture that overwrites `id`. `wiki_write` overwrite
+ * replaces the whole file, so the note's existing fields have to be carried
+ * over here or an update silently drops whatever another writer recorded and
+ * resets `created` to the update time.
+ * @param ctx - registrant context carrying the tool registry.
+ * @param exec - the run context the nested read is dispatched under.
+ * @param id - vault-relative note id about to be overwritten.
+ * @param title - title from this capture; it wins over any stored one.
+ * @param tags - tags from this capture; they win over any stored ones.
+ * @param now - Beijing-time timestamp used for `created`/`updated`.
+ * @returns the merged frontmatter to serialize.
+ */
+async function overwriteFrontmatter(ctx, exec, id, title, tags, now) {
+    let existing;
+    try {
+        const note = await callTool(ctx, exec, 'wiki_read', { id });
+        if (note !== null && typeof note === 'object' && note.frontmatter !== null && typeof note.frontmatter === 'object') {
+            existing = note.frontmatter;
+        }
+    }
+    catch {
+        // No readable note at this id: the ordinary first capture of a new note.
+    }
+    const frontmatter = { ...existing, title, tags };
+    const created = existing?.created;
+    frontmatter.created = typeof created === 'string' && created !== '' ? created : now;
+    if (existing !== undefined)
+        frontmatter.updated = now;
+    return frontmatter;
+}
 /**
  * Register `memory_recall` and `memory_capture` on the tool registry.
  * @param ctx - registrant context carrying the tool registry.
@@ -90,7 +156,7 @@ export function apply(ctx, config) {
     const approval = ctx.get('approval');
     ctx.effect(() => ctx.tools.register(defineTool({
         name: 'memory_recall',
-        description: 'Search the memory vault for prior notes related to the current task or topic. Call this at the start of a development task to avoid asking the user to repeat context that is already captured. Returns matching note ids, titles, and backlink counts.',
+        description: 'Search the memory vault for prior notes related to the current task or topic. Call this at the start of a development task to avoid asking the user to repeat context that is already captured. Query terms are OR-matched and ranked by field-weighted relevance, so partial matches still return. Returns the matching note ids, titles, scores, and backlinks, plus total — how many notes matched before the result cap — and truncated, which is true when hits omits matches. A total above the returned hit count also means the list was truncated.',
         parameters: {
             query: {
                 type: 'string',
@@ -103,11 +169,42 @@ export function apply(ctx, config) {
             render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
         },
         async execute(args, exec) {
-            const hits = await callTool(ctx, exec, 'wiki_search', { query: args.query });
+            const search = await callTool(ctx, exec, 'wiki_search', { query: args.query });
+            // Mechanical per-turn summaries are useful for session replay, but they
+            // are not curated knowledge. Keep them out of proactive recall unless a
+            // caller explicitly searches the wiki. Two shapes exist under the notes
+            // dir: the current subdir `auto-capture/<session>.md` and the legacy flat
+            // `auto-capture-<session>.md`. A bare prefix or substring test would also
+            // swallow unrelated notes that merely share the text, such as
+            // `auto-capture-release-0.1.0-alpha.1.md`, so the flat form is matched by
+            // the exact charset memory-anchor can emit.
+            const notesPrefix = `${resolved.notesDir}/`;
+            const isAutoCapture = (id) => {
+                if (!id.startsWith(notesPrefix))
+                    return false;
+                const rest = id.slice(notesPrefix.length);
+                // The dir form is confined to the subdir, so any nested path is a capture.
+                if (rest.startsWith('auto-capture/'))
+                    return true;
+                // memory-anchor's sessionNoteId sanitizes the session id to [A-Za-z0-9_-]+,
+                // so a legacy flat capture never carries another dot in its file name;
+                // `release-0.1.0-alpha.1` and other dot-bearing names stay in recall.
+                return /^auto-capture-[A-Za-z0-9_-]+\.md$/.test(rest);
+            };
+            const curated = search.hits.filter(hit => !isAutoCapture(hit.id));
+            // `search.total` is the vault-wide count before the search-layer cap. If
+            // any auto-capture hits made it into the capped `hits` list, remove them
+            // from the total so curated numbers stay truthful.
+            const total = search.total - (search.hits.length - curated.length);
+            ctx.logger?.debug(`memory-curator: recall query=${args.query} hits=${curated.length} total=${total}`);
+            const hits = curated.slice(0, 20);
             return {
                 query: args.query,
-                hits: hits.slice(0, 20),
-                total: hits.length,
+                hits,
+                total,
+                // `wiki_search` reports its own cap; recall caps again at 20, so the
+                // page is incomplete whenever either cap bit.
+                truncated: search.truncated || curated.length > hits.length,
             };
         },
     })));
@@ -164,11 +261,11 @@ export function apply(ctx, config) {
             const targetId = resolveNoteId(args.id, args.title, scope, notesDir);
             const mode = args.mode ?? 'append';
             const tags = Array.isArray(args.tags) ? args.tags.map(String) : [];
-            const [titleHits, idHits] = await Promise.all([
+            const [titleSearch, idSearch] = await Promise.all([
                 callTool(ctx, exec, 'wiki_search', { query: args.title }),
                 callTool(ctx, exec, 'wiki_search', { query: targetId }),
             ]);
-            const conflicts = dedupeHits(findConflicts(targetId, args.title, [...titleHits, ...idHits]));
+            const conflicts = dedupeHits(findConflicts(targetId, args.title, [...titleSearch.hits, ...idSearch.hits]));
             const conflictExists = conflicts.length > 0;
             const finalId = conflicts[0]?.id ?? targetId;
             if (conflictExists) {
@@ -210,29 +307,35 @@ export function apply(ctx, config) {
                     };
                 }
             }
-            const now = new Date().toISOString();
+            const now = formatBeijingTime(new Date());
             const detailsText = args.details ? `\n\n## Details\n\n${args.details}` : '';
             const appendContent = `${args.summary}${detailsText}\n`;
-            const frontmatter = {
-                title: args.title,
-                tags,
-                created: now,
-            };
-            const newNoteContent = `---\n${yaml.dump(frontmatter).trim()}\n---\n\n# ${args.title}\n\n${appendContent}`;
             const appending = conflictExists && mode === 'append';
-            const content = appending ? appendContent : newNoteContent;
             const writeMode = appending ? 'append' : 'overwrite';
-            await callTool(ctx, exec, 'wiki_write', {
+            ctx.logger?.debug(`memory-curator: capture target=${finalId} conflicts=${conflicts.length} writeMode=${writeMode}`);
+            const frontmatter = appending ? undefined : await overwriteFrontmatter(ctx, exec, finalId, args.title, tags, now);
+            const content = appending
+                ? appendContent
+                : `---\n${yaml.dump(frontmatter).trim()}\n---\n\n# ${args.title}\n\n${appendContent}`;
+            const writeResult = await callTool(ctx, exec, 'wiki_write', {
                 id: finalId,
                 content,
                 mode: writeMode,
             });
-            return {
+            const response = {
                 written: true,
                 id: finalId,
                 mode: writeMode,
                 conflict: conflictExists,
+                version: writeResult.version,
             };
+            if (typeof writeResult.created === 'string' && writeResult.created !== '')
+                response.created = writeResult.created;
+            if (typeof writeResult.updated === 'string' && writeResult.updated !== '')
+                response.updated = writeResult.updated;
+            if (typeof writeResult.committed === 'boolean')
+                response.committed = writeResult.committed;
+            return response;
         },
     })));
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jacklika/dsh-memory-curator",
   "description": "Curator tools for the DSH memory vault: memory_recall before acting and memory_capture after significant work, with conflict detection and optional user approval.",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.11",
   "publishConfig": {
     "access": "public"
   },
@@ -32,17 +32,18 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "3.18.4",
-    "js-yaml": "^4.2.0"
+    "js-yaml": "^4.2.0",
+    "@jacklika/dsh-memory-time": "^0.1.0-alpha.0"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "4.0.4",
-    "@deepseek-ai/dsh-agent": ">=0.1.7-rc.1 <0.3.0-0",
-    "@deepseek-ai/dsh-llm": ">=0.1.7-rc.1 <0.3.0-0",
-    "@deepseek-ai/dsh-tools": ">=0.1.7-rc.1 <0.3.0-0",
-    "@deepseek-ai/dsh-user-approval": ">=0.1.7-rc.1 <0.3.0-0",
-    "@deepseek-ai/dsh-util-values": ">=0.1.7-rc.1 <0.3.0-0"
+    "@deepseek-ai/dsh-agent": ">=0.1.7-rc.1 <0.3.0-0 || >=0.2.0-rc.1 <0.3.0-0",
+    "@deepseek-ai/dsh-llm": ">=0.1.7-rc.1 <0.3.0-0 || >=0.2.0-rc.1 <0.3.0-0",
+    "@deepseek-ai/dsh-tools": ">=0.1.7-rc.1 <0.3.0-0 || >=0.2.0-rc.1 <0.3.0-0",
+    "@deepseek-ai/dsh-user-approval": ">=0.1.7-rc.1 <0.3.0-0 || >=0.2.0-rc.1 <0.3.0-0",
+    "@deepseek-ai/dsh-util-values": ">=0.1.7-rc.1 <0.3.0-0 || >=0.2.0-rc.1 <0.3.0-0"
   },
   "devDependencies": {
-    "@jacklika/dsh-tool-memory-filesystem": "0.1.3-alpha.2"
+    "@jacklika/dsh-tool-memory-filesystem": "^0.1.3-alpha.10"
   }
 }