@snoai/memory 0.0.0-stage → 1.0.1

package/dist/internal/engine/shared/iso-date-time.d.ts

@@ -0,0 +1,16 @@
+//#region src/engine/shared/iso-date-time.d.ts
+/**
+ * Accepts `2023-05-07`, `2023-05-07T12:30:00`, or `2023-05-07T12:30:00Z`.
+ * Returns the trimmed input unchanged when valid; otherwise undefined.
+ */
+export declare function normalizeIsoDateTimeString(value: unknown): string | undefined;
+/** Parses a validated ISO date/date-time string into epoch milliseconds. */
+export declare function parseIsoDateTimeMs(value: unknown): number | undefined;
+/**
+ * Formats epoch milliseconds as an ISO calendar date (`YYYY-MM-DD`, UTC).
+ * The result validates as an ISO date string, so it round-trips through
+ * `normalizeIsoDateTimeString`. Used to give episodic memories a concrete
+ * event date when only a millisecond anchor (e.g. `valid_from`) is known.
+ */
+export declare function isoDateFromMs(ms: number): string;
+//#endregion

package/dist/internal/engine/shared/iso-date-time.js

@@ -0,0 +1,40 @@
+import { z } from "zod";
+//#region src/engine/shared/iso-date-time.ts
+/** @file iso-date-time.ts
+* @purpose Validates persisted ISO date/date-time strings without JavaScript Date rollover.
+* @boundary ISO string normalization and epoch parsing only; no relative date parsing.
+*/
+const ISO_DATE_STRING_SCHEMA = z.string().date();
+const ISO_DATE_TIME_STRING_SCHEMA = z.string().datetime({
+	offset: true,
+	local: true
+});
+/**
+* Accepts `2023-05-07`, `2023-05-07T12:30:00`, or `2023-05-07T12:30:00Z`.
+* Returns the trimmed input unchanged when valid; otherwise undefined.
+*/
+function normalizeIsoDateTimeString(value) {
+	if (typeof value !== "string") return void 0;
+	const trimmed = value.trim();
+	if (!trimmed) return void 0;
+	if (!ISO_DATE_STRING_SCHEMA.safeParse(trimmed).success && !ISO_DATE_TIME_STRING_SCHEMA.safeParse(trimmed).success) return;
+	return trimmed;
+}
+/** Parses a validated ISO date/date-time string into epoch milliseconds. */
+function parseIsoDateTimeMs(value) {
+	const normalized = normalizeIsoDateTimeString(value);
+	if (normalized === void 0) return void 0;
+	const parsed = Date.parse(normalized);
+	return Number.isNaN(parsed) ? void 0 : parsed;
+}
+/**
+* Formats epoch milliseconds as an ISO calendar date (`YYYY-MM-DD`, UTC).
+* The result validates as an ISO date string, so it round-trips through
+* `normalizeIsoDateTimeString`. Used to give episodic memories a concrete
+* event date when only a millisecond anchor (e.g. `valid_from`) is known.
+*/
+function isoDateFromMs(ms) {
+	return new Date(ms).toISOString().slice(0, 10);
+}
+//#endregion
+export { isoDateFromMs, normalizeIsoDateTimeString, parseIsoDateTimeMs };

package/dist/internal/engine/shared/lru.d.ts

@@ -0,0 +1,2 @@
+import { n as setLruEntry, r as touchLruEntry, t as pruneOldestEntries } from "../../../lru-DyoaTyIs.js";
+export { pruneOldestEntries, setLruEntry, touchLruEntry };

package/dist/internal/engine/shared/lru.js

@@ -0,0 +1,30 @@
+//#region src/engine/shared/lru.ts
+/** @file lru.ts
+* @purpose Provides a small bounded cache primitive for hot-path runtime state.
+* @boundary In-memory capacity limits and deterministic eviction behavior.
+* @see derived-line-cache.ts, retrieval-stats.ts, sno-station-mem-plugin-runtime.ts.
+*/
+/** Generic LRU helpers for bounded Map caches. */
+function pruneOldestEntries(map, maxEntries) {
+	while (map.size > maxEntries) {
+		const oldestKey = map.keys().next().value;
+		if (oldestKey === void 0) return;
+		map.delete(oldestKey);
+	}
+}
+/** Implements touch lru entry as the local bounded session cache operation. */
+function touchLruEntry(map, key) {
+	const value = map.get(key);
+	if (value === void 0) return void 0;
+	map.delete(key);
+	map.set(key, value);
+	return value;
+}
+/** Updates lru entry while preserving bounded session cache invariants. */
+function setLruEntry(map, key, value, maxEntries) {
+	if (map.has(key)) map.delete(key);
+	map.set(key, value);
+	pruneOldestEntries(map, maxEntries);
+}
+//#endregion
+export { pruneOldestEntries, setLruEntry, touchLruEntry };

