@snoai/memory 0.0.0-stage → 1.0.1

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

@@ -0,0 +1,2 @@
+import { C as RemVerdictCheckpoint, D as parseRemOperationType, E as assertJobIdentity, S as RemUpdateRewriteConfig, T as WriteTextVersionInput, _ as RemOwner, a as REM_ROW_STATES, b as RemStatementLike, c as RemConfig, d as RemEnableGateArtifact, f as RemForgetPort, g as RemOperationType, h as RemMutationResult, i as REM_OPERATION_TYPES, l as RemConflictPort, m as RemMutationRefusalReason, n as REM_BUILT_OPERATION_TYPES, o as RemBuiltOperationType, p as RemJobState, r as REM_JOB_STATES, s as RemClockPort, t as MoveLaneInput, u as RemDatabaseLike, v as RemPorts, w as SoftCloseInput, x as RemTransactionLike, y as RemRowState } from "../../../types-pVomjzqR.js";
+export { MoveLaneInput, REM_BUILT_OPERATION_TYPES, REM_JOB_STATES, REM_OPERATION_TYPES, REM_ROW_STATES, RemBuiltOperationType, RemClockPort, RemConfig, RemConflictPort, RemDatabaseLike, RemEnableGateArtifact, RemForgetPort, RemJobState, RemMutationRefusalReason, RemMutationResult, RemOperationType, RemOwner, RemPorts, RemRowState, RemStatementLike, RemTransactionLike, RemUpdateRewriteConfig, RemVerdictCheckpoint, SoftCloseInput, WriteTextVersionInput, assertJobIdentity, parseRemOperationType };

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

@@ -0,0 +1,40 @@
+//#region src/engine/rem/types.ts
+const REM_OPERATION_TYPES = [
+	"rem-update",
+	"rem-replace",
+	"rem-distill",
+	"rem-retire"
+];
+const REM_BUILT_OPERATION_TYPES = ["rem-update", "rem-replace"];
+function parseRemOperationType(value) {
+	for (const operation of REM_OPERATION_TYPES) if (value === operation) return operation;
+}
+const REM_JOB_STATES = [
+	"queued",
+	"running",
+	"done",
+	"failed"
+];
+const REM_ROW_STATES = [
+	"transition",
+	"stale-current",
+	"pure-negation",
+	"ambiguous"
+];
+/**
+* Refuses a write whose audit identity is not real. A required `string` is not proof of one:
+* TypeScript accepts `""`, the journal's `job_id`/`job_type` columns are `NOT NULL` but not
+* non-blank, and a JavaScript caller can omit the field entirely.
+*
+* No valid identity, no write — the whole operation is refused before any transaction opens. This
+* does not rescue the write; it refuses it, which is the intended trade: an unattributable row in
+* the audit ledger is worse than a refused operation the caller can see and retry.
+*
+* The accepted set is `REM_OPERATION_TYPES` itself, so the runtime check and the type cannot drift.
+*/
+function assertJobIdentity(jobId, jobType) {
+	if (typeof jobId !== "string" || jobId.trim().length === 0) throw new Error(`REM write requires a non-blank job id, got: ${String(jobId)}`);
+	if (typeof jobType !== "string" || parseRemOperationType(jobType) === void 0) throw new Error(`REM write requires a known job type, got: ${String(jobType)}`);
+}
+//#endregion
+export { REM_BUILT_OPERATION_TYPES, REM_JOB_STATES, REM_OPERATION_TYPES, REM_ROW_STATES, assertJobIdentity, parseRemOperationType };

package/dist/internal/engine/retrieval/access-tracker.d.ts

@@ -0,0 +1,2 @@
+import { a as computeEffectiveHalfLife, i as buildUpdatedMetadata, n as AccessTracker, o as parseAccessMetadata, r as AccessTrackerOptions, t as AccessMetadata } from "../../../access-tracker-BbEvEocb.js";
+export { AccessMetadata, AccessTracker, AccessTrackerOptions, buildUpdatedMetadata, computeEffectiveHalfLife, parseAccessMetadata };

package/dist/internal/engine/retrieval/access-tracker.js

