@jacklika/dsh-memory-curator 0.1.0-alpha.2 → 0.1.0-alpha.20

package/README.md

@@ -4,7 +4,25 @@ 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. 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`. When a capture is refused for conflict reasons, the response also carries `suggested: { tool: 'memory_correct', id, baseVersion? }` naming the collided note (and its version when already read) so the caller can correct the existing note instead of retrying an append. The returned `id` is the actual on-disk id, including the agent namespace when private scope rewrites it. When `summary` itself begins with a Markdown heading, that heading is used as-is and no `# <title>` heading is prepended, so a caller-supplied H1 never produces duplicates. For headless runs without an approval service, the environment variable `DSH_MEMORY_CONFLICT_POLICY=skip` relaxes the default `ask` policy to `skip` — it can never tighten a configured `skip` back to `ask`, and a per-call `conflictPolicy` argument still wins; any other value fails plugin load.
+
+- `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. A `summary` that begins with a Markdown heading is used as-is without a prepended `# <title>` heading. 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.
+
+- `memory_forget(id, baseVersion)` — Move a curated note into the vault archive area (`archive/<original-relative-path>`). The note is not deleted; it can still be read directly, but `wiki_search` and `wiki_graph` exclude it by default. Requires the current `version` from `wiki_read`; a stale version fails closed. The move is committed by `memory-git` when configured.
+
+- `memory_compact(scope?, maxAgeDays?, dryRun?)` — Archive notes. With the default `scope: 'auto-capture'` it archives old per-turn auto-capture notes, keeping only the most recent sessions (disabled by default; enable with `autoCaptureCompact: { enabled: true, keepSessions: N }` in the curator config). With `scope: 'stale'` it archives any note that is both older than `maxAgeDays` (required, ≥ 1) and has no inbound `[[links]]` — link presence is derived from the active `wiki_graph` link edges, so the graph tool must be installed for stale passes. Stale compaction needs no curator config beyond the parameters. The pass is idempotent: repeated runs produce no duplicate archives. It respects the same cross-process lock lane as other mutation tools. Pass `dryRun: true` to preview the selection — it returns `{ compacted: true, dryRun: true, kept, archived: 0, archivedIds: [], wouldArchive }` and archives nothing.
+
+## 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. An intervening change detected between reading the old note and writing it fails instead of replacing that change. A first capture writes `created` only.
+
+## Provenance fields
+
+`memory_capture` and `memory_correct` accept optional `source_session`, `commit`, and `verified` arguments. When supplied, they are written into the note frontmatter as first-class fields for later retrieval weighting and audit. They do not change search ranking in this release.
 
 See the Bundle documentation in `docs/usage.md` for configuration and workflow.

package/README.zh.md