package/dist/internal/engine/shared/memory-kind-policy.d.ts

@@ -0,0 +1,2 @@
+import { a as canExtractorWrite, c as canToolWrite, d as isAppendOnly, f as isDerivedOnly, i as allowedWriters, l as canTrustedWrite, m as writePolicy, n as WritePolicy, o as canOfflineFamilyWrite, p as isMutationNative, r as WriterAuthority, s as canProfileWriterWrite, t as DedupePolicy, u as dedupePolicy } from "../../../memory-kind-policy-BiuRjSJc.js";
+export { DedupePolicy, WritePolicy, WriterAuthority, allowedWriters, canExtractorWrite, canOfflineFamilyWrite, canProfileWriterWrite, canToolWrite, canTrustedWrite, dedupePolicy, isAppendOnly, isDerivedOnly, isMutationNative, writePolicy };

package/dist/internal/engine/shared/memory-kind-policy.js

@@ -0,0 +1,64 @@
+//#region src/engine/shared/memory-kind-policy.ts
+const WRITE_POLICY = {
+	episodic: "append-only",
+	lesson: "append-only",
+	profile: "mutation-native",
+	persona: "mutation-native",
+	summary: "derived-only",
+	state: "mutation-native"
+};
+const DEDUPE_POLICY = {
+	episodic: { mode: "none" },
+	lesson: {
+		mode: "signature",
+		field: "anti_pattern_signature"
+	},
+	profile: { mode: "none" },
+	persona: { mode: "none" },
+	summary: { mode: "none" },
+	state: { mode: "none" }
+};
+const ALLOWED_WRITERS = {
+	episodic: ["extraction", "offline-family"],
+	lesson: ["offline-family"],
+	profile: ["profile-writer", "offline-family"],
+	persona: ["offline-family"],
+	summary: ["offline-family"],
+	state: ["extraction", "offline-family"]
+};
+function isAppendOnly(kind) {
+	return WRITE_POLICY[kind] === "append-only";
+}
+function isMutationNative(kind) {
+	return WRITE_POLICY[kind] === "mutation-native";
+}
+function isDerivedOnly(kind) {
+	return WRITE_POLICY[kind] === "derived-only";
+}
+function writePolicy(kind) {
+	return WRITE_POLICY[kind];
+}
+function dedupePolicy(kind) {
+	return DEDUPE_POLICY[kind];
+}
+function allowedWriters(kind) {
+	return ALLOWED_WRITERS[kind];
+}
+function canExtractorWrite(kind) {
+	return ALLOWED_WRITERS[kind].includes("extraction");
+}
+function canProfileWriterWrite(kind) {
+	return ALLOWED_WRITERS[kind].includes("profile-writer");
+}
+function canToolWrite(kind) {
+	return ALLOWED_WRITERS[kind].includes("extraction");
+}
+function canTrustedWrite(kind) {
+	const writers = ALLOWED_WRITERS[kind];
+	return writers.includes("extraction") || writers.includes("profile-writer");
+}
+function canOfflineFamilyWrite(kind) {
+	return ALLOWED_WRITERS[kind].includes("offline-family");
+}
+//#endregion
+export { allowedWriters, canExtractorWrite, canOfflineFamilyWrite, canProfileWriterWrite, canToolWrite, canTrustedWrite, dedupePolicy, isAppendOnly, isDerivedOnly, isMutationNative, writePolicy };

package/dist/internal/engine/shared/paths.d.ts

@@ -0,0 +1,3 @@
+import { c as getStateDir, o as getSnoStationMemStateDir, r as getPrincipal } from "../../../profile-TWPJ_myr.js";
+import "../../../paths-qVF-5uBq.js";
+export { getPrincipal, getSnoStationMemStateDir, getStateDir };