@@ -0,0 +1,314 @@
+import { DEFAULT_RECALL_LIFECYCLE } from "../../config/index.js";
+import { createLogger } from "@snoai/utils/logger";
+//#region src/engine/retrieval/access-tracker.ts
+/** @file access-tracker.ts
+* @purpose Tracks memory access signals that feed recency, ranking, and decay decisions.
+* @boundary Memory store metadata and retrieval result identifiers.
+* @see store.ts, retriever.ts, selective-forgetting-scorer.ts, retrieval-stats.ts.
+*/
+/**
+* Access Tracker
+*
+* Tracks memory access patterns to support reinforcement-based decay.
+* Frequently accessed memories decay more slowly (longer effective half-life).
+*/
+const log = createLogger("sno-station-mem:access-tracker");
+const MIN_ACCESS_COUNT = 0;
+const LEGACY_MAX_ACCESS_COUNT = 1e4;
+/** Default debounce interval before flushing pending writes (5 seconds) */
+const DEFAULT_DEBOUNCE_MS = 5e3;
+const MAX_RETRY_DELAY_MS = 6e4;
+const MAX_WRITE_FAILURES_PER_ID = 5;
+/** Access count itself decays with a 30-day half-life */
+const ACCESS_DECAY_HALF_LIFE_DAYS = 30;
+/** Implements clamp access count as the local access reinforcement metadata operation. */
+function clampAccessCount(value, ceiling = LEGACY_MAX_ACCESS_COUNT) {
+	if (!Number.isFinite(value)) return MIN_ACCESS_COUNT;
+	return Math.min(ceiling, Math.max(MIN_ACCESS_COUNT, Math.floor(value)));
+}
+/**
+* Parse access-related fields from a metadata JSON string.
+*
+* Handles: undefined, empty string, malformed JSON, negative numbers,
+* numbers exceeding 10000. Always returns a valid AccessMetadata.
+*/
+function parseAccessMetadata(metadata) {
+	if (metadata === void 0 || metadata === "") return {
+		accessCount: 0,
+		lastAccessedAt: 0
+	};
+	let parsed;
+	try {
+		parsed = JSON.parse(metadata);
+	} catch {
+		return {
+			accessCount: 0,
+			lastAccessedAt: 0
+		};
+	}
+	if (typeof parsed !== "object" || parsed === null) return {
+		accessCount: 0,
+		lastAccessedAt: 0
+	};
+	const obj = parsed;
+	const rawCountAny = obj.accessCount ?? obj.access_count;
+	const rawCount = typeof rawCountAny === "number" ? rawCountAny : Number(rawCountAny ?? 0);
+	const rawLastAny = obj.lastAccessedAt ?? obj.last_accessed_at;
+	const rawLastAccessed = typeof rawLastAny === "number" ? rawLastAny : Number(rawLastAny ?? 0);
+	return {
+		accessCount: clampAccessCount(rawCount),
+		lastAccessedAt: Number.isFinite(rawLastAccessed) && rawLastAccessed >= 0 ? rawLastAccessed : 0
+	};
+}
+/**
+* Merge an access-count increment into existing metadata JSON.
+*
+* Preserves ALL existing fields in the metadata object — only overwrites
+* `accessCount` and `lastAccessedAt`. Returns a new JSON string.
+*/
+function buildUpdatedMetadata(existingMetadata, accessDelta, ceiling = LEGACY_MAX_ACCESS_COUNT) {
+	let existing = {};
+	if (existingMetadata !== void 0 && existingMetadata !== "") try {
+		const parsed = JSON.parse(existingMetadata);
+		if (typeof parsed === "object" && parsed !== null) existing = { ...parsed };
+	} catch {}
+	const newCount = clampAccessCount(parseAccessMetadata(existingMetadata).accessCount + accessDelta, ceiling);
+	const now = Date.now();
+	return JSON.stringify({
+		...existing,
+		accessCount: newCount,
+		lastAccessedAt: now,
+		access_count: newCount,
+		last_accessed_at: now
+	});
+}
+/**
+* Compute the effective half-life for a memory based on its access history.
+*
+* The access count itself decays over time (30-day half-life for access
+* freshness), so stale accesses contribute less reinforcement. The extension
+* uses a logarithmic curve (`Math.log1p`) to provide diminishing returns.
+*
+* @param baseHalfLife        - Base half-life in days (e.g. 30)
+* @param accessCount         - Raw number of times the memory was accessed
+* @param lastAccessedAt      - Timestamp (ms) of last access
+* @param reinforcementFactor - Scaling factor for reinforcement (0 = disabled)
+* @param maxMultiplier       - Hard cap: result <= baseHalfLife * maxMultiplier
+* @returns Effective half-life in days
+*/
+function computeEffectiveHalfLife(baseHalfLife, accessCount, lastAccessedAt, reinforcementFactor, maxMultiplier, now = Date.now()) {
+	if (reinforcementFactor === 0 || accessCount <= 0) return baseHalfLife;
+	const daysSinceLastAccess = Math.max(0, (now - lastAccessedAt) / 864e5);
+	const effectiveAccessCount = accessCount * Math.exp(-daysSinceLastAccess * (Math.LN2 / ACCESS_DECAY_HALF_LIFE_DAYS));
+	const result = baseHalfLife + baseHalfLife * reinforcementFactor * Math.log1p(effectiveAccessCount);
+	const cap = baseHalfLife * maxMultiplier;
+	return Math.min(result, cap);
+}
+/**
+* Debounced write-back tracker for memory access events.
+*
+* `recordAccess()` is synchronous (Map update only, no I/O). Pending deltas
+* accumulate until `flush()` is called (or after debounceMs timeout).
+* On flush, each pending entry is read via `store.getById()`, its metadata
+* is merged with the accumulated access delta, and written back via
+* `store.update()`.
+*/
+var AccessTracker = class {
+	pending = /* @__PURE__ */ new Map();
+	debounceTimer;
+	flushPromise;
+	debounceMs;
+	store;
+	retryDelayMs;
+	writeFailures = /* @__PURE__ */ new Map();
+	destroying = false;
+	recallLifecycle;
+	clampedOnce = /* @__PURE__ */ new Set();
+	/**
+	* Initializes access reinforcement metadata collaborators while keeping runtime work in
+	* explicit methods.
+	*/
+	constructor(options) {
+		this.store = options.store;
+		this.debounceMs = options.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+		this.retryDelayMs = this.debounceMs;
+		this.recallLifecycle = options.recallLifecycle ?? DEFAULT_RECALL_LIFECYCLE;
+	}
+	/**
+	* Record one access for each of the given memory IDs.
+	* Synchronous — only updates the in-memory pending map.
+	*/
+	recordAccess(ids) {
+		if (this.destroying) return;
+		for (const id of ids) {
+			const current = this.pending.get(id) ?? 0;
+			this.pending.set(id, current + 1);
+		}
+		this.resetTimer();
+	}
+	/** Return a snapshot of all pending (id -> delta) entries. */
+	getPendingUpdates() {
+		return new Map(this.pending);
+	}
+	/**
+	* Flush pending access deltas to the store.
+	*
+	* If a flush is already in progress, awaits the current flush to complete.
+	* If new pending data accumulated during the in-flight flush, a follow-up
+	* flush is automatically triggered.
+	*/
+	async flush() {
+		this.clearTimer();
+		if (this.flushPromise) {
+			await this.flushPromise;
+			if (this.pending.size > 0 && !this.destroying) this.scheduleRetry();
+			return;
+		}
+		if (this.pending.size === 0) return;
+		this.flushPromise = this.doFlush();
+		try {
+			await this.flushPromise;
+		} finally {
+			this.flushPromise = void 0;
+		}
+		if (this.pending.size > 0) {
+			if (!this.destroying) this.scheduleRetry();
+			return;
+		}
+		this.retryDelayMs = this.debounceMs;
+	}
+	/** Tear down the tracker with one final best-effort flush. */
+	async destroy() {
+		this.destroying = true;
+		this.clearTimer();
+		if (this.flushPromise) await this.flushPromise;
+		if (this.pending.size > 0) await this.doFlush();
+		if (this.pending.size > 0) log.warn("destroying with pending writes", { pendingCount: this.pending.size }, {
+			event_name: "sno_station_mem.access-tracker.destroying.with.pending.writes",
+			file: "packages/memory/src/engine/retrieval/access-tracker.ts",
+			function: "destroy",
+			site_id: "access-tracker.destroy.5991e0f580"
+		});
+		this.pending.clear();
+		this.writeFailures.clear();
+		this.retryDelayMs = this.debounceMs;
+	}
+	/**
+	* Flushes all pending deltas in ONE store call (one mutex acquisition + one
+	* transaction), instead of the historical per-id mutex+transaction+full
+	* update() round trip. Policy (rate-limit window, ceiling clamp) stays here,
+	* delivered through per-id delta callbacks; the store only merges and writes.
+	*/
+	async doFlush() {
+		const batch = new Map(this.pending);
+		this.pending.clear();
+		if (batch.size === 0) return;
+		try {
+			const entries = Array.from(batch).flatMap(([id, delta]) => {
+				if (this.store.getById(id)?.category !== "episodic") return [];
+				return [{
+					memoryId: id,
+					deltaFn: (current) => this.buildAccessDelta(id, delta, current)
+				}];
+			});
+			await this.store.applyMetadataDeltas(entries);
+			for (const id of batch.keys()) this.writeFailures.delete(id);
+		} catch (err) {
+			for (const [id, delta] of batch) {
+				const failures = (this.writeFailures.get(id) ?? 0) + 1;
+				if (failures >= MAX_WRITE_FAILURES_PER_ID) {
+					this.writeFailures.delete(id);
+					log.warn("dropping access delta after repeated write failures", {
+						memory_id: id,
+						failures,
+						error: err
+					}, {
+						event_name: "sno_station_mem.access-tracker.dropping.access.delta.after.repeated.write.failures",
+						file: "packages/memory/src/engine/retrieval/access-tracker.ts",
+						function: "doFlush",
+						site_id: "access-tracker.doFlush.b3bb3939f2"
+					});
+					continue;
+				}
+				this.writeFailures.set(id, failures);
+				this.pending.set(id, (this.pending.get(id) ?? 0) + delta);
+			}
+			log.warn("access flush batch failed", {
+				batchSize: batch.size,
+				error: err,
+				committed_count: 0
+			}, {
+				event_name: "sno_station_mem.access-tracker.access.flush.batch.failed",
+				file: "packages/memory/src/engine/retrieval/access-tracker.ts",
+				function: "doFlush",
+				site_id: "access-tracker.doFlush.f82865a307"
+			});
+		}
+	}
+	/**
+	* Per-id policy transform executed inside the store's batch transaction.
+	* Returns undefined to skip the write (rate-limited). Both metadata key
+	* styles are written — see the cross-subsystem naming note on
+	* buildUpdatedMetadata.
+	*/
+	buildAccessDelta(id, delta, current) {
+		const record = current;
+		const rawCount = record.accessCount ?? record.access_count;
+		const prevCount = clampAccessCount(typeof rawCount === "number" ? rawCount : Number(rawCount ?? 0));
+		const rawLast = record.lastAccessedAt ?? record.last_accessed_at;
+		const prevLastRaw = typeof rawLast === "number" ? rawLast : Number(rawLast ?? 0);
+		const prevLast = Number.isFinite(prevLastRaw) && prevLastRaw >= 0 ? prevLastRaw : 0;
+		const now = Date.now();
+		let ceiling = LEGACY_MAX_ACCESS_COUNT;
+		if (this.recallLifecycle.autoRecallAccessTracking) {
+			ceiling = this.recallLifecycle.accessCountCeiling;
+			if (prevLast > 0 && now - prevLast < this.recallLifecycle.accessRateLimitMs) return void 0;
+			if (prevCount > ceiling && !this.clampedOnce.has(id)) {
+				this.clampedOnce.add(id);
+				log.warn("legacy access count clamped to ceiling", {
+					memory_id: id,
+					previousCount: prevCount,
+					ceiling
+				}, {
+					event_name: "sno_station_mem.access-tracker.legacy.access.count.clamped.to.ceiling",
+					file: "packages/memory/src/engine/retrieval/access-tracker.ts",
+					function: "buildAccessDelta",
+					site_id: "access-tracker.buildAccessDelta.4ac8f20936"
+				});
+			}
+		}
+		const newCount = clampAccessCount(prevCount + delta, ceiling);
+		return {
+			accessCount: newCount,
+			lastAccessedAt: now,
+			access_count: newCount,
+			last_accessed_at: now
+		};
+	}
+	/** Implements reset timer as the local access reinforcement metadata operation. */
+	resetTimer() {
+		this.resetTimerWithDelay(this.debounceMs);
+	}
+	/** Implements schedule retry as the local access reinforcement metadata operation. */
+	scheduleRetry() {
+		this.retryDelayMs = Math.min(this.retryDelayMs * 2, MAX_RETRY_DELAY_MS);
+		this.resetTimerWithDelay(this.retryDelayMs);
+	}
+	/** Implements reset timer with delay as the local access reinforcement metadata operation. */
+	resetTimerWithDelay(delayMs) {
+		if (this.destroying) return;
+		this.clearTimer();
+		this.debounceTimer = setTimeout(() => {
+			this.flush();
+		}, delayMs);
+	}
+	/** Removes timer while preserving access reinforcement metadata invariants. */
+	clearTimer() {
+		if (this.debounceTimer !== void 0) {
+			clearTimeout(this.debounceTimer);
+			this.debounceTimer = void 0;
+		}
+	}
+};
+//#endregion
+export { AccessTracker, buildUpdatedMetadata, computeEffectiveHalfLife, parseAccessMetadata };

