@snoai/memory 0.0.0-stage → 1.0.1

package/dist/memory-telemetry-receipts-YsxbwOAf.js

@@ -0,0 +1,91 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+//#region src/engine/telemetry/memory-telemetry-config.ts
+function loadMemoryTelemetryKeySet(options) {
+	if (!options.enabled) return {
+		enabled: false,
+		current: null,
+		historic: /* @__PURE__ */ new Map()
+	};
+	const key = options.key;
+	if (!key || key.trim().length === 0) throw new Error("telemetry.memoryUsage.key is required when memory telemetry is enabled");
+	const currentKeyVersion = options.currentKeyVersion ?? options.historicKeys.length + 1;
+	if (!Number.isInteger(currentKeyVersion) || currentKeyVersion <= 0) throw new Error("memory telemetry current key version must be a positive integer");
+	return {
+		enabled: true,
+		current: {
+			version: currentKeyVersion,
+			key
+		},
+		historic: new Map(options.historicKeys.map((value, index) => [index + 1, value]))
+	};
+}
+//#endregion
+//#region src/engine/telemetry/memory-telemetry-receipts.ts
+const CONTENT_HASH_PATTERN = /^[a-f0-9]{64}$/;
+const TIMESTAMP_MS_PATTERN = /^[0-9]{13}$/;
+const RECEIPT_HMAC_PATTERN = /^[a-f0-9]{64}$/;
+function createMemoryTelemetryReceiptService(keySet, options = {}) {
+	const signHmac = options.signHmac ?? defaultSignHmac;
+	return {
+		sign(input) {
+			validateReceiptInput(input);
+			const current = requireCurrentKey(keySet);
+			const canonicalInput = canonicalReceiptInput(input);
+			return {
+				...input,
+				keyVersion: current.version,
+				receiptHmac: signHmac(current.key, canonicalInput)
+			};
+		},
+		verify(receipt) {
+			validateReceipt(receipt);
+			const key = resolveVerificationKey(keySet, receipt.keyVersion);
+			if (!key) return verification("key_expired", receipt);
+			return verification(safeEqualHex(signHmac(key.key, canonicalReceiptInput(receipt)), receipt.receiptHmac) ? "valid" : "tampered", receipt);
+		}
+	};
+}
+function requireCurrentKey(keySet) {
+	if (!keySet.enabled || !keySet.current) throw new Error("memory telemetry receipt signing requires an enabled current key");
+	return keySet.current;
+}
+function resolveVerificationKey(keySet, keyVersion) {
+	if (keySet.current?.version === keyVersion) return keySet.current;
+	const historicKey = keySet.historic.get(keyVersion);
+	if (!historicKey) return null;
+	return {
+		version: keyVersion,
+		key: historicKey
+	};
+}
+function canonicalReceiptInput(input) {
+	return `${input.factId}${input.contentHash}${String(input.timestampMs)}`;
+}
+function validateReceiptInput(input) {
+	if (input.factId.length === 0) throw new Error("fact_id must be non-empty for receipt signing");
+	if (!CONTENT_HASH_PATTERN.test(input.contentHash)) throw new Error("content_hash must be a 64-character lowercase hex SHA-256");
+	if (!TIMESTAMP_MS_PATTERN.test(String(input.timestampMs))) throw new Error("timestamp_ms must serialize to exactly 13 decimal digits");
+}
+function validateReceipt(receipt) {
+	validateReceiptInput(receipt);
+	if (!Number.isInteger(receipt.keyVersion) || receipt.keyVersion <= 0) throw new Error("key_version must be a positive integer");
+	if (!RECEIPT_HMAC_PATTERN.test(receipt.receiptHmac)) throw new Error("receipt_hmac must be a 64-character lowercase hex HMAC-SHA256");
+}
+function defaultSignHmac(key, canonicalInput) {
+	return createHmac("sha256", key).update(canonicalInput, "utf8").digest("hex");
+}
+function safeEqualHex(left, right) {
+	const leftBuffer = Buffer.from(left, "hex");
+	const rightBuffer = Buffer.from(right, "hex");
+	return leftBuffer.length === rightBuffer.length && timingSafeEqual(leftBuffer, rightBuffer);
+}
+function verification(status, receipt) {
+	return {
+		status,
+		contentHash: receipt.contentHash,
+		timestampMs: receipt.timestampMs,
+		keyVersion: receipt.keyVersion
+	};
+}
+//#endregion
+export { loadMemoryTelemetryKeySet as n, createMemoryTelemetryReceiptService as t };

