@snoai/memory 0.0.0-stage → 1.0.1

package/dist/internal/engine/bindings/memory-cli-shared.js

@@ -0,0 +1,84 @@
+import { DEFAULT_IMPORTANCE, DEFAULT_SCOPE } from "../../config/index.js";
+import { MEMORY_CATEGORIES } from "../shared/types.js";
+import { SnoStationMemError } from "../shared/errors.js";
+import { stableHash } from "../shared/utils.js";
+import path from "node:path";
+import { tmpdir } from "node:os";
+import { once } from "node:events";
+import { createInterface } from "node:readline/promises";
+//#region src/engine/bindings/memory-cli-shared.ts
+/** @file memory-cli-shared.ts
+* @purpose Shares memory CLI context, parsing, serialization, and prompt helpers.
+* @boundary Pure CLI helper logic only; command registration lives in dedicated modules.
+*/
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+async function writeImportSpoolRow(writer, row) {
+	if (!writer.write(`${JSON.stringify(row)}\n`)) await once(writer, "drain");
+}
+function createImportSpoolPath(filePath) {
+	const safeName = path.basename(filePath).replace(/[^a-zA-Z0-9._-]/g, "_");
+	return path.join(tmpdir(), `sno-station-mem-import-${process.pid}-${Date.now()}-${safeName}.jsonl`);
+}
+function parseImportSpoolRow(line) {
+	const parsed = JSON.parse(line);
+	if (!isRecord(parsed)) throw new SnoStationMemError("invalid_import_spool", "Internal import spool row was not an object.");
+	const category = parseCategory(typeof parsed.category === "string" ? parsed.category : void 0);
+	if (typeof parsed.id !== "string" || typeof parsed.text !== "string" || !category) throw new SnoStationMemError("invalid_import_spool", "Internal import spool row was missing required fields.");
+	const metadata = isRecord(parsed.metadata) ? parsed.metadata : {};
+	const vector = Array.isArray(parsed.vector) ? parsed.vector : void 0;
+	if (vector && !vector.every((value) => typeof value === "number" && Number.isFinite(value))) throw new SnoStationMemError("invalid_import_spool", "Internal import spool row had an invalid vector.");
+	return {
+		id: parsed.id,
+		text: parsed.text,
+		category,
+		scope: typeof parsed.scope === "string" ? parsed.scope : DEFAULT_SCOPE,
+		importance: typeof parsed.importance === "number" ? parsed.importance : DEFAULT_IMPORTANCE,
+		timestamp: typeof parsed.timestamp === "string" ? parsed.timestamp : void 0,
+		metadata,
+		vector,
+		hash: typeof parsed.hash === "string" ? parsed.hash : stableHash(parsed.text)
+	};
+}
+/** Parses category into the normalized shape used by slash-command registration. */
+function parseCategory(value) {
+	if (!value) return void 0;
+	if (MEMORY_CATEGORIES.includes(value)) return value;
+	throw new SnoStationMemError("invalid_category", `Invalid category: ${value}`);
+}
+/** Implements serialize entry as the local slash-command registration operation. */
+function serializeEntry(entry) {
+	return {
+		id: entry.id,
+		text: entry.text,
+		category: entry.category,
+		scope: entry.projectId,
+		importance: entry.importance,
+		timestamp: new Date(entry.timestamp).toISOString(),
+		metadata: safeParseMetadata(entry.metadata)
+	};
+}
+/** Parses metadata defensively and returns a safe fallback on bad input. */
+function safeParseMetadata(raw) {
+	try {
+		return JSON.parse(raw);
+	} catch {
+		return { _invalidMetadata: raw };
+	}
+}
+/** Implements confirm destructive action as the local slash-command registration operation. */
+async function confirmDestructiveAction(message) {
+	const prompt = createInterface({
+		input: process.stdin,
+		output: process.stdout
+	});
+	try {
+		const answer = (await prompt.question(message)).trim().toLowerCase();
+		return answer === "y" || answer === "yes";
+	} finally {
+		prompt.close();
+	}
+}
+//#endregion
+export { confirmDestructiveAction, createImportSpoolPath, isRecord, parseCategory, parseImportSpoolRow, safeParseMetadata, serializeEntry, writeImportSpoolRow };

