@jacklika/dsh-memory-curator 0.1.0-alpha.13 → 0.1.0-alpha.14

package/README.md

@@ -5,7 +5,7 @@ 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. 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. Set `requireExisting: true` for an update-only capture: it updates a note that must already exist, appends when `mode` is `append` (the default), and fails instead of creating a missing note. Because changing that note is the declared intent, no conflict approval is requested. 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. `conflict` reports a detected match that needed a policy decision, so a successful update-only capture reports `false`.
+- `memory_capture(title, summary, ...)` — Persist durable knowledge after significant work, with conflict detection and optional user approval. Set `requireExisting: true` for an update-only capture targeting the exact derived or explicit `id` (title matches do not redirect it): it replaces the body of an existing note by default (provide the complete current summary), preserves `created` and other frontmatter fields, and fails instead of creating a missing note. Pass `mode: 'append'` explicitly only to add genuinely new material; old text remains visible. Without `requireExisting`, approved conflicts still default to append. Because changing that note is the declared intent, no conflict approval is requested. 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 updates, and `committed` is present when `memory-git` completed the commit. `conflict` reports a detected match that needed a policy decision, so a successful update-only capture reports `false`.
 
 ## Note ids
 
@@ -13,6 +13,6 @@ When `id` is omitted, `memory_capture` derives it from the title: Unicode letter
 
 ## 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.