package/dist/internal/engine/retrieval/intent-analyzer.d.ts

@@ -0,0 +1,2 @@
+import { t as formatAtDepth } from "../../../intent-analyzer-B5XVrWwe.js";
+export { formatAtDepth };

package/dist/internal/engine/retrieval/intent-analyzer.js

@@ -0,0 +1,27 @@
+//#region src/engine/retrieval/intent-analyzer.ts
+/** @file intent-analyzer.ts
+* @purpose Renders a recalled memory as one line of text for context injection.
+* @boundary Pure formatting; no query parsing, no pattern banks, no locale rules.
+*
+* The name is historical. This file used to read the query's wording through nine locale rule
+* banks and return a category set plus a rendering depth: a match restricted which categories
+* were eligible and how much of each memory was shown, and a miss returned the shortest form.
+* All of it was deleted on 2026-08-21 — a keyword may hint at scoring, never decide the path or
+* shorten the answer. What survived is the renderer below.
+*/
+/**
+* Format a memory entry as one line for context injection.
+*
+* One form only: the complete text. The shorter tiers were chosen from the query's wording, so
+* a question phrased outside the pattern banks received the shortest one. Deleted 2026-08-21.
+*/
+function formatAtDepth(entry, score, _index, extra) {
+	const scoreStr = `${(score * 100).toFixed(0)}%`;
+	const sourceSuffix = [extra?.bm25Hit ? "vector+BM25" : null, extra?.reranked ? "+reranked" : null].filter(Boolean).join("");
+	const sourceTag = sourceSuffix ? `, ${sourceSuffix}` : "";
+	const safe = extra?.sanitize ? extra.sanitize(entry.text) : entry.text;
+	const datePrefix = extra?.eventDate ? `[${extra.eventDate}] ` : "";
+	return `- [${entry.category}] ${datePrefix}${safe} (${scoreStr}${sourceTag})`;
+}
+//#endregion
+export { formatAtDepth };