package/dist/internal/engine/bindings/memory-forget-tool.d.ts

@@ -0,0 +1,5 @@
+import { resolveAgentAccess } from "./memory-tool-access.js";
+import { ToolContext, ToolResult } from "./memory-tool-schemas.js";
+//#region src/engine/bindings/memory-forget-tool.d.ts
+export declare function executeMemoryForgetTool(ctx: ToolContext, access: ReturnType<typeof resolveAgentAccess>, _toolCallId: unknown, params: unknown): Promise<ToolResult>;
+//#endregion

package/dist/internal/engine/bindings/memory-forget-tool.js

@@ -0,0 +1,66 @@
+import { FORGET_QUERY_MIN_SCORE, MAX_CANDIDATE_POOL_SIZE } from "../../config/index.js";
+import { SnoStationMemError } from "../shared/errors.js";
+import { clamp01, clampInt } from "../shared/utils.js";
+import "../../../memory-tool-dependencies-DjUoelnm.js";
+import { assertAccessibleScopeForTool, isScopeAccessibleForTool, resolveReadableScopesForTool } from "./memory-tool-access.js";
+import { makeResult, runWithAudit } from "./memory-tool-results.js";
+import { forgetParamsSchema } from "./memory-tool-schemas.js";
+import { MEMORY_TELEMETRY_DELETE_REASONS } from "../telemetry/memory-telemetry-types.js";
+//#region src/engine/bindings/memory-forget-tool.ts
+/** @file memory-forget-tool.ts
+* @purpose Registers the memory_forget tool.
+* @boundary One host tool registration and its handler logic.
+*/
+async function executeMemoryForgetTool(ctx, access, _toolCallId, params) {
+	return runWithAudit(ctx, "memory_forget", void 0, async () => {
+		const parsed = forgetParamsSchema.parse(params);
+		if (parsed.suppress_key || parsed.suppress_content) {
+			const projectId = assertAccessibleScopeForTool(ctx.scopePolicy, parsed.scope ?? "", access);
+			const suppression = parsed.suppress_key ? await ctx.store.createMemorySuppression({
+				projectId,
+				subject: parsed.suppress_key.subject,
+				attribute: parsed.suppress_key.attribute,
+				nowMs: Date.now()
+			}) : await ctx.store.createMemorySuppression({
+				projectId,
+				content: parsed.suppress_content ?? "",
+				nowMs: Date.now()
+			});
+			return makeResult(`${suppression.shape} suppression ${suppression.created ? "created" : "already exists"}.`, { suppression });
+		}
+		if (parsed.id) {
+			const target = ctx.store.getById(parsed.id);
+			if (!target) return makeResult(`Memory not found: ${parsed.id}`, {});
+			if (!isScopeAccessibleForTool(ctx.scopePolicy, target.projectId, access)) throw new SnoStationMemError("invalid_scope", `Scope not accessible: ${target.projectId}`);
+			const deleted = await ctx.store.delete(parsed.id, { deleteReason: MEMORY_TELEMETRY_DELETE_REASONS.memoryForget });
+			return makeResult(`Deleted memory: ${parsed.id}`, { deletedCount: deleted });
+		}
+		const scopeFilter = parsed.scope ? [assertAccessibleScopeForTool(ctx.scopePolicy, parsed.scope, access)] : resolveReadableScopesForTool(ctx.scopePolicy, access);
+		const minScore = clamp01(parsed.min_score ?? .8, FORGET_QUERY_MIN_SCORE);
+		const maxDelete = clampInt(parsed.max_delete ?? 10, 1, MAX_CANDIDATE_POOL_SIZE);
+		if (!parsed.scope && scopeFilter.length === 0) return makeResult("No matching memories found to delete.", {});
+		const candidates = (await ctx.retriever.retrieve({
+			query: parsed.query ?? "",
+			limit: maxDelete,
+			...scopeFilter.length > 0 ? { scopeFilter } : {},
+			source: "manual",
+			...ctx.language ? { explicitLocale: ctx.language } : {},
+			excludeInvalidatedBefore: 0
+		})).filter((match) => match.score >= minScore);
+		if (candidates.length === 0) return makeResult("No matching memories found to delete.", {});
+		const ids = Array.from(new Set(candidates.map((candidate) => candidate.entry.id))).slice(0, maxDelete);
+		if (parsed.confirm !== true) return makeResult(`Found ${ids.length} matching memories. Re-run with confirm=true to delete.`, {
+			deletedCount: 0,
+			candidateCount: ids.length,
+			ids,
+			requireConfirm: true
+		}, true);
+		const deletedCount = await ctx.store.deleteMany(ids, { deleteReason: MEMORY_TELEMETRY_DELETE_REASONS.memoryForget });
+		return makeResult(`Deleted ${deletedCount} memories.`, {
+			deletedCount,
+			ids
+		});
+	});
+}
+//#endregion
+export { executeMemoryForgetTool };