+`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. An intervening change detected between reading the old note and writing it fails instead of replacing that change. A first capture writes `created` only.
 
 See the Bundle documentation in `docs/usage.md` for configuration and workflow.

package/README.zh.md

@@ -5,7 +5,7 @@ DSH 记忆库的策展工具。本包是 `@jacklika/dsh-memory` Bundle 的成员
 ## 工具
 
 - `memory_recall(query)` — 在任务开始前搜索知识库中的相关笔记。返回 `{ query, hits, total, truncated }`，其中 `total` 是从 `wiki_search` 透传的全库命中数；任一层截断（搜索层上限或 recall 自身的 20 条展示上限）都会使 `total` 大于 `hits.length` 且 `truncated` 为 `true`——调用方因此能区分“这就是全部命中”与“还有更多”。`memory-anchor` 写入的逐回合自动入库笔记会从命中列表中隐藏，并从 `total` 中扣除，记账内容不会挤占策展知识；匹配锚定在策展区命名空间上，仅名字前缀相同的策展笔记仍会返回。
-- `memory_capture(title, summary, ...)` — 在有意义的任务结束后持久化知识，支持冲突检测与可选的用户审批。设置 `requireExisting: true` 表示只更新、不新建：目标笔记必须已存在，`mode` 为默认的 `append` 时追加写入，笔记缺失时直接失败而不会创建。由于“更新这篇笔记”本身就是声明的意图，此类调用不会请求冲突审批。返回 `{ written, id, mode, conflict, version, created?, updated?, committed? }`：`version` 是持久化笔记文本的 SHA-1 指纹；首次入库返回 `created`；追加写入返回 `updated`；挂载 `memory-git` 完成提交时还会返回 `committed`。`conflict` 表示检测到的命中需要策略裁决，因此成功执行的只更新捕获会返回 `false`。
+- `memory_capture(title, summary, ...)` — 在有意义的任务结束后持久化知识，支持冲突检测与可选的用户审批。设置 `requireExisting: true` 表示只更新、不新建，严格使用标题推导或显式给出的目标 `id`（不会重定向到同标题的其他笔记）：默认覆盖现有笔记的正文（`summary` 应包含完整的当前结论），保留 `created` 等既有 frontmatter 字段；笔记缺失时直接失败而不会创建。只有新增材料才显式传 `mode: 'append'`，此时旧正文仍可见。不设置 `requireExisting` 时，经批准的冲突写入仍默认追加。由于“更新这篇笔记”本身就是声明的意图，此类调用不会请求冲突审批。返回 `{ written, id, mode, conflict, version, created?, updated?, committed? }`：`version` 是持久化笔记文本的 SHA-1 指纹；首次入库返回 `created`；更新写入返回 `updated`；挂载 `memory-git` 完成提交时还会返回 `committed`。`conflict` 表示检测到的命中需要策略裁决，因此成功执行的只更新捕获会返回 `false`。
 
 ## 笔记 id
 
@@ -13,6 +13,6 @@ DSH 记忆库的策展工具。本包是 `@jacklika/dsh-memory` Bundle 的成员
 
 ## 覆盖式入库
 
-`mode: 'overwrite'` 替换笔记正文，但会合并既有 frontmatter：其他写入方记录的字段与原始 `created` 都保留，`title` 与 `tags` 以本次调用为准，并写入 `updated`。首次入库只写 `created`。
+`mode: 'overwrite'` 替换笔记正文，但会合并既有 frontmatter：其他写入方记录的字段与原始 `created` 都保留，`title` 与 `tags` 以本次调用为准，并写入 `updated`。如果从读取旧笔记到写入之间检测到其他修改，则拒绝覆盖该修改。首次入库只写 `created`。
 
 配置与工作流请参阅 Bundle 文档 `docs/usage.zh.md`。

package/lib/index.js

@@ -121,14 +121,17 @@ function dedupeHits(hits) {
  * @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.
+ * @returns the stored frontmatter and version for a guarded write.
  */
 async function readFrontmatter(ctx, exec, id) {
     try {
         const note = await callTool(ctx, exec, 'wiki_read', { id });
-        return note !== null && typeof note === 'object' && note.frontmatter !== null && typeof note.frontmatter === 'object'
-            ? note.frontmatter
-            : {};
+        return {
+            frontmatter: note !== null && typeof note === 'object' && note.frontmatter !== null && typeof note.frontmatter === 'object'
+                ? note.frontmatter
+                : {},
+            version: note.version,
+        };
     }
     catch (error) {
         // Only a missing note means a first capture: `wiki_read` reports it as
@@ -141,12 +144,12 @@ async function readFrontmatter(ctx, exec, id) {
 }
 async function overwriteFrontmatter(ctx, exec, id, title, tags, now) {
     const existing = await readFrontmatter(ctx, exec, id);
-    const frontmatter = { ...existing, title, tags };
-    const created = existing?.created;
+    const frontmatter = { ...existing?.frontmatter, title, tags };
+    const created = existing?.frontmatter.created;
     frontmatter.created = typeof created === 'string' && created !== '' ? created : now;
     if (existing !== undefined)
         frontmatter.updated = now;
-    return frontmatter;
+    return { frontmatter, ...(existing !== undefined ? { baseVersion: existing.version } : {}) };
 }
 /**
  * Register `memory_recall` and `memory_capture` on the tool registry.
@@ -217,7 +220,7 @@ export function apply(ctx, config) {
     })));
     ctx.effect(() => ctx.tools.register(defineTool({
         name: 'memory_capture',
-        description: 'Persist durable knowledge to the memory vault. Call this at the end of a significant task to capture decisions, discovered APIs, project conventions, fixes, or user preferences. It checks for conflicting notes, asks for approval when a conflict is found, and writes the captured note to the shared curated zone by default. Set requireExisting to declare an update: the capture then only modifies a note that already exists and needs no conflict approval.',
+        description: 'Persist durable knowledge to the memory vault. Call this at the end of a significant task to capture decisions, discovered APIs, project conventions, fixes, or user preferences. It checks for conflicting notes, asks for approval when a conflict is found, and writes the captured note to the shared curated zone by default. Set requireExisting to replace an existing note with one current version without conflict approval; use mode: append only for genuinely additive material.',
         parameters: {
             title: {
                 type: 'string',
@@ -227,7 +230,7 @@ export function apply(ctx, config) {
             summary: {
                 type: 'string',
                 required: true,
-                description: 'The durable knowledge to record: the decision, API, convention, or fix in concise Markdown.',
+                description: 'The durable knowledge to record in concise Markdown. For a correction using requireExisting, provide the complete current conclusion, not only the changed fragment.',
             },
             details: {
                 type: 'string',
@@ -250,7 +253,7 @@ export function apply(ctx, config) {
             mode: {
                 type: 'string',
                 enum: ['append', 'overwrite'],
-                description: 'When a conflict is approved or the note exists, append adds a timestamped section; overwrite replaces the whole body. Defaults to append.',
+                description: 'Use overwrite when the new summary supersedes an old conclusion; it replaces the whole body. Use append only for genuinely additive material: it adds a timestamped section and leaves the old text visible. Defaults to overwrite with requireExisting, otherwise append.',
             },
             conflictPolicy: {
                 type: 'string',
@@ -259,7 +262,7 @@ export function apply(ctx, config) {
             },
             requireExisting: {
                 type: 'boolean',
-                description: 'Update-only capture: the note must already exist, and a conflict needs no approval because updating that note is the declared intent. A missing note fails instead of creating one.',
+                description: 'Update-only capture: the note must exist and needs no conflict approval. Defaults to overwrite with a complete replacement summary; pass mode: append explicitly for additive material. A missing note fails instead of creating one.',
             },
         },
         output: {
@@ -270,8 +273,8 @@ export function apply(ctx, config) {
             const scope = args.scope ?? resolved.defaultScope;
             const notesDir = scope === 'shared' ? resolved.notesDir : '';
             const targetId = resolveNoteId(args.id, args.title, scope, notesDir);
-            const mode = args.mode ?? 'append';
             const requireExisting = args.requireExisting === true;
+            const mode = args.mode ?? (requireExisting ? 'overwrite' : 'append');
             const tags = Array.isArray(args.tags) ? args.tags.map(String) : [];
             const [titleSearch, idSearch] = await Promise.all([
                 callTool(ctx, exec, 'wiki_search', { query: args.title }),
@@ -279,7 +282,7 @@ export function apply(ctx, config) {
             ]);
             const conflicts = dedupeHits(findConflicts(targetId, args.title, [...titleSearch.hits, ...idSearch.hits]));
             const conflictExists = conflicts.length > 0;
-            const finalId = conflicts[0]?.id ?? targetId;
+            const finalId = requireExisting ? targetId : conflicts[0]?.id ?? targetId;
             // A declared update-only capture targets an existing note by
             // construction, so the approval that guards against accidentally
             // clobbering one while creating is not required; `wiki_write` enforces
@@ -307,9 +310,9 @@ export function apply(ctx, config) {
                     agent: exec.agent,
                     toolName: 'memory_capture',
                     callId: exec.callId,
-                    reason: `memory_capture conflicts with existing note(s):\n${conflictList}\nProposed action: ${mode === 'append' ? 'append a new section to' : 'overwrite'} "${finalId}".`,
+                    reason: `memory_capture conflicts with existing note(s):\n${conflictList}\nProposed action: ${mode === 'append' ? 'append a new section (old text remains visible) to' : 'replace the entire body of'} "${finalId}".`,
                     displayReason: {
-                        en: `Memory capture conflicts with existing note(s):\n${conflictList}\nAllow ${mode} to "${finalId}"?`,
+                        en: `Memory capture conflicts with existing note(s):\n${conflictList}\nAllow ${mode} to "${finalId}"? ${mode === 'append' ? 'Old conclusions remain visible.' : 'The old body is replaced.'}`,
                     },
                     signal: exec.signal,
                 });
@@ -326,24 +329,25 @@ export function apply(ctx, config) {
             const now = formatBeijingTime(new Date());
             const detailsText = args.details ? `\n\n## Details\n\n${args.details}` : '';
             const appendContent = `${args.summary}${detailsText}\n`;