@@ -4,7 +4,25 @@ 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, ...)` — 在有意义的任务结束后持久化知识，支持冲突检测与可选的用户审批。直接检查目标笔记是否存在；冲突搜索使用全 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`。当捕获因冲突被拒绝时，响应还会携带 `suggested: { tool: 'memory_correct', id, baseVersion? }`，指明发生冲突的笔记（已读取时附版本），让调用方改为修正既有笔记而不是重试追加。返回的 `id` 为实际落盘 id，私有作用域改写时包含 agent 命名空间。当 `summary` 自身以 Markdown 标题开头时，该标题按原样使用，不再前置 `# <title>`，调用方自带 H1 不会产生重复标题。无审批服务的 headless 场景下，环境变量 `DSH_MEMORY_CONFLICT_POLICY=skip` 可把默认 `ask` 策略放宽为 `skip`——它永远不能将已配置的 `skip` 收紧回 `ask`，且逐次调用的 `conflictPolicy` 参数仍优先；其他取值会导致插件加载失败。
+
+- `memory_correct(id, baseVersion, summary, details?, tags?)` — 先 `wiki_read` 目标笔记，再传入其精确 `id`、返回的 `version` 与完整替换正文。它不追加、不按标题猜选目标、不创建缺失笔记；版本过期时拒绝写入。省略 tags 时保留原值，其他 frontmatter 字段也保留。以 Markdown 标题开头的 `summary` 按原样使用，不前置 `# <title>`。返回字段与 `memory_capture` 写入结果一致，`mode: 'overwrite'`、`conflict: false`；DSH 写入仍经过既有 queue 与 git 审计路径。
+
+- `memory_forget(id, baseVersion)` — 将策展笔记移入归档区（`archive/<原相对路径>`）。笔记未被物理删除，仍可显式 `wiki_read` 读取，但 `wiki_search` 与 `wiki_graph` 默认不再返回它。必须传入 `wiki_read` 得到的当前 `version`；过期版本会失败关闭。若配置了 `memory-git`，此次移动会被提交。
+
+- `memory_compact(scope?, maxAgeDays?, dryRun?)` — 归档笔记。默认 `scope: 'auto-capture'` 归档旧的逐回合自动捕获笔记，只保留最近 N 个会话（默认关闭；在 curator 配置中通过 `autoCaptureCompact: { enabled: true, keepSessions: N }` 开启）。`scope: 'stale'` 归档同时满足「mtime 早于 `maxAgeDays`（必填，≥ 1）」且「无入链 `[[links]]`」的笔记——链接关系取自 `wiki_graph` 的 link 边，因此 stale pass 需要安装 graph 工具；除参数外无需额外 curator 配置。该 pass 是幂等的：重复执行不会产生重复归档文件。它与其他变更工具使用同一跨进程锁车道。传 `dryRun: true` 可预览选中项——返回 `{ compacted: true, dryRun: true, kept, archived: 0, archivedIds: [], wouldArchive }`，不归档任何内容。
+
+## 笔记 id
+
+省略 `id` 时，`memory_capture` 由标题推导笔记 id：保留 Unicode 字母与数字（先做 NFC 归一化并转小写），其余连续字符统一折叠为单个 `-`，因此中日韩等非拉丁标题依然可读且互不相同。完全不含字母与数字的标题退化为 `note-<标题 sha256 的前 12 位十六进制>`，纯符号标题的写入不会坍缩到同一个文件。
+
+## 覆盖式入库
+
+`mode: 'overwrite'` 替换笔记正文，但会合并既有 frontmatter：其他写入方记录的字段与原始 `created` 都保留，`title` 与 `tags` 以本次调用为准，并写入 `updated`。如果从读取旧笔记到写入之间检测到其他修改，则拒绝覆盖该修改。首次入库只写 `created`。
+
+## 来源字段
+
+`memory_capture` 与 `memory_correct` 接受可选的 `source_session`、`commit`、`verified` 参数。传入后会被写入笔记 frontmatter，作为后续检索加权与审计的一等公民字段。当前版本暂不改变搜索排序。
 
 配置与工作流请参阅 Bundle 文档 `docs/usage.zh.md`。

package/lib/index.js

@@ -7,35 +7,12 @@
  * 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';
-/**
- * Format a Date as an ISO-like string in Asia/Shanghai (+08:00).
- * The project convention is to store all vault timestamps in Beijing time.
- */
-function formatBeijingTime(date) {
-    const parts = new Intl.DateTimeFormat('sv-SE', {
-        timeZone: 'Asia/Shanghai',
-        year: 'numeric',
-        month: '2-digit',
-        day: '2-digit',
-        hour: '2-digit',
-        minute: '2-digit',
-        second: '2-digit',
-        hour12: false,
-    }).formatToParts(date);
-    const get = (type) => parts.find((p) => p.type === type)?.value ?? '00';
-    const yyyy = get('year');
-    const MM = get('month');
-    const dd = get('day');
-    const HH = get('hour');
-    const mm = get('minute');
-    const ss = get('second');
-    return `${yyyy}-${MM}-${dd}T${HH}:${mm}:${ss}+08:00`;
-}
 /** Cordis plugin name used by loader diagnostics. */
 export const name = 'memory-curator';
 /** Services required by the curator tools. */
@@ -45,19 +22,54 @@ export const Config = z.object({
     conflictPolicy: z.union(['ask', 'skip']).default('ask'),
     defaultScope: z.union(['shared', 'private']).default('shared'),
     notesDir: z.string().default('shared/notes'),
+    autoCaptureCompact: z.object({
+        enabled: z.boolean().default(false),
+        keepSessions: z.number().default(0),
+    }).default({ enabled: false, keepSessions: 0 }),
 });
