dsh-mnemon-source-memory-spaces 0.5.14 → 0.5.16

package/lib/index.js

@@ -1,5 +1,5 @@
 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 } from "./contracts.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 { n as ProcessError, r as runProcess } from "./process-DIK9NnTg.js";
 import { r as defineMemorySpaceProvider } from "./definitions-DfmOqJjR.js";
@@ -348,6 +348,8 @@ var MemorySpaceRegistry = class MemorySpaceRegistry {
 		let normalizedService = this.providerCatalog.normalizeService(providerId, service);
 		const seen = /* @__PURE__ */ new Set();
 		const existing = this.spaces.filter((body) => body.providerId === providerId);
+		const existingByExternalId = /* @__PURE__ */ new Map();
+		for (const body of existing) if (!existingByExternalId.has(body.externalId)) existingByExternalId.set(body.externalId, body);
 		const reservedIds = new Set(this.spaces.filter((body) => body.providerId !== providerId).map((body) => body.id));
 		const timestamp = this.now().toISOString();
 		const projections = discovered.map((candidate) => {
@@ -359,7 +361,7 @@ var MemorySpaceRegistry = class MemorySpaceRegistry {
 				...normalizedService,
 				...connection
 			});
-			const previous = existing.find((body) => body.externalId === externalId);
+			const previous = existingByExternalId.get(externalId);
 			let id = previous?.id ?? validateMemorySpaceId(`${providerId}-${createHash("sha256").update(externalId).digest("hex").slice(0, 24)}`);
 			let suffix = 1;
 			while (reservedIds.has(id)) {
@@ -756,9 +758,10 @@ var MemorySpaceRegistry = class MemorySpaceRegistry {
 		const timestamp = this.now().toISOString();
 		const legacyActive = this.runner.effectiveStore();
 		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 (this.spaces.some((body) => body.id === entry.name)) continue;
+			if (knownIds.has(entry.name)) continue;
 			this.spaces.push({
 				id: entry.name,
 				name: entry.name,
@@ -768,6 +771,7 @@ var MemorySpaceRegistry = class MemorySpaceRegistry {
 				createdAt: timestamp,
 				updatedAt: timestamp
 			});
+			knownIds.add(entry.name);
 			changed = true;
 		}
 		if (changed) this.save();
@@ -995,6 +999,88 @@ function lexicalRequiredMatchCount(tokens) {
 	return Math.max(2, Math.ceil(tokens.length / 4));
 }
 //#endregion
+//#region src/entity-index.ts
+/**
+* The most memories one space's derived index asks list() for. Mnemon Native
+* lists a whole store; a Provider that stops earlier reports what it listed.
+*/
+const ENTITY_INDEX_LIST_LIMIT = 1e5;
+/** The rail lists at most this many entities; the rest stay reachable by name. */
+const ENTITY_RAIL_LIMIT = 5e3;
+function buildSpaceEntityIndex(memories, memoryCount, complete) {
+	const kept = [];
+	const byKey = /* @__PURE__ */ new Map();
+	const spellings = /* @__PURE__ */ new Map();
+	for (const memory of memories) {
+		const seen = /* @__PURE__ */ new Set();
+		let position;
+		for (const raw of memory.entities ?? []) {
+			if (typeof raw !== "string") continue;
+			const key = normalizeEntityKey(raw);
+			if (key === "" || seen.has(key)) continue;
+			seen.add(key);
+			if (position === void 0) {
+				position = kept.length;
+				kept.push(memory);
+			}
+			const positions = byKey.get(key);
+			if (positions === void 0) byKey.set(key, [position]);
+			else positions.push(position);
+			const name = raw.normalize("NFKC").trim();
+			const names = spellings.get(key);
+			if (names === void 0) spellings.set(key, /* @__PURE__ */ new Map([[name, 1]]));
+			else names.set(name, (names.get(name) ?? 0) + 1);
+		}
+	}
+	return {
+		memories: kept,
+		byKey,
+		spellings,
+		memoryCount,
+		complete
+	};
+}
+/** The spelling most memories use; the first one seen wins a tie. */
+function preferredSpelling(names) {
+	let preferred = "";
+	let most = 0;
+	for (const [name, count] of names) if (count > most) {
+		preferred = name;
+		most = count;
+	}
+	return preferred;
+}
+/** Merge per-space indexes into one entity list, most frequent first. */
+function mergeEntityCounts(indexes) {
+	const counts = /* @__PURE__ */ new Map();
+	const spellings = /* @__PURE__ */ new Map();
+	for (const index of indexes) for (const [key, positions] of index.byKey) {
+		counts.set(key, (counts.get(key) ?? 0) + positions.length);
+		let totals = spellings.get(key);
+		if (totals === void 0) spellings.set(key, totals = /* @__PURE__ */ new Map());
+		for (const [name, count] of index.spellings.get(key) ?? []) totals.set(name, (totals.get(name) ?? 0) + count);
+	}
+	const names = /* @__PURE__ */ new Map();
+	for (const [key, totals] of spellings) names.set(key, preferredSpelling(totals));
+	return {
+		items: [...counts].map(([key, count]) => ({
+			entity: names.get(key),
+			count
+		})).sort((left, right) => right.count - left.count || left.entity.localeCompare(right.entity)),
+		names
+	};
+}
+/** Importance first, then the newest; the order Mnemon Native lists a store in. */
+function compareEntityMemories(left, right) {
+	return (right.importance ?? 0) - (left.importance ?? 0) || (right.createdAt ?? "").localeCompare(left.createdAt ?? "") || (left.memoryBodyName ?? "").localeCompare(right.memoryBodyName ?? "") || left.id.localeCompare(right.id);
+}
+/** Every memory across the indexes that carries the entity key. */
+function memoriesWithEntity(indexes, key) {
+	const memories = [];
+	for (const index of indexes) for (const position of index.byKey.get(key) ?? []) memories.push(index.memories[position]);
+	return memories.sort(compareEntityMemories);
+}
+//#endregion
 //#region src/recall-quality/policies.ts
 function expandedLimit(context) {
 	return Math.min(50, Math.max(context.requestedLimit, Math.ceil(context.requestedLimit * context.config.candidateMultiplier)));
@@ -1204,6 +1290,39 @@ function text(value) {
 function number(value) {
 	return typeof value === "number" && Number.isFinite(value) ? value : void 0;
 }
+/**
+* How long a selection reuses the Provider health its index was checked with.
+* The rail always checks again; a write through this Source drops both at once.
+*/
+const ENTITY_SELECTION_STATUS_REUSE_MS = 1e4;
+/** How long an index that statistics cannot check is reused; a write through this Source still drops it. */
+const ENTITY_INDEX_UNCHECKED_REUSE_MS = 1e4;
+function entityName(entity) {
+	const name = entity.trim();
+	if (name.length > 200) throw new Error("entity is too long (max 200 characters)");
+	return name;
+}
+function memoryKey(memoryBodyId, id) {
+	return `${memoryBodyId}\u0000${id}`;
+}
+/**
+* What must stay the same for a space's entity index to stay valid: its
+* Provider statistics (Mnemon counts every write in its operation log) and the
+* Source's own record of the space. Without statistics it cannot be checked.
+*/
+function entityIndexFingerprint(body, status) {
+	const stats = status.stats;
+	if (stats === void 0) return void 0;
+	return JSON.stringify([
+		body.provider.id,
+		body.updatedAt,
+		stats.totalInsights,
+		stats.deletedInsights,
+		stats.edgeCount,
+		stats.oplogCount,
+		stats.dbSizeBytes
+	]);
+}
 function readSource(body, mode, status, itemCount, options = {}) {
 	return {
 		memoryBodyId: body.id,
@@ -1373,6 +1492,12 @@ var MemorySpacesService = class {
 	providers;
 	recallQualityPolicy;
 	spacesInFlight;
+	/** One entity index per active entity space, valid while its fingerprint holds. */
+	entityIndexCache = /* @__PURE__ */ new Map();
+	/** settledAt stays undefined while the read runs, which every caller shares. */
+	entityStatusCache = /* @__PURE__ */ new Map();
+	/** The related read each page view is waiting for; a newer selection cancels the older one. */
+	entityRelatedViews = /* @__PURE__ */ new Map();
 	providersDisposed = false;
 	/** The CLI version a full status last read, and the binary it read it from. */
 	cliVersion;
@@ -1684,6 +1809,7 @@ var MemorySpacesService = class {
 		}
 		const provider = this.providerFor(body);
 		provider.invalidateStatus?.(body.id);
+		this.invalidateEntityIndex(body.id);
 		const status = await provider.status(body, signal);
 		return {
 			...body,
@@ -1692,7 +1818,8 @@ var MemorySpacesService = class {
 			...status
 		};
 	}
-	async search(request, signal) {
+	/** exclude: memoryKey()s to leave out before the quality policy selects. */
+	async search(request, signal, options = {}) {
 		const query = required(request.query, "query", 2e3);
 		const limit = memoryInputInteger(request.limit, this.config.defaultRecallLimit, 1, 50);
 		const qualityContext = {
@@ -1751,7 +1878,8 @@ var MemorySpacesService = class {
 			const hints = [];
 			for (const [bodyOrder, { body, result }] of selectedBatches.entries()) {
 				const scoreSemantics = this.providerFor(body).scoreSemantics;
-				candidates.push(...result.results.map((entry, index) => ({
+				const entries = options.exclude === void 0 ? result.results : result.results.filter((entry) => !options.exclude.has(memoryKey(body.id, entry.id)));
+				candidates.push(...entries.map((entry, index) => ({
 					insight: this.annotate(entry, body),
 					memoryBodyId: body.id,
 					providerId: body.provider.id,
@@ -1797,22 +1925,36 @@ var MemorySpacesService = class {
 		}
 		const { hints, quality } = evaluation;
 		const selected = recoveryPlan === void 0 ? quality.selected : prioritizeRecoveryEvidence(quality.selected, recoveryPlan);
-		const qualityStats = (memoryBodyId) => {
-			const evaluated = quality.evaluated.filter((candidate) => candidate.candidate.memoryBodyId === memoryBodyId);
-			const selected = quality.selected.filter((candidate) => candidate.candidate.memoryBodyId === memoryBodyId);
-			return {
-				policyId: quality.policyId,
-				...quality.fallbackFrom === void 0 ? {} : { fallbackFrom: quality.fallbackFrom },
-				fetched: evaluated.length,
-				retained: evaluated.filter((candidate) => candidate.decision.action === "keep").length,
-				selected: selected.length,
-				droppedLowScore: evaluated.filter((candidate) => candidate.decision.action === "drop" && candidate.decision.reason === "low-score").length,
-				droppedNonPositiveScore: evaluated.filter((candidate) => candidate.decision.action === "drop" && candidate.decision.reason === "non-positive-score").length,
-				droppedInvalidScore: evaluated.filter((candidate) => candidate.decision.action === "drop" && candidate.decision.reason === "invalid-score").length,
-				unscored: evaluated.filter((candidate) => candidate.decision.reason === "unscored").length,
-				unscaled: evaluated.filter((candidate) => candidate.decision.reason === "unscaled-score").length
-			};
-		};
+		const qualityStats = /* @__PURE__ */ new Map();
+		for (const { body } of batches) qualityStats.set(body.id, {
+			policyId: quality.policyId,
+			...quality.fallbackFrom === void 0 ? {} : { fallbackFrom: quality.fallbackFrom },
+			fetched: 0,
+			retained: 0,
+			selected: 0,
+			droppedLowScore: 0,
+			droppedNonPositiveScore: 0,
+			droppedInvalidScore: 0,
+			unscored: 0,
+			unscaled: 0
+		});
+		for (const { candidate, decision } of quality.evaluated) {
+			const stats = qualityStats.get(candidate.memoryBodyId);
+			if (stats === void 0) continue;
+			stats.fetched += 1;
+			if (decision.action === "keep") stats.retained += 1;
+			if (decision.action === "drop") {
+				if (decision.reason === "low-score") stats.droppedLowScore += 1;
+				if (decision.reason === "non-positive-score") stats.droppedNonPositiveScore += 1;
+				if (decision.reason === "invalid-score") stats.droppedInvalidScore += 1;
+			}
+			if (decision.reason === "unscored") stats.unscored += 1;
+			if (decision.reason === "unscaled-score") stats.unscaled += 1;
+		}
+		for (const { candidate } of quality.selected) {
+			const stats = qualityStats.get(candidate.memoryBodyId);
+			if (stats !== void 0) stats.selected += 1;
+		}
 		return {
 			query,
 			mode,
@@ -1822,7 +1964,7 @@ var MemorySpacesService = class {
 				...decision.normalizedScore === void 0 ? {} : { normalizedScore: decision.normalizedScore }
 			})),
 			sources: batches.map((batch) => {
-				const stats = qualityStats(batch.body.id);
+				const stats = qualityStats.get(batch.body.id);
 				if (batch.source.status === "unavailable" || batch.source.status === "unsupported") return {
 					...batch.source,
 					quality: stats
@@ -1995,41 +2137,208 @@ var MemorySpacesService = class {
 			sources: batches.map((batch) => batch.source)
 		};
 	}
+	/**
+	* The entities of the active spaces, each counted once per memory that
+	* carries it. With an entity, also the first page of those memories.
+	*/
 	async entities(entity, limit, signal) {
-		const active = (await this.spaces(signal)).items.filter((body) => body.active);
-		const capable = active.filter((body) => body.provider.capabilities.entities);
-		const entityCounts = /* @__PURE__ */ new Map();
-		for (const body of capable) for (const item of body.stats?.topEntities ?? []) entityCounts.set(item.entity, (entityCounts.get(item.entity) ?? 0) + item.count);
-		const items = [...entityCounts].map(([name, count]) => ({
-			entity: name,
-			count
-		})).sort((left, right) => right.count - left.count);
-		const sources = active.map((body) => {
-			if (!body.provider.capabilities.entities) return readSource(body, "unsupported", "unsupported", 0, { hint: "This provider does not expose an entity index." });
-			if (!body.healthy) return readSource(body, "entities", "unavailable", 0, { hint: body.error ?? "Provider unavailable." });
-			const count = body.stats?.topEntities.length ?? 0;
-			return readSource(body, "entities", count === 0 ? "empty" : "ready", count);
-		});
-		const selected = entity?.trim() ?? "";
-		if (selected === "") return {
-			items,
+		const selected = entity === void 0 ? "" : entityName(entity);
+		const read = await this.readEntityIndexes(signal, 0);
+		const { items } = mergeEntityCounts(read.indexes);
+		const view = {
+			items: items.slice(0, ENTITY_RAIL_LIMIT),
 			insights: [],
-			sources
+			sources: read.sources,
+			total: items.length,
+			complete: read.complete
 		};
-		if (selected.length > 200) throw new Error("entity is too long (max 200 characters)");
-		const readableIds = capable.filter((body) => body.healthy).map((body) => body.id);
+		if (selected === "") return view;
+		const page = this.entityPage(read, selected, 0, memoryInputInteger(limit, 20, 1, 50));
 		return {
-			items,
-			selected,
-			insights: readableIds.length === 0 ? [] : (await this.search({
+			...view,
+			selected: page.entity,
+			insights: page.items
+		};
+	}
+	/** One page of the memories that carry an entity, by importance and then recency. */
+	async entityMemories(entity, offset, limit, signal) {
+		const selected = entityName(entity);
+		if (selected === "") throw new Error("entity is required");
+		const read = await this.readEntityIndexes(signal, ENTITY_SELECTION_STATUS_REUSE_MS);
+		return this.entityPage(read, selected, memoryInputInteger(offset, 0, 0, 1e6), memoryInputInteger(limit, 50, 1, 200));
+	}
+	/**
+	* What recall relates to an entity, without the memories that carry it.
+	* Those are left out before the quality policy selects, so they cannot use up
+	* its places and leave the related list empty.
+	*/
+	async entityRelated(entity, limit, signal, view) {
+		const selected = entityName(entity);
+		if (selected === "") throw new Error("entity is required");
+		const superseding = view === void 0 ? void 0 : new AbortController();
+		if (view !== void 0) {
+			this.entityRelatedViews.get(view)?.abort(/* @__PURE__ */ new Error("superseded by a newer entity selection"));
+			this.entityRelatedViews.set(view, superseding);
+		}
+		const combined = superseding === void 0 ? signal : signal === void 0 ? superseding.signal : AbortSignal.any([signal, superseding.signal]);
+		try {
+			const read = await this.readEntityIndexes(combined, ENTITY_SELECTION_STATUS_REUSE_MS);
+			const key = normalizeEntityKey(selected);
+			const carrying = /* @__PURE__ */ new Set();
+			for (const [bodyId, index] of read.byBody) for (const position of index.byKey.get(key) ?? []) carrying.add(memoryKey(bodyId, index.memories[position].id));
+			const display = mergeEntityCounts(read.indexes).names.get(key) ?? selected;
+			const readableIds = read.readable.map((body) => body.id);
+			if (readableIds.length === 0) return {
+				entity: display,
+				items: [],
+				sources: []
+			};
+			const result = await this.search({
 				query: selected,
 				intent: "ENTITY",
 				limit: memoryInputInteger(limit, 20, 1, 50),
 				memoryBodyIds: readableIds
-			}, signal)).results,
-			sources
+			}, combined, { exclude: carrying });
+			combined?.throwIfAborted();
+			return {
+				entity: display,
+				items: result.results,
+				sources: result.sources
+			};
+		} finally {
+			if (view !== void 0 && this.entityRelatedViews.get(view) === superseding) this.entityRelatedViews.delete(view);
+		}
+	}
+	entityPage(read, selected, offset, limit) {
+		const key = normalizeEntityKey(selected);
+		const memories = memoriesWithEntity(read.indexes, key);
+		return {
+			entity: mergeEntityCounts(read.indexes).names.get(key) ?? selected,
+			total: memories.length,
+			offset,
+			items: memories.slice(offset, offset + limit),
+			complete: read.complete,
+			sources: read.sources
 		};
 	}
+	/**
+	* One entity index per active space that has an entity index, read
+	* concurrently. A space keeps its index while its Provider statistics and
+	* metadata stay the same; a write through this Source drops it.
+	*/
+	async readEntityIndexes(signal, statusMaxAgeMs) {
+		signal?.throwIfAborted();
+		const active = this.memorySpaces.active();
+		const capable = new Set(active.filter((body) => body.provider.capabilities.entities).map((body) => body.id));
+		for (const id of this.entityIndexCache.keys()) if (!capable.has(id)) this.entityIndexCache.delete(id);
+		const reads = await Promise.all(active.map(async (body) => {
+			if (!body.provider.capabilities.entities) return {
+				body,
+				recall: false,
+				source: readSource(body, "unsupported", "unsupported", 0, { hint: "This provider does not expose an entity index." })
+			};
+			const status = await this.entitySpaceStatus(body, statusMaxAgeMs);
+			if (!status.healthy) return {
+				body,
+				recall: false,
+				source: readSource(body, "entities", "unavailable", 0, { hint: status.error ?? "Provider unavailable." })
+			};
+			const recall = body.provider.capabilities.search;
+			if (this.providerFor(body).entityIndex === void 0 && !body.provider.capabilities.browse) return {
+				body,
+				recall,
+				source: readSource(body, "query-only", "query-required", 0, { hint: "This provider can only be queried; its memories appear among related memories." })
+			};
+			try {
+				const index = await this.entityIndexFor(body, status);
+				const options = {
+					memoryCount: index.memoryCount,
+					complete: index.complete,
+					...index.complete ? {} : { hint: "The Provider indexed only part of this space." }
+				};
+				return {
+					body,
+					index,
+					recall,
+					source: readSource(body, "entities", index.byKey.size === 0 ? "empty" : "ready", index.byKey.size, options)
+				};
+			} catch (error) {
+				return {
+					body,
+					recall: false,
+					source: readSource(body, "entities", "unavailable", 0, { hint: error instanceof Error ? error.message : String(error) })
+				};
+			}
+		}));
+		signal?.throwIfAborted();
+		const byBody = /* @__PURE__ */ new Map();
+		for (const read of reads) if (read.index !== void 0) byBody.set(read.body.id, read.index);
+		const indexes = [...byBody.values()];
+		return {
+			byBody,
+			indexes,
+			readable: reads.filter((read) => read.recall).map((read) => read.body),
+			sources: reads.map((read) => read.source),
+			complete: indexes.every((index) => index.complete)
+		};
+	}
+	/** Provider health for the entity reads: a read in flight is shared, a finished one reused for less than maxAgeMs. */
+	entitySpaceStatus(body, maxAgeMs) {
+		const recent = this.entityStatusCache.get(body.id);
+		if (recent !== void 0 && (recent.settledAt === void 0 || Date.now() - recent.settledAt < maxAgeMs)) return recent.status;
+		const entry = {
+			settledAt: void 0,
+			status: Promise.resolve(void 0)
+		};
+		entry.status = this.providerFor(body).status(body).catch((error) => ({
+			healthy: false,
+			error: error instanceof Error ? error.message : String(error)
+		})).then((status) => {
+			entry.settledAt = Date.now();
+			return status;
+		});
+		this.entityStatusCache.set(body.id, entry);
+		return entry.status;
+	}
+	entityIndexFor(body, status) {
+		const fingerprint = entityIndexFingerprint(body, status);
+		const cached = this.entityIndexCache.get(body.id);
+		if (cached !== void 0 && cached.fingerprint === fingerprint) {
+			if (fingerprint !== void 0 || cached.settledAt === void 0 || Date.now() - cached.settledAt < ENTITY_INDEX_UNCHECKED_REUSE_MS) return cached.index;
+		}
+		const entry = {
+			fingerprint,
+			settledAt: void 0,
+			index: Promise.resolve(void 0)
+		};
+		entry.index = this.buildEntityIndex(body).then((index) => {
+			entry.settledAt = Date.now();
+			return index;
+		}, (error) => {
+			if (this.entityIndexCache.get(body.id) === entry) this.entityIndexCache.delete(body.id);
+			throw error;
+		});
+		this.entityIndexCache.set(body.id, entry);
+		return entry.index;
+	}
+	async buildEntityIndex(body) {
+		const provider = this.providerFor(body);
+		if (provider.entityIndex !== void 0) {
+			const owned = await provider.entityIndex(body);
+			return buildSpaceEntityIndex(owned.memories.map((memory) => this.entityMemory(memory, body)), owned.memories.length, owned.complete);
+		}
+		const listed = await provider.list(body, { limit: ENTITY_INDEX_LIST_LIMIT });
+		return buildSpaceEntityIndex(listed.map((memory) => this.entityMemory(memory, body)), listed.length, listed.length < ENTITY_INDEX_LIST_LIMIT);
+	}
+	/** A listed memory, not a query result: no relevance fields. */
+	entityMemory(memory, body) {
+		const { score: _score, normalizedScore: _normalized, relevanceTier: _tier, federatedScore: _federated, confidence: _confidence, intent: _intent, matchedVia: _matchedVia, depth: _depth, edgeType: _edgeType, ...listed } = memory;
+		return this.annotate(listed, body);
+	}
+	invalidateEntityIndex(memoryBodyId) {
+		this.entityIndexCache.delete(memoryBodyId);
+		this.entityStatusCache.delete(memoryBodyId);
+	}
 	async remember(request, signal) {
 		this.assertWritable();
 		const prepared = this.prepareRemember(request);
@@ -2044,13 +2353,21 @@ var MemorySpacesService = class {
 	*/
 	async rememberMany(requests, signal) {
 		this.assertWritable();
-		const prepared = requests.map((request) => this.prepareRemember(request));
+		const destinations = /* @__PURE__ */ new Map();
+		const prepared = requests.map((request) => this.prepareRemember(request, destinations));
 		const results = new Array(prepared.length);
 		const groups = /* @__PURE__ */ new Map();
-		for (const [index, entry] of prepared.entries()) groups.set(entry.body.id, [...groups.get(entry.body.id) ?? [], {
-			...entry,
-			index
-		}]);
+		for (const [index, entry] of prepared.entries()) {
+			const group = groups.get(entry.body.id);
+			if (group === void 0) groups.set(entry.body.id, [{
+				...entry,
+				index
+			}]);
+			else group.push({
+				...entry,
+				index
+			});
+		}
 		for (const group of groups.values()) {
 			const body = group[0].body;
 			const provider = this.providerFor(body);
@@ -2066,8 +2383,9 @@ var MemorySpacesService = class {
 					providerChanged ||= mutationResultCommitted(result);
 				}
 			}
+			const batched = new Set(batch);
 			for (const entry of group) {
-				if (batch.includes(entry)) continue;
+				if (batched.has(entry)) continue;
 				const result = await provider.remember(body, entry.request, signal);
 				results[entry.index] = this.annotateResult(result, body);
 				providerChanged ||= mutationResultCommitted(result);
@@ -2273,10 +2591,14 @@ var MemorySpacesService = class {
 		return provider;
 	}
 	readSpaces(ids) {
-		const active = this.memorySpaces.active();
-		if (ids === void 0 || ids.length === 0) return active;
-		return [...new Set(ids.map((id) => id.trim()).filter((id) => id !== ""))].map((id) => {
-			const body = this.memorySpaces.get(id);
+		if (ids === void 0 || ids.length === 0) return this.memorySpaces.active();
+		const requested = [...new Set(ids.map((id) => id.trim()).filter((id) => id !== ""))];
+		const available = /* @__PURE__ */ new Map();
+		for (const body of this.memorySpaces.list()) if (!available.has(body.id)) available.set(body.id, body);
+		return requested.map((id) => {
+			const normalized = validateMemorySpaceId(id);
+			const body = available.get(normalized);
+			if (body === void 0) throw new Error(`unknown memory space: ${normalized}`);
 			if (!body.active) throw new Error(`memory space is not active for reading: ${id}`);
 			if (!this.isNativeSpace(body) && !this.memorySpaces.providerServiceEnabled(body.provider.id)) throw new Error(`${body.provider.label} is disabled on the dsh-mnemon page under Plugins`);
 			return body;
@@ -2303,8 +2625,10 @@ var MemorySpacesService = class {
 		if (active.length !== 1) throw new Error("memoryBodyId is required when the number of active memory spaces is not exactly one");
 		return active[0];
 	}
-	prepareRemember(request) {
-		const body = this.writeSpace(request.memoryBodyId);
+	prepareRemember(request, destinations) {
+		const key = request.memoryBodyId?.trim() ?? "";
+		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";
@@ -2345,6 +2669,7 @@ var MemorySpacesService = class {
 		};
 	}
 	activateAfterWrite(body, providerChanged) {
+		this.invalidateEntityIndex(body.id);
 		if (!providerChanged) return;
 		if (!body.active) this.memorySpaces.setActive(body.id, true);
 		else this.memorySpaces.touch(body.id);
@@ -2741,6 +3066,8 @@ async function manageMemorySpaces(service, request) {
 			...memoryInputStringArray(input.memoryBodyIds, "memoryBodyIds", 1e4) === void 0 ? {} : { memoryBodyIds: memoryInputStringArray(input.memoryBodyIds, "memoryBodyIds", 1e4) }
 		}, request.signal));
 		case "entities": return managementResult(service, await service.entities(memoryInputText(input.entity, "entity", 500, false), input.limit === void 0 ? void 0 : memoryInputInteger(input.limit, 100, 1, 1e4), request.signal));
+		case "entity-memories": return managementResult(service, await service.entityMemories(memoryInputText(input.entity, "entity", 500), input.offset === void 0 ? void 0 : memoryInputInteger(input.offset, 0, 0, 1e6), input.limit === void 0 ? void 0 : memoryInputInteger(input.limit, 50, 1, 200), request.signal));
+		case "entity-related": return managementResult(service, await service.entityRelated(memoryInputText(input.entity, "entity", 500), input.limit === void 0 ? void 0 : memoryInputInteger(input.limit, 20, 1, 50), request.signal, memoryInputText(input.view, "view", 200, false)));
 		case "search": return managementResult(service, await service.search({
 			query: memoryInputText(input.query, "query", 2e3),
 			...memoryInputText(input.mode, "mode", 20, false) === void 0 ? {} : { mode: memoryInputText(input.mode, "mode", 20, false) },

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 ProviderSpaceStatus, S as ProviderSearchResult, _ as MemorySpaceNativeRunner, a as MemorySpaceProviderHost, b as ProviderMemorySpace, 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, x as ProviderScoreSemantics, y as ProviderBodyStatus } from "./definitions-DwiEZSE_.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-BcYzE092.js";
 //#region src/providers/http.d.ts
 interface HttpProviderOptions {
   label?: string;
@@ -60,4 +60,4 @@ declare const DEFAULT_MAX_OUTPUT_BYTES: number;
 /** Spawn without a shell, with bounded output and cooperative cancellation. */
 declare const runProcess: ProcessRunner;
 //#endregion
-export { CATEGORIES, type Category, DEFAULT_MAX_OUTPUT_BYTES, EDGE_TYPES, type EdgeType, HttpMemoryProvider, HttpProviderOptions, INTENTS, type Insight, type Intent, JsonRequestOptions, type JsonValue, MEMORY_SPACE_PROVIDER_API_VERSION, type MemoryBody, type MemoryBodyProvider, type MemoryBodyStats, type MemoryGraphEdge, type MemoryGraphNode, type MemoryGraphSnapshot, type MemoryListRequest, MemoryProviderAdapter, MemoryProviderAdapterFactoryContext, type MemoryProviderCapabilities, type MemoryProviderConfigField, type MemoryProviderConfigOption, type MemoryProviderConnection, type MemoryProviderConnectionValue, type MemoryProviderDescriptor, type MemoryProviderIcon, type MemoryProviderId, MemoryProviderScoreSemantics, type MemorySpace, MemorySpaceAuthority, MemorySpaceNativeRunOptions, MemorySpaceNativeRunner, type MemorySpaceProvider, type MemorySpaceProviderDefinition, type MemorySpaceProviderDisposer, type MemorySpaceProviderEntry, type MemorySpaceProviderHost, type MemorySpaceProviderManifest, type MemorySpaceProviderModule, type MemorySpaceProviderRuntimeContext, type MemorySpaceProviderScoreSemantics, type MemorySpaceStats, NORMALIZED_RELEVANCE_SCORE, type OpenVikingBodyConnection, type OpenVikingSpaceConnection, ProcessError, ProcessFailureReason, ProcessOptions, ProcessResult, ProcessRunner, ProviderBodyStatus, ProviderMemorySpace, ProviderScoreSemantics, ProviderSearchResult, ProviderSpaceStatus, type RememberRequest, SOURCES, type SearchRequest, type Source, defineMemorySpaceProvider, defineMemorySpaceProviderDefinition, firstArray, jsonArray, jsonNumber, jsonObject, jsonString, runProcess };
+export { CATEGORIES, type Category, DEFAULT_MAX_OUTPUT_BYTES, EDGE_TYPES, type EdgeType, HttpMemoryProvider, HttpProviderOptions, INTENTS, type Insight, type Intent, JsonRequestOptions, type JsonValue, MEMORY_SPACE_PROVIDER_API_VERSION, type MemoryBody, type MemoryBodyProvider, type MemoryBodyStats, type MemoryGraphEdge, type MemoryGraphNode, type MemoryGraphSnapshot, type MemoryListRequest, MemoryProviderAdapter, MemoryProviderAdapterFactoryContext, type MemoryProviderCapabilities, type MemoryProviderConfigField, type MemoryProviderConfigOption, type MemoryProviderConnection, type MemoryProviderConnectionValue, type MemoryProviderDescriptor, type MemoryProviderIcon, type MemoryProviderId, MemoryProviderScoreSemantics, type MemorySpace, MemorySpaceAuthority, MemorySpaceNativeRunOptions, MemorySpaceNativeRunner, type MemorySpaceProvider, type MemorySpaceProviderDefinition, type MemorySpaceProviderDisposer, type MemorySpaceProviderEntry, type MemorySpaceProviderHost, type MemorySpaceProviderManifest, type MemorySpaceProviderModule, type MemorySpaceProviderRuntimeContext, type MemorySpaceProviderScoreSemantics, type MemorySpaceStats, NORMALIZED_RELEVANCE_SCORE, type OpenVikingBodyConnection, type OpenVikingSpaceConnection, ProcessError, ProcessFailureReason, ProcessOptions, ProcessResult, ProcessRunner, ProviderBodyStatus, ProviderEntityIndex, ProviderMemorySpace, ProviderScoreSemantics, ProviderSearchResult, ProviderSpaceStatus, type RememberRequest, SOURCES, type SearchRequest, type Source, defineMemorySpaceProvider, defineMemorySpaceProviderDefinition, firstArray, jsonArray, jsonNumber, jsonObject, jsonString, runProcess };

package/lib/testing.d.ts

@@ -1,5 +1,5 @@
 import { MemoryProviderConnection, MemoryProviderDescriptor, MemorySpace } from "./contracts.js";
-import { f as MemoryProviderAdapter, h as MemorySpaceAuthority, o as MemorySpaceProviderManifest, p as MemoryProviderAdapterFactoryContext, s as MemorySpaceProviderModule } from "./definitions-DwiEZSE_.js";
+import { f as MemoryProviderAdapter, h as MemorySpaceAuthority, o as MemorySpaceProviderManifest, p as MemoryProviderAdapterFactoryContext, s as MemorySpaceProviderModule } from "./definitions-BcYzE092.js";
 //#region src/testing.d.ts
 interface MemorySpaceProviderTest {
   readonly registered: boolean;

package/lib/types/client/api.d.ts

@@ -1,4 +1,4 @@
-import type { CreateMemorySpaceRequest, EntityView, Insight, MemorySpace, MemorySpaceView, MemorySpaceMetadataMaintenanceResult, MemorySpaceCatalog, MemoryGraphSnapshot, MemoryListRequest, MemoryListView, MemoryReadSource, RememberRequest, SearchRequest, UpdateMemorySpaceRequest } from '../contracts.ts';
+import type { CreateMemorySpaceRequest, EntityMemoriesView, EntityRelatedView, EntityView, Insight, MemorySpace, MemorySpaceView, MemorySpaceMetadataMaintenanceResult, MemorySpaceCatalog, MemoryGraphSnapshot, MemoryListRequest, MemoryListView, MemoryReadSource, RememberRequest, SearchRequest, UpdateMemorySpaceRequest } from '../contracts.ts';
 /**
  * Source-owned structural page API; the default bundle may supply agent-assisted callbacks.
  * body/bodies method and wire-field spellings remain compatible with existing
@@ -10,6 +10,10 @@ export interface MemorySpacesPageClient {
     graph(memoryBodyIds?: string[]): Promise<MemoryGraphSnapshot>;
     list(request?: MemoryListRequest): Promise<MemoryListView>;
     entities(entity?: string, limit?: number): Promise<EntityView>;
+    /** Optional for page clients written against an older Source; the Entities page then lists entities(entity) only. */
+    entityMemories?(entity: string, offset?: number, limit?: number): Promise<EntityMemoriesView>;
+    /** view: one id per page view; its next selection cancels the related read it is still waiting for. */
+    entityRelated?(entity: string, limit?: number, view?: string): Promise<EntityRelatedView>;
     search(request: SearchRequest): Promise<SearchResponse>;
     agentSearch(request: SearchRequest): Promise<AgentSearchResponse>;
     related(id: string, memoryBodyId?: string): Promise<Insight[]>;