@jacklika/dsh-memory-curator 0.1.0-alpha.0

package/README.md

@@ -0,0 +1,10 @@
+# @jacklika/dsh-memory-curator
+
+Curator tools for the DSH memory vault. This package is a member of the `@jacklika/dsh-memory` Bundle; do not install it directly.
+
+## 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.
+
+See the Bundle documentation in `docs/usage.md` for configuration and workflow.

package/README.zh.md

@@ -0,0 +1,10 @@
+# @jacklika/dsh-memory-curator
+
+DSH 记忆库的策展工具。本包是 `@jacklika/dsh-memory` Bundle 的成员，不要单独安装。
+
+## 工具
+
+- `memory_recall(query)` — 在任务开始前搜索知识库中的相关笔记。
+- `memory_capture(title, summary, ...)` — 在有意义的任务结束后持久化知识，支持冲突检测与可选的用户审批。
+
+配置与工作流请参阅 Bundle 文档 `docs/usage.zh.md`。

package/lib/index.js

@@ -0,0 +1,239 @@
+/**
+ * Curator tools for the DSH memory vault. `memory_recall` is meant to run at
+ * the start of a task so the agent does not ask the user to repeat context.
+ * `memory_capture` runs at the end of significant work: it derives a stable
+ * note id from the title, checks for conflicts with existing notes, asks the
+ * user for approval when one is found, and writes the captured knowledge to the
+ * shared curated zone.
+ * @module @jacklika/dsh-memory-curator
+ */
+import { 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 yaml from 'js-yaml';
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'memory-curator';
+/** Services required by the curator tools. */
+export const inject = ['tools'];
+/** Schemastery configuration for the memory curator consumer. */
+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'),
+});
+function normalizeTitle(title) {
+    return title.toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim();
+}
+function slugify(title) {
+    return title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+}
+function ensureMdExtension(id) {
+    return id.endsWith('.md') ? id : `${id}.md`;
+}
+function resolveNoteId(id, title, scope, notesDir) {
+    if (id !== undefined && id !== '') {
+        const withExt = ensureMdExtension(id);
+        if (scope === 'private')
+            return withExt;
+        return withExt.startsWith('shared/') ? withExt : `${notesDir}/${withExt.replace(/^\//, '')}`;
+    }
+    const slug = slugify(title);
+    return scope === 'private' ? `${slug}.md` : `${notesDir}/${slug}.md`;
+}
+function textFromContent(content) {
+    return content
+        .map(block => {
+        const maybe = block;
+        return maybe.type === 'text' && typeof maybe.text === 'string' ? maybe.text : '';
+    })
+        .join('');
+}
+async function callTool(ctx, exec, toolName, args) {
+    const result = await ctx.tools.execute({
+        callId: ToolCallId(`${exec.callId}:${toolName}:${randomUUID()}`),
+        rootCallId: exec.rootCallId,
+        name: toolName,
+        arguments: args,
+        parent: exec.token,
+        signal: exec.signal,
+        ...(exec.agent !== undefined ? { agent: exec.agent } : {}),
+    });
+    if (result.isError) {
+        throw new Error(`memory-curator: nested ${toolName} failed: ${result.error.message}`);
+    }
+    return JSON.parse(textFromContent(result.content) || 'null');
+}
+function findConflicts(targetId, title, hits) {
+    const normalized = normalizeTitle(title);
+    return hits.filter(hit => {
+        if (hit.id.toLowerCase() === targetId.toLowerCase())
+            return true;
+        return normalizeTitle(hit.title) === normalized;
+    });
+}
+function dedupeHits(hits) {
+    return [...new Map(hits.map(hit => [hit.id, hit])).values()];
+}
+/**
+ * Register `memory_recall` and `memory_capture` on the tool registry.
+ * @param ctx - registrant context carrying the tool registry.
+ * @param config - deployment's explicit curator configuration.
+ */
+export function apply(ctx, config) {
+    const tools = ctx.get('tools');
+    if (typeof tools?.execute !== 'function') {
+        ctx.logger?.warn('memory-curator: ctx.tools.execute unavailable; curator tools will not register.');
+        return;
+    }
+    const resolved = 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. Returns matching note ids, titles, and backlink counts.',
+        parameters: {
+            query: {
+                type: 'string',
+                required: true,
+                description: 'Keywords, concepts, or the task description to search for in the vault.',
+            },
+        },
+        output: {
+            schema: { type: 'json' },
+            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 });
+            return {
+                query: args.query,
+                hits: hits.slice(0, 20),
+                total: 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.',
+        parameters: {
+            title: {
+                type: 'string',
+                required: true,
+                description: 'Short human-readable title for the knowledge entry. Used to derive the note id when id is omitted.',
+            },
+            summary: {
+                type: 'string',
+                required: true,
+                description: 'The durable knowledge to record: the decision, API, convention, or fix in concise Markdown.',
+            },
+            details: {
+                type: 'string',
+                description: 'Optional additional Markdown context (error traces, alternatives considered, links).',
+            },
+            id: {
+                type: 'string',
+                description: 'Optional explicit vault-relative note id. If omitted, it is derived from the title as <notesDir>/<slug>.md.',
+            },
+            tags: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Optional tags for the note frontmatter (e.g. ["api", "decision", "bugfix"]).',
+            },
+            scope: {
+                type: 'string',
+                enum: ['shared', 'private'],
+                description: 'Whether the note lives in the shared curated zone or the private agent namespace. Defaults to shared.',
+            },
+            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.',
+            },
+            conflictPolicy: {
+                type: 'string',
+                enum: ['ask', 'skip'],
+                description: 'Override the deployment conflict policy for this capture: ask for approval on conflict, or skip the write.',
+            },
+        },
+        output: {
+            schema: { type: 'json' },
+            render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+        },
+        async execute(args, exec) {
+            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 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 conflicts = dedupeHits(findConflicts(targetId, args.title, [...titleHits, ...idHits]));
+            const conflictExists = conflicts.length > 0;
+            const finalId = conflicts[0]?.id ?? targetId;
+            if (conflictExists) {
+                const policy = args.conflictPolicy ?? resolved.conflictPolicy;
+                if (policy === 'skip') {
+                    return {
+                        written: false,
+                        id: finalId,
+                        conflict: true,
+                        reason: 'skipped by conflictPolicy=skip',
+                    };
+                }
+                if (approval === undefined || exec.agent === undefined) {
+                    return {
+                        written: false,
+                        id: finalId,
+                        conflict: true,
+                        reason: 'approval service or agent unavailable; set conflictPolicy=skip to allow silent skip in headless mode',
+                    };
+                }
+                const conflictList = conflicts.map(c => `- ${c.id} (${c.title})`).join('\n');
+                const outcome = await approval.request({
+                    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}".`,
+                    displayReason: {
+                        en: `Memory capture conflicts with existing note(s):\n${conflictList}\nAllow ${mode} to "${finalId}"?`,
+                    },
+                    signal: exec.signal,
+                });
+                if (outcome !== 'allowed-once') {
+                    return {
+                        written: false,
+                        id: finalId,
+                        conflict: true,
+                        approval: outcome,
+                        reason: 'user did not approve the conflict',
+                    };
+                }
+            }
+            const now = new Date().toISOString();
+            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 noteExists = conflictExists;
+            const content = noteExists && mode === 'append' ? appendContent : newNoteContent;
+            const writeMode = mode;
+            await callTool(ctx, exec, 'wiki_write', {
+                id: finalId,
+                content,
+                mode: writeMode,
+            });
+            return {
+                written: true,
+                id: finalId,
+                mode: writeMode,
+                conflict: conflictExists,
+            };
+        },
+    })));
+}
+//# sourceMappingURL=index.js.map