-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(/^\//, '')}`;
@@ -89,16 +101,69 @@ 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.
+ * 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.
+ * 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) {
+    try {
+        const note = await callTool(ctx, exec, 'wiki_read', { id });
+        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
+        // "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;
+    }
+}
+function pickProvenance(args) {
+    const picked = {};
+    if (typeof args.source_session === 'string' && args.source_session !== '')
+        picked.source_session = args.source_session;
+    if (typeof args.commit === 'string' && args.commit !== '')
+        picked.commit = args.commit;
+    if (typeof args.verified === 'boolean')
+        picked.verified = args.verified;
+    return picked;
+}
+function overwriteFrontmatter(existing, title, tags, now, provenance) {
+    const frontmatter = { ...existing?.frontmatter, title, tags, ...provenance };
+    const created = existing?.frontmatter.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.
@@ -112,9 +177,18 @@ export function apply(ctx, config) {
     }
     const resolved = config;
     const approval = ctx.get('approval');
+    // `DSH_MEMORY_CONFLICT_POLICY` is a headless escape hatch: it can only
+    // relax the policy, never tighten it — an explicit config or per-call
+    // `conflictPolicy: 'skip'`/`'ask'` still wins.
+    const envPolicyRaw = process.env.DSH_MEMORY_CONFLICT_POLICY;
+    if (envPolicyRaw !== undefined && envPolicyRaw !== 'ask' && envPolicyRaw !== 'skip') {
+        throw new Error(`memory-curator: DSH_MEMORY_CONFLICT_POLICY must be "ask" or "skip", received ${JSON.stringify(envPolicyRaw)}`);
+    }
+    const envPolicy = envPolicyRaw === 'ask' || envPolicyRaw === 'skip' ? envPolicyRaw : undefined;
+    const defaultConflictPolicy = resolved.conflictPolicy === 'skip' ? 'skip' : (envPolicy ?? 'ask');
     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',
@@ -127,17 +201,48 @@ 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,
             };
         },
     })));
     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 replace an existing note with one current version without conflict approval; use mode: append only for genuinely additive material.',
         parameters: {
             title: {
                 type: 'string',
@@ -147,7 +252,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',
@@ -170,13 +275,29 @@ 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',
                 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 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.',
+            },
+            source_session: {
+                type: 'string',
+                description: 'Optional session id that produced this capture, stored in frontmatter for provenance.',
+            },
+            commit: {
+                type: 'string',
+                description: 'Optional upstream commit hash or reference this capture relates to, stored in frontmatter for provenance.',
+            },
+            verified: {
+                type: 'boolean',
+                description: 'Optional boolean marking the captured knowledge as verified, stored in frontmatter for provenance.',
+            },
         },
         output: {
             schema: { type: 'json' },
@@ -186,22 +307,50 @@ 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 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 [titleHits, idHits] = 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, [...titleHits, ...idHits]));
+            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 = conflicts[0]?.id ?? targetId;
-            if (conflictExists) {
-                const policy = args.conflictPolicy ?? resolved.conflictPolicy;
+            const finalId = requireExisting || explicitId || targetNote !== undefined ? targetId : conflicts[0]?.id ?? targetId;
+            // A conflict means the knowledge probably already has a home: point the
+            // caller at the correction tool for the note it collided with instead of
+            // letting a retry append a second, contradictory copy. The suggested
+            // baseVersion is included whenever the note was already read.
+            const correctionHint = (version) => ({
+                tool: 'memory_correct',
+                id: finalId,
+                ...(version !== undefined ? { baseVersion: version } : {}),
+            });
+            if (!requireExisting && !explicitId && targetNote === undefined && (titleSearch.truncated || conflicts.length > 1)) {
+                return {
+                    written: false,
+                    id: targetId,
+                    conflict: true,
+                    ...(conflicts.length > 0 ? { suggested: correctionHint() } : {}),
+                    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
+            // the existence requirement itself, atomically with the write.
+            if (conflictExists && !requireExisting) {
+                const policy = args.conflictPolicy ?? defaultConflictPolicy;
                 if (policy === 'skip') {
                     return {
                         written: false,
                         id: finalId,
                         conflict: true,
+                        suggested: correctionHint(approvedVersion),
                         reason: 'skipped by conflictPolicy=skip',
                     };
                 }
@@ -210,6 +359,7 @@ export function apply(ctx, config) {
                         written: false,
                         id: finalId,
                         conflict: true,
+                        suggested: correctionHint(approvedVersion),
                         reason: 'approval service or agent unavailable; set conflictPolicy=skip to allow silent skip in headless mode',
                     };
                 }
@@ -218,9 +368,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,
                 });
@@ -229,6 +379,7 @@ export function apply(ctx, config) {
                         written: false,
                         id: finalId,
                         conflict: true,
+                        suggested: correctionHint(approvedVersion),
                         approval: outcome,
                         reason: 'user did not approve the conflict',
                     };
@@ -237,25 +388,208 @@ 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 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;
+            // 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 ? targetNote !== undefined : conflictExists;
+            const appending = exists && mode === 'append';
             const writeMode = appending ? 'append' : 'overwrite';
-            await callTool(ctx, exec, 'wiki_write', {
+            const provenance = pickProvenance(args);
+            ctx.logger?.debug(`memory-curator: capture target=${finalId} conflicts=${conflicts.length} writeMode=${writeMode} requireExisting=${requireExisting}`);
+            const overwrite = appending ? undefined : overwriteFrontmatter(selectedNote, args.title, tags, now, provenance);
+            const headingPrefix = args.summary.trimStart().startsWith('#') ? '' : `# ${args.title}\n\n`;
+            const content = appending
+                ? appendContent
+                : `---\n${yaml.dump(overwrite).trim()}\n---\n\n${headingPrefix}${appendContent}`;
+            const writeResult = await callTool(ctx, exec, 'wiki_write', {
                 id: finalId,
                 content,
                 mode: writeMode,
+                baseVersion: approvedVersion ?? createHash('sha1').update('').digest('hex'),
+                ...(requireExisting || (conflictExists && !explicitId) ? { requireExisting: true } : {}),
             });
-            return {
+            const response = {
                 written: true,
-                id: finalId,
+                id: writeResult.id,
                 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 !== '')
+                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;
+        },
+    })));
+    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.' },
+            source_session: { type: 'string', description: 'Optional session id that produced this correction, stored in frontmatter for provenance.' },
+            commit: { type: 'string', description: 'Optional upstream commit hash or reference this correction relates to, stored in frontmatter for provenance.' },
+            verified: { type: 'boolean', description: 'Optional boolean marking the corrected knowledge as verified, stored in frontmatter for provenance.' },
+        },
+        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 correctionProvenance = pickProvenance(args);
+            const frontmatter = {
+                ...existing,
+                title,
+                ...(args.tags !== undefined ? { tags: args.tags.map(String) } : {}),
+                created: typeof existing.created === 'string' && existing.created !== '' ? existing.created : now,
+                updated: now,
+                ...correctionProvenance,
+            };
+            const details = args.details ? `\n\n## Details\n\n${args.details}` : '';
+            const headingPrefix = args.summary.trimStart().startsWith('#') ? '' : `# ${title}\n\n`;
+            const content = `---\n${yaml.dump(frontmatter).trim()}\n---\n\n${headingPrefix}${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 } : {}),
+            };
+        },
+    })));
+    ctx.effect(() => ctx.tools.register(defineTool({
+        name: 'memory_compact',
+        description: 'Archive old per-turn auto-capture notes, keeping only the most recent sessions. This reduces search noise while preserving every capture in git history. Disabled by default; enable via autoCaptureCompact in the curator config. Returns { compacted, kept, archived, archivedIds } when active, or { compacted: false, reason } when disabled. Pass dryRun: true to preview the same selection without archiving anything. With scope: \'stale\', archives indexed notes whose last modification is older than maxAgeDays and that have no inbound explicit links; dryRun previews that selection too.',
+        parameters: {
+            dryRun: { type: 'boolean', description: 'Preview which notes would be archived without writing. Defaults to false.' },
+            scope: { type: 'string', enum: ['auto-capture', 'stale'], description: "What to compact: 'auto-capture' (default) prunes old capture sessions; 'stale' archives notes older than maxAgeDays with no inbound explicit links." },
+            maxAgeDays: { type: 'number', description: "Required when scope is 'stale': notes whose recorded mtime is older than this many days are candidates." },
+        },
+        output: {
+            schema: { type: 'json' },
+            render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+        },
+        async execute(args, exec) {
+            const notesPrefix = `${resolved.notesDir}/`;
+            const isAutoCapture = (id) => {
+                if (!id.startsWith(notesPrefix))
+                    return false;
+                const rest = id.slice(notesPrefix.length);
+                if (rest.startsWith('auto-capture/'))
+                    return true;
+                return /^auto-capture-[A-Za-z0-9_-]+\.md$/.test(rest);
+            };
+            if (args.scope === 'stale') {
+                const days = typeof args.maxAgeDays === 'number' && args.maxAgeDays > 0 ? args.maxAgeDays : undefined;
+                if (days === undefined) {
+                    return { compacted: false, reason: "scope 'stale' requires maxAgeDays > 0" };
+                }
+                const graph = await callTool(ctx, exec, 'wiki_graph', { maxNodes: 2000, maxEdges: 20000 });
+                // A capped view cannot prove "no inbound links" — archiving on a
+                // partial graph would hide notes that are actually referenced.
+                if (graph.truncated) {
+                    return { compacted: false, reason: 'vault graph exceeds the node cap; stale compaction refuses a partial view' };
+                }
+                const inbound = new Set();
+                for (const edge of graph.edges) {
+                    if (edge.type !== 'keyword')
+                        inbound.add(edge.to);
+                }
+                const cutoff = Date.now() - days * 86_400_000;
+                const candidates = [];
+                for (const node of graph.nodes) {
+                    if (inbound.has(node.id) || isAutoCapture(node.id))
+                        continue;
+                    const note = await callTool(ctx, exec, 'wiki_read', { id: node.id });
+                    const mtime = typeof note.mtime === 'string' ? Date.parse(note.mtime) : NaN;
+                    if (Number.isFinite(mtime) && mtime < cutoff)
+                        candidates.push({ id: node.id, version: note.version });
+                }
+                candidates.sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+                if (args.dryRun === true) {
+                    return {
+                        compacted: true,
+                        dryRun: true,
+                        scope: 'stale',
+                        maxAgeDays: days,
+                        archived: 0,
+                        archivedIds: [],
+                        wouldArchive: candidates.map(c => c.id),
+                    };
+                }
+                const archivedIds = [];
+                for (const candidate of candidates) {
+                    const result = await callTool(ctx, exec, 'memory_forget', { id: candidate.id, baseVersion: candidate.version });
+                    if (result.forgotten)
+                        archivedIds.push(result.id);
+                }
+                return {
+                    compacted: true,
+                    scope: 'stale',
+                    maxAgeDays: days,
+                    archived: archivedIds.length,
+                    archivedIds,
+                };
+            }
+            const compact = resolved.autoCaptureCompact;
+            if (!compact.enabled) {
+                return { compacted: false, reason: 'auto-capture compaction is disabled in curator config' };
+            }
+            const keep = typeof compact.keepSessions === 'number' && compact.keepSessions >= 1 ? Math.floor(compact.keepSessions) : 0;
+            if (keep < 1) {
+                return { compacted: false, reason: 'autoCaptureCompact.keepSessions must be >= 1' };
+            }
+            const search = await callTool(ctx, exec, 'wiki_search', { query: 'auto-capture', maxResults: 10000 });
+            const captures = dedupeHits(search.hits.filter(hit => isAutoCapture(hit.id)))
+                .sort((a, b) => b.id.localeCompare(a.id));
+            if (captures.length <= keep) {
+                return { compacted: true, kept: captures.length, archived: 0, archivedIds: [] };
+            }
+            const toArchive = captures.slice(keep);
+            if (args.dryRun === true) {
+                return {
+                    compacted: true,
+                    dryRun: true,
+                    kept: keep,
+                    archived: 0,
+                    archivedIds: [],
+                    wouldArchive: toArchive.map(hit => hit.id),
+                };
+            }
+            const archivedIds = [];
+            for (const hit of toArchive) {
+                const note = await callTool(ctx, exec, 'wiki_read', { id: hit.id });
+                const result = await callTool(ctx, exec, 'memory_forget', { id: hit.id, baseVersion: note.version });
+                if (result.forgotten)
+                    archivedIds.push(result.id);
+            }
+            return {
+                compacted: true,
+                kept: keep,
+                archived: archivedIds.length,
+                archivedIds,
             };
         },
     })));

package/lib/types/index.d.ts

@@ -30,6 +30,27 @@ export interface Config {
     defaultScope?: 'shared' | 'private';
     /** Vault-relative directory where shared curated notes live. */
     notesDir?: string;
+    /**
+     * Optional compaction of per-turn auto-capture notes. Disabled by default;
+     * when enabled, old session captures are archived and no longer appear in
+     * default search results.
+     */
+    autoCaptureCompact?: AutoCaptureCompactConfig;
+}
+/** Configuration for the optional auto-capture compaction pass. */
+export interface AutoCaptureCompactConfig {
+    /**
+     * Whether the compaction pass is active. Default false: without explicit
+     * opt-in, `memory_compact` is a no-op so a caller cannot accidentally archive
+     * human-written notes.
+     */
+    enabled?: boolean;
+    /**
+     * How many recent auto-capture sessions to keep in the active vault. Older
+     * captures are moved to `archive/` by `memory_forget`. Must be >= 1 when
+     * enabled.
+     */
+    keepSessions?: number;
 }
 /** Schemastery configuration for the memory curator consumer. */
 export declare const Config: z<Config>;

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.2",
+  "version": "0.1.0-alpha.20",
   "publishConfig": {
     "access": "public"
   },
@@ -32,17 +32,21 @@
   "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-memory-git": "^0.1.0-alpha.9",
+    "@jacklika/dsh-tool-memory-filesystem": "^0.1.3-alpha.19",
+    "@jacklika/dsh-memory-scope": "^0.1.0-alpha.4",
+    "@jacklika/dsh-tool-memory-graph": "^0.1.0-alpha.13"
   }
 }