package/dist/internal/engine/retrieval/retrieval-gate.d.ts

@@ -0,0 +1,2 @@
+import { n as shouldSkipRetrieval, t as normalizeQuery } from "../../../retrieval-gate-Bx2Zg7jD.js";
+export { normalizeQuery, shouldSkipRetrieval };

package/dist/internal/engine/retrieval/retrieval-gate.js

@@ -0,0 +1,47 @@
+//#region src/engine/retrieval/retrieval-gate.ts
+/** @file retrieval-gate.ts
+* @purpose Decides whether a query needs memory retrieval at all (skip vs proceed).
+* @boundary Intent analysis, temporal classification, and retrieval configuration.
+* @see intent-analyzer.ts, memory-temporality-classifier.ts, retriever.ts.
+*/
+/**
+* Retrieval Gate
+* Determines whether a query needs memory retrieval at all.
+* Skips retrieval for greetings, commands, simple instructions, and system messages.
+* Saves embedding API calls and reduces noise injection.
+*/
+/**
+* Strip SnoStationMem metadata headers, cron wrappers, and timestamp prefixes
+* so that the raw user intent is what gets evaluated by skip/force patterns.
+*/
+function normalizeQuery(raw) {
+	let q = raw;
+	q = q.replace(/^(Conversation info|Sender) \(untrusted metadata\):[\s\S]*?\n\s*\n/gim, "");
+	q = q.replace(/\[cron:[^\]]*\]\s*/gi, "");
+	q = q.replace(/\[\w{3}\s+\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}(?:\s+[\w/+-]+)?\]\s*/g, "");
+	return q.trim();
+}
+/**
+* The floor below which there is nothing to search FOR — not a judgement about whether a query
+* deserves a search. Mirrors the `autoRecallMinLength` default in the plugin config schema; the
+* two must not drift.
+*/
+const RETRIEVAL_MIN_QUERY_CHARS = 2;
+/**
+* Decide whether a query is too short to search on. Length only.
+*
+* There is deliberately NO pattern list here. Until 2026-08-21 this function also read 118 skip
+* and force-retrieve regexes across nine locale bundles, and a match on a negative one meant the
+* turn was never searched at all — a keyword deciding the control flow, which is the shape this
+* repository forbids. Retrieval is a local SQLite plus local-embedding search; the cost argument
+* that justified a gate does not hold, and whether a result is relevant belongs to scoring.
+*
+* @param minLength - Override minimum length threshold (for autoRecallMinLength support).
+*/
+function shouldSkipRetrieval(query, minLength) {
+	const trimmed = normalizeQuery(query);
+	const effectiveMinLength = minLength ?? RETRIEVAL_MIN_QUERY_CHARS;
+	return trimmed.length < effectiveMinLength && !trimmed.includes("?") && !trimmed.includes("？");
+}
+//#endregion
+export { normalizeQuery, shouldSkipRetrieval };