package/dist/memory-telemetry-types-CufVmrCs.d.ts

@@ -0,0 +1,14 @@
+//#region src/engine/telemetry/memory-telemetry-types.d.ts
+declare const MEMORY_TELEMETRY_EVENT_TYPES: readonly ["create", "update", "recall", "supersede", "delete", "inject", "epoch_boundary", "purge"];
+type MemoryTelemetryEventType = (typeof MEMORY_TELEMETRY_EVENT_TYPES)[number];
+type MemoryTelemetryMetadata = Record<string, unknown>;
+type MemoryTelemetryReceiptStatus = "valid" | "invalid" | "tampered" | "key_expired";
+declare const MEMORY_TELEMETRY_DELETE_REASONS: {
+  readonly admin: "admin_delete";
+  readonly cli: "cli_delete";
+  readonly memoryForget: "memory_forget";
+};
+type MemoryTelemetryDeleteReason = (typeof MEMORY_TELEMETRY_DELETE_REASONS)[keyof typeof MEMORY_TELEMETRY_DELETE_REASONS];
+declare function isMemoryTelemetryEventType(value: unknown): value is MemoryTelemetryEventType;
+//#endregion
+export { MemoryTelemetryMetadata as a, MemoryTelemetryEventType as i, MEMORY_TELEMETRY_EVENT_TYPES as n, MemoryTelemetryReceiptStatus as o, MemoryTelemetryDeleteReason as r, isMemoryTelemetryEventType as s, MEMORY_TELEMETRY_DELETE_REASONS as t };

package/dist/memory-temporality-classifier-BUjXG5o7.js

