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

package/README.md

@@ -9,6 +9,10 @@ Curator tools for the DSH memory vault. This package is a member of the `@jackli
 
 - `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.
 
+- `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()` — Archive 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. The pass is idempotent: repeated runs produce no duplicate archives. It respects the same cross-process lock lane as other mutation tools.
+
 ## 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.
@@ -17,4 +21,8 @@ When `id` is omitted, `memory_capture` derives it from the title: Unicode letter
 
 `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

@@ -9,6 +9,10 @@ DSH 记忆库的策展工具。本包是 `@jacklika/dsh-memory` Bundle 的成员
 
 - `memory_correct(id, baseVersion, summary, details?, tags?)` — 先 `wiki_read` 目标笔记，再传入其精确 `id`、返回的 `version` 与完整替换正文。它不追加、不按标题猜选目标、不创建缺失笔记；版本过期时拒绝写入。省略 tags 时保留原值，其他 frontmatter 字段也保留。返回字段与 `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()` — 归档旧的逐回合自动捕获笔记，只保留最近 N 个会话。默认关闭；在 curator 配置中通过 `autoCaptureCompact: { enabled: true, keepSessions: N }` 开启。该 pass 是幂等的：重复执行不会产生重复归档文件。它与其他变更工具使用同一跨进程锁车道。
+
 ## 笔记 id
 
 省略 `id` 时，`memory_capture` 由标题推导笔记 id：保留 Unicode 字母与数字（先做 NFC 归一化并转小写），其余连续字符统一折叠为单个 `-`，因此中日韩等非拉丁标题依然可读且互不相同。完全不含字母与数字的标题退化为 `note-<标题 sha256 的前 12 位十六进制>`，纯符号标题的写入不会坍缩到同一个文件。
@@ -17,4 +21,8 @@ DSH 记忆库的策展工具。本包是 `@jacklika/dsh-memory` Bundle 的成员
 
 `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

@@ -22,6 +22,10 @@ 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 }),
 });
 /**
  * Fold a title to its comparison form: NFC, case-insensitive, every run of
@@ -142,8 +146,18 @@ async function readFrontmatter(ctx, exec, id) {
         throw error;
     }
 }
-function overwriteFrontmatter(existing, title, tags, now) {
-    const frontmatter = { ...existing?.frontmatter, title, tags };
+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)
@@ -263,6 +277,18 @@ export function apply(ctx, config) {
                 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' },
@@ -349,8 +375,9 @@ export function apply(ctx, config) {
             const exists = requireExisting ? targetNote !== undefined : conflictExists;
             const appending = exists && mode === 'append';
             const writeMode = appending ? 'append' : 'overwrite';
+            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);
+            const overwrite = appending ? undefined : overwriteFrontmatter(selectedNote, args.title, tags, now, provenance);
             const content = appending
                 ? appendContent
                 : `---\n${yaml.dump(overwrite).trim()}\n---\n\n# ${args.title}\n\n${appendContent}`;
@@ -388,6 +415,9 @@ export function apply(ctx, config) {
             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' },
@@ -403,12 +433,14 @@ export function apply(ctx, config) {
             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 content = `---\n${yaml.dump(frontmatter).trim()}\n---\n\n# ${title}\n\n${args.summary}${details}\n`;
@@ -423,5 +455,53 @@ export function apply(ctx, config) {
             };
         },
     })));
+    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.',
+        parameters: {},
+        output: {
+            schema: { type: 'json' },
+            render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+        },
+        async execute(_args, exec) {
+            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 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);
+            };
+            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);
+            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,
+            };
+        },
+    })));
 }
 //# sourceMappingURL=index.js.map

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