@lmzhen/dsh-tool-memory 0.1.0-rc.1

package/README.md

@@ -0,0 +1,24 @@
+# @deepseek-ai/dsh-tool-memory
+
+Model-facing memory tool and prompt context
+
+## Model Experience
+
+### Memory tool and runtime snapshot
+
+#### What the model sees
+
+The model sees the `memory` tool schema, one fixed guidance section, and a runtime snapshot containing the current memory entries.
+
+#### Token effect
+
+Fixed guidance has a constant token cost. The runtime snapshot scales with stored memory entries and is absent when memory is empty.
+
+#### KV Cache effect
+
+Guidance text is prefix-stable. The runtime snapshot is replaced after successful memory writes and is otherwise unchanged between requests.
+
+## Known Limitations and Deferred Work
+
+
+- No known durable consumer gaps at this time. Runtime contracts are covered by package and boundary tests.

package/lib/index.js

@@ -0,0 +1,161 @@
+import z from "@deepseek-ai/schemastery";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+//#region lib/types/index.js
+/**
+* Model-facing memory tool and runtime-context memory snapshot.
+* @module @lmzhen/dsh-tool-memory
+*/
+const name = "tool-memory";
+const inject = [
+	"tools",
+	"systemPrompt",
+	"memory"
+];
+const Config = z.object({
+	memoryEnabled: z.boolean().default(true),
+	entryPreviewChars: z.number().default(200)
+});
+async function apply(ctx, rawConfig) {
+	if (!rawConfig.memoryEnabled) return;
+	let snapshotText = await ctx.memory.renderContext();
+	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."
+	});
+	ctx.systemPrompt.context({
+		name: "evolution:memory-snapshot",
+		order: 150,
+		text: () => snapshotText
+	});
+	async function executeCore(normalized) {
+		const result = normalized.operations ? await ctx.memory.applyBatch(normalized.target, normalized.operations) : await ctx.memory.applyBatch(normalized.target, [{
+			action: normalized.action ?? "add",
+			facts: normalized.facts,
+			old_text: normalized.old_text
+		}]);
+		if (result.ok) snapshotText = await ctx.memory.renderContext();
+		return {
+			ok: result.ok,
+			message: result.message,
+			entries: result.entries.map((entry) => entry.slice(0, rawConfig.entryPreviewChars ?? 200)),
+			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.",
+		parameters: {
+			target: {
+				type: "string",
+				enum: ["memory", "user"],
+				required: true
+			},
+			action: {
+				type: "string",
+				enum: [
+					"add",
+					"replace",
+					"remove"
+				]
+			},
+			facts: { type: "string" },
+			content: { type: "string" },
+			old_text: { type: "string" },
+			operations: {
+				type: "array",
+				items: {
+					type: "object",
+					additionalProperties: false,
+					properties: {
+						action: {
+							type: "string",
+							enum: [
+								"add",
+								"replace",
+								"remove"
+							],
+							required: true
+						},
+						facts: { type: "string" },
+						content: { type: "string" },
+						old_text: { type: "string" }
+					}
+				}
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					ok: {
+						type: "boolean",
+						required: true
+					},
+					message: {
+						type: "string",
+						required: true
+					},
+					entries: {
+						type: "array",
+						required: true,
+						items: { type: "string" }
+					},
+					chars: {
+						type: "integer",
+						required: true
+					},
+					limit: {
+						type: "integer",
+						required: true
+					},
+					pending_id: { type: "string" }
+				}
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: `${value.ok ? "OK" : "Error"}: ${value.message} (${value.chars}/${value.limit} chars)`
+			}]
+		},
+		isConcurrencySafe: () => false,
+		async execute(args, exec) {
+			const target = args.target === "user" ? "user" : "memory";
+			const normalized = Array.isArray(args.operations) ? {
+				target,
+				operations: args.operations
+			} : {
+				target,
+				action: args.action ?? "add",
+				facts: args.facts ?? args.content,
+				old_text: args.old_text
+			};
+			const origin = exec.agent?.session.header.origin === "subagent" ? "background_review" : "foreground";
+			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
+				});
+				if (decision.action === "staged") return {
+					ok: true,
+					message: decision.message,
+					entries: [],
+					chars: 0,
+					limit: 0,
+					pending_id: decision.pendingId ?? ""
+				};
+			}
+			return await executeCore(normalized);
+		}
+	}));
+	ctx.inject(["evolutionApproval"], (approvalCtx) => {
+		const dispose = approvalCtx.evolutionApproval.registerRunner("memory", (args) => executeCore(args));
+		approvalCtx.effect(() => dispose, "tool-memory.approval-runner");
+	});
+}
+//#endregion
+export { Config, apply, inject, name };

package/lib/invariant.js

@@ -0,0 +1,8 @@
+//#region lib/types/invariant.js
+const PACKAGE_NAME = "@deepseek-ai/dsh-tool-memory";
+const name = "tool-memory-invariant";
+const inject = ["invariants"];
+const install = () => {};
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Model-facing memory tool and runtime-context memory snapshot.
+ * @module @deepseek-ai/dsh-tool-memory
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+export declare const name = "tool-memory";
+export declare const inject: string[];
+export interface Config {
+    memoryEnabled?: boolean;
+    /** Maximum characters of each memory entry echoed back in tool results. */
+    entryPreviewChars?: number;
+}
+export declare const Config: z<Config>;
+export declare function apply(ctx: Context, rawConfig: Config): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,5 @@
+import type { Context } from '@deepseek-ai/cordis';
+export declare const name = "tool-memory-invariant";
+export declare const inject: string[];
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@lmzhen/dsh-tool-memory",
+  "description": "Model-facing memory tool and prompt context (community build)",
+  "version": "0.1.0-rc.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lmzhen/dsh-evolution.git",
+    "directory": "packages/dsh-tool-memory"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/invariant.d.ts"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+    "@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.1",
+    "@lmzhen/dsh-memory-files": "^0.1.0-rc.1"
+  },
+  "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.1",
+    "@lmzhen/dsh-memory-files": "^0.1.0-rc.1"
+  }
+}