package/lib/types/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Curator tools for the DSH memory vault. `memory_recall` is meant to run at
+ * the start of a task so the agent does not ask the user to repeat context.
+ * `memory_capture` runs at the end of significant work: it derives a stable
+ * note id from the title, checks for conflicts with existing notes, asks the
+ * user for approval when one is found, and writes the captured knowledge to the
+ * shared curated zone.
+ * @module @jacklika/dsh-memory-curator
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+/** Cordis plugin name used by loader diagnostics. */
+export declare const name = "memory-curator";
+/** Services required by the curator tools. */
+export declare const inject: string[];
+/** Plugin configuration. */
+export interface Config {
+    /**
+     * What to do when a capture matches an existing note. `ask` requests user
+     * approval through the DSH approval seam before writing. `skip` silently
+     * aborts the write so nothing is overwritten in headless or CI runs.
+     */
+    conflictPolicy?: 'ask' | 'skip';
+    /**
+     * Default zone for captured notes. `shared` puts them under the configured
+     * `notesDir` and makes them visible to every agent and session. `private`
+     * leaves the id unchanged so `memory-scope` routes it under the current
+     * agent's namespace.
+     */
+    defaultScope?: 'shared' | 'private';
+    /** Vault-relative directory where shared curated notes live. */
+    notesDir?: string;
+}
+/** Schemastery configuration for the memory curator consumer. */
+export declare const Config: z<Config>;
+/**
+ * Register `memory_recall` and `memory_capture` on the tool registry.
+ * @param ctx - registrant context carrying the tool registry.
+ * @param config - deployment's explicit curator configuration.
+ */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -0,0 +1,48 @@
+{
+  "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.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JackLiKa/jacklika-agent-plugins-repo.git",
+    "directory": "packages/memory-curator"
+  },
+  "type": "module",
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/**/*.js",
+    "lib/types/**/*.d.ts",
+    "README.md",
+    "README.zh.md"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@deepseek-ai/schemastery": "3.18.4",
+    "js-yaml": "^4.2.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"
+  },
+  "devDependencies": {
+    "@jacklika/dsh-tool-memory-filesystem": "0.1.3-alpha.2"
+  }
+}