@dsh-agentic-roleplay/state 0.1.0 → 0.2.1

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";
@@ -1922,9 +1922,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)`]
@@ -2033,6 +2039,7 @@ const MAX_DEPTH = 4;
 const MAX_NODES = 24;
 const MAX_EFFECTS = 6;
 const MAX_TEXT$1 = 1e3;
+const MAX_JUDGED = 300;
 const text = (entry, key) => typeof entry[key] === "string" && entry[key].trim() !== "" ? entry[key].trim() : void 0;
 function parseCondition(value, path, problems, count, depth = 0) {
 	count.nodes += 1;
@@ -2132,6 +2139,17 @@ function parseCondition(value, path, problems, count, depth = 0) {
 				trigger
 			};
 		}
+		case "judged": {
+			const statement = need("text");
+			if (statement !== void 0 && statement.length > MAX_JUDGED) {
+				problems.push(`${path}.text: at most ${MAX_JUDGED} characters`);
+				return;
+			}
+			return statement === void 0 ? void 0 : {
+				type: "judged",
+				text: statement
+			};
+		}
 		case "all":
 		case "any": {
 			if (!Array.isArray(value["conditions"]) || value["conditions"].length === 0) {
@@ -2152,7 +2170,7 @@ function parseCondition(value, path, problems, count, depth = 0) {
 			};
 		}
 		default:
-			problems.push(`${path}.type: one of time, place, variable, item, event, fired, all, any, not`);
+			problems.push(`${path}.type: one of time, place, variable, item, event, fired, judged, all, any, not`);
 			return;
 	}
 }
@@ -2302,6 +2320,7 @@ function conditionProblems(target, condition, path, known) {
 		];
 		case "event": return [];
 		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);
@@ -2338,6 +2357,16 @@ function compare(op, have, want) {
 	if (typeof have === "number" && typeof want === "number") return COMPARE[op](have, want);
 	return op === "ne" ? have !== want : op === "eq" ? have === want : false;
 }
+/** The statements of the `judged` parts of a condition, in order, each once. */
+function judgedStatements(condition) {
+	switch (condition.type) {
+		case "judged": return [condition.text];
+		case "all":
+		case "any": return [...new Set(condition.conditions.flatMap(judgedStatements))];
+		case "not": return judgedStatements(condition.condition);
+		default: return [];
+	}
+}
 function holds(target, condition, clock) {
 	switch (condition.type) {
 		case "time": {
@@ -2375,6 +2404,7 @@ function holds(target, condition, clock) {
 		}
 		case "event": return target.events.list().some((event) => event.tags.includes(condition.tag));
 		case "fired": return (target.triggers.getByKey(condition.trigger)?.fireCount ?? 0) > 0;
+		case "judged": return clock.judged?.(condition.text) ?? false;
 		case "all": return condition.conditions.every((part) => holds(target, part, clock));
 		case "any": return condition.conditions.some((part) => holds(target, part, clock));
 		case "not": return !holds(target, condition.condition, clock);
@@ -5047,11 +5077,12 @@ const isObject = (value) => typeof value === "object" && value !== null && !Arra
 const DEFAULT_MAX_FIRES = 3;
 /** An edit effect, as it is applied at this turn and round: events default to now and to what those in their place saw. */
 function editOf(target, raw, options) {
+	const round = Math.max(1, options.round);
 	const events = Array.isArray(raw["events"]) ? raw["events"].filter(isObject).map((event) => {
 		const where = typeof event["location"] === "string" ? target.locations.list().find((entry) => locationKey(entry) === event["location"])?.id : void 0;
 		if (event["perceived_by"] === "everyone") return {
 			turn: options.turn,
-			round: options.round,
+			round,
 			importance: 3,
 			tags: [],
 			involves: [],
@@ -5067,7 +5098,7 @@ function editOf(target, raw, options) {
 		}));
 		return {
 			turn: options.turn,
-			round: options.round,
+			round,
 			importance: 3,
 			tags: [],
 			involves: [],
@@ -5185,7 +5216,9 @@ 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;
@@ -5316,7 +5349,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);
@@ -5334,24 +5367,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,
@@ -5380,20 +5435,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 }
 	};
 }
 /**
@@ -5404,7 +5464,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([
 		{
@@ -5421,18 +5481,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. */
@@ -5444,26 +5514,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);
+}
 /**
-* The last stage: choose the `policy.recall` best of the pool. With a reranker's judgement each
+* 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, 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 = {}) {
@@ -6716,7 +6889,7 @@ var SqliteItemRepository = class {
 				patch.notable ?? current.notable ? 1 : 0,
 				patch.hidden ?? current.hidden ? 1 : 0,
 				patch.container?.state ?? current.container?.state ?? null,
-				patch.ownerId ?? current.ownerId ?? null,
+				patch.ownerId === void 0 ? current.ownerId ?? null : patch.ownerId,
 				id
 			]);
 			return this.require(id);
@@ -7090,10 +7263,16 @@ var SqliteLocationRepository = class {
 			const features = patch.features === void 0 ? current.features : checkedFeatures(patch.features);
 			const removed = current.features.filter((feature) => !features.some((kept) => kept.key === feature.key));
 			for (const feature of removed) if (this.db.get("SELECT 1 FROM placements WHERE location_id = ? AND feature_key = ?", [id, feature.key]) !== void 0) throw new ConflictError(`feature "${feature.key}" cannot be removed while someone is at it`);
-			this.db.run("UPDATE locations SET name = ?, description = ?, features = ? WHERE id = ?", [
+			const parentId = patch.parentId === void 0 ? current.parentId ?? null : patch.parentId;
+			if (parentId !== null && parentId !== (current.parentId ?? null)) {
+				if (this.get(parentId) === void 0) throw new NotFoundError(`the parent place ${parentId} does not exist`);
+				for (let ancestor = parentId; ancestor !== null; ancestor = this.get(ancestor)?.parentId ?? null) if (ancestor === id) throw new InvalidValueError(`${current.name} cannot be inside itself or a place within it`);
+			}
+			this.db.run("UPDATE locations SET name = ?, description = ?, features = ?, parent_id = ? WHERE id = ?", [
 				name,
 				(patch.description ?? current.description).trim(),
 				toJson(features),
+				parentId,
 				id
 			]);
 			if (name !== current.name) this.renamed(id);
@@ -7621,10 +7800,10 @@ var SqliteMetadataRepository = class {
 //#endregion
 //#region src/sqlite/schema.ts
 /**
-* Migrations are applied in order and never edited once released: a change to
-* the schema is a new entry. Until the first release the schema is still being
-* shaped, so migration 1 is edited in place. Enumerations are spelled out so that
-* a later change to the model cannot alter what an old migration did.
+* Migrations are applied in order and never edited once released (0.1.0 released
+* versions 1 to 6; tests/sqlite/migrate.spec.ts pins them): a change to the schema
+* is a new entry. Enumerations are spelled out so that a later change to the model
+* cannot alter what an old migration did.
 */
 const MIGRATIONS = [
 	{
@@ -9138,6 +9317,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) {
@@ -9145,6 +9325,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";
@@ -11161,11 +11359,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",
@@ -11190,20 +11394,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
@@ -11241,7 +11449,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,
@@ -11352,6 +11560,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, 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, 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, migrationBackupPath, 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 };
 
 //# sourceMappingURL=index.js.map