@snoai/memory 0.0.0-stage → 1.0.1

package/dist/internal/engine/operations/learning-file-maintenance.js

@@ -0,0 +1,255 @@
+import "../../../signed-registry-constants-yq3DlG3B.js";
+import { i as memoryOperationSignal, n as memoryFileWrite, t as checkMemoryOperation } from "../../../operation-cancellation-CTKWwNHk.js";
+import { createLogger } from "@snoai/utils/logger";
+import { join } from "node:path";
+import { appendFile, mkdir, open, readFile, rm, stat, writeFile } from "node:fs/promises";
+//#region src/engine/operations/learning-file-maintenance.ts
+/** @file learning-file-maintenance.ts
+* @purpose Manages learning files and skill extraction artifacts for improvement loops.
+* @boundary Filesystem layout, markdown records, and promotion state.
+* @see learning-file-hooks.ts, daily-log-generator.ts, memory-tool-registration.ts.
+*/
+const diagnosticLog = createLogger("sno-station-mem:learning-file-maintenance");
+const DEFAULT_LEARNINGS_TEMPLATE = `# Learnings
+
+Append structured entries:
+- LRN-YYYYMMDD-XXX for corrections / best practices / knowledge gaps
+- Include summary, details, suggested action, metadata, and status`;
+const DEFAULT_ERRORS_TEMPLATE = `# Errors
+
+Append structured entries:
+- ERR-YYYYMMDD-XXX for command/tool/integration failures
+- Include symptom, context, probable cause, and prevention`;
+const DEFAULT_FEATURE_REQUESTS_TEMPLATE = `# Feature Requests
+
+Append structured entries:
+- FEAT-YYYYMMDD-XXX for missing capabilities or workflow gaps
+- Include the requested capability, why it matters, and a concrete suggested action`;
+const fileWriteQueues = /* @__PURE__ */ new Map();
+const FILE_APPEND_LOCK_STALE_MS = 3e4;
+const FILE_APPEND_LOCK_RETRY_MS = 25;
+const ENTRY_DESTINATIONS = {
+	learning: {
+		fileName: "LEARNINGS.md",
+		idPrefix: "LRN"
+	},
+	error: {
+		fileName: "ERRORS.md",
+		idPrefix: "ERR"
+	},
+	feature: {
+		fileName: "FEATURE_REQUESTS.md",
+		idPrefix: "FEAT"
+	}
+};
+/** Implements with file write queue as the local self-improvement learning files operation. */
+async function withFileWriteQueue(filePath, action) {
+	const previous = fileWriteQueues.get(filePath) ?? Promise.resolve();
+	let release;
+	const lock = new Promise((resolve) => {
+		release = resolve;
+	});
+	const next = previous.then(() => lock);
+	fileWriteQueues.set(filePath, next);
+	await previous;
+	try {
+		return await action();
+	} finally {
+		release?.();
+		if (fileWriteQueues.get(filePath) === next) fileWriteQueues.delete(filePath);
+	}
+}
+/** Implements today ymd as the local self-improvement learning files operation. */
+function todayYmd() {
+	return (/* @__PURE__ */ new Date()).toISOString().slice(0, 10).replace(/-/g, "");
+}
+/** Implements sleep as the local self-improvement learning files operation. */
+function sleep(ms) {
+	return new Promise((resolve) => {
+		setTimeout(resolve, ms);
+	});
+}
+/** Implements with append lock as the local self-improvement learning files operation. */
+async function withAppendLock(filePath, action) {
+	const lockPath = `${filePath}.lock`;
+	for (;;) {
+		checkMemoryOperation();
+		let handle;
+		try {
+			handle = await open(lockPath, "wx");
+			try {
+				return await action();
+			} finally {
+				await handle.close().catch((error) => {
+					diagnosticLog.warn("Learning lock handle close failed", { error }, {
+						event_name: "memory.learning.lock.close.failed",
+						file: "packages/memory/src/engine/operations/learning-file-maintenance.ts",
+						function: "withAppendLock",
+						site_id: "memory.learning.lock.close.failed"
+					});
+				});
+				await rm(lockPath, { force: true }).catch((error) => {
+					diagnosticLog.warn("Learning lock cleanup failed", { error }, {
+						event_name: "memory.learning.lock.cleanup.failed",
+						file: "packages/memory/src/engine/operations/learning-file-maintenance.ts",
+						function: "withAppendLock",
+						site_id: "memory.learning.lock.cleanup.failed"
+					});
+				});
+			}
+		} catch (error) {
+			if (!(error instanceof Error) || !("code" in error) || error.code !== "EEXIST") throw error;
+			const lockStats = await stat(lockPath).catch((error) => {
+				if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) diagnosticLog.warn("Learning lock metadata unavailable", { error }, {
+					event_name: "memory.learning.lock.stat.failed",
+					file: "packages/memory/src/engine/operations/learning-file-maintenance.ts",
+					function: "withAppendLock",
+					site_id: "memory.learning.lock.stat.failed"
+				});
+				return null;
+			});
+			if (lockStats && Date.now() - lockStats.mtimeMs > FILE_APPEND_LOCK_STALE_MS) {
+				await rm(lockPath, { force: true }).catch((error) => {
+					diagnosticLog.warn("Stale learning lock removal failed", { error }, {
+						event_name: "memory.learning.lock.stale.cleanup.failed",
+						file: "packages/memory/src/engine/operations/learning-file-maintenance.ts",
+						function: "withAppendLock",
+						site_id: "memory.learning.lock.stale.cleanup.failed"
+					});
+				});
+				continue;
+			}
+			await sleep(FILE_APPEND_LOCK_RETRY_MS);
+		}
+	}
+}
+/** Implements next learning id as the local self-improvement learning files operation. */
+async function nextLearningId(filePath, prefix) {
+	const date = todayYmd();
+	let count = 0;
+	try {
+		count = (await readFile(filePath, {
+			encoding: "utf8",
+			signal: memoryOperationSignal()
+		})).match(new RegExp(`\\[${prefix}-${date}-\\d{3}\\]`, "g"))?.length ?? 0;
+	} catch (error) {
+		if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) diagnosticLog.warn("Learning identifier history unavailable", { error }, {
+			event_name: "memory.learning.history.read.failed",
+			file: "packages/memory/src/engine/operations/learning-file-maintenance.ts",
+			function: "nextLearningId",
+			site_id: "memory.learning.history.read.failed"
+		});
+	}
+	return `${prefix}-${date}-${String(count + 1).padStart(3, "0")}`;
+}
+function learningFilesDir(baseDir) {
+	return join(baseDir, ".learnings");
+}
+async function ensureLearningFile(filePath, content) {
+	try {
+		if ((await readFile(filePath, {
+			encoding: "utf8",
+			signal: memoryOperationSignal()
+		})).trim().length > 0) return;
+	} catch (error) {
+		if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) diagnosticLog.warn("Learning file read failed before creation", { error }, {
+			event_name: "memory.learning.ensure.read.failed",
+			file: "packages/memory/src/engine/operations/learning-file-maintenance.ts",
+			function: "ensureLearningFile",
+			site_id: "memory.learning.ensure.read.failed"
+		});
+	}
+	await memoryFileWrite(() => writeFile(filePath, `${content.trim()}\n`, "utf-8"));
+}
+async function ensureLearningFileWithLock(filePath, content) {
+	await withFileWriteQueue(filePath, async () => {
+		await withAppendLock(filePath, async () => {
+			await ensureLearningFile(filePath, content);
+		});
+	});
+}
+/**
+* Ensures the self-improvement learning directory has the baseline files required by tools.
+*/
+async function ensureSelfImprovementLearningFiles(baseDir) {
+	const learningsDir = learningFilesDir(baseDir);
+	checkMemoryOperation();
+	await mkdir(learningsDir, { recursive: true });
+	await ensureLearningFileWithLock(join(learningsDir, "LEARNINGS.md"), DEFAULT_LEARNINGS_TEMPLATE);
+	await ensureLearningFileWithLock(join(learningsDir, "ERRORS.md"), DEFAULT_ERRORS_TEMPLATE);
+	await ensureLearningFileWithLock(join(learningsDir, "FEATURE_REQUESTS.md"), DEFAULT_FEATURE_REQUESTS_TEMPLATE);
+}
+function normalizeSelfImprovementEntryParams(params) {
+	return {
+		baseDir: params.baseDir,
+		type: params.type,
+		summary: params.summary,
+		details: params.details ?? "",
+		suggestedAction: params.suggestedAction ?? "",
+		category: params.category ?? "best_practice",
+		area: params.area ?? "config",
+		priority: params.priority ?? "medium",
+		status: params.status ?? "pending",
+		source: params.source ?? "mem-claw/self_improvement_log"
+	};
+}
+function renderSelfImprovementEntry(params, entryId, loggedAtIso) {
+	return [
+		`## [${entryId}]${params.type === "learning" ? ` ${params.category}` : ""}`,
+		"",
+		`**Logged**: ${loggedAtIso}`,
+		`**Priority**: ${params.priority}`,
+		`**Status**: ${params.status}`,
+		`**Area**: ${params.area}`,
+		"",
+		"### Summary",
+		params.summary.trim(),
+		"",
+		"### Details",
+		params.details.trim() || "-",
+		"",
+		"### Suggested Action",
+		params.suggestedAction.trim() || "-",
+		"",
+		"### Metadata",
+		`- Source: ${params.source}`,
+		"---",
+		""
+	].join("\n");
+}
+/**
+* Persists self improvement entry through the single self-improvement learning files write
+* path.
+*/
+async function appendSelfImprovementEntry(params) {
+	const normalized = normalizeSelfImprovementEntryParams(params);
+	await ensureSelfImprovementLearningFiles(normalized.baseDir);
+	const destination = ENTRY_DESTINATIONS[normalized.type];
+	const filePath = join(learningFilesDir(normalized.baseDir), destination.fileName);
+	return {
+		id: await withFileWriteQueue(filePath, async () => {
+			return withAppendLock(filePath, async () => {
+				const entryId = await nextLearningId(filePath, destination.idPrefix);
+				const nowIso = (/* @__PURE__ */ new Date()).toISOString();
+				const entry = renderSelfImprovementEntry(normalized, entryId, nowIso);
+				const separator = (await readFile(filePath, {
+					encoding: "utf8",
+					signal: memoryOperationSignal()
+				}).catch((error) => {
+					if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) diagnosticLog.warn("Learning file read failed before append", { error }, {
+						event_name: "memory.learning.append.read.failed",
+						file: "packages/memory/src/engine/operations/learning-file-maintenance.ts",
+						function: "appendSelfImprovementEntry",
+						site_id: "memory.learning.append.read.failed"
+					});
+					return "";
+				})).trimEnd().length > 0 ? "\n\n" : "";
+				await memoryFileWrite(() => appendFile(filePath, `${separator}${entry}`, "utf-8"));
+				return entryId;
+			});
+		}),
+		filePath
+	};
+}
+//#endregion
+export { DEFAULT_ERRORS_TEMPLATE, DEFAULT_FEATURE_REQUESTS_TEMPLATE, DEFAULT_LEARNINGS_TEMPLATE, appendSelfImprovementEntry, ensureSelfImprovementLearningFiles };