package/dist/internal/engine/retrieval/retriever.d.ts

@@ -0,0 +1,2 @@
+import { a as RerankFallbackSignal, c as collectParallelStage, d as RetrievalConfig, f as RetrievalContext, i as RerankFallbackReason, l as DEFAULT_RETRIEVAL_CONFIG, n as MemoryRetrieverInternals, o as RerankOutcome, p as withServingValidityDefault, r as RERANK_FALLBACK_REASONS, s as createRetriever, t as MemoryRetriever, u as RerankProvider } from "../../../retriever-Dxss5fRv.js";
+export { DEFAULT_RETRIEVAL_CONFIG, MemoryRetriever, MemoryRetrieverInternals, RERANK_FALLBACK_REASONS, RerankFallbackReason, RerankFallbackSignal, RerankOutcome, RerankProvider, RetrievalConfig, RetrievalContext, collectParallelStage, createRetriever, withServingValidityDefault };

package/dist/internal/engine/retrieval/retriever.js

@@ -0,0 +1,2 @@
+import { a as DEFAULT_RETRIEVAL_CONFIG, i as createRetriever, n as MemoryRetriever, o as withServingValidityDefault, r as RERANK_FALLBACK_REASONS, t as collectParallelStage } from "../../../retriever-ZoLvPRHq.js";
+export { DEFAULT_RETRIEVAL_CONFIG, MemoryRetriever, RERANK_FALLBACK_REASONS, collectParallelStage, createRetriever, withServingValidityDefault };