package/dist/internal/engine/shared/paths.js

@@ -0,0 +1,2 @@
+import { getPrincipal, getSnoStationMemStateDir, getStateDir } from "../../contract/profile.js";
+export { getPrincipal, getSnoStationMemStateDir, getStateDir };

package/dist/internal/engine/shared/types.d.ts

@@ -0,0 +1,3 @@
+import { C as SESSION_STRATEGIES, n as pluginConfigSchema, t as PluginConfig, w as SessionStrategy } from "../../../plugin-config-schema-C0UUbOmG.js";
+import { S as normalizeCategory, _ as MemoryLane, a as CandidateExtractionTrace, b as MemoryTier, c as DEFAULT_MEMORY_TIER, d as DedupDecision, f as DedupResult, g as MemoryEntry, h as MemoryCategory, i as CANDIDATE_EXTRACTION_TRACE_VERSION, l as DecayScore, m as MEMORY_CATEGORIES, n as AggregationOperation, o as CandidateMemory, p as ExtractionStats, r as AggregationQuery, s as CandidateRelation, t as AGGREGATION_OPERATIONS, u as DecayableMemory, v as MemoryMetadata, x as RetrievalResult, y as MemorySearchResult } from "../../../types-CWdhXLxr.js";
+export { AGGREGATION_OPERATIONS, AggregationOperation, AggregationQuery, CANDIDATE_EXTRACTION_TRACE_VERSION, CandidateExtractionTrace, CandidateMemory, CandidateRelation, DEFAULT_MEMORY_TIER, DecayScore, DecayableMemory, DedupDecision, DedupResult, ExtractionStats, MEMORY_CATEGORIES, MemoryCategory, MemoryEntry, MemoryLane, MemoryMetadata, MemorySearchResult, MemoryTier, type PluginConfig, RetrievalResult, SESSION_STRATEGIES, type SessionStrategy, normalizeCategory, pluginConfigSchema };

package/dist/internal/engine/shared/types.js

@@ -0,0 +1,25 @@
+import { l as SESSION_STRATEGIES, t as pluginConfigSchema } from "../../../plugin-config-schema-YJLyIIcJ.js";
+//#region src/engine/shared/types.ts
+const MEMORY_CATEGORIES = [
+	"episodic",
+	"profile",
+	"persona",
+	"lesson",
+	"summary",
+	"state"
+];
+const CANDIDATE_EXTRACTION_TRACE_VERSION = "insight-distill-2026-06-27";
+const AGGREGATION_OPERATIONS = [
+	"count",
+	"first",
+	"last",
+	"evidence"
+];
+const DEFAULT_MEMORY_TIER = "peripheral";
+/** Validate and normalize a category string to a foundation kind. */
+function normalizeCategory(raw) {
+	const lower = raw.toLowerCase().trim();
+	if (MEMORY_CATEGORIES.includes(lower)) return lower;
+}
+//#endregion
+export { AGGREGATION_OPERATIONS, CANDIDATE_EXTRACTION_TRACE_VERSION, DEFAULT_MEMORY_TIER, MEMORY_CATEGORIES, SESSION_STRATEGIES, normalizeCategory, pluginConfigSchema };

package/dist/internal/engine/shared/utils.d.ts

@@ -0,0 +1,2 @@
+import { a as f32ToBytes, c as sanitizeFtsConjunctiveQuery, i as debugContentPreview, l as sanitizeFtsQuery, n as clamp01, o as readFileTail, r as clampInt, s as sanitizeForContext, t as bytesToF32, u as stableHash } from "../../../utils-Ctb9aevJ.js";
+export { bytesToF32, clamp01, clampInt, debugContentPreview, f32ToBytes, readFileTail, sanitizeForContext, sanitizeFtsConjunctiveQuery, sanitizeFtsQuery, stableHash };

package/dist/internal/engine/shared/utils.js