package/dist/internal/engine/operations/memory-tier-promoter.d.ts

@@ -0,0 +1,2 @@
+import { a as TierableMemory, i as TierTransition, n as TierConfig, o as createTierPromoter, r as TierPromoter, t as DEFAULT_TIER_CONFIG } from "../../../memory-tier-promoter-CqGxCkue.js";
+export { DEFAULT_TIER_CONFIG, TierConfig, TierPromoter, TierTransition, TierableMemory, createTierPromoter };

package/dist/internal/engine/operations/memory-tier-promoter.js

@@ -0,0 +1,95 @@
+//#region src/engine/operations/memory-tier-promoter.ts
+const DEFAULT_TIER_CONFIG = {
+	coreAccessThreshold: 10,
+	coreCompositeThreshold: .7,
+	coreImportanceThreshold: .8,
+	peripheralCompositeThreshold: .15,
+	peripheralAgeDays: 60,
+	workingAccessThreshold: 3,
+	workingCompositeThreshold: .4
+};
+const MS_PER_DAY = 864e5;
+function createTransition(context, toTier, reason) {
+	return {
+		memoryId: context.memory.id,
+		fromTier: context.memory.tier,
+		toTier,
+		reason
+	};
+}
+const TIER_RULES = [
+	{
+		from: "peripheral",
+		matches({ memory, score, config }) {
+			return memory.accessCount >= config.workingAccessThreshold && score.composite >= config.workingCompositeThreshold;
+		},
+		transition(context) {
+			const { memory, score, config } = context;
+			return createTransition(context, "working", `Access count (${memory.accessCount}) >= ${config.workingAccessThreshold} and composite (${score.composite.toFixed(2)}) >= ${config.workingCompositeThreshold}`);
+		}
+	},
+	{
+		from: "working",
+		matches({ memory, score, config }) {
+			return memory.accessCount >= config.coreAccessThreshold && score.composite >= config.coreCompositeThreshold && memory.importance >= config.coreImportanceThreshold;
+		},
+		transition(context) {
+			const { memory, score } = context;
+			return createTransition(context, "core", `High access (${memory.accessCount}), composite (${score.composite.toFixed(2)}), importance (${memory.importance})`);
+		}
+	},
+	{
+		from: "working",
+		matches({ memory, score, ageDays, config }) {
+			return score.composite < config.peripheralCompositeThreshold || ageDays > config.peripheralAgeDays && memory.accessCount < config.workingAccessThreshold;
+		},
+		transition(context) {
+			const { memory, score, ageDays } = context;
+			return createTransition(context, "peripheral", `Low composite (${score.composite.toFixed(2)}) or aged ${ageDays.toFixed(0)} days with low access (${memory.accessCount})`);
+		}
+	},
+	{
+		from: "core",
+		matches({ memory, score, config }) {
+			return score.composite < config.peripheralCompositeThreshold && memory.accessCount < config.workingAccessThreshold;
+		},
+		transition(context) {
+			const { memory, score } = context;
+			return createTransition(context, "working", `Severely low composite (${score.composite.toFixed(2)}) and access (${memory.accessCount})`);
+		}
+	}
+];
+/** 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). */
+function createTierPromoter(config = DEFAULT_TIER_CONFIG) {
+	function createContext(memory, score, now) {
+		return {
+			memory,
+			score,
+			now,
+			ageDays: (now - memory.timestamp) / MS_PER_DAY,
+			config
+		};
+	}
+	function evaluate(memory, decayScore, now = Date.now()) {
+		const context = createContext(memory, decayScore, now);
+		const rule = TIER_RULES.find((candidate) => candidate.from === memory.tier && candidate.matches(context));
+		return rule ? rule.transition(context) : null;
+	}
+	return {
+		evaluate,
+		evaluateAll(memories, decayScores, now = Date.now()) {
+			const scoreMap = new Map(decayScores.map((s) => [s.memoryId, s]));
+			const transitions = [];
+			for (const memory of memories) {
+				const score = scoreMap.get(memory.id);
+				if (!score) continue;
+				const transition = evaluate(memory, score, now);
+				if (transition) transitions.push(transition);
+			}
+			return transitions;
+		}
+	};
+}
+//#endregion
+export { DEFAULT_TIER_CONFIG, createTierPromoter };

