@lmzhen/dsh-tool-memory 0.1.0-rc.5 → 0.1.0-rc.50

package/lib/index.js

@@ -1,19 +1,203 @@
 import z from "@deepseek-ai/schemastery";
 import { defineTool } from "@deepseek-ai/dsh-tools";
+import { createHash } from "node:crypto";
+//#region ../evolution-core/src/prompts.ts
+/**
+* Review and curation prompts adapted from Hermes Agent
+* `agent/background_review.py`, `agent/curator.py`, and
+* `agent/learn_prompt.py`, with tool names translated to the DSH-native
+* catalog (`memory`, `skill_manage`, `skill`, `bash`, `str_replace_editor`).
+*
+* Every prompt is pinned in a versioned bundle. Review workers verify the
+* bundle digest before spending a model call, so a partially-patched
+* deployment fails closed instead of silently running a truncated prompt.
+*/
+/**
+* Prompt bundle identity. Bump both id and version whenever a prompt's text
+* changes semantically: the bundle digest is the fail-closed signal for
+* review workers, so a stale id across deployments must be distinguishable.
+*/
+const PROMPT_BUNDLE_ID = "dsh-evolution@3";
+const MEMORY_REVIEW_PROMPT = `[Auto-review — Memory]
+Review the conversation above and consider saving to memory if appropriate.
+
+Focus on:
+1. Has the user revealed things about themselves — persona, desires, preferences, or personal details worth remembering?
+2. Has the user expressed expectations about how you should behave, their work style, or ways they want you to operate?
+
+If something stands out, save it using the memory tool.
+If nothing is worth saving, just say "Nothing to save." and stop.`;
+const SKILL_REVIEW_PROMPT = `[Auto-review — Skills]
+Review the conversation above and update the skill library. Be ACTIVE — most sessions produce at least one skill update, even if small.
+
+Target shape: CLASS-LEVEL skills with a rich SKILL.md and a references/ directory for session-specific detail. Not a flat list of narrow one-session skills.
+
+Signals that warrant action:
+- The user corrected your style, tone, format, verbosity, workflow, or approach.
+- A non-trivial technique, fix, workaround, or debugging path emerged.
+- A loaded skill turned out wrong, missing, or outdated — patch it now.
+
+Only update skills you loaded or read in THIS session; never touch skills you have not read.
+
+Preference order:
+1. Patch a skill that was loaded or read this session.
+2. Patch an existing umbrella skill.
+3. Add references/, templates/, or scripts/ support under an existing skill.
+4. Create a new class-level umbrella skill only when nothing fits.
+
+Protected skills (bundled/hub-installed) must not be edited. Pinned skills are read-only to the background review: the pinned write guard refuses background changes, so only the foreground may update or archive them.
+
+Do NOT capture:
+- Environment-dependent failures (missing binaries, unconfigured credentials).
+- Negative claims about tools ("browser tools do not work").
+- Transient errors that resolved during the session.
+- One-off task narratives.
+
+If a tool failed because of setup state, capture the FIX under an existing setup skill — never "this tool does not work" as a standalone constraint.
+
+"Nothing to save." is a real option but should NOT be the default.`;
+const COMBINED_REVIEW_PROMPT = `[Auto-review]
+Review the conversation above and update two things.
+
+**Memory**: who the user is. Save durable user preferences, personal details, and expectations with the memory tool.
+
+**Skills**: how to do this class of task. Be ACTIVE. Only update skills you loaded or read in THIS session. Follow the same class-level umbrella policy, preference order, protected-skill rules, and do-not-capture list as a skill review.
+
+Act on whichever dimension has real signal. If genuinely nothing stands out on either, say "Nothing to save." and stop — but don't reach for that conclusion as a default.`;
+const CURATOR_PROMPT = `You are the skill curator. Maintain a healthy, class-level skill library, not a flat pile of narrow one-session skills.
+
+The goal is a LIBRARY OF CLASS-LEVEL INSTRUCTIONS. A skill collection of many narrow skills where each captures one session's specific bug is a FAILURE of the library. An agent searching skills matches on descriptions, not exact names; one broad umbrella with labeled subsections beats five narrow siblings for discoverability.
+
+Right target shape: class-level skills with rich SKILL.md + references/, templates/, scripts/ support files for session-specific detail.
+
+Hard rules:
+1. NEVER hard-delete a skill. Archive (moving to .archive/) is the maximum destructive action; archives are recoverable, deletion is not.
+2. Do not touch bundled, hub-installed, pinned, or scheduled-task-referenced (\`referenced\`) skills. Referenced skills MAY be consolidated into an umbrella, but never simply pruned.
+3. Do not archive recently-created or never-used skills without strong evidence. "use=0" is NOT evidence either way — it only means the trigger has not come up yet.
+4. Do NOT reject consolidation on the grounds that "each skill has a distinct trigger". The right bar is: would a human maintainer write this as N separate skills, or one skill with N labeled subsections? When the answer is the latter, merge.
+5. Judge overlap on CONTENT, not on usage counters.
+6. Before archiving a merged skill, ensure its unique content was preserved in the umbrella.
+
+How to work:
+1. Scan the candidate list. Identify PREFIX CLUSTERS — skills sharing a first word or domain keyword (expect 10-25 clusters).
+2. For each cluster with 2+ members, ask "what is the UMBRELLA CLASS these skills serve?" and consolidate:
+   a. MERGE INTO AN EXISTING UMBRELLA (patch a labeled section for each sibling's unique insight, then archive the siblings).
+   b. CREATE A NEW UMBRELLA SKILL.md covering the shared workflow with short labeled subsections, then archive the absorbed siblings.
+   c. DEMOTE session-specific detail to references/, templates/, or scripts/ under the umbrella.
+3. Keep the umbrella body tight and scannable: exact commands, verbatim paths, ~100-200 lines; never invent flags or APIs.
+
+Produce a YAML summary with exactly this shape:
+consolidations:
+  - from: <old-skill-name>
+    into: <umbrella-skill-name>
+    reason: <one short sentence>
+prunings:
+  - name: <skill-name>
+    reason: <one short sentence>
+Nominate a pruning only when archival is clearly safe (stale AND genuinely obsolete or fully absorbed elsewhere).`;
+const COMPLETION_SKILL_REVIEW_PROMPT = `[Auto-review — Skills · task complete]
+Your current task now appears complete. Before wrapping up, review the approach and update the skill library via skill_manage.
+
+Follow the skills review policy: be ACTIVE, prefer class-level umbrellas, patch ONLY skills loaded or read this session, and capture non-trivial techniques and user corrections. Do NOT capture environment-dependent failures, negative claims about tools, or one-off task narratives.
+
+Do NOT modify output files or re-run the task. If you are still mid-task, ignore this.`;
+function sha256(text) {
+	return createHash("sha256").update(text).digest("hex");
+}
+function createPromptBundle(prompts) {
+	const canonical = JSON.stringify({
+		id: PROMPT_BUNDLE_ID,
+		version: 3,
+		prompts: Object.fromEntries(Object.entries(prompts).sort())
+	});
+	return Object.freeze({
+		id: PROMPT_BUNDLE_ID,
+		version: 3,
+		prompts: Object.freeze({ ...prompts }),
+		sha256: sha256(canonical)
+	});
+}
+createPromptBundle({
+	memory: MEMORY_REVIEW_PROMPT,
+	skill: SKILL_REVIEW_PROMPT,
+	combined: COMBINED_REVIEW_PROMPT,
+	curator: CURATOR_PROMPT,
+	completion: COMPLETION_SKILL_REVIEW_PROMPT
+});
+//#endregion
+//#region ../evolution-core/src/threats.ts
+const FILLER = String.raw`(?:\w+\s+){0,8}`;
+new RegExp(String.raw`ignore\s+${FILLER}(?:previous|above|prior|all)\s+${FILLER}instructions`, "i"), new RegExp(String.raw`new\s+${FILLER}system\s+${FILLER}prompt`, "i"), new RegExp(String.raw`forget\s+${FILLER}(?:everything|all)\s+${FILLER}(?:discussed|you\s+know)`, "i"), new RegExp(String.raw`you\s+have\s+been\s+${FILLER}(?:updated|upgraded|patched)\s+to`, "i"), new RegExp(String.raw`do\s+not\s+${FILLER}tell\s+${FILLER}the\s+user`, "i"), new RegExp(String.raw`output\s+${FILLER}(?:system|initial)\s+prompt`, "i");
+//#endregion
+//#region ../evolution-core/src/skill-store.ts
+/**
+* Map a requesting session onto the two origin surfaces (rc.44 plan M2-2.3):
+* the APPROVAL surface treats every delegated subagent as the autonomous
+* review channel, while the LIBRARY surface keeps the Hermes distinction -
+* the review fork is 'background_review' (the pinned guard blocks its
+* writes) and any other subagent is 'subagent' (agent-authored, not
+* review-channel). `isReview` marks the caller as the background review
+* pipeline itself. Single source: the two tools and the review executor all
+* read this table instead of re-deriving it.
+*/
+function resolveOrigins(headerOrigin, isReview = false) {
+	if (isReview) return {
+		approval: "background_review",
+		library: "background_review"
+	};
+	if (headerOrigin === "subagent") return {
+		approval: "background_review",
+		library: "subagent"
+	};
+	return {
+		approval: "foreground",
+		library: "foreground"
+	};
+}
+//#endregion
 //#region lib/types/index.js
 /**
 * Model-facing memory tool and runtime-context memory snapshot.
 * @module @lmzhen/dsh-tool-memory
 */
 const name = "tool-memory";