@@ -0,0 +1,175 @@
+import { DEFAULT_IMPORTANCE } from "../../config/index.js";
+import { redactSecrets } from "../security/redact.js";
+import { stripHtmlTags, tokenizeForFts, truncateGraphemes } from "./i18n-text.js";
+import { open, stat } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { sanitizeContentIngress } from "@snoai/content-sanitizer";
+//#region src/engine/shared/utils.ts
+/** @file utils.ts
+* @purpose Provides shared utility functions used across plugin runtime modules.
+* @boundary Text normalization, hashing, filesystem helpers, and small conversions.
+* @see store.ts, capture-policy-detector.ts, memory-management-cli.ts.
+*/
+/**
+* Clamps integer options into the configured range before they reach storage or ranking code.
+*/
+function clampInt(value, min, max) {
+	if (!Number.isFinite(value)) return min;
+	return Math.min(max, Math.max(min, Math.floor(value)));
+}
+/** Clamps score-like values to the 0..1 range while honoring a caller-provided fallback. */
+function clamp01(value, fallback = DEFAULT_IMPORTANCE) {
+	if (!Number.isFinite(value)) return fallback;
+	return Math.min(1, Math.max(0, value));
+}
+/** Redacts markup-sensitive characters before memory text is embedded in prompt context. */
+function sanitizeForContext(text, maxChars = 500, newlineReplacement = " ") {
+	const storageSafe = sanitizeContentIngress({
+		source: "generic-text",
+		content: text
+	}).projections.plainText;
+	const sanitized = stripHtmlTags(storageSafe).replace(/[\r\n]+/g, newlineReplacement).replace(/</g, "＜").replace(/>/g, "＞").replace(/\s+/g, " ").trim();
+	return truncateGraphemes(sanitized, maxChars);
+}
+const FTS5_RESERVED_TOKENS = /* @__PURE__ */ new Set([
+	"AND",
+	"OR",
+	"NOT",
+	"NEAR"
+]);
+const MAX_FTS_QUERY_TOKENS = 50;
+const FTS_STOPWORDS = /* @__PURE__ */ new Set([
+	"a",
+	"an",
+	"the",
+	"and",
+	"or",
+	"but",
+	"of",
+	"to",
+	"in",
+	"on",
+	"at",
+	"for",
+	"is",
+	"are",
+	"was",
+	"were",
+	"be",
+	"been",
+	"being",
+	"do",
+	"does",
+	"did",
+	"has",
+	"have",
+	"had",
+	"what",
+	"which",
+	"who",
+	"whom",
+	"when",
+	"where",
+	"how",
+	"why",
+	"this",
+	"that",
+	"these",
+	"those",
+	"with",
+	"as",
+	"by",
+	"from",
+	"it",
+	"its",
+	"i",
+	"you",
+	"he",
+	"she",
+	"we",
+	"they",
+	"them",
+	"his",
+	"her",
+	"their",
+	"our",
+	"your",
+	"my"
+]);
+/** Escapes SQLite FTS operators so user queries cannot break MATCH syntax. */
+function sanitizeFtsQuery(rawQuery) {
+	const tokens = tokenizeForFts(rawQuery).filter((token) => token.length > 0).filter((token) => !FTS5_RESERVED_TOKENS.has(token.toUpperCase())).filter((token) => !FTS_STOPWORDS.has(token.toLowerCase())).slice(0, MAX_FTS_QUERY_TOKENS);
+	if (tokens.length === 0) return "";
+	return tokens.map((token) => `"${token}"`).join(" OR ");
+}
+/** Builds a conjunctive FTS predicate from validated structured aggregation terms. */
+function sanitizeFtsConjunctiveQuery(terms) {
+	let remainingTokens = MAX_FTS_QUERY_TOKENS;
+	return terms.flatMap((term) => {
+		const tokens = tokenizeForFts(term).filter((token) => token.length > 0).filter((token) => !FTS5_RESERVED_TOKENS.has(token.toUpperCase())).slice(0, remainingTokens);
+		remainingTokens -= tokens.length;
+		return tokens.length > 0 ? [`(${tokens.map((token) => `"${token}"`).join(" OR ")})`] : [];
+	}).join(" AND ");
+}
+/** Serializes Float32 vectors into little-endian bytes for SQLite vector storage. */
+function f32ToBytes(f32) {
+	return new Uint8Array(f32.buffer, f32.byteOffset, f32.byteLength);
+}
+/** Rehydrates SQLite vector bytes into Float32 values and rejects malformed payloads. */
+function bytesToF32(bytes) {
+	if (bytes.byteLength % 4 !== 0) throw new Error(`bytesToF32: byteLength ${bytes.byteLength} not a multiple of 4`);
+	const aligned = new Uint8Array(bytes.byteLength);
+	aligned.set(bytes);
+	return new Float32Array(aligned.buffer);
+}
+/** Produces the stable content hash used for deduplication and idempotent writes. */
+function stableHash(text) {
+	return createHash("sha256").update(text).digest("hex");
+}
+/**
+* Return a short, secret-redacted, whitespace-collapsed preview of `text` for
+* debug audit logs when explicitly enabled. Off-by-default
+* and passes the text through `redactSecrets` first because previews persist
+* in audit.jsonl on disk. Enable for bench investigations only.
+*/
+function debugContentPreview(text, enabled, maxChars = 80) {
+	if (!enabled) return void 0;
+	if (!text) return void 0;
+	const collapsed = redactSecrets(text).replace(/\s+/g, " ").trim();
+	if (collapsed.length === 0) return void 0;
+	return collapsed.length > maxChars ? `${collapsed.slice(0, maxChars)}...` : collapsed;
+}
+/** Max bytes to read from the tail of a session JSONL file (512 KB). */
+const SESSION_TAIL_MAX_BYTES = 524288;
+/**
+* Read the tail of a text file (up to `maxBytes`).
+* Returns the file content from the tail. If the file is smaller than `maxBytes`,
+* returns the entire file. The first partial line is dropped (it was likely truncated).
+*/
+async function readFileTail(filePath, maxBytes = SESSION_TAIL_MAX_BYTES) {
+	const fileStat = await stat(filePath);
+	if (fileStat.size <= maxBytes) {
+		const handle = await open(filePath, "r");
+		try {
+			const buf = Buffer.alloc(fileStat.size);
+			await handle.read(buf, 0, fileStat.size, 0);
+			return buf.toString("utf-8");
+		} finally {
+			await handle.close();
+		}
+	}
+	const handle = await open(filePath, "r");
+	try {
+		const startPos = fileStat.size - maxBytes;
+		const buf = Buffer.alloc(maxBytes);
+		await handle.read(buf, 0, maxBytes, startPos);
+		const raw = buf.toString("utf-8");
+		const firstNewline = raw.indexOf("\n");
+		if (firstNewline === -1) return "";
+		return raw.slice(firstNewline + 1);
+	} finally {
+		await handle.close();
+	}
+}
+//#endregion
+export { bytesToF32, clamp01, clampInt, debugContentPreview, f32ToBytes, readFileTail, sanitizeForContext, sanitizeFtsConjunctiveQuery, sanitizeFtsQuery, stableHash };

