@snoai/memory 0.0.0-stage → 1.0.1

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

@@ -0,0 +1,150 @@
+import { 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 { t as parseReflectionMetadata } from "../../../entry-metadata-parser-BIVSMCIk.js";
+import { z } from "zod";
+//#region src/engine/bindings/memory-reflection-resolve-tool.ts
+/** @file memory-reflection-resolve-tool.ts
+* @purpose Registers the memory_reflection_resolve tool.
+* @boundary Marks reflection items resolved so they stop participating in reflection recall.
+*/
+const REFLECTION_ITEM_TYPE = "memory-reflection-item";
+/** Bounded scan ceiling for query-mode candidate discovery. */
+const REFLECTION_SCAN_LIMIT = 240;
+const resolveParamsSchema = z.object({
+	memoryId: z.string().trim().min(1).optional(),
+	query: z.string().trim().min(1).optional(),
+	scope: z.string().optional(),
+	dryRun: z.boolean().optional(),
+	note: z.string().optional(),
+	limit: z.number().int().optional()
+});
+function isUnresolvedReflectionItem(entry) {
+	const metadata = parseReflectionMetadata(entry.metadata);
+	return metadata.type === REFLECTION_ITEM_TYPE && metadata.resolvedAt === void 0;
+}
+function describeCandidate(entry) {
+	const metadata = parseReflectionMetadata(entry.metadata);
+	return {
+		id: entry.id,
+		itemKind: typeof metadata.itemKind === "string" ? metadata.itemKind : "item",
+		scope: entry.projectId,
+		text: entry.text.replace(/\s+/g, " ").trim().slice(0, 180)
+	};
+}
+/** Lexical relevance: count of distinct query tokens present in the entry text. */
+function lexicalScore(text, queryTokens) {
+	const lower = text.toLowerCase();
+	let score = 0;
+	for (const token of queryTokens) if (lower.includes(token)) score += 1;
+	return score;
+}
+async function resolveById(ctx, access, memoryId, options) {
+	const entry = ctx.store.getById(memoryId);
+	if (!entry) return makeResult(`Memory not found: ${memoryId}`, {
+		error: "not_found",
+		memoryId
+	}, true);
+	const metadata = parseReflectionMetadata(entry.metadata);
+	if (metadata.type !== REFLECTION_ITEM_TYPE) return makeResult(`Memory ${entry.id} is not a reflection item.`, {
+		error: "not_reflection_item",
+		memoryId: entry.id
+	}, true);
+	if (!isScopeAccessibleForTool(ctx.scopePolicy, entry.projectId, access)) return makeResult(`Access denied to scope: ${entry.projectId}`, {
+		error: "scope_access_denied",
+		scope: entry.projectId
+	}, true);
+	if (options.dryRun) {
+		if (metadata.resolvedAt !== void 0) return makeResult(`Reflection item already resolved: ${entry.id}`, {
+			action: "already_resolved",
+			memoryId: entry.id
+		});
+		return makeResult(`Reflection resolve preview (no changes): ${entry.id}`, {
+			action: "preview",
+			candidate: describeCandidate(entry)
+		});
+	}
+	switch (await ctx.store.resolveReflectionItem(entry.id, {
+		writerAuthority: "offline-family",
+		resolvedAt: Date.now(),
+		...access.agentId ? { resolvedBy: access.agentId } : {},
+		...options.note ? { note: options.note } : {}
+	})) {
+		case "resolved":
+			ctx.clearReflectionSliceCache?.();
+			return makeResult(`Resolved reflection item: ${entry.id}`, {
+				action: "resolved",
+				memoryId: entry.id
+			});
+		case "already_resolved": return makeResult(`Reflection item already resolved: ${entry.id}`, {
+			action: "already_resolved",
+			memoryId: entry.id
+		});
+		case "not_found": return makeResult(`Memory not found: ${entry.id}`, {
+			error: "not_found",
+			memoryId: entry.id
+		}, true);
+		case "not_reflection_item": return makeResult(`Memory ${entry.id} is not a reflection item.`, {
+			error: "not_reflection_item",
+			memoryId: entry.id
+		}, true);
+	}
+}
+async function resolveByQuery(ctx, access, query, options) {
+	if (options.projectIdFilter.length === 0) return makeResult("No accessible scopes.", {
+		action: "preview",
+		candidates: []
+	});
+	const unresolved = (await ctx.store.listReflectionItems({
+		projectIdFilter: options.projectIdFilter,
+		limit: REFLECTION_SCAN_LIMIT,
+		unresolvedOnly: true
+	})).filter(isUnresolvedReflectionItem);
+	if (unresolved.length === 0) return makeResult("No unresolved reflection items found.", {
+		action: "preview",
+		candidates: []
+	});
+	const queryTokens = query.toLowerCase().split(/[^\p{L}\p{N}]+/u).filter(Boolean);
+	const ranked = unresolved.map((entry, index) => ({
+		entry,
+		index,
+		score: lexicalScore(entry.text, queryTokens)
+	})).sort((a, b) => b.score - a.score || a.index - b.index).slice(0, options.limit).map((ranking) => ranking.entry);
+	if (options.dryRun) return makeResult(`Reflection resolve preview: ${ranked.length} unresolved item(s). No changes made.`, {
+		action: "preview",
+		candidates: ranked.map((entry) => describeCandidate(entry))
+	});
+	const resolvedIds = [];
+	for (const entry of ranked) if (await ctx.store.resolveReflectionItem(entry.id, {
+		writerAuthority: "offline-family",
+		resolvedAt: Date.now(),
+		...access.agentId ? { resolvedBy: access.agentId } : {},
+		...options.note ? { note: options.note } : {}
+	}) === "resolved") resolvedIds.push(entry.id);
+	if (resolvedIds.length > 0) ctx.clearReflectionSliceCache?.();
+	return makeResult(`Resolved ${resolvedIds.length} reflection item(s).`, {
+		action: "resolved",
+		resolvedIds
+	});
+}
+async function executeMemoryReflectionResolveTool(ctx, access, _toolCallId, params) {
+	return runWithAudit(ctx, "memory_reflection_resolve", void 0, async () => {
+		const parsed = resolveParamsSchema.parse(params);
+		if (!parsed.memoryId && !parsed.query) return makeResult("Provide memoryId or query.", { error: "missing_selector" }, true);
+		if (parsed.memoryId && parsed.query) return makeResult("Provide only one of memoryId or query.", { error: "ambiguous_selector" }, true);
+		if (parsed.memoryId) return resolveById(ctx, access, parsed.memoryId, {
+			dryRun: parsed.dryRun ?? false,
+			note: parsed.note
+		});
+		const scopeFilter = parsed.scope ? [assertAccessibleScopeForTool(ctx.scopePolicy, parsed.scope, access)] : resolveReadableScopesForTool(ctx.scopePolicy, access);
+		return resolveByQuery(ctx, access, parsed.query ?? "", {
+			projectIdFilter: scopeFilter,
+			dryRun: parsed.dryRun ?? true,
+			note: parsed.note,
+			limit: clampInt(parsed.limit ?? 5, 1, 20)
+		});
+	});
+}
+//#endregion
+export { executeMemoryReflectionResolveTool };

package/dist/internal/engine/bindings/memory-stats-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-stats-tool.d.ts
+export declare function executeMemoryStatsTool(ctx: ToolContext, access: ReturnType<typeof resolveAgentAccess>, _toolCallId: unknown, params: unknown): Promise<ToolResult>;
+//#endregion

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

@@ -0,0 +1,43 @@
+import { i as isSystemBypassId } from "../../../memory-scope-policy-DICSCURA.js";
+import { readEstimatedSpendToday } from "../operations/daily-spend-estimator.js";
+import "../../../memory-tool-dependencies-DjUoelnm.js";
+import { assertAccessibleScopeForTool, getStoreScopeFilterForTool, resolveReadableScopesForTool } from "./memory-tool-access.js";
+import { makeResult, runWithAudit } from "./memory-tool-results.js";
+import { statsParamsSchema } from "./memory-tool-schemas.js";
+//#region src/engine/bindings/memory-stats-tool.ts
+/** @file memory-stats-tool.ts
+* @purpose Registers the memory_stats tool.
+* @boundary One host tool registration and its handler logic.
+*/
+async function executeMemoryStatsTool(ctx, access, _toolCallId, params) {
+	return runWithAudit(ctx, "memory_stats", void 0, async () => {
+		const parsed = statsParamsSchema.parse(params);
+		const requestedScopes = parsed.scope ? assertAccessibleScopeForTool(ctx.scopePolicy, parsed.scope, access) : resolveReadableScopesForTool(ctx.scopePolicy, access);
+		const scopeFilter = Array.isArray(requestedScopes) ? requestedScopes : [requestedScopes];
+		const useUnfiltered = !parsed.scope && isSystemBypassId(access.agentId) && getStoreScopeFilterForTool(ctx.scopePolicy, access) === void 0;
+		let total = 0;
+		const projectBreakdown = {};
+		const categoryBreakdown = {};
+		if (useUnfiltered) {
+			const allStats = await ctx.store.stats();
+			total = allStats.total;
+			Object.assign(projectBreakdown, allStats.projectBreakdown);
+			Object.assign(categoryBreakdown, allStats.categoryBreakdown);
+		} else for (const scope of scopeFilter) {
+			const scoped = await ctx.store.stats(scope);
+			total += scoped.total;
+			for (const [key, value] of Object.entries(scoped.projectBreakdown)) projectBreakdown[key] = (projectBreakdown[key] ?? 0) + value;
+			for (const [key, value] of Object.entries(scoped.categoryBreakdown)) categoryBreakdown[key] = (categoryBreakdown[key] ?? 0) + value;
+		}
+		const estimatedSpendTodayUsd = await readEstimatedSpendToday(ctx.stateDir);
+		const payload = {
+			total,
+			scopeBreakdown: projectBreakdown,
+			categoryBreakdown,
+			estimatedSpendTodayUsd
+		};
+		return makeResult(JSON.stringify(payload), payload);
+	});
+}
+//#endregion
+export { executeMemoryStatsTool };

package/dist/internal/engine/bindings/memory-store-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-store-tool.d.ts
+export declare function executeMemoryStoreTool(ctx: ToolContext, access: ReturnType<typeof resolveAgentAccess>, _toolCallId: unknown, params: unknown): Promise<ToolResult>;
+//#endregion

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

@@ -0,0 +1,165 @@
+import { DEFAULT_IMPORTANCE } from "../../config/index.js";
+import "../i18n/locales.js";
+import { normalizeCategory } from "../shared/types.js";
+import { clamp01, stableHash } from "../shared/utils.js";
+import { a as detectCategory } from "../../../capture-policy-detector-DaMfy9CZ.js";
+import { stripEnvelopeMetadata } from "../extraction/extraction-text-sanitizer.js";
+import { a as serializeIntervalMetadata, o as resolveMemoryDate } from "../../../memory-temporality-classifier-BUjXG5o7.js";
+import { t as appendAuditEntry } from "../../../runtime-audit-log-BCeujlEp.js";
+import "../../../memory-tool-dependencies-DjUoelnm.js";
+import { assertAccessibleScopeForTool, getDefaultScopeForTool } from "./memory-tool-access.js";
+import { makeResult, runWithAudit } from "./memory-tool-results.js";
+import { storeParamsSchema } from "./memory-tool-schemas.js";
+import { n as createRetireByNameRunBudget, r as runProfileSectionUpdate } from "../../../profile-section-writer-BhGKPBjw.js";
+//#region src/engine/bindings/memory-store-tool.ts
+/** @file memory-store-tool.ts
+* @purpose Registers the memory_store tool.
+* @boundary One host tool registration and its handler logic.
+*/
+function resolveStoreScope(parsed, ctx, access) {
+	if (parsed.scope) return assertAccessibleScopeForTool(ctx.scopePolicy, parsed.scope, access);
+	return getDefaultScopeForTool(ctx.scopePolicy, access);
+}
+function auditEnvelopeStrip(ctx, original, stripped) {
+	if (stripped.length === original.length) return;
+	appendAuditEntry(ctx.stateDir, {
+		event: "envelope_strip",
+		tool: "memory_store",
+		resultStatus: "ok",
+		decision: "stripped",
+		details: {
+			beforeChars: original.length,
+			afterChars: stripped.length
+		}
+	});
+}
+function rejectContentIfNeeded(stripped) {
+	if (stripped.trim()) return void 0;
+	return makeResult("Skipped: content is purely envelope metadata with no extractable memory.", { resultStatus: "skipped" });
+}
+function resolveStoreCategory(parsed, stripped, ctx) {
+	const explicitCategory = parsed.category ? normalizeCategory(parsed.category) : void 0;
+	if (explicitCategory) return explicitCategory;
+	const detectedCategory = detectCategory(stripped, { explicitLocale: ctx.language });
+	if (detectedCategory === "lesson") return "episodic";
+	if (detectedCategory) return detectedCategory;
+	appendAuditEntry(ctx.stateDir, {
+		event: "tool_call",
+		tool: "memory_store",
+		resultStatus: "ok",
+		decision: "category_fallback_episodic",
+		details: { chars: stripped.length }
+	});
+	return "episodic";
+}
+function buildStoreMetadata(parsed, category, dateResolution) {
+	const callerValidFrom = normalizeCallerValidFrom(parsed.metadata?.["valid_from"]);
+	const temporalMetadata = serializeIntervalMetadata(category, dateResolution.interval);
+	return {
+		...parsed.metadata ?? {},
+		source: "manual",
+		memory_category: category,
+		...temporalMetadata,
+		...callerValidFrom === void 0 ? {} : { valid_from: callerValidFrom }
+	};
+}
+function normalizeCallerValidFrom(value) {
+	if (typeof value === "number") return Number.isFinite(value) && value > 0 ? Math.floor(value) : void 0;
+	if (typeof value !== "string" || value.trim().length === 0) return void 0;
+	const trimmed = value.trim();
+	const numeric = Number(trimmed);
+	const parsed = Number.isFinite(numeric) ? numeric : Date.parse(trimmed);
+	return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : void 0;
+}
+function metadataStringValue(metadata, key) {
+	const value = metadata?.[key];
+	return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+async function executeMemoryStore(ctx, access, params) {
+	const parsed = storeParamsSchema.parse(params);
+	const scope = resolveStoreScope(parsed, ctx, access);
+	const importance = clamp01(parsed.importance ?? .7, DEFAULT_IMPORTANCE);
+	const stripped = stripEnvelopeMetadata(parsed.content);
+	auditEnvelopeStrip(ctx, parsed.content, stripped);
+	const rejected = rejectContentIfNeeded(stripped);
+	if (rejected) return rejected;
+	const category = resolveStoreCategory(parsed, stripped, ctx);
+	if (!category) return makeResult("Skipped: content has no unambiguous memory category.", { resultStatus: "skipped" });
+	const hash = stableHash(stripped);
+	const duplicate = ctx.store.findByContentHash(hash, scope);
+	if (duplicate) return makeResult(`Memory already exists: ${duplicate.id}`, {
+		id: duplicate.id,
+		scope
+	});
+	if (category === "profile") {
+		const sectionName = metadataStringValue(parsed.metadata, "section_name");
+		if (!sectionName) return makeResult("Rejected: memory_store profile writes require metadata.section_name.", {
+			resultStatus: "rejected",
+			category
+		}, true);
+		const at = ctx.sessionTimestamp ?? Date.now();
+		const callerValidFrom = normalizeCallerValidFrom(parsed.metadata?.["valid_from"]);
+		const retireByNameBudget = createRetireByNameRunBudget(6e4);
+		const result = await runProfileSectionUpdate({
+			scope,
+			sectionName,
+			topic: metadataStringValue(parsed.metadata, "topic"),
+			newAssertion: stripped,
+			evidence: stripped,
+			source: {
+				source: "manual",
+				messageId: `manual:${hash}`,
+				agentId: access.agentId
+			},
+			...callerValidFrom === void 0 ? {} : { metadataPatch: { valid_from: callerValidFrom } },
+			store: ctx.store,
+			...ctx.profileToolLlm ? { llm: ctx.profileToolLlm } : {},
+			...ctx.llmRouting ? { routing: ctx.llmRouting } : {},
+			at,
+			timeoutMs: 6e4,
+			retireByNameBudget
+		});
+		if (!result.rowId) return makeResult("Rejected: profile memory was not stored because the active-task assertion could not be applied.", {
+			resultStatus: "rejected",
+			category,
+			profileOutcome: result.outcome
+		}, true);
+		return makeResult(`Stored profile memory ${result.rowId}`, {
+			id: result.rowId,
+			scope,
+			category,
+			profileOutcome: result.outcome
+		});
+	}
+	const dateResolution = await resolveMemoryDate({
+		text: stripped,
+		sessionTimestamp: ctx.sessionTimestamp,
+		sessionTimezone: ctx.sessionTimezone,
+		locale: ctx.language ?? "en",
+		llm: ctx.profileToolLlm,
+		routing: ctx.llmRouting
+	});
+	const stored = await ctx.store.store({
+		offlineFamily: true,
+		text: stripped,
+		category,
+		projectId: scope,
+		importance,
+		metadata: JSON.stringify({
+			...buildStoreMetadata(parsed, category, dateResolution),
+			writer_agent_id: access.agentId
+		}),
+		...dateResolution.timestamp === void 0 ? {} : { timestamp: dateResolution.timestamp },
+		timezone: dateResolution.timezone
+	});
+	return makeResult(`Stored memory ${stored.id}`, {
+		id: stored.id,
+		scope,
+		category: stored.category
+	});
+}
+async function executeMemoryStoreTool(ctx, access, _toolCallId, params) {
+	return runWithAudit(ctx, "memory_store", void 0, () => executeMemoryStore(ctx, access, params));
+}
+//#endregion
+export { executeMemoryStoreTool };

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

@@ -0,0 +1,16 @@
+import { t as MemoryScopePolicy } from "../../../memory-scope-policy-1gg5QlWZ.js";
+import "../../../memory-tool-dependencies-CatGzI9R.js";
+//#region src/engine/bindings/memory-tool-access.d.ts
+export declare function assertAccessibleScope(scopePolicy: MemoryScopePolicy, scope: string, agentId?: string): string;
+export declare function resolveAgentId(runtimeAgentId: unknown, fallback?: string): string | undefined;
+export type ResolvedAgentAccess = {
+  agentId?: string;
+};
+export declare function resolveAgentAccess(runtimeAgentId: unknown, fallback?: string): ResolvedAgentAccess;
+export declare function hasMissingToolIdentity(access: ResolvedAgentAccess): boolean;
+export declare function assertAccessibleScopeForTool(scopePolicy: MemoryScopePolicy, scope: string, access: ResolvedAgentAccess): string;
+export declare function resolveReadableScopesForTool(scopePolicy: MemoryScopePolicy, access: ResolvedAgentAccess): string[];
+export declare function isScopeAccessibleForTool(scopePolicy: MemoryScopePolicy, scope: string, access: ResolvedAgentAccess): boolean;
+export declare function getDefaultScopeForTool(scopePolicy: MemoryScopePolicy, access: ResolvedAgentAccess): string;
+export declare function getStoreScopeFilterForTool(scopePolicy: MemoryScopePolicy, access: ResolvedAgentAccess): string[] | undefined;
+//#endregion

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

@@ -0,0 +1,46 @@
+import { SnoStationMemError } from "../shared/errors.js";
+import "../../../memory-tool-dependencies-DjUoelnm.js";
+//#region src/engine/bindings/memory-tool-access.ts
+function assertAccessibleScope(scopePolicy, scope, agentId) {
+	const normalized = scope.trim();
+	if (!scopePolicy.validateScope(normalized) || !scopePolicy.isAccessible(normalized, agentId)) throw new SnoStationMemError("invalid_scope", `Scope not accessible: ${normalized}`);
+	return normalized;
+}
+function resolveAgentId(runtimeAgentId, fallback) {
+	/** Treats literal "undefined" as absent because some host contexts serialize missing ids. */
+	const normalize = (value) => {
+		if (typeof value !== "string") return void 0;
+		const normalized = value.trim();
+		if (!normalized || normalized === "undefined") return;
+		return normalized;
+	};
+	return normalize(runtimeAgentId) ?? normalize(fallback);
+}
+function resolveAgentAccess(runtimeAgentId, fallback) {
+	return { agentId: resolveAgentId(runtimeAgentId, fallback) };
+}
+function hasMissingToolIdentity(access) {
+	return access.agentId === void 0;
+}
+function assertAccessibleScopeForTool(scopePolicy, scope, access) {
+	if (hasMissingToolIdentity(access)) throw new SnoStationMemError("invalid_scope", `Scope not accessible: ${scope.trim()}`);
+	return assertAccessibleScope(scopePolicy, scope, access.agentId);
+}
+function resolveReadableScopesForTool(scopePolicy, access) {
+	if (hasMissingToolIdentity(access)) return [];
+	return scopePolicy.resolveAgentScopes(access.agentId);
+}
+function isScopeAccessibleForTool(scopePolicy, scope, access) {
+	if (hasMissingToolIdentity(access)) return false;
+	return scopePolicy.isAccessible(scope, access.agentId);
+}
+function getDefaultScopeForTool(scopePolicy, access) {
+	if (hasMissingToolIdentity(access)) throw new SnoStationMemError("invalid_scope", "No accessible scope available for memory_store.");
+	return assertAccessibleScope(scopePolicy, scopePolicy.getDefaultScope(access.agentId), access.agentId);
+}
+function getStoreScopeFilterForTool(scopePolicy, access) {
+	if (hasMissingToolIdentity(access)) return [];
+	return scopePolicy.getScopeFilter?.(access.agentId);
+}
+//#endregion
+export { assertAccessibleScope, assertAccessibleScopeForTool, getDefaultScopeForTool, getStoreScopeFilterForTool, hasMissingToolIdentity, isScopeAccessibleForTool, resolveAgentAccess, resolveAgentId, resolveReadableScopesForTool };

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

@@ -0,0 +1,62 @@
+//#region src/engine/bindings/memory-tool-formatting.d.ts
+export declare function sanitizeRecalledText(text: string): string;
+export declare function safeParseMetadata(raw: string): unknown;
+export declare function parseEntryMetadata(entry: {
+  metadata?: string;
+}): Record<string, unknown>;
+/**
+ * Display the resolved event precision; unresolved text never inherits a record timestamp.
+ *
+ * Keyed on whether the claim has a resolved date, never on `kind`. `kind` records where a memory
+ * is kept — an event that is over, or a fact that stands — and a dated plan, intention or
+ * commitment is `standing` by the extraction contract while carrying a date the engine resolved
+ * from the speaker's own words. Gating on `kind` hid those dates from every reader: measured
+ * 2026-09-20 over 1,993 re-extracted rows, 77 held a resolved `temporal_date` that no model was
+ * ever shown, among them "Jon is getting ready for a dance competition near him next month"
+ * resolved to 2023-03.
+ */
+export declare function episodicEventDate(entry: {
+  metadata?: string;
+}): string | undefined;
+/**
+ * The sentence a row was written from, exactly as it was said.
+ *
+ * A row's `text` is what the extractor made of that sentence, and extraction paraphrases: asked
+ * what a poster said, a row reading "posters full of pride and strength" cannot answer "Trans
+ * Lives Matter" even though the turn contained it, and asked how someone described a dancer, a row
+ * reading "talented and passionate" cannot answer "graceful". Both wordings are already in the
+ * store beside the paraphrase; until 2026-09-15 only the paraphrase was ever shown to a model.
+ *
+ * Absent for a row written from a shared photo, and for anything rewritten by a maintenance wave.
+ */
+export declare function sourceQuote(entry: {
+  metadata?: string;
+}): string | undefined;
+/**
+ * The calendar day a row was said: the session moment it was extracted in, the anchor every
+ * relative date resolved against. A row with no session moment (rewritten by a maintenance wave,
+ * or written before source order existed) makes no claim about when it was said — its row
+ * timestamp is when it was written, which is not the same day.
+ */
+export declare function saidOnDate(entry: {
+  metadata?: string;
+}): string | undefined;
+export declare function isReflectionEntry(entry: {
+  category: string;
+  metadata?: string;
+}): boolean;
+export declare function getDisplayCategoryTag(entry: {
+  category: string;
+  projectId: string;
+  metadata?: string;
+}): string;
+export declare function serializeMemory(entry: {
+  id: string;
+  text: string;
+  category: string;
+  projectId: string;
+  importance: number;
+  timestamp: number;
+  metadata: string;
+}): Record<string, unknown>;
+//#endregion

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

@@ -0,0 +1,106 @@
+import { normalizeIsoDateTimeString } from "../shared/iso-date-time.js";
+import { stripHtmlTags, stripRoleLabelPrefix } from "../shared/i18n-text.js";
+import { i as isCalendarLabel } from "../../../calendar-instruction-CzqZbAPG.js";
+import { sanitizeContentIngress } from "@snoai/content-sanitizer";
+//#region src/engine/bindings/memory-tool-formatting.ts
+/** @file memory-tool-formatting.ts
+* @purpose Converts memory entries into safe user-visible tool output.
+* @boundary Metadata parsing, recalled-text sanitization, and serialization only.
+*/
+function sanitizeRecalledText(text) {
+	const projected = sanitizeContentIngress({
+		source: "generic-text",
+		content: text
+	}).projections.plainText;
+	return stripRoleLabelPrefix(stripHtmlTags(projected));
+}
+function safeParseMetadata(raw) {
+	try {
+		return JSON.parse(raw);
+	} catch {
+		return { _invalidMetadata: raw };
+	}
+}
+function parseEntryMetadata(entry) {
+	if (!entry.metadata) return {};
+	try {
+		const parsed = JSON.parse(entry.metadata);
+		return parsed && typeof parsed === "object" ? parsed : {};
+	} catch {
+		return {};
+	}
+}
+/**
+* Display the resolved event precision; unresolved text never inherits a record timestamp.
+*
+* Keyed on whether the claim has a resolved date, never on `kind`. `kind` records where a memory
+* is kept — an event that is over, or a fact that stands — and a dated plan, intention or
+* commitment is `standing` by the extraction contract while carrying a date the engine resolved
+* from the speaker's own words. Gating on `kind` hid those dates from every reader: measured
+* 2026-09-20 over 1,993 re-extracted rows, 77 held a resolved `temporal_date` that no model was
+* ever shown, among them "Jon is getting ready for a dance competition near him next month"
+* resolved to 2023-03.
+*/
+function episodicEventDate(entry) {
+	const metadata = parseEntryMetadata(entry);
+	if (metadata.temporal_resolution_status === "unresolved" || metadata.temporal_resolution_status === "static") return void 0;
+	if (isCalendarLabel(metadata.temporal_date, metadata.temporal_precision)) return metadata.temporal_date;
+	const eventAt = metadata.event_at;
+	const iso = normalizeIsoDateTimeString(eventAt);
+	if (iso !== void 0) return iso.slice(0, 10);
+	if (typeof eventAt === "number") {
+		const date = new Date(eventAt);
+		if (Number.isFinite(date.getTime())) return date.toISOString().slice(0, 10);
+	}
+}
+/**
+* The sentence a row was written from, exactly as it was said.
+*
+* A row's `text` is what the extractor made of that sentence, and extraction paraphrases: asked
+* what a poster said, a row reading "posters full of pride and strength" cannot answer "Trans
+* Lives Matter" even though the turn contained it, and asked how someone described a dancer, a row
+* reading "talented and passionate" cannot answer "graceful". Both wordings are already in the
+* store beside the paraphrase; until 2026-09-15 only the paraphrase was ever shown to a model.
+*
+* Absent for a row written from a shared photo, and for anything rewritten by a maintenance wave.
+*/
+function sourceQuote(entry) {
+	const span = parseEntryMetadata(entry).source_span;
+	if (!span || typeof span !== "object") return void 0;
+	const quote = span.quote;
+	return typeof quote === "string" && quote.trim().length > 0 ? quote : void 0;
+}
+/**
+* The calendar day a row was said: the session moment it was extracted in, the anchor every
+* relative date resolved against. A row with no session moment (rewritten by a maintenance wave,
+* or written before source order existed) makes no claim about when it was said — its row
+* timestamp is when it was written, which is not the same day.
+*/
+function saidOnDate(entry) {
+	const order = parseEntryMetadata(entry).source_order;
+	const moment = order && typeof order === "object" ? order.session_moment : void 0;
+	if (typeof moment !== "number") return void 0;
+	const date = new Date(moment);
+	return Number.isFinite(date.getTime()) ? date.toISOString().slice(0, 10) : void 0;
+}
+function isReflectionEntry(entry) {
+	const metadata = parseEntryMetadata(entry);
+	return metadata.type === "memory-reflection" || metadata.type === "memory-reflection-event" || metadata.type === "memory-reflection-item" || metadata.type === "memory-reflection-mapped";
+}
+function getDisplayCategoryTag(entry) {
+	if (isReflectionEntry(entry)) return `reflection:${entry.projectId}`;
+	return `${entry.category}:${entry.projectId}`;
+}
+function serializeMemory(entry) {
+	return {
+		id: entry.id,
+		text: sanitizeRecalledText(entry.text),
+		category: getDisplayCategoryTag(entry),
+		rawCategory: entry.category,
+		scope: entry.projectId,
+		importance: entry.importance,
+		timestamp: new Date(entry.timestamp).toISOString()
+	};
+}
+//#endregion
+export { episodicEventDate, getDisplayCategoryTag, isReflectionEntry, parseEntryMetadata, safeParseMetadata, saidOnDate, sanitizeRecalledText, serializeMemory, sourceQuote };

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

@@ -0,0 +1,8 @@
+import { i as SnoStationMemError } from "../../../errors-CeVRxf9V.js";
+import "../../../memory-tool-dependencies-CatGzI9R.js";
+import { ToolContext, ToolResult } from "./memory-tool-schemas.js";
+//#region src/engine/bindings/memory-tool-results.d.ts
+export declare function makeResult(text: string, details: Record<string, unknown>, isError?: boolean): ToolResult;
+export declare function normalizeError(error: unknown): SnoStationMemError;
+export declare function runWithAudit(_ctx: ToolContext, _tool: string, _scope: string | undefined, run: () => Promise<ToolResult>): Promise<ToolResult>;
+//#endregion

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

@@ -0,0 +1,41 @@
+import { RetrievalError, SnoStationMemError } from "../shared/errors.js";
+import { n as z } from "../../../memory-tool-dependencies-DjUoelnm.js";
+import { createLogger } from "@snoai/utils/logger";
+//#region src/engine/bindings/memory-tool-results.ts
+/** @file memory-tool-results.ts
+* @purpose Normalizes tool success, audit, and error envelopes.
+* @boundary Result construction and error conversion only.
+*/
+const log = createLogger("sno-station-mem:memory-tools");
+function makeResult(text, details, isError = false) {
+	if (isError) log.error("Memory operation failed; later requests remain available", { cause: text }, {
+		event_name: "memory.tool.operation.failed",
+		file: "packages/memory/src/engine/bindings/memory-tool-results.ts",
+		function: "makeResult",
+		site_id: "memory.tool.operation.failed"
+	});
+	return {
+		...isError ? { isError: true } : {},
+		content: [{
+			type: "text",
+			text
+		}],
+		details
+	};
+}
+function normalizeError(error) {
+	if (error instanceof SnoStationMemError) return error;
+	if (error instanceof z.ZodError) return new RetrievalError(error.issues.map((issue) => issue.message).join(", "), error);
+	if (error instanceof Error) return new SnoStationMemError("unknown_error", error.message, error);
+	return new SnoStationMemError("unknown_error", String(error));
+}
+async function runWithAudit(_ctx, _tool, _scope, run) {
+	try {
+		return await run();
+	} catch (error) {
+		const normalized = normalizeError(error);
+		return makeResult(normalized.message, { errorCode: normalized.code }, true);
+	}
+}
+//#endregion
+export { makeResult, normalizeError, runWithAudit };