@dsh-agentic-roleplay/state 0.1.1 → 0.3.0

package/lib/index.js

@@ -1,6 +1,6 @@
 import { createRequire } from "node:module";
 import { DatabaseSync } from "node:sqlite";
-import { join, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { Service } from "@deepseek-ai/cordis";
 import z from "@deepseek-ai/schemastery";
 import { randomUUID } from "node:crypto";
@@ -346,6 +346,8 @@ const COMPARISONS = [
 	"gt",
 	"ge"
 ];
+/** In a cue, the key of the character it is said to: in a `while` condition and in the words of the cue. */
+const SELF = "@self";
 const TRIGGER_STATUSES = [
 	"dormant",
 	"fired",
@@ -835,14 +837,14 @@ function parseInstant(text, zone) {
 /** `Tuesday 4 October 1912, 21:40`. */
 function describeInstant(instant, zone) {
 	const local = localTime(instant, zone);
-	return `${WEEKDAYS[local.weekday]} ${local.day} ${MONTHS[local.month - 1]} ${local.year}, ${pad(local.hour)}:${pad(local.minute)}`;
+	return `${WEEKDAYS[local.weekday]} ${local.day} ${MONTHS[local.month - 1]} ${local.year}, ${pad$1(local.hour)}:${pad$1(local.minute)}`;
 }
 /** `1912-10-04T21:40:00` as the wall clock of a zone reads, the form a file or a person can write back. */
 function localIso(instant, zone) {
 	const local = localTime(instant, zone);
-	return `${String(local.year).padStart(4, "0")}-${pad(local.month)}-${pad(local.day)}T${pad(local.hour)}:${pad(local.minute)}:${pad(local.second)}`;
+	return `${String(local.year).padStart(4, "0")}-${pad$1(local.month)}-${pad$1(local.day)}T${pad$1(local.hour)}:${pad$1(local.minute)}:${pad$1(local.second)}`;
 }
-const pad = (value) => String(value).padStart(2, "0");
+const pad$1 = (value) => String(value).padStart(2, "0");
 const DAY_PARTS = [
 	"night",
 	"morning",
@@ -946,7 +948,7 @@ function catchUpPlan(cursor, now, limits = {}) {
 /** `21:40`: the clock of a zone at an instant. */
 function clockTime(instant, zone) {
 	const local = localTime(instant, zone);
-	return `${pad(local.hour)}:${pad(local.minute)}`;
+	return `${pad$1(local.hour)}:${pad$1(local.minute)}`;
 }
 /** The local calendar day `days` after the one the instant falls on, as year, month and day. */
 function addLocalDays(instant, zone, days) {
@@ -964,7 +966,7 @@ function addLocalDays(instant, zone, days) {
 	};
 }
 /** `07:30` for a minute of the day. */
-const minuteText = (minute) => `${pad(Math.floor(minute / 60))}:${pad(minute % 60)}`;
+const minuteText = (minute) => `${pad$1(Math.floor(minute / 60))}:${pad$1(minute % 60)}`;
 //#endregion
 //#region src/records/agenda-edit.ts
 const MAX_PLAN_STEPS = 8;
@@ -1664,6 +1666,78 @@ function moveCharacter(context, characterId, move) {
 	return result.plan;
 }
 //#endregion
+//#region src/records/template.ts
+/**
+* What the words of a cue or a beat may name by `{kind:key}`, filled in from the story when they are told. The key is how the world's files
+* name the thing (`@self` in a cue is the character it is said to), and a name follows the story: a renamed character is renamed in the words.
+*/
+const TEMPLATE_KINDS = {
+	/** The name of a character. */
+	character: {
+		args: 1,
+		about: "a character"
+	},
+	/** The name of a place. */
+	place: {
+		args: 1,
+		about: "a place"
+	},
+	/** The name of an item. */
+	item: {
+		args: 1,
+		about: "an item"
+	},
+	/** The name of the place a character is in now. */
+	where: {
+		args: 1,
+		about: "a character"
+	},
+	/** Who holds an item now, or the place it lies in. */
+	holder: {
+		args: 1,
+		about: "an item"
+	},
+	/** What a variable is now, in words: `{value:key}` for a world variable, `{value:key:subject}` for the character, item or place it is about. */
+	value: {
+		args: 2,
+		about: "a variable"
+	},
+	/** The time of day in the story, as `19:30`. */
+	time: {
+		args: 0,
+		about: ""
+	}
+};
+const PATTERN = /\{([a-z]+)(?::([^{}]*))?\}/g;
+/** The placeholders in some words, and what is wrong with any that is not one. Anything that does not look like `{word}` or `{word:key}` is plain text. */
+function placeholdersOf(text) {
+	const found = [];
+	const problems = [];
+	for (const match of text.matchAll(PATTERN)) {
+		const [raw, word, rest] = match;
+		if (!(word in TEMPLATE_KINDS)) {
+			problems.push(`${raw}: there is no "${word}"; the words may name ${Object.keys(TEMPLATE_KINDS).join(", ")}`);
+			continue;
+		}
+		const kind = word;
+		const args = rest === void 0 ? [] : rest.split(":").map((part) => part.trim());
+		const { args: wanted } = TEMPLATE_KINDS[kind];
+		if (!(kind === "value" ? args.length >= 1 && args.length <= 2 : args.length === wanted) || args.some((part) => part === "")) {
+			problems.push(`${raw}: ${kind === "time" ? "{time} takes nothing" : kind === "value" ? "{value:variable} or {value:variable:subject}" : `{${kind}:key} takes the key of ${TEMPLATE_KINDS[kind].about}`}`);
+			continue;
+		}
+		found.push({
+			raw,
+			kind,
+			args
+		});
+	}
+	return {
+		found,
+		problems
+	};
+}
+//#endregion
 //#region src/sqlite/variable-repository.ts
 const MAX_BANDS = 8;
 const MAX_OPTIONS = 12;
@@ -1922,9 +1996,15 @@ function describeValue(def, value) {
 	const band = def.bands.find((candidate) => value <= candidate.upTo) ?? def.bands.at(-1);
 	return band === void 0 ? shortNumber(value) : `${band.label} (${shortNumber(value)})`;
 }
+/** A variable written by its name or in other letter case ("Valence" for `valence`), when exactly one variable has that name or key. */
+function namedVariable(variables, written) {
+	const wanted = written.trim().normalize("NFKC").toLowerCase();
+	const found = wanted === "" ? [] : variables.defs().filter((def) => def.key.normalize("NFKC").toLowerCase() === wanted || def.name.normalize("NFKC").toLowerCase() === wanted);
+	return found.length === 1 ? found[0] : void 0;
+}
 /** Whether a change can be made, and what it would come to. Nothing is changed. */
 function planVariableChange(context, spec) {
-	const def = context.variables.def(spec.variable);
+	const def = context.variables.def(spec.variable) ?? namedVariable(context.variables, spec.variable);
 	if (def === void 0) return {
 		ok: false,
 		problems: [`there is no variable "${spec.variable}" (list_variables shows them)`]
@@ -2200,6 +2280,21 @@ function parseAnnouncement(value, path, problems) {
 		...at === void 0 ? {} : { at }
 	};
 }
+/** Whether words or a condition name the character a cue is said to. */
+function usesSelf(words, condition) {
+	return placeholdersOf(words).found.some((placeholder) => placeholder.args.includes("@self")) || condition !== void 0 && mentionsSelf(condition);
+}
+function mentionsSelf(condition) {
+	switch (condition.type) {
+		case "place": return condition.character === SELF;
+		case "variable": return condition.subject === SELF;
+		case "item": return condition.item === "@self" || condition.heldBy === "@self";
+		case "all":
+		case "any": return condition.conditions.some(mentionsSelf);
+		case "not": return mentionsSelf(condition.condition);
+		default: return false;
+	}
+}
 function parseEffect(value, path, problems, checkEdit) {
 	if (!isObject$2(value)) {
 		problems.push(`${path}: an effect is an object`);
@@ -2219,6 +2314,10 @@ function parseEffect(value, path, problems, checkEdit) {
 			problems.push(`${path}.edit: ${error instanceof InvalidEditError ? error.problems.join("; ") : String(error)}`);
 			return;
 		}
+		if (value["while"] !== void 0) {
+			problems.push(`${path}.while: only a beat or a cue can wait on a condition when it is told`);
+			return;
+		}
 		return {
 			type: "edit",
 			edit: value["edit"]
@@ -2233,16 +2332,26 @@ function parseEffect(value, path, problems, checkEdit) {
 		problems.push(`${path}.text: required text of at most ${MAX_TEXT$1} characters`);
 		return;
 	}
-	if (value["type"] === "beat") return {
-		type: "beat",
-		text: words
-	};
+	const template = placeholdersOf(words);
+	for (const problem of template.problems) problems.push(`${path}.text: ${problem}`);
+	const waiting = value["while"] === void 0 ? void 0 : parseCondition(value["while"], `${path}.while`, problems, { nodes: 0 });
+	if (value["while"] !== void 0 && waiting === void 0) return void 0;
+	if (waiting !== void 0 && judgedStatements(waiting).length > 0) problems.push(`${path}.while: a statement a model judges (judged) cannot be waited on when something is told; use what the story records`);
+	if (value["type"] === "beat") {
+		if (usesSelf(words, waiting)) problems.push(`${path}: only a cue is said to someone, so only a cue can name ${SELF}`);
+		return template.problems.length > 0 ? void 0 : {
+			type: "beat",
+			text: words,
+			...waiting === void 0 ? {} : { while: waiting }
+		};
+	}
 	if (value["type"] === "cue") {
 		const audience = value["audience"] !== void 0 ? parseAudience(value["audience"], `${path}.audience`, problems) : parseAudience({ characters: value["characters"] }, `${path}.characters`, problems);
-		return audience === void 0 ? void 0 : {
+		return audience === void 0 || template.problems.length > 0 ? void 0 : {
 			type: "cue",
 			audience,
-			text: words
+			text: words,
+			...waiting === void 0 ? {} : { while: waiting }
 		};
 	}
 	problems.push(`${path}.type: one of edit, beat, cue`);
@@ -2294,8 +2403,8 @@ function parseTriggerDefinition(value, path, checkEdit) {
 		...announce === void 0 ? {} : { announce }
 	} };
 }
-function conditionProblems(target, condition, path, known) {
-	const character = (key) => target.characters.list().some((entry) => characterKey(entry) === key) ? [] : [`${path}: there is no character "${key}"`];
+function conditionProblems(target, condition, path, known, self = false) {
+	const character = (key) => self && key === "@self" || target.characters.list().some((entry) => characterKey(entry) === key) ? [] : [`${path}: there is no character "${key}"`];
 	const place = (key) => target.locations.list().some((entry) => locationKey(entry) === key) ? [] : [`${path}: there is no place "${key}"`];
 	switch (condition.type) {
 		case "time": return [];
@@ -2304,11 +2413,11 @@ function conditionProblems(target, condition, path, known) {
 			const def = target.variables.def(condition.variable);
 			if (def === void 0) return [`${path}: there is no variable "${condition.variable}"`];
 			if (def.subject === "world" ? condition.subject !== void 0 : condition.subject === void 0) return [`${path}: ${def.subject === "world" ? "a world variable has no subject" : `give the ${def.subject} it is about as subject`}`];
-			const subject = condition.subject === void 0 ? void 0 : subjectOf(target, def.subject, condition.subject);
-			return [...condition.subject !== void 0 && subject === void 0 ? [`${path}: there is no ${def.subject} "${condition.subject}"`] : [], ...def.kind !== "number" && condition.op !== "eq" && condition.op !== "ne" ? [`${path}: ${def.kind} variables compare with eq or ne only`] : []];
+			const subject = condition.subject === void 0 || self && condition.subject === "@self" ? void 0 : subjectOf(target, def.subject, condition.subject);
+			return [...condition.subject !== void 0 && subject === void 0 && !(self && condition.subject === "@self") ? [`${path}: there is no ${def.subject} "${condition.subject}"`] : [], ...def.kind !== "number" && condition.op !== "eq" && condition.op !== "ne" ? [`${path}: ${def.kind} variables compare with eq or ne only`] : []];
 		}
 		case "item": return [
-			...target.items.list().some((entry) => itemKey(entry) === condition.item) ? [] : [`${path}: there is no item "${condition.item}"`],
+			...self && condition.item === "@self" || target.items.list().some((entry) => itemKey(entry) === condition.item) ? [] : [`${path}: there is no item "${condition.item}"`],
 			...condition.heldBy === void 0 ? [] : character(condition.heldBy),
 			...condition.at === void 0 ? [] : place(condition.at)
 		];
@@ -2316,9 +2425,33 @@ function conditionProblems(target, condition, path, known) {
 		case "fired": return known.has(condition.trigger) ? [] : [`${path}: there is no trigger "${condition.trigger}"`];
 		case "judged": return [];
 		case "all":
-		case "any": return condition.conditions.flatMap((part, index) => conditionProblems(target, part, `${path}.conditions[${index}]`, known));
-		case "not": return conditionProblems(target, condition.condition, `${path}.condition`, known);
-	}
+		case "any": return condition.conditions.flatMap((part, index) => conditionProblems(target, part, `${path}.conditions[${index}]`, known, self));
+		case "not": return conditionProblems(target, condition.condition, `${path}.condition`, known, self);
+	}
+}
+/** What the words of a cue or beat name by `{kind:key}` that the story does not have. */
+function wordsProblems(target, words, path, self) {
+	return placeholdersOf(words).found.flatMap((placeholder) => {
+		const key = placeholder.args[0];
+		const selfKey = self && key === "@self";
+		const missing = (what) => [`${path}: ${placeholder.raw}: there is no ${what} "${key}"`];
+		switch (placeholder.kind) {
+			case "character":
+			case "where": return selfKey || target.characters.list().some((entry) => characterKey(entry) === key) ? [] : missing("character");
+			case "place": return target.locations.list().some((entry) => locationKey(entry) === key) ? [] : missing("place");
+			case "item":
+			case "holder": return target.items.list().some((entry) => itemKey(entry) === key) ? [] : missing("item");
+			case "value": {
+				const def = target.variables.def(key);
+				if (def === void 0) return missing("variable");
+				const subject = placeholder.args[1];
+				if (def.subject === "world") return subject === void 0 ? [] : [`${path}: ${placeholder.raw}: a world variable has no subject`];
+				if (subject === void 0) return [`${path}: ${placeholder.raw}: give the ${def.subject} it is about`];
+				return self && subject === "@self" || subjectOf(target, def.subject, subject) !== void 0 ? [] : [`${path}: ${placeholder.raw}: there is no ${def.subject} "${subject}"`];
+			}
+			case "time": return [];
+		}
+	});
 }
 /**
 * What in a trigger names something the story does not have: a character, place, item or variable in a condition, the characters of a cue,
@@ -2332,10 +2465,12 @@ function triggerReferenceProblems(target, definition, otherKeys = []) {
 		return who.characters.flatMap((key) => target.characters.list().some((entry) => characterKey(entry) === key) ? [] : [`${path}: there is no character "${key}"`]);
 	};
 	const cues = definition.effects.flatMap((effect, index) => effect.type !== "cue" ? [] : audience(effect.audience, `effects[${index}]`));
+	const said = definition.effects.flatMap((effect, index) => effect.type === "edit" ? [] : [...effect.while === void 0 ? [] : conditionProblems(target, effect.while, `effects[${index}].while`, known, effect.type === "cue"), ...wordsProblems(target, effect.text, `effects[${index}].text`, effect.type === "cue")]);
 	const announced = definition.announce === void 0 ? [] : audience(definition.announce.audience, "announce");
 	return [
 		...conditionProblems(target, definition.condition, "when", known),
 		...cues,
+		...said,
 		...announced
 	].map((problem) => `${definition.key}: ${problem}`);
 }
@@ -3677,7 +3812,7 @@ function recordsEditSchema(options = {}) {
 					},
 					effects: {
 						type: "array",
-						description: "What happens, one to six: {type:\"edit\", edit:{...}} a change of the records in the same format as edit_records (events with a location are seen by those there, variable_changes, exit_changes, item_changes, moves, intents_added, engagements); {type:\"beat\", text} something the game master is told to weave into the story; {type:\"cue\", characters:[keys] (or audience: \"everyone\" | {place:key}), text} something those characters notice; in the events of an edit, perceived_by may be \"everyone\".",
+						description: "What happens, one to six: {type:\"edit\", edit:{...}} a change of the records in the same format as edit_records (events with a location are seen by those there, variable_changes, exit_changes, item_changes, moves, intents_added, engagements); {type:\"beat\", text, while?} something the game master is told to weave into the story; {type:\"cue\", characters:[keys] (or audience: \"everyone\" | {place:key}), text, while?} something those characters notice; a beat or cue is written when it is told, which may be turns after the trigger fired: its text may name things as {character:key}, {place:key}, {item:key}, {where:character} (the place a character is in), {holder:item} (who has it or where it lies), {value:variable} or {value:variable:subject}, {time}, and is told as the story stands then, and `while` is a condition (as above, nothing judged) that must still hold then or it is withdrawn; in a cue \"@self\" stands for the character it is said to (for example while:{type:\"place\", character:\"@self\", location:\"cellar\"}); in the events of an edit, perceived_by may be \"everyone\".",
 						items: {
 							type: "object",
 							properties: { type: {
@@ -5205,12 +5340,147 @@ function lapseNotes(target, turn, kept) {
 	return lapsed;
 }
 //#endregion
+//#region src/records/deferred.ts
+/** The words cannot be written as the story stands: something they name is not there. */
+var UnwritableError = class extends Error {};
+const pad = (value) => String(value).padStart(2, "0");
+function resolve$1(target, placeholder, clock, self) {
+	const key = (index) => placeholder.args[index] === "@self" ? self ?? "@self" : placeholder.args[index];
+	const character = (wanted) => {
+		const found = target.characters.list().find((entry) => characterKey(entry) === wanted);
+		if (found === void 0) throw new UnwritableError(`${placeholder.raw}: there is no character "${wanted}"`);
+		return found;
+	};
+	const place = (wanted) => {
+		const found = target.locations.list().find((entry) => locationKey(entry) === wanted);
+		if (found === void 0) throw new UnwritableError(`${placeholder.raw}: there is no place "${wanted}"`);
+		return found;
+	};
+	const item = (wanted) => {
+		const found = target.items.list().find((entry) => itemKey(entry) === wanted);
+		if (found === void 0) throw new UnwritableError(`${placeholder.raw}: there is no item "${wanted}"`);
+		return found;
+	};
+	switch (placeholder.kind) {
+		case "character": return character(key(0)).name;
+		case "place": return place(key(0)).name;
+		case "item": return item(key(0)).name;
+		case "where": {
+			const who = character(key(0));
+			const at = target.placements.get("character", who.id);
+			const found = at === void 0 ? void 0 : target.locations.get(at.locationId);
+			if (found === void 0) throw new UnwritableError(`${placeholder.raw}: ${who.name} is nowhere in particular`);
+			return found.name;
+		}
+		case "holder": {
+			const thing = item(key(0));
+			const where = target.items.where(thing.id);
+			const holder = where.characterId !== void 0 ? target.characters.get(where.characterId)?.name : where.locationId !== void 0 ? target.locations.get(where.locationId)?.name : void 0;
+			if (holder === void 0) throw new UnwritableError(`${placeholder.raw}: ${thing.name} is nowhere that is known`);
+			return holder;
+		}
+		case "value": {
+			const def = target.variables.def(placeholder.args[0]);
+			if (def === void 0) throw new UnwritableError(`${placeholder.raw}: there is no variable "${placeholder.args[0]}"`);
+			const subject = def.subject === "world" ? { id: 0 } : placeholder.args[1] === void 0 ? void 0 : subjectOf(target, def.subject, key(1));
+			if (subject === void 0) throw new UnwritableError(`${placeholder.raw}: ${def.subject === "world" ? "a world variable has no subject" : `give the ${def.subject} it is about`}`);
+			return describeValue(def, target.variables.value(def.key, def.subject, subject.id));
+		}
+		case "time": {
+			const local = localTime(clock.now, clock.zone);
+			return `${pad(local.hour)}:${pad(local.minute)}`;
+		}
+	}
+}
+/** Words as the story stands now. @throws {UnwritableError} when something they name is not there. */
+function renderWords(target, text, clock, self) {
+	const { found } = placeholdersOf(text);
+	let at = 0;
+	let out = "";
+	for (const placeholder of found) {
+		const start = text.indexOf(placeholder.raw, at);
+		out += text.slice(at, start) + resolve$1(target, placeholder, clock, self);
+		at = start + placeholder.raw.length;
+	}
+	return out + text.slice(at);
+}
+/** A condition with `@self` taken as a character. */
+function bindSelf(condition, self) {
+	const bound = (value) => value === "@self" ? self : value;
+	switch (condition.type) {
+		case "place": return {
+			...condition,
+			character: bound(condition.character)
+		};
+		case "variable": return condition.subject === void 0 ? condition : {
+			...condition,
+			subject: bound(condition.subject)
+		};
+		case "item": return {
+			...condition,
+			item: bound(condition.item),
+			...condition.heldBy === void 0 ? {} : { heldBy: bound(condition.heldBy) }
+		};
+		case "all":
+		case "any": return {
+			...condition,
+			conditions: condition.conditions.map((part) => bindSelf(part, self))
+		};
+		case "not": return {
+			...condition,
+			condition: bindSelf(condition.condition, self)
+		};
+		default: return condition;
+	}
+}
+/** The effect of a trigger that a note was made from: the beat or cue whose words it carries. */
+function noteEffect(trigger, note) {
+	return trigger?.effects.find((effect) => effect.type === note.kind && effect.text === note.text);
+}
+/**
+* Decides, at the moment notes are about to be told, what is still to be told and in what words. A note whose effect says something must
+* still hold and does not hold any more is withdrawn; so is one whose words name something that is not there. Nothing is changed.
+*/
+function deliverNotes(target, notes, clock) {
+	const delivery = {
+		shown: [],
+		withdrawn: []
+	};
+	for (const note of notes) {
+		const effect = noteEffect(target.triggers.get(note.triggerId), note);
+		const self = note.kind === "cue" && note.characterIds[0] !== void 0 ? target.characters.list().find((entry) => entry.id === note.characterIds[0]) : void 0;
+		const who = self === void 0 ? void 0 : characterKey(self);
+		if (effect?.while !== void 0 && !conditionHolds(target, who === void 0 ? effect.while : bindSelf(effect.while, who), clock)) {
+			delivery.withdrawn.push({
+				note,
+				reason: "what it was waiting on no longer holds"
+			});
+			continue;
+		}
+		try {
+			delivery.shown.push({
+				note,
+				text: renderWords(target, note.text, clock, who)
+			});
+		} catch (error) {
+			if (!(error instanceof UnwritableError)) throw error;
+			delivery.withdrawn.push({
+				note,
+				reason: error.message
+			});
+		}
+	}
+	return delivery;
+}
+//#endregion
 //#region src/memory/recall.ts
 const DAY$1 = 864e5;
 const DEFAULT_MEMORY_POLICY = {
 	flaky: true,
 	recall: 12,
-	overRetrieve: 4
+	overRetrieve: 4,
+	associate: 2,
+	diversity: .3
 };
 /** Story days for the memory of an unimportant event to halve; each step of importance doubles it. */
 const HALF_LIFE_DAYS = 6;
@@ -5341,7 +5611,7 @@ const DENSE_RANGE = .5;
 const denseScore = (similarity) => Math.min(1, Math.max(0, (similarity - DENSE_FLOOR) / DENSE_RANGE));
 /** Being where something happened calls it to mind, about as much as sharing two words with it. */
 const PLACE_CUE = 2;
-function gather(source, { characterId, characters, situation, locationId }) {
+function gather(source, { characterId, characters, situation, locationId, about }) {
 	const names = new Map(characters.map((character) => [character.id, character.name]));
 	const peers = mentioned(situation, characters);
 	peers.delete(characterId);
@@ -5359,24 +5629,46 @@ function gather(source, { characterId, characters, situation, locationId }) {
 	}
 	const atTurn = (eventTurn) => turns.get(eventTurn) ?? start;
 	const ageDays = (at) => now === void 0 || at === void 0 ? 0 : Math.max(0, now - at) / DAY$1;
-	return [...source.events.perceivedBy(characterId).map((seen) => {
+	const concerns = (ids) => about === void 0 || about.length === 0 || ids.some((id) => about.includes(id));
+	return [...source.events.perceivedBy(characterId).filter((seen) => concerns(seen.event.involves)).map((seen) => {
 		const at = rounds.get(`${seen.event.turn}:${seen.event.round}`) ?? atTurn(seen.event.turn);
+		const cue = {
+			people: peopleCue(seen.event.involves),
+			words: overlap(cues, `${seen.perception.content} ${seen.event.text}`, seen.event.tags),
+			place: locationId !== void 0 && seen.event.locationId === locationId ? PLACE_CUE : 0
+		};
 		return {
 			key: `p:${seen.perception.id}`,
+			links: {
+				people: seen.event.involves.filter((id) => id !== characterId),
+				tags: seen.event.tags.map((tag) => tag.toLowerCase()),
+				...seen.event.locationId === void 0 ? {} : { place: seen.event.locationId }
+			},
 			recalled: describeEvent(seen, names, at),
-			relevance: peopleCue(seen.event.involves) + overlap(cues, `${seen.perception.content} ${seen.event.text}`, seen.event.tags) + (locationId !== void 0 && seen.event.locationId === locationId ? PLACE_CUE : 0),
+			cues: cue,
+			relevance: cue.people + cue.words + cue.place,
 			importance: seen.event.importance,
 			ageDays: ageDays(at),
 			recalls: seen.perception.recalls,
 			seed: seen.perception.id,
 			durability: 1
 		};
-	}), ...source.memories.list(characterId).map((belief) => {
+	}), ...source.memories.list(characterId).filter((belief) => concerns(belief.about)).map((belief) => {
 		const at = atTurn(belief.turn);
+		const cue = {
+			people: peopleCue(belief.about),
+			words: overlap(cues, belief.text, []),
+			place: 0
+		};
 		return {
 			key: `m:${belief.id}`,
+			links: {
+				people: belief.about.filter((id) => id !== characterId),
+				tags: []
+			},
 			recalled: describeBelief(belief, at),
-			relevance: peopleCue(belief.about) + overlap(cues, belief.text, []),
+			cues: cue,
+			relevance: cue.people + cue.words,
 			importance: belief.importance,
 			ageDays: ageDays(at),
 			recalls: belief.recalls,
@@ -5405,20 +5697,25 @@ function fuseScores(searches) {
 /** How well a candidate stands once its relevance is known: what the moment calls to mind, how much it matters and how recent it is. */
 function judged(candidate, relevance, policy) {
 	let clarity = "clear";
-	if (policy.flaky) clarity = clarityAt(retention({
-		ageDays: candidate.ageDays,
-		importance: candidate.importance,
-		recalls: candidate.recalls,
-		seed: candidate.seed,
-		durability: candidate.durability,
-		cue: relevance >= CUE_RELEVANCE
-	}), candidate.importance);
+	let kept;
+	if (policy.flaky) {
+		kept = retention({
+			ageDays: candidate.ageDays,
+			importance: candidate.importance,
+			recalls: candidate.recalls,
+			seed: candidate.seed,
+			durability: candidate.durability,
+			cue: relevance >= CUE_RELEVANCE
+		});
+		clarity = clarityAt(kept, candidate.importance);
+	}
 	if (clarity === void 0) return void 0;
 	const score = RELEVANCE_SCALE * relevance + .6 * candidate.importance + 2 / (1 + Math.max(0, candidate.ageDays)) + (clarity === "vague" ? -1 : 0);
 	return {
 		clarity,
 		score,
-		text: candidate.recalled[clarity === "clear" ? "clear" : clarity === "faded" ? "faded" : "vague"]
+		text: candidate.recalled[clarity === "clear" ? "clear" : clarity === "faded" ? "faded" : "vague"],
+		...kept === void 0 ? {} : { retention: kept }
 	};
 }
 /**
@@ -5429,7 +5726,7 @@ function judged(candidate, relevance, policy) {
 * is, and not what has faded from memory altogether). A reranker may then judge that pool.
 */
 function recallPool(source, query, evidence = {}) {
-	const { policy } = query;
+	const { policy, explain } = query;
 	const candidates = gather(source, query);
 	const fused = fuseScores([
 		{
@@ -5446,18 +5743,28 @@ function recallPool(source, query, evidence = {}) {
 		}
 	]);
 	const width = Math.min(MAX_POOL, Math.max(policy.recall, Math.ceil(policy.recall * Math.max(1, policy.overRetrieve ?? 1))));
+	const entries = candidates.map((candidate) => ({
+		candidate,
+		fused: fused.get(candidate.key) ?? 0,
+		found: {
+			...evidence.lexical?.get(candidate.key) === void 0 ? {} : { lexical: evidence.lexical.get(candidate.key) },
+			...evidence.dense?.get(candidate.key) === void 0 ? {} : { dense: evidence.dense.get(candidate.key) }
+		}
+	})).flatMap((entry) => {
+		const standing = judged(entry.candidate, entry.fused, policy);
+		return standing === void 0 ? [] : [{
+			entry,
+			score: standing.score
+		}];
+	}).sort((a, b) => b.score - a.score || b.entry.candidate.recalled.turn - a.entry.candidate.recalled.turn).map(({ entry }) => entry).slice(0, width);
+	const kept = new Set(entries.map((entry) => entry.candidate.key));
 	return {
-		entries: candidates.map((candidate) => ({
-			candidate,
-			fused: fused.get(candidate.key) ?? 0
-		})).flatMap((entry) => {
-			const standing = judged(entry.candidate, entry.fused, policy);
-			return standing === void 0 ? [] : [{
-				entry,
-				score: standing.score
-			}];
-		}).sort((a, b) => b.score - a.score || b.entry.candidate.recalled.turn - a.entry.candidate.recalled.turn).slice(0, width).map(({ entry }) => entry),
-		query: { policy }
+		entries,
+		others: candidates.filter((candidate) => !kept.has(candidate.key)),
+		query: {
+			policy,
+			...explain === true ? { explain } : {}
+		}
 	};
 }
 /** What a reranker is asked to judge: every candidate of the pool, with the text it would be recalled by. */
@@ -5469,26 +5776,129 @@ function poolCandidates(pool) {
 		importance: candidate.importance
 	}));
 }
+/** Two things are tied by the same people, the same tags and the same place; this is how strongly (people count most, tags and place add a little). */
+function tie(a, b) {
+	const people = a.people.filter((id) => b.people.includes(id)).length;
+	const tags = a.tags.filter((tag) => b.tags.includes(tag)).length;
+	const place = a.place !== void 0 && a.place === b.place;
+	return {
+		strength: 2 * Math.min(people, 2) + Math.min(tags, 2) + (place ? 1 : 0),
+		people,
+		tags,
+		place
+	};
+}
+/** The least a tie has to be for one thing to bring the other to mind. */
+const STRONG_TIE = 3;
+/** What does not matter much is not brought back by association. */
+const ASSOCIABLE_IMPORTANCE = 3;
+/** How much two texts say the same, from 0 to 1: the share of their words (or pairs of characters) they have in common. */
+function resemblance(a, b) {
+	if (a.size === 0 || b.size === 0) return 0;
+	let shared = 0;
+	for (const word of a) if (b.has(word)) shared++;
+	return shared / (a.size + b.size - shared);
+}
+/**
+* Choose `count` of the ranked entries by maximal marginal relevance: each pick is the one with the best score
+* discounted by how much it resembles what is already chosen, so that three memories of the same moment do not
+* crowd out one of another. `diversity` 0 keeps the ranking as it is.
+*/
+function diversified(ranked, count, diversity) {
+	const weight = Math.min(1, Math.max(0, diversity));
+	if (weight === 0 || ranked.length <= 1) return ranked.slice(0, count);
+	const top = Math.max(...ranked.map((entry) => entry.score), Number.EPSILON);
+	const words = new Map(ranked.map((entry) => [entry, tokens(entry.candidate.recalled.clear)]));
+	const left = [...ranked];
+	const chosen = [];
+	while (chosen.length < count && left.length > 0) {
+		let best = 0;
+		let bestValue = -Infinity;
+		left.forEach((entry, index) => {
+			const repeat = Math.max(0, ...chosen.map((picked) => resemblance(words.get(entry), words.get(picked))));
+			const value = (1 - weight) * Math.max(0, entry.score) / top - weight * repeat;
+			if (value > bestValue) {
+				best = index;
+				bestValue = value;
+			}
+		});
+		chosen.push(left.splice(best, 1)[0]);
+	}
+	return chosen;
+}
 /**
-* The last stage: choose the `policy.recall` best of the pool. With a reranker's judgement each
+* The last stage: choose the `policy.recall` best of the pool, spread by `policy.diversity`. With a reranker's judgement each
 * candidate's relevance is mostly that (a candidate it left out counts as 0), and the rest is what
 * retrieval found; without, it is what retrieval found.
 */
 function finishRecall(pool, rerank) {
 	const { policy } = pool.query;
-	return pool.entries.flatMap(({ candidate, fused }) => {
-		const standing = judged(candidate, rerank === void 0 ? fused : RERANK_BLEND * Math.min(1, Math.max(0, rerank.get(candidate.key) ?? 0)) + .30000000000000004 * fused, policy);
-		return standing === void 0 ? [] : [{
+	const standing = pool.entries.flatMap(({ candidate, fused, found }) => {
+		const relevance = rerank === void 0 ? fused : RERANK_BLEND * Math.min(1, Math.max(0, rerank.get(candidate.key) ?? 0)) + .30000000000000004 * fused;
+		const judgement = judged(candidate, relevance, policy);
+		if (judgement === void 0) return [];
+		const why = pool.query.explain === true ? {
+			cues: candidate.cues,
+			...found,
+			...rerank === void 0 ? {} : { rerank: rerank.get(candidate.key) ?? 0 },
+			relevance,
+			importance: candidate.importance,
+			ageDays: candidate.ageDays,
+			...judgement.retention === void 0 ? {} : { retention: judgement.retention },
+			score: judgement.score
+		} : void 0;
+		return [{
 			candidate,
-			...standing
+			relevance,
+			...judgement,
+			why
 		}];
-	}).sort((a, b) => b.score - a.score || b.candidate.recalled.turn - a.candidate.recalled.turn).slice(0, policy.recall).sort((a, b) => a.candidate.recalled.turn - b.candidate.recalled.turn).map(({ candidate, clarity, text }) => ({
+	}).sort((a, b) => b.score - a.score || b.candidate.recalled.turn - a.candidate.recalled.turn);
+	const chosen = diversified(standing, policy.recall, policy.diversity ?? 0);
+	const result = chosen.map(({ candidate, clarity, text, why }) => ({
 		clarity,
 		text,
 		turn: candidate.recalled.turn,
 		...candidate.recalled.at === void 0 ? {} : { at: candidate.recalled.at },
-		source: candidate.recalled.source
+		source: candidate.recalled.source,
+		...why === void 0 ? {} : { why }
 	}));
+	const anchors = chosen.filter((entry) => entry.relevance >= CUE_RELEVANCE);
+	const wanted = anchors.length === 0 ? 0 : Math.max(0, policy.associate ?? 0);
+	if (wanted > 0) {
+		const taken = new Set(chosen.map((entry) => entry.candidate.key));
+		const tied = [...standing.filter((entry) => !chosen.includes(entry)).map((entry) => entry.candidate), ...pool.others].filter((candidate) => !taken.has(candidate.key) && candidate.importance >= ASSOCIABLE_IMPORTANCE).flatMap((candidate) => {
+			const best = anchors.map((anchor) => tie(anchor.candidate.links, candidate.links)).sort((a, b) => b.strength - a.strength)[0];
+			const judgement = best === void 0 || best.strength < STRONG_TIE ? void 0 : judged(candidate, 0, policy);
+			return best === void 0 || judgement === void 0 || judgement.clarity === "vague" ? [] : [{
+				candidate,
+				best,
+				judgement
+			}];
+		}).sort((a, b) => b.best.strength - a.best.strength || b.candidate.importance - a.candidate.importance || b.candidate.recalled.turn - a.candidate.recalled.turn).slice(0, wanted);
+		for (const { candidate, best, judgement } of tied) result.push({
+			clarity: judgement.clarity,
+			text: judgement.text,
+			turn: candidate.recalled.turn,
+			...candidate.recalled.at === void 0 ? {} : { at: candidate.recalled.at },
+			source: candidate.recalled.source,
+			linked: true,
+			...pool.query.explain === true ? { why: {
+				cues: candidate.cues,
+				relevance: 0,
+				importance: candidate.importance,
+				ageDays: candidate.ageDays,
+				...judgement.retention === void 0 ? {} : { retention: judgement.retention },
+				score: judgement.score,
+				linked: {
+					people: best.people,
+					tags: best.tags,
+					place: best.place
+				}
+			} } : {}
+		});
+	}
+	return result.sort((a, b) => a.turn - b.turn);
 }
 /** Remind a character of what the moment calls to mind, in one call: {@link recallPool}, then {@link finishRecall} with the `rerank` evidence if there is any. */
 function recall(source, query, evidence = {}) {
@@ -9091,6 +9501,9 @@ var SqliteSessionStore = class {
 	runTriggers(options) {
 		return runTriggers(this, options);
 	}
+	deliverNotes(notes, clock) {
+		return deliverNotes(this, notes, clock);
+	}
 	lapseNotes(turn, kept) {
 		return this.transaction(() => lapseNotes(this, turn, kept));
 	}
@@ -9169,6 +9582,7 @@ function openSessionStore(location, options = {}) {
 	try {
 		const state = inspect(db);
 		if (state.version === 0 || state.applicationId !== 1146245971) throw new SchemaError(`${location} is not a session database`);
+		if (state.version < LATEST_VERSION && location !== ":memory:") backUpBeforeMigrating(db, location, state.version);
 		migrate(db);
 		return new SqliteSessionStore(db, options.clock ?? systemClock, vectors);
 	} catch (error) {
@@ -9176,6 +9590,24 @@ function openSessionStore(location, options = {}) {
 		throw error;
 	}
 }
+/** Folder, beside the database, holding the copies made before a schema upgrade. */
+const MIGRATION_BACKUP_FOLDER = "migration-backups";
+/** Where the copy of a database as it was at schema `version` is kept. */
+function migrationBackupPath(location, version) {
+	return join(dirname(location), MIGRATION_BACKUP_FOLDER, `schema-${version}.sqlite`);
+}
+/**
+* A released session cannot be rebuilt, so an upgrade starts from a copy that passed the integrity check; one copy per old version is kept.
+* @throws {CorruptDataError} when the database is damaged, before anything is changed.
+*/
+function backUpBeforeMigrating(db, location, version) {
+	const check = db.get("PRAGMA quick_check")?.quick_check;
+	if (check !== "ok") throw new CorruptDataError(`${location} failed its integrity check, so it was not upgraded: ${check ?? "no result"}`);
+	const target = migrationBackupPath(location, version);
+	if (existsSync(target)) return;
+	mkdirSync(dirname(target), { recursive: true });
+	db.run("VACUUM INTO ?", [target]);
+}
 //#endregion
 //#region src/sessions.ts
 const SESSION_DATABASE_FILE = "session.sqlite";
@@ -11157,6 +11589,7 @@ var RoleplayState = class extends Service {
 			edit: (edit, options) => store.edit(edit, options),
 			runTriggers: (options) => store.runTriggers(options),
 			lapseNotes: (turn, kept) => store.lapseNotes(turn, kept),
+			deliverNotes: (notes, clock) => store.deliverNotes(notes, clock),
 			records: (scope) => store.records(scope)
 		};
 		this.sessions.set(key, {
@@ -11192,11 +11625,17 @@ function createCharacterTools(link, characterId) {
 		defineTool({
 			name: "recall_my_memories",
 			description: "Ask yourself what you remember about something: a person, an object, a place or an earlier moment. You get your own version of it, what you took in yourself and what you believe, and what has faded comes back as hazy or not at all. Use it only when you need a memory that the situation does not already give you.",
-			parameters: { about: {
-				type: "string",
-				required: true,
-				description: "What to remember: a name, an object, a topic or a short description of the moment."
-			} },
+			parameters: {
+				about: {
+					type: "string",
+					required: true,
+					description: "What to remember: a name, an object, a topic or a short description of the moment."
+				},
+				person: {
+					type: "string",
+					description: "Only what concerns this person (a name or alias you know): everything you remember of them."
+				}
+			},
 			output: {
 				schema: {
 					type: "array",
@@ -11221,20 +11660,24 @@ function createCharacterTools(link, characterId) {
 				},
 				render: (_args, value) => [{
 					type: "text",
-					text: value.length === 0 ? "You do not remember anything about that." : value.map((entry) => `- (${entry.clarity === "clear" ? "" : entry.clarity === "faded" ? "the details are fuzzy" : "you barely remember"}) ${entry.text}`.replace("- () ", "- ")).join("\n")
+					text: value.length === 0 ? "You do not remember anything about that, and there is nothing more to find: go on with what you know." : value.map((entry) => `- (${entry.clarity === "clear" ? "" : entry.clarity === "faded" ? "the details are fuzzy" : "you barely remember"}) ${entry.text}`.replace("- () ", "- ")).join("\n")
 				}]
 			},
 			isConcurrencySafe: () => false,
 			async execute(args, exec) {
 				const agent = link();
 				const { session, turn, policy } = agent;
+				const who = args.person === void 0 || args.person.trim() === "" ? [] : [...mentioned(args.person, session.characters.list())].filter((id) => id !== characterId);
+				if (args.person !== void 0 && args.person.trim() !== "" && who.length === 0) return [];
+				const situation = who.length === 0 ? args.about : `${args.about} ${args.person}`;
 				return (await session.recallRanked({
 					characterId,
-					situation: args.about,
+					situation,
 					turn,
 					policy,
+					...who.length === 0 ? {} : { about: who },
 					...placeOf(session, characterId)
-				}, exec.signal, await vectorOf(agent, args.about, exec.signal))).map((entry) => ({
+				}, exec.signal, await vectorOf(agent, situation, exec.signal))).map((entry) => ({
 					clarity: entry.clarity,
 					turn: entry.turn,
 					text: entry.text
@@ -11272,7 +11715,7 @@ function createCharacterTools(link, characterId) {
 				},
 				render: (_args, value) => [{
 					type: "text",
-					text: value.length === 0 ? "You know of nothing matching that." : value.map((entry) => `- ${entry.kind}: ${entry.name} (${entry.key})`).join("\n")
+					text: value.length === 0 ? "You know of nothing matching that." : value.map((entry) => `- ${entry.kind}: ${entry.name}`).join("\n")
 				}]
 			},
 			isConcurrencySafe: () => true,
@@ -11383,6 +11826,6 @@ function createCharacterTools(link, characterId) {
 	];
 }
 //#endregion
-export { ACCURACIES, CHARACTER_CONTROLS, CHARACTER_KINDS, CHARACTER_ROLES, CHARACTER_TIERS, CLOCK_MODES, COMPARISONS, CONSOLIDATION_KINDS, CONTAINER_STATES, Config, ConflictError, CorruptDataError, DAY, DAY_PARTS, DEFAULT_MEMORY_POLICY, DEFAULT_SLOTS, EMOTION_VARIABLES, ENGAGEMENT_GRACE, ENGAGEMENT_STATUSES, EXIT_STATES, HOUR, IMPORTANCE_MAX, IMPORTANCE_MIN, INTENT_HORIZONS, INTENT_STATUSES, INTENT_TYPES, ITEM_ACTIONS, InvalidEditError, InvalidMoveError, InvalidValueError, KNOWLEDGE_KINDS, LORE_KINDS, LORE_SUBJECT_KINDS, MAX_LOCATION_FEATURES, MAX_ROUTINE_WINDOWS, MAX_SHOWN, MAX_TRIGGERS, MAX_VARIABLES, MEMBERSHIP_STATUSES, MEMORY_KINDS, MINUTE, NotFoundError, PERCEPTION_MODES, PLACEABLE_KINDS, PLOT_NUDGE_MODES, PLOT_STATUSES, RECALL_ITEM_KINDS, RoleplayState, LATEST_VERSION as SCHEMA_VERSION, SECOND, SESSION_DATABASE_FILE, SLOT_ID, SUMMARY_LEVELS, SchemaError, StateError, THREAD_STATUSES, TIME_CHANGE_KINDS, TRIGGER_NOTE_KINDS, TRIGGER_STATUSES, VARIABLE_KEY, VARIABLE_KINDS, VARIABLE_SUBJECTS, VARIABLE_VISIBILITIES, VISUAL_SUBJECT_KINDS, WEEKDAY_NAMES, addLocalDays, agendaAt, announcements, apply, applyItemPlan, applyRecordsEdit, audienceIds, catchUpPlan, changeItem, changeVariable, characterKey, clarityAt, clockTime, conditionHolds, createCharacterTools, createSession, createSessionStore, createTools, dayPart, deleteSession, denseScore, describeDuration, describeHolder, describeInstant, describeValue, finishRecall, fuseScores, inAudience, inWindow, isSessionId, isTimeZone, itemKey, jitter, judgedStatements, lapseNotes, lintWorld, listSessions, localIso, localTime, locationKey, mentioned, moveCharacter, name, nextOccurrence, nextTimeOfDay, nodeSqliteDriver, occurrenceAt, openSession, openSessionStore, overlap, parseInstant, parseRecordsEdit, parseTimeOfDay, parseTriggerDefinition, planItemChange, planKnownMove, planMove, planVariableChange, poolCandidates, rankGoals, readRecords, readTriggerDefinition, recall, recallCandidates, recallPool, recordsEditSchema, retention, runTriggers, seededRoll, sessionDatabase, sessionFolder, shownVariables, subjectOf, systemClock, systemTimeZone, tokens, triggerReferenceProblems, valueIssue, zonedInstant };
+export { ACCURACIES, CHARACTER_CONTROLS, CHARACTER_KINDS, CHARACTER_ROLES, CHARACTER_TIERS, CLOCK_MODES, COMPARISONS, CONSOLIDATION_KINDS, CONTAINER_STATES, Config, ConflictError, CorruptDataError, DAY, DAY_PARTS, DEFAULT_MEMORY_POLICY, DEFAULT_SLOTS, EMOTION_VARIABLES, ENGAGEMENT_GRACE, ENGAGEMENT_STATUSES, EXIT_STATES, HOUR, IMPORTANCE_MAX, IMPORTANCE_MIN, INTENT_HORIZONS, INTENT_STATUSES, INTENT_TYPES, ITEM_ACTIONS, InvalidEditError, InvalidMoveError, InvalidValueError, KNOWLEDGE_KINDS, LORE_KINDS, LORE_SUBJECT_KINDS, MAX_LOCATION_FEATURES, MAX_ROUTINE_WINDOWS, MAX_SHOWN, MAX_TRIGGERS, MAX_VARIABLES, MEMBERSHIP_STATUSES, MEMORY_KINDS, MIGRATION_BACKUP_FOLDER, MINUTE, NotFoundError, PERCEPTION_MODES, PLACEABLE_KINDS, PLOT_NUDGE_MODES, PLOT_STATUSES, RECALL_ITEM_KINDS, RoleplayState, LATEST_VERSION as SCHEMA_VERSION, SECOND, SELF, SESSION_DATABASE_FILE, SLOT_ID, SUMMARY_LEVELS, SchemaError, StateError, TEMPLATE_KINDS, THREAD_STATUSES, TIME_CHANGE_KINDS, TRIGGER_NOTE_KINDS, TRIGGER_STATUSES, UnwritableError, VARIABLE_KEY, VARIABLE_KINDS, VARIABLE_SUBJECTS, VARIABLE_VISIBILITIES, VISUAL_SUBJECT_KINDS, WEEKDAY_NAMES, addLocalDays, agendaAt, announcements, apply, applyItemPlan, applyRecordsEdit, audienceIds, catchUpPlan, changeItem, changeVariable, characterKey, clarityAt, clockTime, conditionHolds, createCharacterTools, createSession, createSessionStore, createTools, dayPart, deleteSession, deliverNotes, denseScore, describeDuration, describeHolder, describeInstant, describeValue, finishRecall, fuseScores, inAudience, inWindow, isSessionId, isTimeZone, itemKey, jitter, judgedStatements, lapseNotes, lintWorld, listSessions, localIso, localTime, locationKey, mentioned, migrationBackupPath, moveCharacter, name, nextOccurrence, nextTimeOfDay, nodeSqliteDriver, occurrenceAt, openSession, openSessionStore, overlap, parseInstant, parseRecordsEdit, parseTimeOfDay, parseTriggerDefinition, placeholdersOf, planItemChange, planKnownMove, planMove, planVariableChange, poolCandidates, rankGoals, readRecords, readTriggerDefinition, recall, recallCandidates, recallPool, recordsEditSchema, renderWords, retention, runTriggers, seededRoll, sessionDatabase, sessionFolder, shownVariables, subjectOf, systemClock, systemTimeZone, tokens, triggerReferenceProblems, valueIssue, zonedInstant };
 
 //# sourceMappingURL=index.js.map