package/dist/internal/engine/security/memory-scope-policy.d.ts

@@ -0,0 +1,2 @@
+import { n as createScopePolicy, t as MemoryScopePolicy } from "../../../memory-scope-policy-1gg5QlWZ.js";
+export { MemoryScopePolicy, createScopePolicy };

package/dist/internal/engine/security/memory-scope-policy.js

@@ -0,0 +1,2 @@
+import { n as createScopePolicy, t as MemoryScopePolicy } from "../../../memory-scope-policy-DICSCURA.js";
+export { MemoryScopePolicy, createScopePolicy };

package/dist/internal/engine/security/redact.d.ts

@@ -0,0 +1,2 @@
+import { t as redactSecrets } from "../../../redact-BTIZcHQL.js";
+export { redactSecrets };

package/dist/internal/engine/security/redact.js

@@ -0,0 +1,34 @@
+import { redactForStorage } from "@snoai/content-sanitizer";
+//#region src/engine/security/redact.ts
+/** @file redact.ts
+* @purpose Redacts sensitive values before logs, diagnostics, or model-visible text.
+* @boundary Security boundaries, capture payloads, and CLI output hygiene.
+* @see capture-policy-detector.ts, memory-management-cli.ts, memory-tool-registration.ts.
+*/
+const REDACTED_SECRET = "[REDACTED_SECRET]";
+const NAMED_CREDENTIAL_PATTERN = /\b[A-Za-z0-9]+_(?:live|key|secret|token)_[A-Za-z0-9][A-Za-z0-9_-]{11,}\b/gi;
+const LABELED_CREDENTIAL_PATTERN = /\b((?:api[\s_-]*key|access[\s_-]*token|refresh[\s_-]*token|auth[\s_-]*token|password|passphrase|secret|credential|token)\s*(?:is|was|=|:)\s*)([A-Za-z0-9][A-Za-z0-9._/+=$:-]{11,})/gi;
+const LONG_ALPHANUMERIC_PATTERN = /\b[A-Za-z0-9]{32,}\b/g;
+function isHighEntropyCredentialCandidate(value) {
+	if (/^[A-Fa-f0-9]+$/.test(value)) return false;
+	if (!/[A-Za-z]/.test(value) || !/\d/.test(value)) return false;
+	const counts = /* @__PURE__ */ new Map();
+	for (const character of value) counts.set(character, (counts.get(character) ?? 0) + 1);
+	return [...counts.values()].reduce((total, count) => {
+		const probability = count / value.length;
+		return total - probability * Math.log2(probability);
+	}, 0) >= 3.2;
+}
+function redactGenericCredentials(text) {
+	return text.replace(NAMED_CREDENTIAL_PATTERN, REDACTED_SECRET).replace(LABELED_CREDENTIAL_PATTERN, (_match, label) => `${label}${REDACTED_SECRET}`).replace(LONG_ALPHANUMERIC_PATTERN, (value) => isHighEntropyCredentialCandidate(value) ? REDACTED_SECRET : value);
+}
+/** Redacts provider-specific and conservative generic credential forms. */
+function redactSecrets(text) {
+	const providerRedacted = redactForStorage(text, {
+		source: "generic-text",
+		contentType: "plain_text"
+	}).text;
+	return redactGenericCredentials(providerRedacted);
+}
+//#endregion
+export { redactSecrets };

package/dist/internal/engine/security/scopes.d.ts