package/dist/internal/engine/operations/runtime-audit-log.d.ts

@@ -0,0 +1,3 @@
+import { c as getStateDir, o as getSnoStationMemStateDir } from "../../../profile-TWPJ_myr.js";
+import { S as runWithMutationAttempt, _ as getAuditPath, a as MemoryAuditEvent, b as runWithMemoryAudit, c as MutationAttemptCompletion, d as MutationAttemptWriter, f as appendAuditEntry, g as flushAuditWrites, h as currentMutationAttemptId, i as MemoryAuditDetailsByEvent, l as MutationAttemptOutcome, m as appendAuditEntrySync, n as AuditEvent, o as MemoryAuditRunOptions, p as appendAuditEntryStrict, r as AuditStatus, s as MemoryAuditSyncRunOptions, t as AuditEntry, u as MutationAttemptRunOptions, v as getCostPath, x as runWithMemoryAuditSync, y as recoverInterruptedMutationAttempts } from "../../../runtime-audit-log-zpQiR9HT.js";
+export { AuditEntry, AuditEvent, AuditStatus, MemoryAuditDetailsByEvent, MemoryAuditEvent, MemoryAuditRunOptions, MemoryAuditSyncRunOptions, MutationAttemptCompletion, MutationAttemptOutcome, MutationAttemptRunOptions, MutationAttemptWriter, appendAuditEntry, appendAuditEntryStrict, appendAuditEntrySync, currentMutationAttemptId, flushAuditWrites, getAuditPath, getCostPath, getSnoStationMemStateDir, getStateDir, recoverInterruptedMutationAttempts, runWithMemoryAudit, runWithMemoryAuditSync, runWithMutationAttempt };