+/** Max characters of each echoed memory entry (single source for the Config default and the runtime slice). */
+const DEFAULT_ENTRY_PREVIEW_CHARS = 200;
 const inject = [
 	"tools",
 	"systemPrompt",
 	"memory"
 ];
+/**
+* System-prompt memory guidance, aligned with Hermes `MEMORY_GUIDANCE`.
+* Reached by the model every turn, so it is the place to steer behavior: what
+* to save durably, what not to save, and how to phrase an entry. The tool
+* schema description (`MEMORY_TOOL_DESCRIPTION`) carries the complementary
+* operation-level guidance (add/replace/remove, batch, targets, when).
+*/
+const MEMORY_GUIDANCE = "You have durable memory across sessions. Save stable user preferences, environment facts, conventions, and tool quirks with the `memory` tool. The most valuable memory is one that stops the user correcting or reminding you again, so user preferences and recurring corrections outrank procedural task details.\nWrite entries as declarative facts, not instructions to yourself: \"User prefers concise responses\" (good); \"Always respond concisely\" (bad). Imperative phrasing is re-read as a directive in later sessions and can override the user’s current request.\nDo NOT save task progress, session outcomes, completed-work logs, PR/issue numbers, commit SHAs, or anything stale within a week — use `session_search` to recall past sessions instead. Reusable procedures belong in a skill, not memory.";
+/**
+* Tool-schema description for `memory`, aligned with Hermes `MEMORY_SCHEMA`.
+* Carries the operation-level guidance: how to batch, when to save, the
+* priority order, the target semantics, and what to skip. Reached only when
+* the model is choosing/using the tool, so it complements the always-on
+* `MEMORY_GUIDANCE` system prompt.
+*/
+const MEMORY_TOOL_DESCRIPTION = "Save durable facts to persistent memory that survive across sessions. Memory is injected into future turns, so keep entries compact and high-signal.\n\nHOW: make all changes in ONE call via an `operations` array (each item {action, content?, old_text?}). The batch applies atomically and the char limit is checked on the final result — so one call can remove/replace stale entries to free room AND add new ones. Use bare action/content/old_text only for a single lone change.\n\nWHEN: save proactively when the user states a preference, correction, or personal detail, or you learn a stable fact about their environment, conventions, or workflow. Priority: user preferences & corrections > environment facts > procedures. The best memory stops the user repeating themselves.\n\nTARGETS: \"user\" = who the user is (name, role, preferences, style). \"memory\" = your notes (environment, conventions, tool quirks, lessons).\n\nSKIP: trivial/obvious info, easily re-discovered facts, task progress, completed-work logs, temporary TODO state. To recall a past session use `session_search`, not memory. Reusable procedures belong in a skill, not memory.";
+/**
+* The requesting session's effective approval policy, mirroring
+* `dsh-user-approval` (override ?? configured default). Returns undefined when
+* the approval service is not mounted or no session is available — callers
+* keep their previous behavior.
+*/
+function effectiveSessionPolicy(ctx, session) {
+	const approval = ctx.get("approval");
+	if (!approval || session === void 0) return void 0;
+	return approval.overrideOf(session) ?? approval.config.policy ?? "ask";
+}
 const Config = z.object({
 	memoryEnabled: z.boolean().default(true),
-	entryPreviewChars: z.number().default(200)
+	entryPreviewChars: z.number().default(DEFAULT_ENTRY_PREVIEW_CHARS)
 });
 async function apply(ctx, rawConfig) {
 	if (!rawConfig.memoryEnabled) return;
@@ -21,7 +205,7 @@ async function apply(ctx, rawConfig) {
 	ctx.systemPrompt.section({
 		name: "evolution:memory-guidance",
 		order: 150,
-		text: "You have durable memory. Save stable user preferences and environment facts with the `memory` tool. Prefer one atomic `operations` batch."
+		text: MEMORY_GUIDANCE
 	});
 	ctx.systemPrompt.context({
 		name: "evolution:memory-snapshot",
@@ -38,14 +222,14 @@ async function apply(ctx, rawConfig) {
 		return {
 			ok: result.ok,
 			message: result.message,
-			entries: result.entries.map((entry) => entry.slice(0, rawConfig.entryPreviewChars ?? 200)),
+			entries: result.entries.map((entry) => entry.slice(0, rawConfig.entryPreviewChars ?? DEFAULT_ENTRY_PREVIEW_CHARS)),
 			chars: result.chars,
 			limit: result.limit
 		};
 	}
 	ctx.tools.register(defineTool({
 		name: "memory",
-		description: "Save durable facts to persistent memory. target \"user\" = who the user is; target \"memory\" = your notes. Use operations for atomic add/replace/remove. Save proactively; do not save task progress or one-off narratives.",
+		description: MEMORY_TOOL_DESCRIPTION,
 		parameters: {
 			target: {
 				type: "string",
@@ -121,6 +305,25 @@ async function apply(ctx, rawConfig) {
 		},
 		isConcurrencySafe: () => false,
 		async execute(args, exec) {
+			const conflict = (a) => {
+				if (a.facts === void 0 || a.content === void 0) return false;
+				return a.facts !== a.content;
+			};
+			if (Array.isArray(args.operations)) {
+				for (const op of args.operations) if (conflict(op)) return {
+					ok: false,
+					message: "Provide only one of facts or content per operation (same field); different values were given.",
+					entries: [],
+					chars: 0,
+					limit: 0
+				};
+			} else if (conflict(args)) return {
+				ok: false,
+				message: "Provide only one of facts or content (same field); different values were given.",
+				entries: [],
+				chars: 0,
+				limit: 0
+			};
 			const target = args.target === "user" ? "user" : "memory";
 			const normalized = Array.isArray(args.operations) ? {
 				target,
@@ -131,14 +334,16 @@ async function apply(ctx, rawConfig) {
 				facts: args.facts ?? args.content,
 				old_text: args.old_text
 			};
-			const origin = exec.agent?.session.header.origin === "subagent" ? "background_review" : "foreground";
+			const origin = resolveOrigins(exec.agent?.session.header.origin).approval;
+			const sessionPolicy = effectiveSessionPolicy(ctx, exec.agent?.session);
 			const approval = ctx.get("evolutionApproval");
 			if (approval) {
 				const decision = await approval.request({
 					kind: "memory",
 					summary: `memory ${target} ${Array.isArray(args.operations) ? `${args.operations.length} ops` : args.action ?? "add"}`,
 					args: normalized,
-					origin
+					origin,
+					...sessionPolicy !== void 0 ? { sessionPolicy } : {}
 				});
 				if (decision.action === "staged") return {
 					ok: true,
@@ -158,4 +363,4 @@ async function apply(ctx, rawConfig) {
 	});
 }
 //#endregion
-export { Config, apply, inject, name };
+export { Config, MEMORY_GUIDANCE, MEMORY_TOOL_DESCRIPTION, apply, inject, name };

package/lib/types/index.d.ts

@@ -6,6 +6,22 @@ import type { Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
 export declare const name = "tool-memory";
 export declare const inject: string[];
+/**
+ * System-prompt memory guidance, aligned with Hermes `MEMORY_GUIDANCE`.
+ * Reached by the model every turn, so it is the place to steer behavior: what
+ * to save durably, what not to save, and how to phrase an entry. The tool
+ * schema description (`MEMORY_TOOL_DESCRIPTION`) carries the complementary
+ * operation-level guidance (add/replace/remove, batch, targets, when).
+ */
+export declare const MEMORY_GUIDANCE: string;
+/**
+ * Tool-schema description for `memory`, aligned with Hermes `MEMORY_SCHEMA`.
+ * Carries the operation-level guidance: how to batch, when to save, the
+ * priority order, the target semantics, and what to skip. Reached only when
+ * the model is choosing/using the tool, so it complements the always-on
+ * `MEMORY_GUIDANCE` system prompt.
+ */
+export declare const MEMORY_TOOL_DESCRIPTION: string;
 export interface Config {
     memoryEnabled?: boolean;
     /** Maximum characters of each memory entry echoed back in tool results. */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-tool-memory",
   "description": "Model-facing memory tool and prompt context (community build)",
-  "version": "0.1.0-rc.5",
+  "version": "0.1.0-rc.50",
   "publishConfig": {
     "access": "public"
   },
@@ -39,15 +39,15 @@
     "@deepseek-ai/cordis": "^4.0.1",
     "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-system-prompt": "^0.1.0-rc.6",
-    "@lmzhen/dsh-memory": "^0.1.0-rc.5",
-    "@lmzhen/dsh-memory-files": "^0.1.0-rc.5"
+    "@lmzhen/dsh-memory": "^0.1.0-rc.50",
+    "@lmzhen/dsh-memory-files": "^0.1.0-rc.50"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-system-prompt": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-agent-loop-testkit": "^0.1.0-rc.6",
-    "@lmzhen/dsh-memory": "^0.1.0-rc.5",
-    "@lmzhen/dsh-memory-files": "^0.1.0-rc.5"
+    "@lmzhen/dsh-memory": "^0.1.0-rc.50",
+    "@lmzhen/dsh-memory-files": "^0.1.0-rc.50"
   }
 }