@@ -0,0 +1,184 @@
+import { isSupportedLocale } from "./internal/engine/i18n/locales.js";
+import { parseIsoDateTimeMs } from "./internal/engine/shared/iso-date-time.js";
+import { n as modelCallDestination } from "./model-call-table-CspopkBg.js";
+import { a as isTerminalLlmFailure } from "./llm-client-BSYUAcUb.js";
+import { n as readModelReplyJson } from "./model-reply-text-CKopStP2.js";
+import { n as RESOURCES_BY_LOCALE } from "./all-resources-BQK2ugjB.js";
+import { a as sessionZoneCarriedBy, n as calendarInstructionSchema, r as calendarSessionTimestamp, t as calculateCalendarTime } from "./calendar-instruction-CzqZbAPG.js";
+import { z } from "zod";
+import { createLogger } from "@snoai/utils/logger";
+import { Temporal } from "@js-temporal/polyfill";
+//#region src/engine/extraction/date-resolution.ts
+/** Model-only time interpretation followed by deterministic calendar arithmetic. */
+const log = createLogger("sno-station-mem:date-resolution");
+/** No model means no semantic decision. Preserve the text rather than interpreting it. */
+function unresolvedMemoryDate(input) {
+	return {
+		interval: {
+			type: "unresolved",
+			resolutionStatus: "unresolved",
+			phrase: input.expression ?? input.text
+		},
+		timestamp: input.sessionTimestamp ?? calendarSessionTimestamp(input.sessionDateTime, input.sessionTimezone),
+		timezone: input.sessionTimezone ?? sessionZoneCarriedBy(input.sessionDateTime) ?? "UTC",
+		stage: {
+			modelCalled: false,
+			reason: "no-model-judgment"
+		}
+	};
+}
+const replySchema = z.object({
+	reason: z.string(),
+	time: calendarInstructionSchema
+}).strict();
+async function resolveMemoryDate(input) {
+	const unresolved = unresolvedMemoryDate(input);
+	if (!input.llm) return unresolved;
+	const modelCalls = input.routing?.modelCalls;
+	if (input.routing && !modelCalls) throw new Error("modelCalls unavailable");
+	if (input.routing && modelCalls && modelCallDestination("E11", input.routing.mode, modelCalls) === "off") return unresolved;
+	const anchor = input.sessionDateTime ?? (input.sessionTimestamp === void 0 ? void 0 : new Date(input.sessionTimestamp).toISOString());
+	const prompt = [RESOURCES_BY_LOCALE[input.locale ?? input.routing?.language ?? "en"].extractionPrompts.buildDateResolutionPrompt(), JSON.stringify({
+		schema: z.toJSONSchema(replySchema),
+		sentence: input.text,
+		expression: input.expression ?? null,
+		session_date_time: anchor ?? null,
+		session_timezone: unresolved.timezone
+	})].join("\n\n");
+	let raw = null;
+	try {
+		raw = await input.llm.completeText({
+			callId: "E11",
+			prompt,
+			enableThinking: true
+		});
+	} catch (error) {
+		if (isTerminalLlmFailure(error)) throw error;
+	}
+	const reply = raw ? readModelReplyJson(raw, (value) => {
+		const parsed = replySchema.safeParse(value);
+		return parsed.success ? parsed.data : void 0;
+	}) : void 0;
+	if (!reply) {
+		const reason = raw === null ? "model-unavailable" : "invalid-model-instruction";
+		log.warn("Memory time judgment failed; preserving unresolved time", {
+			model_called: true,
+			reason
+		}, {
+			event_name: "memory.date_resolution.unavailable",
+			file: "packages/memory/src/engine/extraction/date-resolution.ts",
+			function: "resolveMemoryDate",
+			site_id: "date-resolution.model_unavailable"
+		});
+		return {
+			...unresolved,
+			stage: {
+				modelCalled: true,
+				reason
+			}
+		};
+	}
+	const stage = {
+		modelCalled: true,
+		reason: reply.reason
+	};
+	const calculated = calculateCalendarTime(reply.time, anchor, unresolved.timezone);
+	log.info("Memory date resolution completed", {
+		model_called: true,
+		resolved: calculated !== null
+	}, {
+		event_name: "sno_station_mem.date-resolution.date.resolution.stage",
+		file: "packages/memory/src/engine/extraction/date-resolution.ts",
+		function: "resolveMemoryDate",
+		site_id: "date-resolution.resolveMemoryDate.1224fa35b2"
+	});
+	if (reply.time.kind === "none") return {
+		...unresolved,
+		interval: {
+			type: "static",
+			resolutionStatus: "static"
+		},
+		stage
+	};
+	if (!calculated) return {
+		...unresolved,
+		stage
+	};
+	return {
+		interval: {
+			type: "bounded",
+			resolutionStatus: "resolved",
+			from: calculated.from,
+			until: calculated.until,
+			phrase: input.expression ?? input.text,
+			date: calculated.label,
+			precision: calculated.precision,
+			timezone: calculated.timezone
+		},
+		timestamp: unresolved.timestamp,
+		timezone: unresolved.timezone,
+		stage
+	};
+}
+//#endregion
+//#region src/engine/extraction/memory-temporality-classifier.ts
+/** @file memory-temporality-classifier.ts
+* @purpose Resolves temporal intervals through the shared date resolver.
+* @boundary Metadata writes and deterministic capture callers.
+*/
+function parseSessionTimestamp(sessionDateTime) {
+	return parseIsoDateTimeMs(sessionDateTime);
+}
+function sessionDateTime(context) {
+	if (context.sessionTimestamp === void 0) return void 0;
+	const timezone = context.sessionTimezone ?? Intl.DateTimeFormat().resolvedOptions().timeZone;
+	return Temporal.Instant.fromEpochMilliseconds(context.sessionTimestamp).toZonedDateTimeISO(timezone).toString({
+		smallestUnit: "millisecond",
+		timeZoneName: "never"
+	});
+}
+function inferTemporalInterval(text, locale, context = {}) {
+	return unresolvedMemoryDate({
+		text,
+		sessionDateTime: sessionDateTime(context),
+		sessionTimezone: context.sessionTimezone,
+		locale: locale && isSupportedLocale(locale) ? locale : "en"
+	}).interval;
+}
+function serializeIntervalMetadata(category, interval) {
+	if (interval.type === "static") return {
+		memory_temporal_type: "static",
+		temporal_resolution_status: "static"
+	};
+	const base = {
+		memory_temporal_type: "dynamic",
+		temporal_resolution_status: interval.resolutionStatus
+	};
+	if ("phrase" in interval && interval.phrase) base.temporal_phrase = interval.phrase;
+	if (interval.type === "instant") {
+		if (category === "episodic") base.event_at = interval.at;
+		base.valid_from = interval.at;
+	} else if (interval.type === "bounded") {
+		base.valid_from = interval.from;
+		if (category === "episodic") base.valid_until = interval.until;
+		if (interval.date !== void 0) base.temporal_date = interval.date;
+		if (interval.precision !== void 0) base.temporal_precision = interval.precision;
+		if (interval.timezone !== void 0) base.temporal_timezone = interval.timezone;
+	} else if (interval.type === "ongoing") {
+		base.valid_from = interval.from;
+		if (interval.until !== void 0) base.valid_until = interval.until;
+	}
+	return base;
+}
+function classifyTemporal(text) {
+	return inferTemporalInterval(text).type === "static" ? "static" : "dynamic";
+}
+function inferExpiry(text, now = Date.now()) {
+	const interval = inferTemporalInterval(text, "en", {
+		sessionTimestamp: now,
+		sessionTimezone: Intl.DateTimeFormat().resolvedOptions().timeZone
+	});
+	return interval.type === "bounded" ? interval.until : void 0;
+}
+//#endregion
+export { serializeIntervalMetadata as a, parseSessionTimestamp as i, inferExpiry as n, resolveMemoryDate as o, inferTemporalInterval as r, unresolvedMemoryDate as s, classifyTemporal as t };

