dsh-mnemon-source-memory-spaces 0.5.21 → 0.5.23

package/lib/index.js

@@ -1,6 +1,6 @@
 import { findMnemonCommand, isMnemonExecutable, resolveMnemonInvocation } from "./native-cli.js";
-import { CATEGORIES as CATEGORIES$1, EDGE_TYPES, INTENTS as INTENTS$1, MNEMON_EMBEDDING_PROTOCOLS, SOURCES as SOURCES$1, normalizeEntityKey } from "./contracts.js";
-import { a as MemoryProviderCatalog, i as EMPTY_MEMORY_PROVIDER_CATALOG, n as PrivateMemorySpaceProviderHost, r as MemoryProviderAdapterRegistry, t as createMemorySpaceProviderPlugin } from "./plugin-DlsNeZbQ.js";
+import { CATEGORIES, EDGE_TYPES, INTENTS, MEMORY_PLACEMENT_CAPABILITIES, MEMORY_PROVIDER_REGISTRY_FILE, MEMORY_SPACES_DIRECTORY, MEMORY_SPACE_DATABASE_FILE, MEMORY_SPACE_DESCRIPTION_MAX_LENGTH, MEMORY_SPACE_ID_PATTERN, MEMORY_SPACE_REGISTRY_FILE, MNEMON_ACTIVE_STORE_FILE, MNEMON_EMBEDDING_PROTOCOLS, NATIVE_PROVIDER_ID, SOURCES, isNativeProvider, normalizeEntityKey } from "./contracts.js";
+import { a as MemoryProviderCatalog, i as EMPTY_MEMORY_PROVIDER_CATALOG, n as PrivateMemorySpaceProviderHost, r as MemoryProviderAdapterRegistry, t as createMemorySpaceProviderPlugin } from "./plugin-m1PeU1IE.js";
 import { i as runProcess, r as ProcessError } from "./adapter-D-BnWkko.js";
 import { r as defineMemorySpaceProvider } from "./definitions-DfmOqJjR.js";
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
@@ -104,7 +104,6 @@ function modelJson(value, maximum) {
 //#region src/memory-spaces.ts
 const NATIVE_REGISTRY_VERSION = 1;
 const PROVIDER_REGISTRY_VERSION = 4;
-const ID_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/;
 const PROVIDER_ID_PATTERN = /^[a-z][a-z0-9-]{0,127}$/u;
 const DISCONNECTS_VERSION = 1;
 /** Settings whose value can name a namespace: a bank, workspace, user, tag, URI or folder. */
@@ -191,10 +190,10 @@ function providerProjectionMetadata(providerCatalog, providerId, candidate) {
 	const nearestName = PROVIDER_METADATA_KEYS.map((key) => compactProviderMetadataValue(candidate.connection[key])).find((value) => value !== void 0);
 	const fallbackId = compactProviderMetadataValue(externalId) ?? externalId;
 	const name = (mappedName || nearestName || `${descriptor.label} ${fallbackId}`).slice(0, 100);
-	const description = (String(candidate.description ?? "").trim() || `${descriptor.label} memory namespace mapped from ${externalId}.`).slice(0, 1e3);
+	const description = (String(candidate.description ?? "").trim() || `${descriptor.label} memory namespace mapped from ${externalId}.`).slice(0, MEMORY_SPACE_DESCRIPTION_MAX_LENGTH);
 	return {
 		name: requiredText(name, "name", 100),
-		description: optionalText$1(description, "description", 1e3)
+		description: optionalText$1(description, "description", MEMORY_SPACE_DESCRIPTION_MAX_LENGTH)
 	};
 }
 function providerDisplayLocation(descriptor, connection) {
@@ -232,7 +231,7 @@ function normalizePlacementDecision(value, providerId, providerCatalog = EMPTY_M
 }
 function validateMemorySpaceId(value) {
 	const normalized = value.trim();
-	if (!ID_PATTERN.test(normalized)) throw new Error("memoryBodyId must match [a-zA-Z0-9][a-zA-Z0-9_-]*");
+	if (!MEMORY_SPACE_ID_PATTERN.test(normalized)) throw new Error("memoryBodyId must match [a-zA-Z0-9][a-zA-Z0-9_-]*");
 	return normalized;
 }
 /**
@@ -265,9 +264,9 @@ var MemorySpaceRegistry = class MemorySpaceRegistry {
 			serviceEnabled: {},
 			disconnected: {}
 		};
-		this.directory = join(runner.effectiveDataDir(), "data");
-		this.registryPath = join(this.directory, ".dsh-memory-bodies.json");
-		this.providerRegistryPath = join(runner.effectiveDataDir(), "state", "memory-providers.json");
+		this.directory = join(runner.effectiveDataDir(), MEMORY_SPACES_DIRECTORY);
+		this.registryPath = join(this.directory, MEMORY_SPACE_REGISTRY_FILE);
+		this.providerRegistryPath = join(runner.effectiveDataDir(), "state", MEMORY_PROVIDER_REGISTRY_FILE);
 		this.disconnectsPath = join(runner.effectiveDataDir(), "state", "memory-provider-disconnects.json");
 		if (sharedState === void 0) this.reload();
 	}
@@ -300,7 +299,7 @@ var MemorySpaceRegistry = class MemorySpaceRegistry {
 		return new MemorySpaceRegistry(this.runner, this.persistent, this.now, providerCatalog, this.state);
 	}
 	isNative(providerId) {
-		return this.providerTypeId(providerId) === "mnemon-native";
+		return this.providerTypeId(providerId) === NATIVE_PROVIDER_ID;
 	}
 	providerTypeId(providerId) {
 		const descriptor = this.providerCatalog.descriptor(providerId);
@@ -355,7 +354,7 @@ var MemorySpaceRegistry = class MemorySpaceRegistry {
 	}
 	providerServices(options = {}) {
 		this.refreshIfChanged();
-		const providers = this.providerCatalog.providers.filter((provider) => (provider.typeId ?? provider.id) !== "mnemon-native");
+		const providers = this.providerCatalog.providers.filter((provider) => !isNativeProvider(provider));
 		const items = providers.map((provider) => {
 			const connection = this.services[provider.id];
 			const publicConnection = this.providerCatalog.publicScoped(provider.id, "service", connection ?? {});
@@ -647,7 +646,7 @@ var MemorySpaceRegistry = class MemorySpaceRegistry {
 	}
 	async create(request, signal, placement) {
 		const name = requiredText(request.name, "name", 100);
-		const description = requiredText(request.description, "description", 1e3);
+		const description = requiredText(request.description, "description", MEMORY_SPACE_DESCRIPTION_MAX_LENGTH);
 		if (request.placement !== void 0 && placement === void 0) throw new Error("automatic provider placement must be resolved before creating a Memory Space");
 		if (placement !== void 0 && request.providerId !== void 0 && request.providerId !== placement.providerId) throw new Error("resolved provider placement conflicts with providerId");
 		const providerId = placement?.providerId ?? request.providerId ?? this.defaultProviderId();
@@ -734,7 +733,7 @@ var MemorySpaceRegistry = class MemorySpaceRegistry {
 		const body = {
 			...currentBody,
 			...request.name === void 0 ? {} : { name: requiredText(request.name, "name", 100) },
-			...request.description === void 0 ? {} : { description: optionalText$1(request.description, "description", 1e3) },
+			...request.description === void 0 ? {} : { description: optionalText$1(request.description, "description", MEMORY_SPACE_DESCRIPTION_MAX_LENGTH) },
 			...request.active === void 0 ? {} : { active: request.active },
 			...nativeProvider || request.name === void 0 && request.description === void 0 ? {} : { metadataSource: "manual" },
 			...connection === void 0 ? {} : { connection },
@@ -874,14 +873,14 @@ var MemorySpaceRegistry = class MemorySpaceRegistry {
 			const parsed = JSON.parse(readFileSync(this.registryPath, "utf8"));
 			if ((parsed.version === NATIVE_REGISTRY_VERSION || parsed.version === 2) && Array.isArray(parsed.bodies)) {
 				migratedProviderRegistry = parsed.version === 2;
-				this.spaces = parsed.bodies.filter((body) => ID_PATTERN.test(body.id)).map((body) => {
+				this.spaces = parsed.bodies.filter((body) => MEMORY_SPACE_ID_PATTERN.test(body.id)).map((body) => {
 					const syntheticDefault = body.id === "default" && body.name === "默认记忆体" && body.description === "从现有 Mnemon Store 自动接入。";
 					migratedSyntheticDefault ||= syntheticDefault;
-					const providerId = "providerId" in body && storedProviderId(body.providerId) ? body.providerId : "mnemon-native";
+					const providerId = "providerId" in body && storedProviderId(body.providerId) ? body.providerId : NATIVE_PROVIDER_ID;
 					if (!this.providerCatalog.has(providerId)) return {
 						id: body.id,
 						name: requiredText(body.name || body.id, "name", 100),
-						description: optionalText$1(body.description, "description", 1e3),
+						description: optionalText$1(body.description, "description", MEMORY_SPACE_DESCRIPTION_MAX_LENGTH),
 						active: body.active === true,
 						providerId,
 						connection: storedProviderConnection("connection" in body ? body.connection : void 0),
@@ -903,7 +902,7 @@ var MemorySpaceRegistry = class MemorySpaceRegistry {
 					return {
 						id: body.id,
 						name: requiredText(syntheticDefault ? body.id : body.name || body.id, "name", 100),
-						description: optionalText$1(syntheticDefault ? "Existing Mnemon Store discovered on disk." : body.description, "description", 1e3),
+						description: optionalText$1(syntheticDefault ? "Existing Mnemon Store discovered on disk." : body.description, "description", MEMORY_SPACE_DESCRIPTION_MAX_LENGTH),
 						active: body.active === true,
 						providerId,
 						...placement === void 0 ? {} : { placement },
@@ -927,12 +926,12 @@ var MemorySpaceRegistry = class MemorySpaceRegistry {
 			if ((parsed.version === 1 || parsed.version === 2 || parsed.version === 3 || parsed.version === PROVIDER_REGISTRY_VERSION) && Array.isArray(parsed.bodies)) {
 				migratedProviderRegistry ||= parsed.version !== PROVIDER_REGISTRY_VERSION;
 				const existingIds = new Set(this.spaces.map((body) => body.id));
-				this.spaces.push(...parsed.bodies.filter((body) => storedProviderId(body.providerId) && (!this.providerCatalog.has(body.providerId) || !this.isNative(body.providerId)) && ID_PATTERN.test(body.id) && !existingIds.has(body.id)).map((body) => {
+				this.spaces.push(...parsed.bodies.filter((body) => storedProviderId(body.providerId) && (!this.providerCatalog.has(body.providerId) || !this.isNative(body.providerId)) && MEMORY_SPACE_ID_PATTERN.test(body.id) && !existingIds.has(body.id)).map((body) => {
 					const providerId = body.providerId;
 					if (!this.providerCatalog.has(providerId)) return {
 						id: body.id,
 						name: requiredText(body.name || body.id, "name", 100),
-						description: optionalText$1(body.description, "description", 1e3),
+						description: optionalText$1(body.description, "description", MEMORY_SPACE_DESCRIPTION_MAX_LENGTH),
 						active: body.active === true,
 						providerId,
 						...typeof body.externalId !== "string" || body.externalId.trim() === "" ? {} : { externalId: body.externalId.trim() },
@@ -959,7 +958,7 @@ var MemorySpaceRegistry = class MemorySpaceRegistry {
 					return {
 						id: body.id,
 						name: requiredText(body.name || body.id, "name", 100),
-						description: optionalText$1(body.description, "description", 1e3),
+						description: optionalText$1(body.description, "description", MEMORY_SPACE_DESCRIPTION_MAX_LENGTH),
 						active: body.active === true,
 						providerId,
 						...typeof body.externalId !== "string" || body.externalId.trim() === "" ? {} : { externalId: body.externalId.trim() },
@@ -994,14 +993,14 @@ var MemorySpaceRegistry = class MemorySpaceRegistry {
 		let changed = false;
 		const knownIds = new Set(this.spaces.map((body) => body.id));
 		for (const entry of readdirSync(this.directory, { withFileTypes: true })) {
-			if (!entry.isDirectory() || !ID_PATTERN.test(entry.name) || !existsSync(join(this.directory, entry.name, "mnemon.db"))) continue;
+			if (!entry.isDirectory() || !MEMORY_SPACE_ID_PATTERN.test(entry.name) || !existsSync(join(this.directory, entry.name, "mnemon.db"))) continue;
 			if (knownIds.has(entry.name)) continue;
 			this.spaces.push({
 				id: entry.name,
 				name: entry.name,
 				description: "Existing Mnemon Store discovered on disk.",
 				active: this.spaces.length === 0 || entry.name === legacyActive,
-				providerId: "mnemon-native",
+				providerId: NATIVE_PROVIDER_ID,
 				createdAt: timestamp,
 				updatedAt: timestamp
 			});
@@ -1012,7 +1011,7 @@ var MemorySpaceRegistry = class MemorySpaceRegistry {
 	}
 	nativeStoreIds() {
 		if (!existsSync(this.directory)) return [];
-		return readdirSync(this.directory, { withFileTypes: true }).filter((entry) => entry.isDirectory() && ID_PATTERN.test(entry.name)).map((entry) => entry.name).sort();
+		return readdirSync(this.directory, { withFileTypes: true }).filter((entry) => entry.isDirectory() && MEMORY_SPACE_ID_PATTERN.test(entry.name)).map((entry) => entry.name).sort();
 	}
 	nextTimestamp(previous, candidate = this.now().toISOString()) {
 		if (previous === void 0) return candidate;
@@ -1027,7 +1026,7 @@ var MemorySpaceRegistry = class MemorySpaceRegistry {
 		const connection = nativeProvider ? {} : this.connectionFor(body);
 		const effectivePublicConnection = this.providerCatalog.public(body.providerId, connection);
 		const publicConnection = nativeProvider ? effectivePublicConnection : this.providerCatalog.publicScoped(body.providerId, "memory", body.connection ?? {});
-		const location = nativeProvider ? join(this.directory, body.id, "mnemon.db") : providerDisplayLocation(descriptor, connection);
+		const location = nativeProvider ? join(this.directory, body.id, MEMORY_SPACE_DATABASE_FILE) : providerDisplayLocation(descriptor, connection);
 		const provider = {
 			id: descriptor.id,
 			...descriptor.typeId === void 0 || descriptor.typeId === descriptor.id ? {} : { typeId: descriptor.typeId },
@@ -1156,10 +1155,10 @@ function createRunner(config, processRunner = runProcess) {
 	};
 	const effectiveDataDir = () => config.dataDir;
 	const persistedStore = () => {
-		const active = join(effectiveDataDir(), "active");
+		const active = join(effectiveDataDir(), MNEMON_ACTIVE_STORE_FILE);
 		if (existsSync(active)) try {
 			const value = readFileSync(active, "utf8").trim();
-			if (/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(value)) return value;
+			if (MEMORY_SPACE_ID_PATTERN.test(value)) return value;
 		} catch {}
 		return "default";
 	};
@@ -1473,6 +1472,11 @@ function scoreDecision(candidate, context, lowScoreAction, nonPositiveAction) {
 		tier: "unknown",
 		reason: "invalid-score"
 	};
+	if (candidate.scoreSemantics?.kind === "provider-native") return {
+		action: "keep",
+		tier: "ranked",
+		reason: "native-score"
+	};
 	if (candidate.scoreSemantics?.kind !== "normalized-relevance") return {
 		action: "keep",
 		tier: "unknown",
@@ -1486,8 +1490,8 @@ function scoreDecision(candidate, context, lowScoreAction, nonPositiveAction) {
 	};
 	if (score > 1) return {
 		action: "keep",
-		tier: "unknown",
-		reason: "unscaled-score"
+		tier: "ranked",
+		reason: "out-of-range-score"
 	};
 	if (score < context.config.lowScoreThreshold) return {
 		action: lowScoreAction,
@@ -1517,9 +1521,12 @@ const STRICT_RECALL_QUALITY_POLICY = {
 	evaluate: (candidate, context) => scoreDecision(candidate, context, "drop", "drop"),
 	select(candidates, context) {
 		const kept = candidates.filter((candidate) => candidate.decision.action === "keep");
+		let medium = 0;
+		let ranked = 0;
+		const scored = kept.filter(({ decision }) => decision.tier === "medium" ? medium++ < context.config.maxMediumResults : decision.tier === "ranked" && ranked++ < context.config.maxRankedResults);
 		return [
 			...kept.filter((candidate) => candidate.decision.tier === "high"),
-			...kept.filter((candidate) => candidate.decision.tier === "medium").slice(0, context.config.maxMediumResults),
+			...scored,
 			...kept.filter((candidate) => candidate.decision.tier === "unknown").slice(0, context.config.maxUnknownResults)
 		].slice(0, context.requestedLimit);
 	}
@@ -1548,6 +1555,7 @@ const ACTIONS = /* @__PURE__ */ new Set(["keep", "drop"]);
 const TIERS = /* @__PURE__ */ new Set([
 	"high",
 	"medium",
+	"ranked",
 	"low",
 	"unknown"
 ]);
@@ -1557,6 +1565,8 @@ const REASONS = /* @__PURE__ */ new Set([
 	"low-score",
 	"non-positive-score",
 	"invalid-score",
+	"native-score",
+	"out-of-range-score",
 	"unscaled-score",
 	"unscored"
 ]);
@@ -1946,11 +1956,11 @@ var MemorySpacesService = class {
 		const descriptor = catalog.descriptor(providerId);
 		return descriptor.typeId ?? descriptor.id;
 	}
-	isNativeProvider(providerId) {
-		return this.providerTypeId(providerId) === "mnemon-native";
+	isNativeProviderId(providerId) {
+		return this.providerTypeId(providerId) === NATIVE_PROVIDER_ID;
 	}
 	isNativeSpace(body) {
-		return (body.provider.typeId ?? body.provider.id) === "mnemon-native";
+		return isNativeProvider(body.provider);
 	}
 	constructor(runner, config, memorySpaces, recallQualityPolicyRegistry = recallQualityPolicies, providerAdapterRegistry = new MemoryProviderAdapterRegistry(), providerCatalog = EMPTY_MEMORY_PROVIDER_CATALOG) {
 		this.runner = runner;
@@ -2040,7 +2050,7 @@ var MemorySpacesService = class {
 			items,
 			providers: this.providerCatalog.providers.map((provider) => ({
 				...provider,
-				serviceConfigured: (provider.typeId ?? provider.id) === "mnemon-native" ? this.runner.commandFound : enabled.has(provider.id)
+				serviceConfigured: isNativeProvider(provider) ? this.runner.commandFound : enabled.has(provider.id)
 			})),
 			persistenceStrategy: {
 				mode: this.config.persistenceStrategy.mode,
@@ -2131,6 +2141,7 @@ var MemorySpacesService = class {
 			timeoutMs: this.config.timeoutMs,
 			defaultRecallLimit: this.config.defaultRecallLimit,
 			recallQuality: this.config.recallQuality,
+			embeddingManaged: this.config.embedding.enabled,
 			memoryBodyDirectory: catalog.directory,
 			memoryBodies: catalog.items,
 			providerServices,
@@ -2310,6 +2321,7 @@ var MemorySpacesService = class {
 			timeoutMs: this.config.timeoutMs,
 			defaultRecallLimit: this.config.defaultRecallLimit,
 			recallQuality: this.config.recallQuality,
+			embeddingManaged: this.config.embedding.enabled,
 			memoryBodyDirectory: catalog.directory,
 			memoryBodies: catalog.items,
 			providerServices
@@ -2388,9 +2400,9 @@ var MemorySpacesService = class {
 			"keyword",
 			"basic"
 		], "mode") ?? "smart";
-		const category = allowed(request.category, CATEGORIES$1, "category");
-		const source = allowed(request.source, SOURCES$1, "source");
-		const intent = allowed(request.intent, INTENTS$1, "intent");
+		const category = allowed(request.category, CATEGORIES, "category");
+		const source = allowed(request.source, SOURCES, "source");
+		const intent = allowed(request.intent, INTENTS, "intent");
 		const spaces = this.readSpaces(request.memoryBodyIds);
 		const normalizedRequest = {
 			query,
@@ -2448,7 +2460,8 @@ var MemorySpacesService = class {
 			}
 			const heterogeneous = new Set(spaces.map((body) => body.provider.id)).size > 1;
 			if (heterogeneous) for (const candidate of candidates) candidate.insight.federatedScore = 1 / (60 + candidate.providerRank);
-			candidates.sort((left, right) => heterogeneous ? (right.insight.federatedScore ?? 0) - (left.insight.federatedScore ?? 0) || left.bodyOrder - right.bodyOrder : (right.insight.score ?? 0) - (left.insight.score ?? 0));
+			const useProviderOrder = heterogeneous || candidates.some((candidate) => candidate.scoreSemantics?.kind === "provider-native");
+			candidates.sort((left, right) => useProviderOrder ? left.providerRank - right.providerRank || left.bodyOrder - right.bodyOrder : (right.insight.score ?? 0) - (left.insight.score ?? 0));
 			return {
 				hints,
 				quality: applyRecallQualityPolicy(preparedPolicy, candidates, qualityContext)
@@ -2508,6 +2521,8 @@ var MemorySpacesService = class {
 			}
 			if (decision.reason === "unscored") stats.unscored += 1;
 			if (decision.reason === "unscaled-score") stats.unscaled += 1;
+			if (decision.tier === "ranked") stats.ranked = (stats.ranked ?? 0) + 1;
+			if (decision.reason === "out-of-range-score") stats.outOfRange = (stats.outOfRange ?? 0) + 1;
 		}
 		for (const { candidate } of quality.selected) {
 			const stats = qualityStats.get(candidate.memoryBodyId);
@@ -2647,7 +2662,7 @@ var MemorySpacesService = class {
 		const rawQuery = request.query?.trim() ?? "";
 		const query = rawQuery.toLocaleLowerCase();
 		if (rawQuery.length > 500) throw new Error("query is too long (max 500 characters)");
-		const category = allowed(request.category, CATEGORIES$1, "category");
+		const category = allowed(request.category, CATEGORIES, "category");
 		const limit = memoryInputInteger(request.limit, 200, 1, 1e3);
 		const spaces = this.readSpaces(request.memoryBodyIds);
 		const batches = await Promise.all(spaces.map(async (body) => {
@@ -3023,7 +3038,7 @@ var MemorySpacesService = class {
 			return this.createSpace({
 				...body,
 				...providerId === void 0 ? {} : { providerId },
-				...providerId === void 0 || this.isNativeProvider(providerId) || connection === void 0 ? {} : { connection }
+				...providerId === void 0 || this.isNativeProviderId(providerId) || connection === void 0 ? {} : { connection }
 			}, signal);
 		}
 		const request = {
@@ -3050,7 +3065,7 @@ var MemorySpacesService = class {
 	}
 	async updateProviderService(providerId, settings, clearSecrets = [], enabled = true, signal) {
 		this.assertWritable();
-		if (this.isNativeProvider(providerId)) throw new Error("Mnemon Native service settings are managed by the native configuration");
+		if (this.isNativeProviderId(providerId)) throw new Error("Mnemon Native service settings are managed by the native configuration");
 		if (!enabled) return this.memorySpaces.updateProviderService(providerId, settings, clearSecrets, false);
 		const connection = this.memorySpaces.resolveProviderService(providerId, settings, clearSecrets);
 		const provider = this.providers.get(providerId);
@@ -3090,7 +3105,7 @@ var MemorySpacesService = class {
 		}
 	}
 	async runRediscovery(trigger, signal, providerTimeoutMs) {
-		const services = this.memorySpaces.providerServices().items.filter((item) => item.enabled && !this.isNativeProvider(item.providerId));
+		const services = this.memorySpaces.providerServices().items.filter((item) => item.enabled && !this.isNativeProviderId(item.providerId));
 		const results = await Promise.all(services.map(async (item) => {
 			const provider = this.providers.get(item.providerId);
 			if (provider?.discover === void 0) return void 0;
@@ -3290,16 +3305,16 @@ var MemorySpacesService = class {
 		const body = destinations?.get(key) ?? this.writeSpace(request.memoryBodyId);
 		destinations?.set(key, body);
 		const content = required(request.content, "content", 8192);
-		const importance = memoryInputInteger(request.importance, 3, 1, 5);
-		const category = allowed(request.category, CATEGORIES$1, "category") ?? "general";
-		const source = allowed(request.source, SOURCES$1, "source") ?? "user";
+		const importance = request.importance === void 0 ? void 0 : memoryInputInteger(request.importance, 3, 1, 5);
+		const category = allowed(request.category, CATEGORIES, "category") ?? "general";
+		const source = allowed(request.source, SOURCES, "source") ?? "user";
 		const tags = commaList(request.tags, "tags", 20)?.split(",");
 		const entities = commaList(request.entities, "entities", 50)?.split(",");
 		return {
 			body,
 			request: {
 				content,
-				importance,
+				...importance === void 0 ? {} : { importance },
 				category,
 				source,
 				memoryBodyId: body.id,
@@ -3355,14 +3370,7 @@ function optionalText(value) {
 	return value?.trim() || void 0;
 }
 const MEMORY_PROVIDER_ID = /^[a-z][a-z0-9-]{0,127}$/u;
-const MEMORY_PLACEMENT_CAPABILITY_SET = /* @__PURE__ */ new Set([
-	"graph",
-	"entities",
-	"related",
-	"exact-write",
-	"link",
-	"forget"
-]);
+const MEMORY_PLACEMENT_CAPABILITY_SET = new Set(MEMORY_PLACEMENT_CAPABILITIES);
 const MEMORY_PLACEMENT_PREFERENCE_SET = /* @__PURE__ */ new Set([
 	"balanced",
 	"local-first",
@@ -3376,7 +3384,7 @@ function resolvePersistenceStrategy(value) {
 	const prompt = value?.prompt?.trim() ?? "";
 	if (prompt.length > 4e3) throw new Error("dsh-mnemon: persistence strategy prompt is too long (max 4000 characters)");
 	const configuredProviderIds = value?.rules?.allowedProviderIds;
-	const allowedProviderIds = [...new Set(configuredProviderIds === void 0 || configuredProviderIds.length === 0 && mode === "manual" ? ["mnemon-native"] : configuredProviderIds)];
+	const allowedProviderIds = [...new Set(configuredProviderIds === void 0 || configuredProviderIds.length === 0 && mode === "manual" ? [NATIVE_PROVIDER_ID] : configuredProviderIds)];
 	if (allowedProviderIds.length === 0) throw new Error("dsh-mnemon: persistence strategy requires at least one allowed provider");
 	for (const id of allowedProviderIds) if (!MEMORY_PROVIDER_ID.test(id)) throw new Error(`dsh-mnemon: invalid persistence strategy provider: ${String(id)}`);
 	const dataBoundary = value?.rules?.dataBoundary ?? "allow-remote";
@@ -3439,12 +3447,14 @@ function resolveRecallQuality(value) {
 	const highScoreThreshold = value?.highScoreThreshold ?? .6;
 	const candidateMultiplier = value?.candidateMultiplier ?? 3;
 	const maxMediumResults = value?.maxMediumResults ?? 4;
+	const maxRankedResults = value?.maxRankedResults ?? 4;
 	const maxUnknownResults = value?.maxUnknownResults ?? 2;
 	if (!Number.isFinite(lowScoreThreshold) || lowScoreThreshold < 0 || lowScoreThreshold > 1) throw new Error("dsh-mnemon: recall low score threshold must be within 0..1");
 	if (!Number.isFinite(highScoreThreshold) || highScoreThreshold < 0 || highScoreThreshold > 1) throw new Error("dsh-mnemon: recall high score threshold must be within 0..1");
 	if (lowScoreThreshold >= highScoreThreshold) throw new Error("dsh-mnemon: recall low score threshold must be less than the high score threshold");
 	if (!Number.isInteger(candidateMultiplier) || candidateMultiplier < 1 || candidateMultiplier > 5) throw new Error("dsh-mnemon: recall candidate multiplier must be an integer within 1..5");
 	if (!Number.isInteger(maxMediumResults) || maxMediumResults < 0 || maxMediumResults > 50) throw new Error("dsh-mnemon: recall max medium results must be an integer within 0..50");
+	if (!Number.isInteger(maxRankedResults) || maxRankedResults < 0 || maxRankedResults > 50) throw new Error("dsh-mnemon: recall max ranked results must be an integer within 0..50");
 	if (!Number.isInteger(maxUnknownResults) || maxUnknownResults < 0 || maxUnknownResults > 50) throw new Error("dsh-mnemon: recall max unknown results must be an integer within 0..50");
 	return {
 		policy,
@@ -3452,6 +3462,7 @@ function resolveRecallQuality(value) {
 		highScoreThreshold,
 		candidateMultiplier,
 		maxMediumResults,
+		maxRankedResults,
 		maxUnknownResults
 	};
 }
@@ -3462,7 +3473,7 @@ function resolveMemorySpacesConfig(value = {}, sourceInstanceKey = "standalone")
 	const dataDir = requested === void 0 ? join(homedir(), ".mnemon", "sources", encodeURIComponent(sourceInstanceKey)) : requested === "~" ? homedir() : requested.startsWith("~/") ? join(homedir(), requested.slice(2)) : requested;
 	if (!isAbsolute(dataDir)) throw new Error("Memory Spaces dataDir must be absolute or start with ~/");
 	const store = optionalText(config.store);
-	if (store !== void 0 && !/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/u.test(store)) throw new Error("Memory Spaces store has an invalid identifier");
+	if (store !== void 0 && !MEMORY_SPACE_ID_PATTERN.test(store)) throw new Error("Memory Spaces store has an invalid identifier");
 	const cliPath = optionalText(config.cliPath);
 	return {
 		storageScope: "custom",
@@ -3479,31 +3490,10 @@ function resolveMemorySpacesConfig(value = {}, sourceInstanceKey = "standalone")
 }
 //#endregion
 //#region src/source.ts
-const CATEGORIES = /* @__PURE__ */ new Set([
-	"preference",
-	"decision",
-	"fact",
-	"insight",
-	"context",
-	"general"
-]);
-const SOURCES = /* @__PURE__ */ new Set([
-	"user",
-	"agent",
-	"external"
-]);
-const INTENTS = /* @__PURE__ */ new Set([
-	"WHY",
-	"WHEN",
-	"ENTITY",
-	"GENERAL"
-]);
-const EDGES = /* @__PURE__ */ new Set([
-	"temporal",
-	"semantic",
-	"causal",
-	"entity"
-]);
+const CATEGORY_SET = new Set(CATEGORIES);
+const SOURCE_SET = new Set(SOURCES);
+const INTENT_SET = new Set(INTENTS);
+const EDGE_SET = new Set(EDGE_TYPES);
 function grantIds(grant) {
 	return memoryInputStringArray(memoryInputRecord(grant.value, "Memory Spaces ReadGrant").memoryBodyIds, "memoryBodyIds", 1e4) ?? [];
 }
@@ -3544,7 +3534,7 @@ function createSpaceRequest(value) {
 	};
 	return {
 		name: memoryInputText(input.name, "name", 100),
-		description: memoryInputText(input.description, "description", 1e3),
+		description: memoryInputText(input.description, "description", MEMORY_SPACE_DESCRIPTION_MAX_LENGTH),
 		...typeof input.active !== "boolean" ? {} : { active: input.active },
 		...providerId === void 0 ? {} : { providerId },
 		...connection === void 0 ? {} : { connection },
@@ -3559,7 +3549,7 @@ function updateSpaceRequest(value) {
 		memoryBodyId: memoryInputText(input.memoryBodyId, "memoryBodyId", 300),
 		request: {
 			...memoryInputText(input.name, "name", 100, false) === void 0 ? {} : { name: memoryInputText(input.name, "name", 100, false) },
-			...memoryInputText(input.description, "description", 1e3, false) === void 0 ? {} : { description: memoryInputText(input.description, "description", 1e3, false) },
+			...memoryInputText(input.description, "description", 1e3, false) === void 0 ? {} : { description: memoryInputText(input.description, "description", MEMORY_SPACE_DESCRIPTION_MAX_LENGTH, false) },
 			...typeof input.active !== "boolean" ? {} : { active: input.active },
 			...connection === void 0 ? {} : { connection },
 			...memoryInputStringArray(input.clearSecrets, "clearSecrets", 100) === void 0 ? {} : { clearSecrets: memoryInputStringArray(input.clearSecrets, "clearSecrets", 100) }
@@ -3595,7 +3585,7 @@ function outsideView(service, memoryBodyId) {
 	if (!body.active) return `${space} is switched off, so this turn's View does not read it and cannot forget from it. Whether it is on is the user's choice, on the Memory Spaces page; once it is on, a forget there works from the next turn`;
 	if (body.providerEnabled === false) return `${space} uses ${body.provider.label}, which is turned off on the dsh-mnemon page under Plugins`;
 	const provider = catalog.providers.find((candidate) => candidate.id === body.provider.id);
-	if (provider?.serviceConfigured === false) return `${space} uses ${body.provider.label}, which is not available here${(provider.typeId ?? provider.id) === "mnemon-native" ? ": the Mnemon CLI is not installed" : ""}`;
+	if (provider?.serviceConfigured === false) return `${space} uses ${body.provider.label}, which is not available here${isNativeProvider(provider) ? ": the Mnemon CLI is not installed" : ""}`;
 	return `${space} was switched on after this turn began, so this turn's View does not read it yet; a forget there works from the next turn`;
 }
 /** The switched-off spaces a forget cannot reach this turn, named only when there are some (#390). */
@@ -4096,9 +4086,9 @@ function createMemorySpacesSource(providerSnapshot, config = {}) {
 						const category = memoryInputText(input.category, "category", 30, false);
 						const source = memoryInputText(input.source, "source", 30, false);
 						const intent = memoryInputText(input.intent, "intent", 30, false);
-						if (category !== void 0 && !CATEGORIES.has(category)) throw new Error(`unsupported category: ${category}`);
-						if (source !== void 0 && !SOURCES.has(source)) throw new Error(`unsupported source: ${source}`);
-						if (intent !== void 0 && !INTENTS.has(intent)) throw new Error(`unsupported intent: ${intent}`);
+						if (category !== void 0 && !CATEGORY_SET.has(category)) throw new Error(`unsupported category: ${category}`);
+						if (source !== void 0 && !SOURCE_SET.has(source)) throw new Error(`unsupported source: ${source}`);
+						if (intent !== void 0 && !INTENT_SET.has(intent)) throw new Error(`unsupported intent: ${intent}`);
 						const requestedSpaces = memoryInputStringArray(input.memoryBodyIds, "memoryBodyIds", 1e4) ?? allowedBodies;
 						if (requestedSpaces.some((id) => !allowedBodies.includes(id))) throw new Error("Recall requested a Memory Space outside this View ReadGrant");
 						const mode = memoryInputText(input.mode, "mode", 20, false);
@@ -4120,7 +4110,7 @@ function createMemorySpacesSource(providerSnapshot, config = {}) {
 						if (owner === void 0) throw new Error("related-memory traversal requires evidence already admitted by this View, or an id found in a Memory Space it can read");
 						if (!allowedBodies.includes(owner)) throw new Error("related-memory owner is outside this View ReadGrant");
 						const edge = memoryInputText(input.edge, "edge", 30, false);
-						if (edge !== void 0 && !EDGES.has(edge)) throw new Error(`unsupported edge: ${edge}`);
+						if (edge !== void 0 && !EDGE_SET.has(edge)) throw new Error(`unsupported edge: ${edge}`);
 						const results = await service.related(id, memoryInputInteger(input.depth, 2, 1, 5), edge, request.signal, owner);
 						return evidence(request, results);
 					}
@@ -4160,7 +4150,7 @@ function createMemorySpacesSource(providerSnapshot, config = {}) {
 							if (!writableBodies.includes(bodyId)) throw new Error("Memory Space update is outside this View scope");
 							const body = service.updateSpace(bodyId, {
 								...input.name === void 0 ? {} : { name: memoryInputText(input.name, "name", 100) },
-								...input.description === void 0 ? {} : { description: memoryInputText(input.description, "description", 1e3) },
+								...input.description === void 0 ? {} : { description: memoryInputText(input.description, "description", MEMORY_SPACE_DESCRIPTION_MAX_LENGTH) },
 								...typeof input.active === "boolean" ? { active: input.active } : {}
 							});
 							result = {
@@ -4187,8 +4177,8 @@ function createMemorySpacesSource(providerSnapshot, config = {}) {
 						if (!writableBodies.includes(bodyId)) throw new Error("remember destination is outside this View scope");
 						const category = memoryInputText(input.category, "category", 30, false);
 						const source = memoryInputText(input.source, "source", 30, false);
-						if (category !== void 0 && !CATEGORIES.has(category)) throw new Error(`unsupported category: ${category}`);
-						if (source !== void 0 && !SOURCES.has(source)) throw new Error(`unsupported source: ${source}`);
+						if (category !== void 0 && !CATEGORY_SET.has(category)) throw new Error(`unsupported category: ${category}`);
+						if (source !== void 0 && !SOURCE_SET.has(source)) throw new Error(`unsupported source: ${source}`);
 						result = await service.remember({
 							content: memoryInputText(input.content, "content", 1e5),
 							...category === void 0 ? {} : { category },
@@ -4206,7 +4196,7 @@ function createMemorySpacesSource(providerSnapshot, config = {}) {
 						if (sourceSpace === void 0 || targetSpace === void 0 || sourceSpace !== targetSpace || !allowedBodies.includes(sourceSpace)) throw new Error("link requires two evidence items admitted by this View from the same Memory Space, or two ids found in one Memory Space it can read");
 						bodyId = sourceSpace;
 						const edge = memoryInputText(input.type, "type", 30, false);
-						if (edge !== void 0 && !EDGES.has(edge)) throw new Error(`unsupported edge: ${edge}`);
+						if (edge !== void 0 && !EDGE_SET.has(edge)) throw new Error(`unsupported edge: ${edge}`);
 						const weight = typeof input.weight === "number" ? input.weight : .5;
 						result = await service.link(sourceId, targetId, edge, weight, memoryInputText(input.reason, "reason", 1e3, false), request.signal, bodyId);
 					} else if (request.offer.sourceActionId === "forget") {

package/lib/{plugin-DlsNeZbQ.js → plugin-m1PeU1IE.js}

@@ -1,3 +1,4 @@
+import { isNativeProvider } from "./contracts.js";
 import { a as digest, i as defineMemorySpaceProviderDefinition, o as requiredId } from "./definitions-DfmOqJjR.js";
 //#region src/providers/catalog.ts
 function memoryProviderDescriptor(id, catalog = []) {
@@ -35,7 +36,7 @@ function validateFieldBounds(field, value) {
 }
 function normalizeScopedProviderConnection(providerId, scope, input, previous = {}, clearSecrets = [], catalog = []) {
 	const descriptor = memoryProviderDescriptor(providerId, catalog);
-	if ((descriptor.typeId ?? descriptor.id) === "mnemon-native") return {};
+	if (isNativeProvider(descriptor)) return {};
 	const fields = descriptor.fields.filter((item) => item.scope === scope);
 	const allowed = new Set(fields.map((item) => item.key));
 	for (const key of Object.keys(input ?? {})) if (!allowed.has(key)) throw new Error(`unsupported ${descriptor.label} ${scope} setting: ${key}`);
@@ -88,7 +89,7 @@ function normalizeProviderMemoryConnection(providerId, input, previous = {}, cat
 }
 function normalizeProviderConnection(providerId, input, previous = {}, clearSecrets = [], catalog = []) {
 	const descriptor = memoryProviderDescriptor(providerId, catalog);
-	if ((descriptor.typeId ?? descriptor.id) === "mnemon-native") return {};
+	if (isNativeProvider(descriptor)) return {};
 	const allowed = new Set(descriptor.fields.map((item) => item.key));
 	for (const key of Object.keys(input ?? {})) if (!allowed.has(key)) throw new Error(`unsupported ${descriptor.label} setting: ${key}`);
 	for (const key of clearSecrets) if (descriptor.fields.find((item) => item.key === key)?.input !== "secret") throw new Error(`cannot clear non-secret ${descriptor.label} setting: ${key}`);

package/lib/provider-sdk.d.ts

@@ -1,5 +1,5 @@
 import { CATEGORIES, Category, EDGE_TYPES, EdgeType, INTENTS, Insight, Intent, JsonValue, MemoryBody, MemoryBodyProvider, MemoryBodyStats, MemoryGraphEdge, MemoryGraphNode, MemoryGraphSnapshot, MemoryListRequest, MemoryProviderCapabilities, MemoryProviderConfigField, MemoryProviderConfigOption, MemoryProviderConnection, MemoryProviderConnectionValue, MemoryProviderDescriptor, MemoryProviderIcon, MemoryProviderId, MemorySpace, MemorySpaceProvider, MemorySpaceStats, OpenVikingBodyConnection, OpenVikingSpaceConnection, RememberRequest, SOURCES, SearchRequest, Source } from "./contracts.js";
-import { C as ProviderSearchResult, S as ProviderScoreSemantics, _ as MemorySpaceNativeRunner, a as MemorySpaceProviderHost, b as ProviderEntityIndex, c as MemorySpaceProviderRuntimeContext, d as defineMemorySpaceProviderDefinition, f as MemoryProviderAdapter, g as MemorySpaceNativeRunOptions, h as MemorySpaceAuthority, i as MemorySpaceProviderEntry, l as MemorySpaceProviderScoreSemantics, m as MemoryProviderScoreSemantics, n as MemorySpaceProviderDefinition, o as MemorySpaceProviderManifest, p as MemoryProviderAdapterFactoryContext, r as MemorySpaceProviderDisposer, s as MemorySpaceProviderModule, t as MEMORY_SPACE_PROVIDER_API_VERSION, u as defineMemorySpaceProvider, v as NORMALIZED_RELEVANCE_SCORE, w as ProviderSpaceStatus, x as ProviderMemorySpace, y as ProviderBodyStatus } from "./definitions-CtjNSwBS.js";
+import { C as ProviderSearchResult, S as ProviderScoreSemantics, _ as MemorySpaceNativeRunner, a as MemorySpaceProviderHost, b as ProviderEntityIndex, c as MemorySpaceProviderRuntimeContext, d as defineMemorySpaceProviderDefinition, f as MemoryProviderAdapter, g as MemorySpaceNativeRunOptions, h as MemorySpaceAuthority, i as MemorySpaceProviderEntry, l as MemorySpaceProviderScoreSemantics, m as MemoryProviderScoreSemantics, n as MemorySpaceProviderDefinition, o as MemorySpaceProviderManifest, p as MemoryProviderAdapterFactoryContext, r as MemorySpaceProviderDisposer, s as MemorySpaceProviderModule, t as MEMORY_SPACE_PROVIDER_API_VERSION, u as defineMemorySpaceProvider, v as NORMALIZED_RELEVANCE_SCORE, w as ProviderSpaceStatus, x as ProviderMemorySpace, y as ProviderBodyStatus } from "./definitions-BNmfQoWk.js";
 //#region src/providers/http.d.ts
 interface HttpProviderOptions {
   label?: string;

package/lib/space-identity.d.ts

@@ -0,0 +1,20 @@
+//#region src/space-identity.d.ts
+declare class MemorySpaceIdentity {
+  #private;
+  /** `parent` holds the short-lived copies a store is read from; dispose of the identity when done. */
+  constructor(parent: string);
+  /** The store's content identity, or the digest of its bytes when its content cannot be read. */
+  of(bytes: Uint8Array): string;
+  /** Whether `outer` holds every row `inner` holds; `outer` may have columns `inner` lacks. */
+  contains(outer: Uint8Array, inner: Uint8Array): boolean;
+  /**
+   * `local` with the rows only `incoming` holds added to it, or undefined when the two cannot
+   * merge: a row both hold differently, a table or column `local` lacks, or a store that cannot
+   * be read. `local` itself comes back when it already holds everything.
+   */
+  merge(local: Uint8Array, incoming: Uint8Array): Uint8Array | undefined;
+  /** Remove the short-lived copies the identity made. */
+  dispose(): void;
+}
+//#endregion
+export { MemorySpaceIdentity };