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

package/README.md

@@ -5,7 +5,9 @@ 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 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`.
+- `memory_capture(title, summary, ...)` — Persist durable knowledge after significant work, with conflict detection and optional user approval. Exact target existence is checked directly, while conflicts use full-vault exact-title matching instead of capped broad keyword hits. Multiple exact-title matches without an explicit id fail closed instead of choosing a note. An approved write refuses a note changed during 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`. The returned `id` is the actual on-disk id, including the agent namespace when private scope rewrites it.
+
+- `memory_correct(id, baseVersion, summary, details?, tags?)` — Read an existing note with `wiki_read`, then submit its exact `id`, returned `version`, and complete replacement summary. It never appends, chooses by title, or creates a missing note. A stale version fails without writing; omitted tags and other frontmatter fields survive. Returns the same write fields as `memory_capture`, with `mode: 'overwrite'` and `conflict: false`. DSH writes still follow the configured queue and git audit path.
 
 ## Note ids
 

package/README.zh.md

@@ -5,7 +5,9 @@ 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` 表示只更新、不新建，严格使用标题推导或显式给出的目标 `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`。
+- `memory_capture(title, summary, ...)` — 在有意义的任务结束后持久化知识，支持冲突检测与可选的用户审批。直接检查目标笔记是否存在；冲突搜索使用全 Vault 精确标题匹配，不受宽泛关键词搜索截断影响。未给出明确 id 且多个笔记同标题时拒绝猜选。审批期间笔记发生变化则拒绝写入。设置 `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` 为实际落盘 id，私有作用域改写时包含 agent 命名空间。
+
+- `memory_correct(id, baseVersion, summary, details?, tags?)` — 先 `wiki_read` 目标笔记，再传入其精确 `id`、返回的 `version` 与完整替换正文。它不追加、不按标题猜选目标、不创建缺失笔记；版本过期时拒绝写入。省略 tags 时保留原值，其他 frontmatter 字段也保留。返回字段与 `memory_capture` 写入结果一致，`mode: 'overwrite'`、`conflict: false`；DSH 写入仍经过既有 queue 与 git 审计路径。
 
 ## 笔记 id
 

package/lib/index.js

@@ -115,12 +115,12 @@ function dedupeHits(hits) {
  * 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.
+ * Capture the note version before approval so any later change makes the
+ * guarded write fail. Never treat a non-ENOENT read error as a missing note.
  * @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`.
+ * Existing frontmatter fields are preserved by the subsequent merge.
  * @returns the stored frontmatter and version for a guarded write.
  */
 async function readFrontmatter(ctx, exec, id) {
@@ -142,14 +142,13 @@ async function readFrontmatter(ctx, exec, id) {
         throw error;
     }
 }