package/dist/internal/engine/operations/runtime-audit-log.js

@@ -0,0 +1,3 @@
+import { a as flushAuditWrites, c as recoverInterruptedMutationAttempts, d as runWithMutationAttempt, i as currentMutationAttemptId, l as runWithMemoryAudit, n as appendAuditEntryStrict, o as getAuditPath, r as appendAuditEntrySync, s as getCostPath, t as appendAuditEntry, u as runWithMemoryAuditSync } from "../../../runtime-audit-log-BCeujlEp.js";
+import { getSnoStationMemStateDir, getStateDir } from "../../contract/profile.js";
+export { appendAuditEntry, appendAuditEntryStrict, appendAuditEntrySync, currentMutationAttemptId, flushAuditWrites, getAuditPath, getCostPath, getSnoStationMemStateDir, getStateDir, recoverInterruptedMutationAttempts, runWithMemoryAudit, runWithMemoryAuditSync, runWithMutationAttempt };

package/dist/internal/engine/provider/canonical-memory-corpus.d.ts

@@ -0,0 +1,38 @@
+import { r as SnoStationMemMemorySearchResult } from "../../../provider-runtime-types-DFhtdA6d.js";
+//#region src/engine/provider/canonical-memory-corpus.d.ts
+export interface CanonicalMemoryFile {
+  path: string;
+  absolutePath: string;
+  realPath: string;
+  lineCount: number;
+}
+export interface CanonicalMemoryDiagnostics {
+  io_failure_count: number;
+  unavailable_file_count: number;
+}
+export interface CanonicalMemoryReadResult {
+  text: string;
+  path: string;
+  startLine: number;
+  endLine: number;
+  truncated?: boolean;
+  from?: number;
+  lines?: number;
+  nextFrom?: number;
+}
+export declare function normalizeCanonicalMemoryPath(relPath: string): string;
+export declare function listCanonicalMemoryFiles(workspaceDir: string, diagnostics?: CanonicalMemoryDiagnostics): Promise<CanonicalMemoryFile[]>;
+export declare function searchCanonicalMemoryFiles(params: {
+  diagnostics?: CanonicalMemoryDiagnostics;
+  workspaceDir: string;
+  query: string;
+  maxResults: number;
+}): Promise<SnoStationMemMemorySearchResult[]>;
+export declare function readCanonicalMemoryFile(params: {
+  workspaceDir: string;
+  relPath: string;
+  from?: number;
+  lines?: number;
+}): Promise<CanonicalMemoryReadResult>;
+export declare function canonicalMemoryWorkspaceFingerprint(workspaceDir: string): string;
+//#endregion