package/dist/internal/engine/bindings/memory-list-tool.d.ts

@@ -0,0 +1,5 @@
+import { resolveAgentAccess } from "./memory-tool-access.js";
+import { ToolContext, ToolResult } from "./memory-tool-schemas.js";
+//#region src/engine/bindings/memory-list-tool.d.ts
+export declare function executeMemoryListTool(ctx: ToolContext, access: ReturnType<typeof resolveAgentAccess>, _toolCallId: unknown, params: unknown): Promise<ToolResult>;
+//#endregion

package/dist/internal/engine/bindings/memory-list-tool.js

@@ -0,0 +1,57 @@
+import { MAX_LIST_LIMIT } from "../../config/index.js";
+import { normalizeCategory } from "../shared/types.js";
+import { SnoStationMemError } from "../shared/errors.js";
+import { clampInt } from "../shared/utils.js";
+import { readEstimatedSpendToday } from "../operations/daily-spend-estimator.js";
+import "../../../memory-tool-dependencies-DjUoelnm.js";
+import { assertAccessibleScopeForTool, resolveReadableScopesForTool } from "./memory-tool-access.js";
+import { serializeMemory } from "./memory-tool-formatting.js";
+import { makeResult, runWithAudit } from "./memory-tool-results.js";
+import { listParamsSchema } from "./memory-tool-schemas.js";
+//#region src/engine/bindings/memory-list-tool.ts
+/** @file memory-list-tool.ts
+* @purpose Registers the memory_list tool.
+* @boundary One host tool registration and its handler logic.
+*/
+async function executeMemoryListTool(ctx, access, _toolCallId, params) {
+	return runWithAudit(ctx, "memory_list", void 0, async () => {
+		const parsed = listParamsSchema.parse(params);
+		const limit = clampInt(parsed.limit ?? 50, 1, MAX_LIST_LIMIT);
+		const offset = clampInt(parsed.offset ?? 0, 0, Number.MAX_SAFE_INTEGER);
+		let validatedScope = parsed.scope ? assertAccessibleScopeForTool(ctx.scopePolicy, parsed.scope, access) : void 0;
+		const resolvedScopes = validatedScope ? [] : resolveReadableScopesForTool(ctx.scopePolicy, access);
+		if (!validatedScope) {
+			if (resolvedScopes.length === 0) {
+				const emptyDetails = {
+					count: 0,
+					limit,
+					offset,
+					estimatedSpendTodayUsd: await readEstimatedSpendToday(ctx.stateDir)
+				};
+				return makeResult(JSON.stringify([]), emptyDetails);
+			}
+			const [onlyScope] = resolvedScopes;
+			if (resolvedScopes.length === 1 && !onlyScope) throw new SnoStationMemError("invalid_scope", "No accessible scope available for memory_list.");
+			validatedScope = resolvedScopes.length === 1 ? onlyScope : void 0;
+		}
+		const listOptions = {
+			...validatedScope ? { projectId: validatedScope } : {},
+			...!validatedScope && resolvedScopes.length > 1 ? { projectIdFilter: resolvedScopes } : {},
+			limit,
+			offset,
+			...parsed.category ? { category: normalizeCategory(parsed.category) } : {},
+			...typeof parsed.importance_min === "number" ? { importanceMin: parsed.importance_min } : {}
+		};
+		const serialized = (await ctx.store.list(listOptions)).map((entry) => serializeMemory(entry));
+		const estimatedSpendTodayUsd = await readEstimatedSpendToday(ctx.stateDir);
+		const details = {
+			count: serialized.length,
+			limit,
+			offset,
+			estimatedSpendTodayUsd
+		};
+		return makeResult(JSON.stringify(serialized), details);
+	});
+}
+//#endregion
+export { executeMemoryListTool };