-async function overwriteFrontmatter(ctx, exec, id, title, tags, now) {
-    const existing = await readFrontmatter(ctx, exec, id);
+function overwriteFrontmatter(existing, title, tags, now) {
     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, ...(existing !== undefined ? { baseVersion: existing.version } : {}) };
+    return frontmatter;
 }
 /**
  * Register `memory_recall` and `memory_capture` on the tool registry.
@@ -274,15 +273,27 @@ export function apply(ctx, config) {
             const notesDir = scope === 'shared' ? resolved.notesDir : '';
             const targetId = resolveNoteId(args.id, args.title, scope, notesDir);
             const requireExisting = args.requireExisting === true;
+            const explicitId = typeof args.id === 'string' && args.id !== '';
             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 }),
-                callTool(ctx, exec, 'wiki_search', { query: targetId }),
+            const [titleSearch, targetNote] = await Promise.all([
+                callTool(ctx, exec, 'wiki_search', { query: args.title, exactTitle: args.title }),
+                readFrontmatter(ctx, exec, targetId),
             ]);
-            const conflicts = dedupeHits(findConflicts(targetId, args.title, [...titleSearch.hits, ...idSearch.hits]));
+            const targetHit = targetNote === undefined ? [] : [{ id: targetId, title: args.title, score: 0, backlinks: [] }];
+            const conflicts = dedupeHits(findConflicts(targetId, args.title, [...targetHit, ...titleSearch.hits]));
             const conflictExists = conflicts.length > 0;
-            const finalId = requireExisting ? targetId : conflicts[0]?.id ?? targetId;
+            const finalId = requireExisting || explicitId || targetNote !== undefined ? targetId : conflicts[0]?.id ?? targetId;
+            if (!requireExisting && !explicitId && targetNote === undefined && (titleSearch.truncated || conflicts.length > 1)) {
+                return {
+                    written: false,
+                    id: targetId,
+                    conflict: true,
+                    reason: 'ambiguous or truncated conflict search; provide the exact existing note id before writing',
+                };
+            }
+            const selectedNote = finalId === targetId ? targetNote : await readFrontmatter(ctx, exec, finalId);
+            const approvedVersion = selectedNote?.version;
             // 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
@@ -335,24 +346,24 @@ export function apply(ctx, config) {
             // 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 exists = requireExisting ? targetNote !== 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 overwrite = appending ? undefined : await overwriteFrontmatter(ctx, exec, finalId, args.title, tags, now);
+            const overwrite = appending ? undefined : overwriteFrontmatter(selectedNote, args.title, tags, now);
             const content = appending
                 ? appendContent
-                : `---\n${yaml.dump(overwrite?.frontmatter).trim()}\n---\n\n# ${args.title}\n\n${appendContent}`;
+                : `---\n${yaml.dump(overwrite).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 } : {}),
+                baseVersion: approvedVersion ?? createHash('sha1').update('').digest('hex'),
+                ...(requireExisting || (conflictExists && !explicitId) ? { requireExisting: true } : {}),
             });
             const response = {
                 written: true,
-                id: finalId,
+                id: writeResult.id,
                 mode: writeMode,
                 // A declared update is not a conflict: the caller named the note it
                 // meant to change, so nothing required approval or a skip decision.
@@ -368,5 +379,49 @@ export function apply(ctx, config) {
             return response;
         },
     })));
+    ctx.effect(() => ctx.tools.register(defineTool({
+        name: 'memory_correct',
+        description: 'Replace one existing curated note with a single complete current conclusion. Read the note with wiki_read first, then provide its exact id and version as baseVersion. Refuses a missing or changed note; never appends or selects a note by title.',
+        parameters: {
+            id: { type: 'string', required: true, description: 'Exact vault-relative id returned by wiki_read; never inferred from a title.' },
+            baseVersion: { type: 'string', required: true, description: 'Version from wiki_read. A concurrent change refuses the correction.' },
+            summary: { type: 'string', required: true, description: 'Complete current conclusion in Markdown, replacing the old body.' },
+            details: { type: 'string', description: 'Optional additional context included in the new current body.' },
+            tags: { type: 'array', items: { type: 'string' }, description: 'Optional replacement tags; omitted tags retain existing tags.' },
+        },
+        output: {
+            schema: { type: 'json' },
+            render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+        },
+        async execute(args, exec) {
+            if (!isSafeNoteId(args.id) || !args.id.endsWith('.md'))
+                throw new Error('memory-curator: correction requires a safe vault-relative .md note id');
+            const note = await callTool(ctx, exec, 'wiki_read', { id: args.id });
+            if (note.version !== args.baseVersion)
+                throw new Error(`memory-curator: note ${args.id} changed since it was read; re-read it before correcting`);
+            const now = formatBeijingTime(new Date());
+            const existing = note.frontmatter ?? {};
+            const heading = /^#\s+(.+)$/m.exec(note.body)?.[1];
+            const title = typeof existing.title === 'string' && existing.title !== '' ? existing.title : heading ?? args.id.replace(/\.md$/, '');
+            const frontmatter = {
+                ...existing,
+                title,
+                ...(args.tags !== undefined ? { tags: args.tags.map(String) } : {}),
+                created: typeof existing.created === 'string' && existing.created !== '' ? existing.created : now,
+                updated: now,
+            };
+            const details = args.details ? `\n\n## Details\n\n${args.details}` : '';
+            const content = `---\n${yaml.dump(frontmatter).trim()}\n---\n\n# ${title}\n\n${args.summary}${details}\n`;
+            const written = await callTool(ctx, exec, 'wiki_write', {
+                id: args.id, content, mode: 'overwrite', requireExisting: true, baseVersion: args.baseVersion,
+            });
+            return {
+                written: true, id: written.id, mode: 'overwrite', conflict: false, version: written.version,
+                ...(written.created !== undefined ? { created: written.created } : {}),
+                ...(written.updated !== undefined ? { updated: written.updated } : {}),
+                ...(written.committed !== undefined ? { committed: written.committed } : {}),
+            };
+        },
+    })));
 }
 //# sourceMappingURL=index.js.map

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.14",
+  "version": "0.1.0-alpha.16",
   "publishConfig": {
     "access": "public"
   },
@@ -44,6 +44,7 @@
     "@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.13"
+    "@jacklika/dsh-memory-scope": "^0.1.0-alpha.3",
+    "@jacklika/dsh-tool-memory-filesystem": "^0.1.3-alpha.14"
   }
 }