package/dist/internal/engine/provider/canonical-memory-corpus.js

@@ -0,0 +1,253 @@
+import { rt as FIXED_PROTOCOL_VALUE_64 } from "../../../signed-registry-constants-yq3DlG3B.js";
+import { clampInt } from "../shared/utils.js";
+import { createLogger } from "@snoai/utils/logger";
+import { isAbsolute, posix, relative, resolve, sep } from "node:path";
+import { lstat, readFile, readdir, realpath, stat } from "node:fs/promises";
+//#region src/engine/provider/canonical-memory-corpus.ts
+/** @file canonical-memory-corpus.ts
+* @purpose Searches and reads the built-in SnoStationMem canonical memory Markdown corpus.
+* @boundary Only exposes root MEMORY.md and ordinary Markdown files under memory/ in one workspace.
+*/
+const diagnosticLog = createLogger("sno-station-mem:canonical-memory-corpus");
+const ROOT_MEMORY_FILE = "MEMORY.md";
+const MEMORY_DIR = "memory";
+const DEFAULT_READ_LINES = 200;
+const MAX_READ_LINES = 2e3;
+const DENIED_SEGMENTS = /* @__PURE__ */ new Set([
+	FIXED_PROTOCOL_VALUE_64,
+	"config",
+	"configs",
+	"context",
+	"contexts",
+	"dream",
+	"dreaming",
+	"instruction",
+	"instructions",
+	"mapping",
+	"mappings",
+	"personality",
+	"personalities",
+	"raw",
+	"secret",
+	"secrets",
+	"session",
+	"sessions",
+	"store",
+	"stores",
+	"telemetry",
+	"trace",
+	"traces",
+	"audit",
+	"audits",
+	"vector",
+	"vectors"
+]);
+function canonicalDeniedError() {
+	return /* @__PURE__ */ new Error("Canonical memory file not found or not authorized");
+}
+function isInside(parent, child) {
+	const relative$1 = relative(parent, child);
+	return relative$1 === "" || !relative$1.startsWith("..") && !isAbsolute(relative$1);
+}
+function normalizeWorkspaceDir(workspaceDir) {
+	const trimmed = workspaceDir.trim();
+	if (!trimmed) throw canonicalDeniedError();
+	return resolve(trimmed);
+}
+function isDeniedSegment(segment) {
+	const lower = segment.toLowerCase();
+	const markdownStem = lower.endsWith(".md") ? lower.slice(0, -3) : lower;
+	return lower.startsWith(".") || lower === "user.md" || DENIED_SEGMENTS.has(lower) || DENIED_SEGMENTS.has(markdownStem);
+}
+function normalizeCanonicalMemoryPath(relPath) {
+	if (!relPath || relPath.includes("\\") || isAbsolute(relPath)) throw canonicalDeniedError();
+	if (relPath === ROOT_MEMORY_FILE) return relPath;
+	const segments = relPath.split("/");
+	if (segments[0] !== MEMORY_DIR || segments.length < 2 || !segments.at(-1)?.endsWith(".md") || segments.some((segment) => segment === "" || segment === "." || segment === "..")) throw canonicalDeniedError();
+	if (segments.some(isDeniedSegment)) throw canonicalDeniedError();
+	return posix.join(...segments);
+}
+async function resolveCanonicalPath(workspaceDir, relPath) {
+	const workspaceRoot = await realpath(normalizeWorkspaceDir(workspaceDir));
+	const normalized = normalizeCanonicalMemoryPath(relPath);
+	const absolutePath = resolve(workspaceRoot, ...normalized.split("/"));
+	if (!isInside(workspaceRoot, absolutePath)) throw canonicalDeniedError();
+	if (!(await lstat(absolutePath).catch(() => {
+		throw canonicalDeniedError();
+	})).isFile()) throw canonicalDeniedError();
+	const realFilePath = await realpath(absolutePath).catch(() => {
+		throw canonicalDeniedError();
+	});
+	if (!isInside(workspaceRoot, realFilePath)) throw canonicalDeniedError();
+	if (!(await stat(realFilePath).catch(() => {
+		throw canonicalDeniedError();
+	})).isFile()) throw canonicalDeniedError();
+	return {
+		workspaceRoot,
+		path: normalized,
+		absolutePath,
+		realPath: realFilePath
+	};
+}
+async function readCanonicalText(workspaceDir, relPath) {
+	const resolved = await resolveCanonicalPath(workspaceDir, relPath);
+	const text = await readFile(resolved.realPath, "utf8");
+	return {
+		resolved,
+		text,
+		lines: text.split("\n")
+	};
+}
+async function walkMemoryDir(workspaceRoot, currentDir, relDir, files, diagnostics) {
+	if (!(await lstat(currentDir).catch((error) => {
+		if ((typeof error === "object" && error ? error.code : void 0) === "ENOENT") return void 0;
+		throw error;
+	}))?.isDirectory()) return;
+	const realDir = await realpath(currentDir).catch((error) => {
+		if (diagnostics) {
+			diagnostics.unavailable_file_count += 1;
+			if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) diagnostics.io_failure_count += 1;
+		}
+	});
+	if (!realDir || !isInside(workspaceRoot, realDir)) return;
+	const entries = await readdir(currentDir, { withFileTypes: true }).catch((error) => {
+		if ((typeof error === "object" && error ? error.code : void 0) === "ENOENT") return [];
+		throw error;
+	});
+	for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+		if (isDeniedSegment(entry.name)) continue;
+		const relPath = posix.join(relDir, entry.name);
+		const absPath = resolve(workspaceRoot, ...relPath.split("/"));
+		if (entry.isDirectory()) {
+			await walkMemoryDir(workspaceRoot, absPath, relPath, files, diagnostics);
+			continue;
+		}
+		if (!entry.isFile()) continue;
+		if (!entry.name.endsWith(".md")) continue;
+		const file = await loadCanonicalFileByPath(workspaceRoot, relPath).catch((error) => {
+			if (diagnostics) {
+				diagnostics.unavailable_file_count += 1;
+				if (error instanceof Error && "code" in error && error.code !== "ENOENT") diagnostics.io_failure_count += 1;
+			}
+		});
+		if (file) files.push(file);
+	}
+}
+async function loadCanonicalFileByPath(workspaceRoot, relPath) {
+	const normalized = normalizeCanonicalMemoryPath(relPath);
+	const absolutePath = resolve(workspaceRoot, ...normalized.split("/"));
+	if (!(await lstat(absolutePath)).isFile()) throw canonicalDeniedError();
+	const realFilePath = await realpath(absolutePath);
+	if (!isInside(workspaceRoot, realFilePath)) throw canonicalDeniedError();
+	if (!(await stat(realFilePath)).isFile()) throw canonicalDeniedError();
+	const text = await readFile(realFilePath, "utf8");
+	return {
+		path: normalized,
+		absolutePath,
+		realPath: realFilePath,
+		lineCount: Math.max(text.split("\n").length, 1)
+	};
+}
+async function listCanonicalMemoryFiles(workspaceDir, diagnostics = {
+	io_failure_count: 0,
+	unavailable_file_count: 0
+}) {
+	const workspaceRoot = await realpath(normalizeWorkspaceDir(workspaceDir));
+	const files = [];
+	const rootFile = await loadCanonicalFileByPath(workspaceRoot, ROOT_MEMORY_FILE).catch((error) => {
+		if (diagnostics) {
+			diagnostics.unavailable_file_count += 1;
+			if (error instanceof Error && "code" in error && error.code !== "ENOENT") diagnostics.io_failure_count += 1;
+		}
+	});
+	if (rootFile) files.push(rootFile);
+	await walkMemoryDir(workspaceRoot, resolve(workspaceRoot, MEMORY_DIR), MEMORY_DIR, files, diagnostics);
+	if (diagnostics.io_failure_count > 0) diagnosticLog.warn("Canonical memory discovery degraded", {
+		outcome: "partial",
+		io_failure_count: diagnostics.io_failure_count,
+		unavailable_file_count: diagnostics.unavailable_file_count,
+		file_count: files.length
+	}, {
+		event_name: "memory.provider.canonical.discovery.degraded",
+		file: "packages/memory/src/engine/provider/canonical-memory-corpus.ts",
+		function: "listCanonicalMemoryFiles",
+		site_id: "memory.provider.canonical.discovery.degraded"
+	});
+	return files.sort((left, right) => left.path.localeCompare(right.path));
+}
+function normalizeSearchText(text) {
+	return text.normalize("NFKC").toLowerCase();
+}
+function queryTerms(query) {
+	const normalized = normalizeSearchText(query).split(/[^\p{L}\p{M}\p{N}]+/u).filter((term) => term.length > 1);
+	return [...new Set(normalized)];
+}
+function scoreText(text, terms) {
+	const lower = normalizeSearchText(text);
+	const matched = terms.filter((term) => lower.includes(term)).length;
+	if (matched === 0) return 0;
+	return matched / Math.max(terms.length, 1);
+}
+function bestSnippet(lines, terms) {
+	let bestLine = 0;
+	let bestScore = 0;
+	for (let index = 0; index < lines.length; index += 1) {
+		const score = scoreText(lines[index] ?? "", terms);
+		if (score > bestScore) {
+			bestLine = index;
+			bestScore = score;
+		}
+	}
+	const snippet = (lines[bestLine] ?? "").trim() || lines.slice(0, 2).join(" ").trim();
+	return {
+		line: bestLine + 1,
+		snippet
+	};
+}
+async function searchCanonicalMemoryFiles(params) {
+	const terms = queryTerms(params.query);
+	if (terms.length === 0) return [];
+	const files = await listCanonicalMemoryFiles(params.workspaceDir, params.diagnostics);
+	const results = [];
+	for (const file of files) {
+		const text = await readFile(file.realPath, "utf8");
+		const score = scoreText(text, terms);
+		if (score <= 0) continue;
+		const { line, snippet } = bestSnippet(text.split("\n"), terms);
+		results.push({
+			path: file.path,
+			startLine: line,
+			endLine: line,
+			score,
+			textScore: score,
+			snippet,
+			source: "memory",
+			citation: `${file.path}:${line}`
+		});
+	}
+	return results.sort((left, right) => right.score - left.score || left.path.localeCompare(right.path)).slice(0, clampInt(params.maxResults, 1, MAX_READ_LINES));
+}
+async function readCanonicalMemoryFile(params) {
+	const { resolved, lines: allLines } = await readCanonicalText(params.workspaceDir, params.relPath);
+	const start = clampInt(params.from ?? 1, 1, Math.max(allLines.length, 1));
+	const requested = clampInt(params.lines ?? DEFAULT_READ_LINES, 1, MAX_READ_LINES);
+	const endExclusive = Math.min(start - 1 + requested, allLines.length);
+	const truncated = endExclusive < allLines.length;
+	return {
+		text: allLines.slice(start - 1, endExclusive).join("\n"),
+		path: resolved.path,
+		startLine: start,
+		endLine: Math.max(start, endExclusive),
+		...truncated ? {
+			truncated,
+			nextFrom: endExclusive + 1
+		} : {},
+		from: start,
+		lines: requested
+	};
+}
+function canonicalMemoryWorkspaceFingerprint(workspaceDir) {
+	return normalizeWorkspaceDir(workspaceDir).split(sep).join("/");
+}
+//#endregion
+export { canonicalMemoryWorkspaceFingerprint, listCanonicalMemoryFiles, normalizeCanonicalMemoryPath, readCanonicalMemoryFile, searchCanonicalMemoryFiles };