package/dist/internal/engine/telemetry/memory-telemetry-api.d.ts

@@ -0,0 +1,134 @@
+import { r as SqliteDatabaseLike } from "../../../sqlite-runtime-L_ywirTm.js";
+import { n as MemoryTelemetryKeySet, t as MemoryTelemetryReceiptService } from "../../../memory-telemetry-receipts-MAJecvXQ.js";
+import { i as MemoryTelemetryEventType, o as MemoryTelemetryReceiptStatus } from "../../../memory-telemetry-types-CufVmrCs.js";
+import { r as MemoryTelemetryUsageOutbox } from "../../../memory-telemetry-outbox-ddTdImt7.js";
+//#region src/engine/telemetry/memory-telemetry-purge.d.ts
+type MemoryTelemetryPurgeActor = "agent" | "operator";
+type MemoryTelemetryPurgeStatus = "complete" | "partial" | "blocked";
+interface MemoryTelemetryPurgePreviewOptions {
+  actor?: MemoryTelemetryPurgeActor;
+}
+interface MemoryTelemetryPurgePreview {
+  targetFactId: string;
+  affectedFactIds: string[];
+  downstreamFactIds: string[];
+  affectedFactCount: number;
+  recentRecallCount: number;
+  affectedEpochIds: string[];
+  blocked: boolean;
+  blockedReason?: "cycle_detected";
+}
+interface MemoryTelemetryConfirmPurgeInput {
+  factId: string;
+  actor: MemoryTelemetryPurgeActor;
+  confirmationToken: string;
+}
+interface MemoryTelemetryPurgeResult {
+  targetFactId: string;
+  status: MemoryTelemetryPurgeStatus;
+  purgedFactIds: string[];
+  failedFactIds: string[];
+  blockedReason?: "cycle_detected" | "recent_recall";
+}
+//#endregion
+//#region src/engine/telemetry/memory-telemetry-api.d.ts
+export interface CreateMemoryTelemetryApiOptions {
+  sqlite: SqliteDatabaseLike;
+  usageOutbox?: MemoryTelemetryUsageOutbox;
+  keySet?: MemoryTelemetryKeySet;
+  key?: string;
+  historicKeys?: readonly string[];
+  receiptService?: MemoryTelemetryReceiptService;
+  agentId?: string;
+}
+export interface MemoryTelemetryLatestReceipt {
+  eventId: number;
+  factId: string;
+  memoryRowId: string | null;
+  contentHash: string;
+  timestampMs: number;
+  receiptHmac: string;
+  keyVersion: number;
+  status: MemoryTelemetryReceiptStatus;
+}
+export interface MemoryTelemetryVerifyReceiptResult {
+  status: MemoryTelemetryReceiptStatus;
+  requestedFactId: string;
+  terminalFactId: string;
+  latestReceipt: MemoryTelemetryLatestReceipt;
+  historicalReceipts: MemoryTelemetryLatestReceipt[];
+}
+export interface MemoryTelemetryProvenanceNode {
+  eventId: number;
+  eventType: MemoryTelemetryEventType;
+  factId: string | null;
+  timestampMs: number;
+  sourceEventId: number | null;
+  derivedFrom: string[];
+}
+export interface MemoryTelemetryProvenanceChain {
+  factId: string;
+  currentState: "active" | "superseded" | "deleted" | "purged" | "missing";
+  nodes: MemoryTelemetryProvenanceNode[];
+}
+export interface MemoryTelemetryUsageSummaryInput {
+  factId?: string;
+  agentId?: string;
+  projectId?: string;
+  window?: {
+    sinceMs?: number;
+    untilMs?: number;
+  };
+}
+export interface MemoryTelemetryUsageSummaryResult {
+  factId?: string;
+  agentId?: string;
+  recallCount: number;
+  injectionCount: number;
+  lastRecalledAt: number | null;
+  lastInjectedAt: number | null;
+  source: "local";
+  cloudForwarding: "ignored";
+  tenantBoundary: {
+    status: "unavailable";
+    queryTenantId: null;
+    resultTenantId: null;
+  };
+}
+export interface MemoryTelemetryRecallTraceInput {
+  sessionUuid?: string;
+  turnId?: string;
+}
+export interface MemoryTelemetryRecallTraceEvent {
+  eventId: number | null;
+  factId: string;
+  timestampMs: number;
+  rank: number | null;
+  score: number | null;
+  agentId: string | null;
+  projectId: string | null;
+  source: "nodix_memory_events" | "nodix_memory_usage_outbox";
+}
+export interface MemoryTelemetryRecallTrace {
+  sessionUuid: string;
+  turnId: string;
+  events: MemoryTelemetryRecallTraceEvent[];
+}
+export interface MemoryTelemetryEpochReport {
+  epochId: string;
+  status: "synthetic" | "real" | "unavailable";
+  boundaryEvents: number[];
+  createdFactIds: string[];
+  supersededFactIds: string[];
+}
+export interface MemoryTelemetryApi {
+  verifyReceipt(factId: string): MemoryTelemetryVerifyReceiptResult;
+  provenanceChain(factId: string, depth?: number): MemoryTelemetryProvenanceChain;
+  editImpactPreview(factId: string, options?: MemoryTelemetryPurgePreviewOptions): MemoryTelemetryPurgePreview;
+  confirmPurge(input: MemoryTelemetryConfirmPurgeInput): MemoryTelemetryPurgeResult;
+  usageSummary(input: MemoryTelemetryUsageSummaryInput): MemoryTelemetryUsageSummaryResult;
+  recallTrace(input: MemoryTelemetryRecallTraceInput): MemoryTelemetryRecallTrace;
+  epochReport(epochId: string): MemoryTelemetryEpochReport;
+}
+export declare function createMemoryTelemetryApi(options: CreateMemoryTelemetryApiOptions): MemoryTelemetryApi;
+//#endregion