@@ -0,0 +1,3 @@
+import { a as ScopeConfig, i as SCOPE_PATTERNS, n as createScopePolicy, o as ScopeDefinition, r as DEFAULT_SCOPE_CONFIG, s as ScopePolicy, t as MemoryScopePolicy } from "../../../memory-scope-policy-1gg5QlWZ.js";
+import { a as createCustomScope, c as filterScopesForAgent, d as resolveScopeFilter, i as createAgentScope, l as isScopeAccessible, n as isSystemBypassId, o as createProjectScope, r as parseAgentIdFromSessionKey, s as createUserScope, t as _resetLegacyFallbackWarningState, u as parseScopeId } from "../../../scopes-CtrY-YQ3.js";
+export { DEFAULT_SCOPE_CONFIG, MemoryScopePolicy, SCOPE_PATTERNS, type ScopeConfig, type ScopeDefinition, type ScopePolicy, _resetLegacyFallbackWarningState, createAgentScope, createCustomScope, createProjectScope, createScopePolicy, createUserScope, filterScopesForAgent, isScopeAccessible, isSystemBypassId, parseAgentIdFromSessionKey, parseScopeId, resolveScopeFilter };

package/dist/internal/engine/security/scopes.js

@@ -0,0 +1,3 @@
+import { a as parseAgentIdFromSessionKey, c as SCOPE_PATTERNS, i as isSystemBypassId, n as createScopePolicy, r as _resetLegacyFallbackWarningState, s as DEFAULT_SCOPE_CONFIG, t as MemoryScopePolicy } from "../../../memory-scope-policy-DICSCURA.js";
+import { a as filterScopesForAgent, c as resolveScopeFilter, i as createUserScope, n as createCustomScope, o as isScopeAccessible, r as createProjectScope, s as parseScopeId, t as createAgentScope } from "../../../scopes-CSOn6zdd.js";
+export { DEFAULT_SCOPE_CONFIG, MemoryScopePolicy, SCOPE_PATTERNS, _resetLegacyFallbackWarningState, createAgentScope, createCustomScope, createProjectScope, createScopePolicy, createUserScope, filterScopesForAgent, isScopeAccessible, isSystemBypassId, parseAgentIdFromSessionKey, parseScopeId, resolveScopeFilter };

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

@@ -0,0 +1,2 @@
+import { a as StorageError, i as SnoStationMemError, n as EmbeddingError, r as RetrievalError, t as ConfigError } from "../../../errors-CeVRxf9V.js";
+export { ConfigError, EmbeddingError, RetrievalError, SnoStationMemError, StorageError };

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

@@ -0,0 +1,66 @@
+//#region src/engine/shared/errors.ts
+/** @file errors.ts
+* @purpose Defines typed plugin errors and stable codes for callers and CLI output.
+* @boundary Runtime boundaries, CLI error mapping, and test assertions.
+* @see memory-management-cli.ts, sno-station-mem-plugin-runtime.ts, memory-tool-registration.ts.
+*/
+var SnoStationMemError = class extends Error {
+	code;
+	/**
+	* Initializes typed error reporting collaborators while keeping runtime work in explicit
+	* methods.
+	*/
+	constructor(code, message, cause) {
+		super(message, cause ? { cause } : void 0);
+		this.name = "SnoStationMemError";
+		this.code = code;
+	}
+};
+var StorageError = class extends SnoStationMemError {
+	/**
+	* Initializes typed error reporting collaborators while keeping runtime work in explicit
+	* methods.
+	*/
+	constructor(message, cause) {
+		super("storage_error", message, cause);
+		this.name = "StorageError";
+	}
+};
+var EmbeddingError = class extends SnoStationMemError {
+	/**
+	* Initializes typed error reporting collaborators while keeping runtime work in explicit
+	* methods.
+	*/
+	constructor(message, cause) {
+		super("embedding_error", message, cause);
+		this.name = "EmbeddingError";
+	}
+};
+var RetrievalError = class extends SnoStationMemError {
+	/**
+	* Carries the cause's own message in `message`, not only in `cause`.
+	*
+	* Retrieval wraps every failure as "Failed to retrieve memories", and every consumer that
+	* reports one — a tool result, an eval harness, an HTTP boundary — reports `message` and drops
+	* the Error. Measured 2026-09-04: a whole evaluation round scored nothing and the only trace
+	* on disk was fifteen identical copies of that sentence, so the reason had to be re-derived by
+	* reproducing the run. The cause stays attached as well; this only makes it survive the trip.
+	*/
+	constructor(message, cause) {
+		const reason = cause instanceof Error ? cause.message : void 0;
+		super("retrieval_error", reason ? `${message}: ${reason}` : message, cause);
+		this.name = "RetrievalError";
+	}
+};
+var ConfigError = class extends SnoStationMemError {
+	/**
+	* Initializes typed error reporting collaborators while keeping runtime work in explicit
+	* methods.
+	*/
+	constructor(message, cause) {
+		super("config_error", message, cause);
+		this.name = "ConfigError";
+	}
+};
+//#endregion
+export { ConfigError, EmbeddingError, RetrievalError, SnoStationMemError, StorageError };

