dsh-mnemon-source-runtime 0.5.11 → 0.5.13

package/lib/client.js

@@ -51,6 +51,7 @@ window.__ModuleLoader__.load({
 			"runtime.result.remove": "已从{target}移除 · 当前 {count} 条",
 			"runtime.result.maintenance": "容量整理完成：已先归档到记忆空间 {spaces}，再更新{target} · 当前 {count} 条",
 			"runtime.result.localCompaction": "本地画像整理完成：未写入记忆空间，已更新{target} · 当前 {count} 条",
+			"runtime.result.localArchive": "容量整理完成：没有可写的记忆空间，已先把 {archived} 条移入本地归档，再更新{target} · 当前 {count} 条",
 			"runtime.readOnly": "当前为只读模式；运行时记忆仍会进入上下文，但不能在此修改。",
 			"runtime.footnote": "memories.json 是唯一事实源；两个 Markdown 文件由控制层生成，不应直接编辑。"
 		};
@@ -97,6 +98,7 @@ window.__ModuleLoader__.load({
 			"runtime.result.remove": "Removed from {target} · {count} entries",
 			"runtime.result.maintenance": "Capacity maintenance complete: archived to {spaces}, then updated {target} · {count} entries",
 			"runtime.result.localCompaction": "Local profile compaction complete: no Memory Space write; updated {target} · {count} entries",
+			"runtime.result.localArchive": "Capacity maintenance complete: with no Memory Space to write to, moved {archived} entries to the local archive, then updated {target} · {count} entries",
 			"runtime.readOnly": "Read only here: runtime memory still enters context but cannot be changed on this page.",
 			"runtime.footnote": "memories.json is the only source of truth. The control plane generates both Markdown files; do not edit them directly."
 		};
@@ -251,6 +253,10 @@ window.__ModuleLoader__.load({
 				}) : result.maintenance.kind === "local-compaction" ? t("runtime.result.localCompaction", {
 					target: t(`runtime.target.${request.target}`),
 					count: result.entryCount
+				}) : result.maintenance.kind === "local-archive" ? t("runtime.result.localArchive", {
+					target: t(`runtime.target.${request.target}`),
+					count: result.entryCount,
+					archived: result.archived?.entries ?? 0
 				}) : t("runtime.result.maintenance", {
 					target: t(`runtime.target.${request.target}`),
 					count: result.entryCount,

package/lib/contracts.d.ts

@@ -55,8 +55,13 @@ type RuntimeMemoryMutationResult = {
     to: string;
   };
   removed?: string;
+  /** MEMORY.md entries a compaction moved to the local archive, when it ran with `archive: 'local'`. */
+  archived?: {
+    entries: number;
+    path: string;
+  };
   maintenance?: {
-    kind: 'local-compaction' | 'mnemon-archive';
+    kind: 'local-compaction' | 'mnemon-archive' | 'local-archive';
     runId: string;
     provider: string;
     summary: string;
@@ -74,6 +79,8 @@ interface RuntimeMemoryMaintenancePlan {
   projected: number;
   limit: number;
   requiresMaintenance: boolean;
+  /** This Runtime Source moves the entries compaction leaves out to its local archive when asked (#336). */
+  localArchive?: true;
 }
 declare const RUNTIME_MEMORY_VERSION = 1;
 declare const RUNTIME_ENTRY_DELIMITER = "\n§\n";

package/lib/index.js

@@ -5,7 +5,7 @@ import { basename, isAbsolute, join } from "node:path";
 import z from "@deepseek-ai/schemastery";
 import { COMPOSABLE_MEMORY_API_VERSION } from "dsh-mnemon/contracts";
 import { execFileSync } from "node:child_process";
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { closeSync, constants, existsSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, writeSync } from "node:fs";
 import { createHash } from "node:crypto";
 //#region src/config.ts
 const Config = z.object({
@@ -64,6 +64,16 @@ const LOCK_TIMEOUT_MS = 5e3;
 const LOCK_STALE_MS = 3e4;
 const LOCK_RETRY_MS = 20;
 const MAX_ENTRY_BYTES = 8192;
+/** Append to a file that is not a symbolic link; the open fails on one. */
+function appendWithoutLinks(path, text) {
+	const descriptor = openSync(path, constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | (constants.O_NOFOLLOW ?? 0), 384);
+	try {
+		const bytes = Buffer.from(text, "utf8");
+		for (let offset = 0; offset < bytes.length;) offset += writeSync(descriptor, bytes, offset, bytes.length - offset);
+	} finally {
+		closeSync(descriptor);
+	}
+}
 var RuntimeMemoryCapacityError = class extends Error {
 	target;
 	used;
@@ -267,12 +277,14 @@ function prepareMutation(before, request, now) {
 }
 function compactionCandidates(compacted, existing, target, now) {
 	const seen = /* @__PURE__ */ new Set();
+	const existingByContent = /* @__PURE__ */ new Map();
+	for (const entry of existing) if (!existingByContent.has(entry.content)) existingByContent.set(entry.content, entry);
 	return compacted.map((entry) => {
 		const content = normalizeContent(entry.content, "compacted content");
 		if (!isImportance(entry.importance)) throw new Error("compacted importance must be critical, normal, or low");
 		if (seen.has(content)) throw new Error("compacted runtime memory contains duplicate entries");
 		seen.add(content);
-		const unchanged = existing.find((current) => current.content === content);
+		const unchanged = existingByContent.get(content);
 		const inheritedBranches = entry.branches ?? unchanged?.branches;
 		return {
 			content,
@@ -285,21 +297,28 @@ function compactionCandidates(compacted, existing, target, now) {
 	});
 }
 function packCompactionCandidates(replacements, target, maxBytes) {
-	const priority = {
-		critical: 0,
-		normal: 1,
-		low: 2
+	const ranked = {
+		critical: [],
+		normal: [],
+		low: []
 	};
-	const ranked = replacements.map((entry, index) => ({
-		entry,
-		index
-	})).sort((left, right) => priority[left.entry.importance] - priority[right.entry.importance] || left.index - right.index);
+	replacements.forEach((entry, index) => ranked[entry.importance].push(index));
 	const selected = /* @__PURE__ */ new Set();
-	const packed = [];
-	for (const candidate of ranked) {
-		if (byteCount([...packed, candidate.entry], target) > maxBytes) continue;
-		packed.push(candidate.entry);
-		selected.add(candidate.index);
+	const delimiterBytes = Buffer.byteLength(RUNTIME_ENTRY_DELIMITER, "utf8");
+	let used = 0;
+	let count = 0;
+	for (const importance of [
+		"critical",
+		"normal",
+		"low"
+	]) for (const index of ranked[importance]) {
+		const entry = replacements[index];
+		const matchesTarget = entry.target === target;
+		const added = matchesTarget ? Buffer.byteLength(entry.content, "utf8") + (count === 0 ? 0 : delimiterBytes) : 0;
+		if (used + added > maxBytes) continue;
+		used += added;
+		if (matchesTarget) count += 1;
+		selected.add(index);
 	}
 	return replacements.filter((_, index) => selected.has(index));
 }
@@ -319,6 +338,9 @@ var RuntimeMemoryController = class RuntimeMemoryController {
 	memoryPath;
 	userPath;
 	lockPath;
+	/** Where MEMORY.md entries go when compaction leaves them out and no Memory Space can take them. */
+	archivePath;
+	archiveSourcePath;
 	limits;
 	queue = Promise.resolve();
 	localUserPath;
@@ -335,6 +357,8 @@ var RuntimeMemoryController = class RuntimeMemoryController {
 		this.memoryPath = join(this.directory, "MEMORY.md");
 		this.localUserPath = join(this.directory, "USER.md");
 		this.lockPath = join(this.directory, ".memories.lock");
+		this.archivePath = join(this.directory, "archived", "MEMORY.md");
+		this.archiveSourcePath = join(this.directory, "archived", "memories.jsonl");
 		const userDirectory = userRunner === void 0 ? this.directory : join(userRunner.effectiveDataDir(), "runtime");
 		this.userController = userDirectory === this.directory || userRunner === void 0 ? void 0 : new RuntimeMemoryController(userRunner, now, this.limits);
 		this.userPath = this.userController?.userPath ?? this.localUserPath;
@@ -466,18 +490,24 @@ ${memory || "(empty)"}
 				used,
 				projected,
 				limit,
-				requiresMaintenance: prepared.changed && projected > limit
+				requiresMaintenance: prepared.changed && projected > limit,
+				localArchive: true
 			};
 		}));
 		this.queue = operation.catch(() => void 0);
 		return operation;
 	}
-	/** Commit semantic compaction and the original mutation together, or leave every local file unchanged. */
-	compactAndMutate(expectedRevision, request, compacted, maxCompactedBytes) {
+	/**
+	* Commit semantic compaction and the original mutation together, or leave every local file unchanged.
+	* With `archive: 'local'`, committed MEMORY.md entries that compaction leaves out are appended to the
+	* local archive first, so a limit with no Memory Space to archive into never loses memory.
+	*/
+	compactAndMutate(expectedRevision, request, compacted, maxCompactedBytes, options = {}) {
 		if (request.target === "user" && this.userController !== void 0) return this.userController.compactAndMutate(expectedRevision, request, compacted, maxCompactedBytes);
 		const operation = this.queue.then(() => this.withLock(() => {
 			const file = this.readSource();
-			if (revision(file) !== expectedRevision) throw new RuntimeMemoryConflictError();
+			const beforeRevision = revision(file);
+			if (beforeRevision !== expectedRevision) throw new RuntimeMemoryConflictError();
 			const now = this.now().toISOString();
 			const prepared = prepareMutation(file.entries, request, now);
 			const compactedByteBudget = maxCompactedBytes ?? this.limits[request.target];
@@ -486,7 +516,8 @@ ${memory || "(empty)"}
 			const replacements = compactionCandidates(compacted, prepared.compactableEntries, request.target, now);
 			if (prepared.pendingEntry !== void 0 && replacements.some((entry) => entry.content === prepared.pendingEntry.content)) throw new Error("compacted runtime memory duplicates the pending mutation");
 			if (prepared.excludedEntry !== void 0 && replacements.some((entry) => entry.content === prepared.excludedEntry.content)) throw new Error("compacted runtime memory reintroduces the replaced or removed entry");
-			const targetEntries = [...packCompactionCandidates(replacements, request.target, compactedByteBudget), ...prepared.pendingEntry === void 0 ? [] : [prepared.pendingEntry]];
+			const fitted = packCompactionCandidates(replacements, request.target, compactedByteBudget);
+			const targetEntries = [...fitted, ...prepared.pendingEntry === void 0 ? [] : [prepared.pendingEntry]];
 			const entries = [...file.entries.filter((entry) => entry.target !== request.target), ...targetEntries];
 			const used = byteCount(entries, request.target);
 			const limit = this.limits[request.target];
@@ -495,12 +526,47 @@ ${memory || "(empty)"}
 				version: 1,
 				entries
 			};
+			const kept = new Set(fitted.map((entry) => entry.content));
+			const archived = options.archive === "local" && request.target === "memory" ? prepared.compactableEntries.filter((entry) => !kept.has(entry.content)) : void 0;
+			if (archived !== void 0 && archived.length > 0) this.archiveLocally(archived, beforeRevision, now);
 			this.persist(next);
-			return this.result(request.target, entries, prepared.fields);
+			return {
+				...this.result(request.target, entries, prepared.fields),
+				...archived === void 0 ? {} : { archived: {
+					entries: archived.length,
+					path: this.archivePath
+				} }
+			};
 		}));
 		this.queue = operation.catch(() => void 0);
 		return operation;
 	}
+	/** Append entries to the local archive: JSON Lines to restore from, and Markdown to read. */
+	archiveLocally(entries, fromRevision, archivedAt) {
+		const directory = join(this.directory, "archived");
+		mkdirSync(directory, {
+			recursive: true,
+			mode: 448
+		});
+		const stat = lstatSync(directory);
+		if (stat.isSymbolicLink() || !stat.isDirectory()) throw new Error(`Runtime Memory archive is not a directory: ${directory}`);
+		for (const path of [this.archiveSourcePath, this.archivePath]) {
+			let file;
+			try {
+				file = lstatSync(path);
+			} catch {
+				continue;
+			}
+			if (!file.isFile()) throw new Error(`Runtime Memory archive file is not a regular file: ${path}`);
+		}
+		appendWithoutLinks(this.archiveSourcePath, entries.map((entry) => `${JSON.stringify({
+			archivedAt,
+			fromRevision,
+			...entry
+		})}\n`).join(""));
+		const header = existsSync(this.archivePath) ? "" : "# MEMORY.md archive\n\nEntries that left MEMORY.md at its limit while no Memory Space could take them, oldest first.\n";
+		appendWithoutLinks(this.archivePath, `${header}\n## ${archivedAt}\n\n${entries.map((entry) => entry.content).join(RUNTIME_ENTRY_DELIMITER)}\n`);
+	}
 	initialize() {
 		mkdirSync(this.directory, {
 			recursive: true,
@@ -834,7 +900,8 @@ function createRuntimeMemorySource(config = {}) {
 								...entry.branches === void 0 ? {} : { branches: memoryInputStringArray(entry.branches, "branches", 100) ?? [] }
 							};
 						});
-						result = await controller.compactAndMutate(memoryInputText(input.revision, "revision", 300), runtimeMutation(input.mutation), compacted, typeof input.maxBytes === "number" ? input.maxBytes : void 0);
+						if (input.archive !== void 0 && input.archive !== "local") throw new Error("archive must be \"local\" when given");
+						result = await controller.compactAndMutate(memoryInputText(input.revision, "revision", 300), runtimeMutation(input.mutation), compacted, typeof input.maxBytes === "number" ? input.maxBytes : void 0, input.archive === "local" ? { archive: "local" } : {});
 					} else throw new Error("unsupported Runtime management mutation operation: " + request.operation);
 					return {
 						revision: controller.snapshot().revision,

package/lib/types/contracts.d.ts

@@ -54,8 +54,13 @@ export type RuntimeMemoryMutationResult = {
         to: string;
     };
     removed?: string;
+    /** MEMORY.md entries a compaction moved to the local archive, when it ran with `archive: 'local'`. */
+    archived?: {
+        entries: number;
+        path: string;
+    };
     maintenance?: {
-        kind: 'local-compaction' | 'mnemon-archive';
+        kind: 'local-compaction' | 'mnemon-archive' | 'local-archive';
         runId: string;
         provider: string;
         summary: string;
@@ -73,6 +78,8 @@ export interface RuntimeMemoryMaintenancePlan {
     projected: number;
     limit: number;
     requiresMaintenance: boolean;
+    /** This Runtime Source moves the entries compaction leaves out to its local archive when asked (#336). */
+    localArchive?: true;
 }
 export declare const RUNTIME_MEMORY_VERSION = 1;
 export declare const RUNTIME_ENTRY_DELIMITER = "\n\u00A7\n";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-mnemon-source-runtime",
-  "version": "0.5.11",
+  "version": "0.5.13",
   "description": "Self-contained runtime Source for Composable View Memory.",
   "license": "MIT",
   "type": "module",
@@ -60,7 +60,7 @@
     "@types/node": "^22.0.0",
     "@types/react": "^18.3.0",
     "@types/react-dom": "^18.3.0",
-    "dsh-mnemon": "^0.5.19",
+    "dsh-mnemon": "^0.5.25",
     "jsdom": "^26.0.0",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",

package/presentation/locales.json

@@ -42,6 +42,7 @@
     "runtime.result.remove": "已从{target}移除 · 当前 {count} 条",
     "runtime.result.maintenance": "容量整理完成：已先归档到记忆空间 {spaces}，再更新{target} · 当前 {count} 条",
     "runtime.result.localCompaction": "本地画像整理完成：未写入记忆空间，已更新{target} · 当前 {count} 条",
+    "runtime.result.localArchive": "容量整理完成：没有可写的记忆空间，已先把 {archived} 条移入本地归档，再更新{target} · 当前 {count} 条",
     "runtime.readOnly": "当前为只读模式；运行时记忆仍会进入上下文，但不能在此修改。",
     "runtime.footnote": "memories.json 是唯一事实源；两个 Markdown 文件由控制层生成，不应直接编辑。"
   },
@@ -88,6 +89,7 @@
     "runtime.result.remove": "Removed from {target} · {count} entries",
     "runtime.result.maintenance": "Capacity maintenance complete: archived to {spaces}, then updated {target} · {count} entries",
     "runtime.result.localCompaction": "Local profile compaction complete: no Memory Space write; updated {target} · {count} entries",
+    "runtime.result.localArchive": "Capacity maintenance complete: with no Memory Space to write to, moved {archived} entries to the local archive, then updated {target} · {count} entries",
     "runtime.readOnly": "Read only here: runtime memory still enters context but cannot be changed on this page.",
     "runtime.footnote": "memories.json is the only source of truth. The control plane generates both Markdown files; do not edit them directly."
   }