package/dist/memory-temporality-classifier-Brht5jyK.d.ts

@@ -0,0 +1,43 @@
+import { h as MemoryCategory, w as InsightMetadata } from "./types-CWdhXLxr.js";
+//#region src/engine/extraction/memory-temporality-classifier.d.ts
+type TemporalType = "static" | "dynamic";
+type TemporalResolutionStatus = "resolved" | "unresolved" | "static";
+interface SessionTemporalContext {
+  sessionTimestamp?: number;
+  sessionTimezone?: string;
+}
+type TemporalInterval = {
+  type: "static";
+  resolutionStatus: "static";
+} | {
+  type: "unresolved";
+  resolutionStatus: "unresolved";
+  phrase: string;
+} | {
+  type: "instant";
+  resolutionStatus: "resolved";
+  at: number;
+  phrase?: string;
+} | {
+  type: "bounded";
+  resolutionStatus: "resolved";
+  from: number;
+  until: number;
+  phrase?: string;
+  date?: string;
+  precision?: "year" | "month" | "week" | "day" | "minute";
+  timezone?: string;
+} | {
+  type: "ongoing";
+  resolutionStatus: "resolved";
+  from: number;
+  until?: number;
+  phrase?: string;
+};
+declare function parseSessionTimestamp(sessionDateTime?: string): number | undefined;
+declare function inferTemporalInterval(text: string, locale?: string, context?: SessionTemporalContext): TemporalInterval;
+declare function serializeIntervalMetadata(category: MemoryCategory, interval: TemporalInterval): Partial<InsightMetadata>;
+declare function classifyTemporal(text: string): TemporalType;
+declare function inferExpiry(text: string, now?: number): number | undefined;
+//#endregion
+export { classifyTemporal as a, parseSessionTimestamp as c, TemporalType as i, serializeIntervalMetadata as l, TemporalInterval as n, inferExpiry as o, TemporalResolutionStatus as r, inferTemporalInterval as s, SessionTemporalContext as t };

package/dist/memory-tier-promoter-CqGxCkue.d.ts