-            // A conflict already proves the note exists, so the write appends. An
-            // update-only capture without a detected conflict has to ask the vault
-            // instead of the search: a note missed by the ranking must be appended
-            // to, and one that is genuinely absent fails the write rather than
-            // replacing it. The other path stays conflict-driven so an ordinary new
-            // capture keeps creating its note.
+            // A conflict suggests the note exists, but update-only writes use the
+            // exact target id and ask the vault instead of relying on search ranking.
+            // A missing note fails the write; other captures stay conflict-driven
+            // and create new notes. Overwrites carry the read version to wiki_write
+            // so an intervening change is refused rather than silently replaced.
+            // Append remains available when the caller requests additive material.
             const exists = requireExisting ? (await readFrontmatter(ctx, exec, finalId)) !== undefined : conflictExists;
             const appending = exists && mode === 'append';
             const writeMode = appending ? 'append' : 'overwrite';
             ctx.logger?.debug(`memory-curator: capture target=${finalId} conflicts=${conflicts.length} writeMode=${writeMode} requireExisting=${requireExisting}`);
-            const frontmatter = appending ? undefined : await overwriteFrontmatter(ctx, exec, finalId, args.title, tags, now);
+            const overwrite = 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}`;
+                : `---\n${yaml.dump(overwrite?.frontmatter).trim()}\n---\n\n# ${args.title}\n\n${appendContent}`;
             const writeResult = await callTool(ctx, exec, 'wiki_write', {
                 id: finalId,
                 content,
                 mode: writeMode,
+                ...(overwrite?.baseVersion !== undefined ? { baseVersion: overwrite.baseVersion } : {}),
                 ...(requireExisting ? { requireExisting: true } : {}),
             });
             const 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.13",
+  "version": "0.1.0-alpha.14",
   "publishConfig": {
     "access": "public"
   },