@jacklika/dsh-memory-curator 0.1.0-alpha.10 → 0.1.0-alpha.12

package/README.md

@@ -4,8 +4,8 @@ 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 }`, where `total` is the vault-wide match count passed through from `wiki_search` and can exceed `hits.length` when the search layer caps its results — 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.
+- `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`.
 
 ## Note ids
 

package/README.zh.md

@@ -4,8 +4,8 @@ DSH 记忆库的策展工具。本包是 `@jacklika/dsh-memory` Bundle 的成员
 
 ## 工具
 
-- `memory_recall(query)` — 在任务开始前搜索知识库中的相关笔记。返回 `{ query, hits, total }`，其中 `total` 是从 `wiki_search` 透传的全库命中数，在搜索层截断结果时可能大于 `hits.length`——调用方因此能区分“这就是全部命中”与“还有更多”。`memory-anchor` 写入的逐回合自动入库笔记会从命中列表中隐藏，并从 `total` 中扣除，记账内容不会挤占策展知识；匹配锚定在策展区命名空间上，仅名字前缀相同的策展笔记仍会返回。
-- `memory_capture(title, summary, ...)` — 在有意义的任务结束后持久化知识，支持冲突检测与可选的用户审批。返回 `{ written, id, mode, conflict, version, created?, updated?, committed? }`：`version` 是持久化笔记文本的 SHA-1 指纹；首次入库返回 `created`；追加写入返回 `updated`；挂载 `memory-git` 完成提交时还会返回 `committed`。
+- `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`。
 
 ## 笔记 id
 

package/lib/index.js

@@ -123,17 +123,24 @@ function dedupeHits(hits) {
  * @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;
+async function readFrontmatter(ctx, exec, id) {
     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;
-        }
+        return note !== null && typeof note === 'object' && note.frontmatter !== null && typeof note.frontmatter === 'object'
+            ? note.frontmatter
+            : {};
     }
-    catch {
-        // No readable note at this id: the ordinary first capture of a new note.
+    catch (error) {
+        // Only a missing note means a first capture: `wiki_read` reports it as
+        // "no such note". Any other failure (permission denied, a directory in the
+        // way) must surface instead of silently turning an update into a replace.
+        if (error.message.includes('no such note'))
+            return undefined;
+        throw error;
     }
+}
+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;
     frontmatter.created = typeof created === 'string' && created !== '' ? created : now;
@@ -156,7 +163,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. 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, so a total above the returned hit count means the list was truncated.',
+        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',
@@ -197,16 +204,20 @@ export function apply(ctx, config) {
             // 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: curated.slice(0, 20),
+                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,
             };
         },
     })));
     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.',
+        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.',
         parameters: {
             title: {
                 type: 'string',
@@ -246,6 +257,10 @@ export function apply(ctx, config) {
                 enum: ['ask', 'skip'],
                 description: 'Override the deployment conflict policy for this capture: ask for approval on conflict, or skip the write.',
             },
+            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.',
+            },
         },
         output: {
             schema: { type: 'json' },
@@ -256,6 +271,7 @@ export function apply(ctx, config) {
             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 tags = Array.isArray(args.tags) ? args.tags.map(String) : [];
             const [titleSearch, idSearch] = await Promise.all([
                 callTool(ctx, exec, 'wiki_search', { query: args.title }),
@@ -264,7 +280,11 @@ 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;
-            if (conflictExists) {
+            // 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
+            // the existence requirement itself, atomically with the write.
+            if (conflictExists && !requireExisting) {
                 const policy = args.conflictPolicy ?? resolved.conflictPolicy;
                 if (policy === 'skip') {
                     return {
@@ -306,9 +326,16 @@ 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`;
-            const appending = conflictExists && mode === 'append';
+            // 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.
+            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}`);
+            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 content = appending
                 ? appendContent
@@ -317,12 +344,15 @@ export function apply(ctx, config) {
                 id: finalId,
                 content,
                 mode: writeMode,
+                ...(requireExisting ? { requireExisting: true } : {}),
             });
             const response = {
                 written: true,
                 id: finalId,
                 mode: writeMode,
-                conflict: conflictExists,
+                // A declared update is not a conflict: the caller named the note it
+                // meant to change, so nothing required approval or a skip decision.
+                conflict: conflictExists && !requireExisting,
                 version: writeResult.version,
             };
             if (typeof writeResult.created === 'string' && writeResult.created !== '')

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