@@ -0,0 +1,43 @@
+import { b as MemoryTier, l as DecayScore } from "./types-CWdhXLxr.js";
+//#region src/engine/operations/memory-tier-promoter.d.ts
+interface TierConfig {
+  /** Minimum access count for Core promotion (default: 10) */
+  coreAccessThreshold: number;
+  /** Minimum composite decay score for Core promotion (default: 0.7) */
+  coreCompositeThreshold: number;
+  /** Minimum importance for Core promotion (default: 0.8) */
+  coreImportanceThreshold: number;
+  /** Composite threshold below which to demote to Peripheral (default: 0.15) */
+  peripheralCompositeThreshold: number;
+  /** Age in days after which infrequent memories demote to Peripheral (default: 60) */
+  peripheralAgeDays: number;
+  /** Minimum access count for Working promotion from Peripheral (default: 3) */
+  workingAccessThreshold: number;
+  /** Minimum composite for Working promotion from Peripheral (default: 0.4) */
+  workingCompositeThreshold: number;
+}
+declare const DEFAULT_TIER_CONFIG: TierConfig;
+interface TierTransition {
+  memoryId: string;
+  fromTier: MemoryTier;
+  toTier: MemoryTier;
+  reason: string;
+}
+/** Minimal memory fields needed for tier evaluation.
+ *  Uses `timestamp` to align with sno-station-mem's MemoryEntry shape. */
+interface TierableMemory {
+  id: string;
+  tier: MemoryTier;
+  importance: number;
+  accessCount: number;
+  timestamp: number;
+}
+interface TierPromoter {
+  evaluate(memory: TierableMemory, decayScore: DecayScore, now?: number): TierTransition | null;
+  evaluateAll(memories: TierableMemory[], decayScores: DecayScore[], now?: number): TierTransition[];
+}
+/** Creates the tier promoter that translates decay scores into promotion/demotion decisions.
+ *  Promote is bidirectional here: Peripheral→Working→Core (up) and Core→Working→Peripheral (down). */
+declare function createTierPromoter(config?: TierConfig): TierPromoter;
+//#endregion
+export { TierableMemory as a, TierTransition as i, TierConfig as n, createTierPromoter as o, TierPromoter as r, DEFAULT_TIER_CONFIG as t };

package/dist/memory-tool-dependencies-CatGzI9R.d.ts

@@ -0,0 +1,14 @@
+import "./types-CWdhXLxr.js";
+import "./index-DL8AVj0Z.js";
+import "./embedding-provider-client-vynZMuit.js";
+import "./retriever-Dxss5fRv.js";
+import "./memory-metadata-codec-DUvsYe_X.js";
+import "./store-C8sUTssE.js";
+import "./capture-policy-detector-CxbHPkMX.js";
+import "./memory-temporality-classifier-Brht5jyK.js";
+import "./runtime-audit-log-zpQiR9HT.js";
+import { z as z$1 } from "zod";
+import "@snoai/chunking";
+import "@sinclair/typebox";
+import "async-mutex";
+export { z$1 as t };

package/dist/memory-tool-dependencies-DjUoelnm.js

@@ -0,0 +1,19 @@
+import "./internal/config/index.js";
+import "./internal/engine/i18n/locales.js";
+import "./internal/engine/shared/types.js";
+import "./memory-metadata-codec-DL1sbJiN.js";
+import "./internal/engine/shared/i18n-text.js";
+import "./internal/engine/shared/utils.js";
+import "./all-resources-BQK2ugjB.js";
+import "./capture-policy-detector-DaMfy9CZ.js";
+import "./internal/engine/extraction/extraction-text-sanitizer.js";
+import "./memory-temporality-classifier-BUjXG5o7.js";
+import "./runtime-audit-log-BCeujlEp.js";
+import "./internal/engine/operations/daily-spend-estimator.js";
+import "./internal/engine/operations/learning-file-maintenance.js";
+import "./scopes-CSOn6zdd.js";
+import { z as z$1 } from "zod";
+import { countTokens as countTokens$1 } from "@snoai/chunking";
+import "@sinclair/typebox";
+import "async-mutex";
+export { z$1 as n, countTokens$1 as t };