package/dist/internal/engine/shared/i18n-text.d.ts

@@ -0,0 +1,2 @@
+import { a as stripRoleLabelPrefix, c as unicodeBoundaryRegex, i as stripHtmlTags, n as boundaryAwareRegex, o as tokenizeForFts, r as normalizeForCompare, s as truncateGraphemes, t as HTML_TAG_PATTERN } from "../../../i18n-text-DbD6Qify.js";
+export { HTML_TAG_PATTERN, boundaryAwareRegex, normalizeForCompare, stripHtmlTags, stripRoleLabelPrefix, tokenizeForFts, truncateGraphemes, unicodeBoundaryRegex };

package/dist/internal/engine/shared/i18n-text.js

@@ -0,0 +1,58 @@
+//#region src/engine/shared/i18n-text.ts
+/** @file i18n-text.ts
+* @purpose Shared Unicode-aware text helpers for multilingual memory paths.
+* @boundary Pure string/RegExp helpers only; no locale detection or persistence.
+*/
+const REGEXP_SPECIAL_CHARS = /[.*+?^${}()|[\]\\]/g;
+const CJK_CHAR_PATTERN = /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}]/u;
+const LETTER_OR_NUMBER = String.raw`[\p{L}\p{N}]`;
+const HTML_TAG_PATTERN = /<!--[\s\S]*?(?:-->|$)|<\/?[A-Za-z][^>]*>/g;
+const ROLE_LABEL_PREFIX_PATTERN = /(^|\n)([ \t]*)(system|assistant|user|developer|tool|function)\s*:/giu;
+function withUnicodeFlag(flags) {
+	return flags.includes("u") ? flags : `${flags}u`;
+}
+function escapeRegExp(term) {
+	return term.replace(REGEXP_SPECIAL_CHARS, "\\$&");
+}
+function splitGraphemes(text) {
+	if (typeof Intl.Segmenter !== "function") return [...text];
+	return [...new Intl.Segmenter(void 0, { granularity: "grapheme" }).segment(text)].map((segment) => segment.segment);
+}
+/** Builds a Unicode-aware left/right token-boundary regex around a regex body. */
+function unicodeBoundaryRegex(body, flags = "i") {
+	return new RegExp(`(?<!${LETTER_OR_NUMBER})(?:${body})(?!${LETTER_OR_NUMBER})`, withUnicodeFlag(flags));
+}
+/** Matches CJK terms by substring and alphabetic terms by Unicode token boundaries. */
+function boundaryAwareRegex(term, flags = "i") {
+	const trimmed = term.trim();
+	if (!trimmed) return /(?!)/u;
+	const escaped = escapeRegExp(trimmed);
+	if (CJK_CHAR_PATTERN.test(trimmed)) return new RegExp(escaped, withUnicodeFlag(flags));
+	return unicodeBoundaryRegex(escaped, flags);
+}
+function stripHtmlTags(text) {
+	return text.replace(HTML_TAG_PATTERN, "");
+}
+function stripRoleLabelPrefix(text) {
+	return text.replace(ROLE_LABEL_PREFIX_PATTERN, "$1$2[$3]:");
+}
+function normalizeForCompare(text) {
+	return text.normalize("NFKC").toLocaleLowerCase().replace(/\s+/gu, " ").trim();
+}
+function truncateGraphemes(text, maxGraphemes, suffix = "") {
+	if (maxGraphemes <= 0) return "";
+	const graphemes = splitGraphemes(text);
+	if (graphemes.length <= maxGraphemes) return text;
+	return `${graphemes.slice(0, maxGraphemes).join("").trimEnd()}${suffix}`;
+}
+function tokenizeForFts(rawQuery) {
+	const normalized = normalizeForCompare(rawQuery).replace(/["']/gu, " ").replace(/[^\p{L}\p{N}\s_-]/gu, " ").trim();
+	if (!normalized) return [];
+	if (typeof Intl.Segmenter === "function") {
+		const tokens = [...new Intl.Segmenter(void 0, { granularity: "word" }).segment(normalized)].filter((segment) => segment.isWordLike).map((segment) => segment.segment);
+		if (tokens.length > 0) return tokens;
+	}
+	return normalized.split(/\s+/u).filter(Boolean);
+}
+//#endregion
+export { HTML_TAG_PATTERN, boundaryAwareRegex, normalizeForCompare, stripHtmlTags, stripRoleLabelPrefix, tokenizeForFts, truncateGraphemes, unicodeBoundaryRegex };