package/dist/internal/engine/bindings/memory-recall-tool.d.ts

@@ -0,0 +1,10 @@
+import { resolveAgentAccess } from "./memory-tool-access.js";
+import { ToolContext, ToolResult } from "./memory-tool-schemas.js";
+//#region src/engine/bindings/memory-recall-tool.d.ts
+export declare function executeMemoryRecallTool(ctx: ToolContext, access: ReturnType<typeof resolveAgentAccess>, _toolCallId: unknown, params: unknown, options: {
+  name: string;
+  label: string;
+  description: string;
+  signal?: AbortSignal;
+}): Promise<ToolResult>;
+//#endregion

package/dist/internal/engine/bindings/memory-recall-tool.js

@@ -0,0 +1,283 @@
+import { MAX_AGGREGATION_RESULT_TOKENS } from "../../config/index.js";
+import { normalizeCategory } from "../shared/types.js";
+import { truncateGraphemes } from "../shared/i18n-text.js";
+import { clamp01, clampInt } from "../shared/utils.js";
+import { formatAtDepth } from "../retrieval/intent-analyzer.js";
+import { t as countTokens } from "../../../memory-tool-dependencies-DjUoelnm.js";
+import { assertAccessibleScopeForTool, resolveReadableScopesForTool } from "./memory-tool-access.js";
+import { episodicEventDate, safeParseMetadata, sanitizeRecalledText, serializeMemory } from "./memory-tool-formatting.js";
+import { makeResult, runWithAudit } from "./memory-tool-results.js";
+import { recallParamsSchema } from "./memory-tool-schemas.js";
+import { i as retrieveForMemoryRecallOrEval, n as packManualRecallRows } from "../../../rem-consumer-retrieval-CR0dtcHR.js";
+import { createLogger, currentLogContext, privateLogReference, withLogContext } from "@snoai/utils/logger";
+import { randomUUID } from "node:crypto";
+//#region src/engine/bindings/memory-recall-tool.ts
+const log = createLogger("sno-station-mem:memory-recall-tool");
+function appendStructuredRecallContent(result) {
+	const count = result.details["count"];
+	const memories = result.details["memories"];
+	const memoryCount = typeof count === "number" ? count : 0;
+	const memoryRows = Array.isArray(memories) ? memories : [];
+	const memoryReferences = Array.from({ length: memoryCount }, (_, index) => {
+		const memory = memoryRows[index];
+		if (typeof memory === "object" && memory !== null && "id" in memory && typeof memory.id === "string" && memory.id.trim().length > 0) return memory.id;
+		return `unknown-memory-${index + 1}`;
+	});
+	return {
+		...result,
+		content: [...result.content, {
+			type: "text",
+			text: JSON.stringify({
+				status: count === 0 ? "no_results" : "ok",
+				count,
+				memories: memoryReferences
+			})
+		}]
+	};
+}
+function makeRecallResult(text, details) {
+	return appendStructuredRecallContent(makeResult(text, details));
+}
+function prependTodoBlock(result, todos) {
+	if (todos.items.length === 0) return result;
+	const lines = [];
+	for (const todo of todos.items) {
+		const description = sanitizeRecalledText(todo.description);
+		const closedAt = todo.closedAt === null ? "unknown" : new Date(todo.closedAt).toISOString();
+		const closeReason = sanitizeRecalledText(todo.closeReason ?? "unknown");
+		const line = todo.status === "open" ? `- [open] ${description}` : `- [${todo.status}] ${description} | closed_at=${closedAt} | close_reason=${closeReason}`;
+		const candidate = `To-dos:\n${[...lines, line].join("\n")}\n... showing ${lines.length + 1} of ${todos.totalCount} to-dos.`;
+		if (countTokens(candidate) > 1e3) break;
+		lines.push(line);
+	}
+	if (todos.totalCount > lines.length) lines.push(`... showing ${lines.length} of ${todos.totalCount} to-dos.`);
+	const text = `To-dos:\n${lines.join("\n")}`;
+	return {
+		...result,
+		content: [{
+			type: "text",
+			text
+		}, ...result.content]
+	};
+}
+async function executeMemoryRecallTool(ctx, access, _toolCallId, params, options) {
+	const raw = typeof params === "object" && params !== null ? params : {};
+	return withLogContext({
+		operation_id: currentLogContext().operation_id ?? randomUUID(),
+		session_reference: ctx.sessionKey,
+		...typeof raw.external_reference === "string" ? {
+			external_reference: raw.external_reference,
+			external_reference_visibility: raw.external_reference_visibility === "public" ? "public" : "private"
+		} : {}
+	}, async () => {
+		const started = performance.now();
+		let budgetRemoved = 0;
+		const retrievalDiagnostics = {};
+		let outcome = "failed";
+		let errorCode;
+		let served = [];
+		try {
+			const output = await runWithAudit(ctx, options.name, void 0, async () => {
+				const parsed = recallParamsSchema.parse(params);
+				packManualRecallRows([], parsed.token_budget);
+				const readsWholePopulation = parsed.aggregation !== void 0;
+				const outputScope = readsWholePopulation ? truncateGraphemes(parsed.scope ?? "global", 256) : parsed.scope ?? "global";
+				const effectiveTopK = 512;
+				const minScore = clamp01(parsed.min_score ?? 0, 0);
+				const scopeFilter = parsed.scope ? [assertAccessibleScopeForTool(ctx.scopePolicy, parsed.scope, access)] : resolveReadableScopesForTool(ctx.scopePolicy, access);
+				if (scopeFilter.length === 0) return makeRecallResult("No relevant memories found.", {
+					count: 0,
+					memories: [],
+					scope: outputScope
+				});
+				const todos = ctx.store.listTodos({
+					projectIdFilter: scopeFilter,
+					includeHistory: parsed.include_history ?? false,
+					limit: 50
+				});
+				const withTodoBlock = (result) => prependTodoBlock(result, todos);
+				const category = parsed.category ? normalizeCategory(parsed.category) : void 0;
+				const retrieved = await retrieveForMemoryRecallOrEval(ctx.retriever, {
+					diagnostics: retrievalDiagnostics,
+					signal: options.signal,
+					query: parsed.query,
+					limit: effectiveTopK,
+					scopeFilter,
+					category,
+					includeRefused: parsed.include_refused ?? true,
+					aggregation: parsed.aggregation,
+					...parsed.include_history ? { facetPolicy: "include-history" } : {},
+					nowMs: Date.now(),
+					...ctx.language ? { explicitLocale: ctx.language } : {}
+				});
+				const aggregationIncomplete = readsWholePopulation && retrieved.some((result) => result.aggregationIncomplete === true);
+				const filtered = parsed.aggregation ? retrieved : retrieved.filter((result) => result.score >= minScore);
+				if (filtered.length === 0 && (readsWholePopulation || !ctx.recallSession)) {
+					if (parsed.aggregation) return withTodoBlock(makeRecallResult(`<relevant-memories>\n<recall-result scope-row-count="${aggregationIncomplete ? "unknown" : "0"}" returned-count="0" population-complete="${!aggregationIncomplete}" truncated="${aggregationIncomplete}" />\nFound 0 memories.\n</relevant-memories>`, {
+						count: 0,
+						memories: [],
+						scope: outputScope,
+						...!aggregationIncomplete && { scopeRowCount: 0 },
+						populationComplete: !aggregationIncomplete,
+						truncated: aggregationIncomplete
+					}));
+					return withTodoBlock(makeRecallResult("No relevant memories found.", {
+						count: 0,
+						memories: [],
+						scope: outputScope
+					}));
+				}
+				const boosted = filtered;
+				const observedScopeRowCount = readsWholePopulation && !aggregationIncomplete ? boosted[0]?.scopeRowCount : void 0;
+				const completeReduction = parsed.aggregation !== void 0 && parsed.aggregation.operation !== "evidence";
+				const limitedResults = readsWholePopulation ? completeReduction ? boosted.slice(0, 1) : boosted : boosted;
+				const requestedRows = readsWholePopulation || parsed.top_k === void 0 ? limitedResults : limitedResults.slice(0, clampInt(parsed.top_k, 1, 512));
+				const session = readsWholePopulation ? void 0 : ctx.recallSession;
+				const history = session ? session.history.get(session.sessionId) : void 0;
+				const unseenRows = session ? requestedRows.filter((row) => history?.get(row.entry.id) !== session.turn) : requestedRows;
+				const alreadyServedCount = requestedRows.length - unseenRows.length;
+				const packedRecall = readsWholePopulation ? {
+					rows: requestedRows,
+					budget_used: 0,
+					dropped_count: 0
+				} : packManualRecallRows(unseenRows, parsed.token_budget);
+				const packedResults = packedRecall.rows;
+				budgetRemoved = packedRecall.dropped_count;
+				const truncated = aggregationIncomplete || packedRecall.dropped_count > 0 || !completeReduction && (observedScopeRowCount !== void 0 && observedScopeRowCount > packedResults.length || boosted.length > packedResults.length);
+				if (!readsWholePopulation) for (const r of packedResults) try {
+					await ctx.store.updateMetadata(r.entry.id, {
+						suppressed_until_ms: void 0,
+						bad_recall_count: 0
+					});
+				} catch {}
+				let aggregationTextTruncated = false;
+				let displayResults = packedResults.map((result) => {
+					const sourceText = result.snippet?.trim() ? result.snippet : result.entry.text;
+					const displayText = readsWholePopulation ? ctx.store.embedder.truncateToTokens(sourceText, 512) : sourceText;
+					if (displayText !== sourceText) aggregationTextTruncated = true;
+					return {
+						...result,
+						entry: {
+							...result.entry,
+							text: displayText
+						}
+					};
+				});
+				const render = (results, outputTruncated, populationTruncated) => {
+					const populationComplete = !aggregationIncomplete && (completeReduction || !populationTruncated);
+					const text = results.map((result, i) => formatAtDepth(result.entry, result.score, i, {
+						bm25Hit: result.sources?.bm25 !== void 0,
+						reranked: result.sources?.reranked !== void 0,
+						sanitize: sanitizeRecalledText,
+						eventDate: episodicEventDate(result.entry)
+					})).join("\n");
+					const serialized = results.map((result) => {
+						const base = serializeMemory(result.entry);
+						if (parsed.include_metadata && !readsWholePopulation) {
+							const metadata = safeParseMetadata(result.entry.metadata);
+							return {
+								...base,
+								metadata: {
+									...typeof metadata === "object" && metadata !== null ? metadata : {},
+									id: result.entry.id
+								}
+							};
+						}
+						return base;
+					});
+					const aggregationSummary = readsWholePopulation ? `<recall-result scope-row-count="${observedScopeRowCount ?? "unknown"}" returned-count="${results.length}" population-complete="${populationComplete}" truncated="${outputTruncated}" />\n` : "";
+					return withTodoBlock(appendStructuredRecallContent(makeResult(`<relevant-memories>\n${aggregationSummary}Found ${results.length} memories:\n\n${text}\n</relevant-memories>` + (alreadyServedCount > 0 ? `\n${alreadyServedCount} memories already shown in this turn were omitted.` : ""), {
+						count: serialized.length,
+						scope: outputScope,
+						memories: serialized,
+						...session && { already_served_count: alreadyServedCount },
+						...!readsWholePopulation && {
+							budget_used: packedRecall.budget_used,
+							dropped_count: packedRecall.dropped_count
+						},
+						...readsWholePopulation && {
+							...observedScopeRowCount !== void 0 && { scopeRowCount: observedScopeRowCount },
+							populationComplete,
+							truncated: outputTruncated
+						}
+					})));
+				};
+				const consumerTokens = (candidate) => Math.max(countTokens(candidate.content.map((part) => part.text).join("\n")), countTokens(JSON.stringify(candidate.details["memories"] ?? [])));
+				let outputTruncated = truncated || aggregationTextTruncated;
+				let populationTruncated = truncated;
+				let result = render(displayResults, outputTruncated, populationTruncated);
+				if (readsWholePopulation) {
+					const textTokens = countTokens(result.content.map((part) => part.text).join("\n"));
+					const memoriesTokens = countTokens(JSON.stringify(result.details["memories"] ?? []));
+					const over = Math.max(textTokens, memoriesTokens) > MAX_AGGREGATION_RESULT_TOKENS;
+					log[over ? "warn" : "debug"]("Aggregation population budget checked", {
+						rows: displayResults.length,
+						textTokens,
+						memoriesTokens,
+						budget: MAX_AGGREGATION_RESULT_TOKENS,
+						over_budget: over
+					}, {
+						event_name: "memory.recall.budget.checked",
+						file: "packages/memory/src/engine/bindings/memory-recall-tool.ts",
+						function: "execute",
+						site_id: "memory.recall.budget.checked"
+					});
+				}
+				if (readsWholePopulation && consumerTokens(result) > 32768) {
+					let lowerBound = 0;
+					let upperBound = displayResults.length;
+					while (lowerBound < upperBound) {
+						const midpoint = Math.ceil((lowerBound + upperBound) / 2);
+						if (consumerTokens(render(displayResults.slice(0, midpoint), true, true)) <= 32768) lowerBound = midpoint;
+						else upperBound = midpoint - 1;
+					}
+					budgetRemoved += displayResults.length - lowerBound;
+					displayResults = displayResults.slice(0, lowerBound);
+					outputTruncated = true;
+					populationTruncated = true;
+					result = render(displayResults, outputTruncated, populationTruncated);
+				}
+				if (readsWholePopulation && consumerTokens(result) > 32768) {
+					const populationComplete = !aggregationIncomplete && completeReduction;
+					return withTodoBlock(makeRecallResult(`<relevant-memories>\n<recall-result scope-row-count="${observedScopeRowCount ?? "unknown"}" returned-count="0" population-complete="${populationComplete}" truncated="true" />\nFound 0 memories.\n</relevant-memories>`, {
+						count: 0,
+						memories: [],
+						...observedScopeRowCount !== void 0 && { scopeRowCount: observedScopeRowCount },
+						populationComplete,
+						truncated: true
+					}));
+				}
+				return result;
+			});
+			const memories = output.details["memories"];
+			served = Array.isArray(memories) ? memories.flatMap((row) => typeof row === "object" && row !== null && "id" in row && typeof row.id === "string" ? [row.id] : []) : [];
+			errorCode = output.details["errorCode"];
+			if (output.details["resultStatus"] === "skipped") outcome = "refused";
+			else if (output.isError) outcome = "failed";
+			else outcome = served.length ? "success" : "empty_success";
+			return output;
+		} finally {
+			log[outcome === "failed" ? "error" : "info"]("Memory recall completed", {
+				outcome,
+				code: errorCode,
+				duration_ms: performance.now() - started,
+				store_reference: privateLogReference(ctx.store.dbPath),
+				served_ids: served.slice(0, 128),
+				served_count: served.length,
+				ids_truncated: served.length > 128,
+				token_budget_removed_count: budgetRemoved,
+				retired_closed_removed_count: retrievalDiagnostics.retired_closed_removed_count ?? "unavailable",
+				sql_excluded_count: "unavailable",
+				sql_excluded_reason: "query_does_not_report_excluded_rows",
+				external_reference: currentLogContext().external_reference
+			}, {
+				event_name: "memory.recall.completed",
+				file: "packages/memory/src/engine/bindings/memory-recall-tool.ts",
+				function: "execute",
+				site_id: "memory.recall.completed"
+			});
+		}
+	});
+}
+//#endregion
+export { executeMemoryRecallTool };

package/dist/internal/engine/bindings/memory-reflection-resolve-tool.d.ts

@@ -0,0 +1,5 @@
+import { resolveAgentAccess } from "./memory-tool-access.js";
+import { ToolContext, ToolResult } from "./memory-tool-schemas.js";
+//#region src/engine/bindings/memory-reflection-resolve-tool.d.ts
+export declare function executeMemoryReflectionResolveTool(ctx: ToolContext, access: ReturnType<typeof resolveAgentAccess>, _toolCallId: unknown, params: unknown): Promise<ToolResult>;
+//#endregion