@agentmemory/agentmemory 0.8.12 → 0.9.0

package/dist/index.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { TriggerAction, registerWorker } from "iii-sdk";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { constants, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname, extname, join, resolve, sep } from "node:path";
 import { homedir } from "node:os";
 import Anthropic from "@anthropic-ai/sdk";
@@ -10,7 +10,7 @@ import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { lookup } from "node:dns/promises";
 import { isIP } from "node:net";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { lstat, mkdir, open, readFile, readdir, writeFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import { createServer } from "node:http";
 
@@ -51,16 +51,20 @@ function detectProvider(env) {
 		maxTokens,
 		baseURL: env["ANTHROPIC_BASE_URL"]
 	};
-	if (env["GEMINI_API_KEY"]) return {
-		provider: "gemini",
-		model: env["GEMINI_MODEL"] || "gemini-2.0-flash",
-		maxTokens
-	};
+	if (env["GEMINI_API_KEY"] || env["GOOGLE_API_KEY"]) {
+		if (!env["GEMINI_API_KEY"] && env["GOOGLE_API_KEY"]) process.stderr.write("[agentmemory] GOOGLE_API_KEY detected — treating as GEMINI_API_KEY. Set GEMINI_API_KEY in ~/.agentmemory/.env to silence this warning.\n");
+		return {
+			provider: "gemini",
+			model: env["GEMINI_MODEL"] || "gemini-2.0-flash",
+			maxTokens
+		};
+	}
 	if (env["OPENROUTER_API_KEY"]) return {
 		provider: "openrouter",
 		model: env["OPENROUTER_MODEL"] || "anthropic/claude-sonnet-4-20250514",
 		maxTokens
 	};
+	if (env["AGENTMEMORY_AUTO_COMPRESS"] === "true") process.stderr.write("[agentmemory] WARNING: AGENTMEMORY_AUTO_COMPRESS=true but no LLM provider key found (GEMINI_API_KEY, ANTHROPIC_API_KEY, OPENROUTER_API_KEY). Falling back to agent-sdk which shares Claude Code's API quota — this can exhaust a Pro subscription during heavy sessions. Set an API key in ~/.agentmemory/.env to avoid rate limits (#149).\n");
 	return {
 		provider: "agent-sdk",
 		model: "claude-sonnet-4-20250514",
@@ -726,7 +730,11 @@ function createBaseProvider(config) {
 	switch (config.provider) {
 		case "minimax": return new MinimaxProvider(requireEnvVar("MINIMAX_API_KEY"), config.model, config.maxTokens);
 		case "anthropic": return new AnthropicProvider(requireEnvVar("ANTHROPIC_API_KEY"), config.model, config.maxTokens, config.baseURL);
-		case "gemini": return new OpenRouterProvider(requireEnvVar("GEMINI_API_KEY"), config.model, config.maxTokens, "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions");
+		case "gemini": {
+			const geminiKey = getEnvVar("GEMINI_API_KEY") || getEnvVar("GOOGLE_API_KEY");
+			if (!geminiKey) throw new Error("GEMINI_API_KEY (or GOOGLE_API_KEY) is required for the gemini provider");
+			return new OpenRouterProvider(geminiKey, config.model, config.maxTokens, "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions");
+		}
 		case "openrouter": return new OpenRouterProvider(requireEnvVar("OPENROUTER_API_KEY"), config.model, config.maxTokens, "https://openrouter.ai/api/v1/chat/completions");
 		default: return new AgentSDKProvider();
 	}
@@ -2121,7 +2129,7 @@ function stringifyForNarrative(v) {
 		return String(v);
 	}
 }
-function truncate$1(s, n) {
+function truncate$2(s, n) {
 	return s.length > n ? s.slice(0, n - 1) + "…" : s;
 }
 function buildSyntheticCompression(raw) {
@@ -2138,10 +2146,10 @@ function buildSyntheticCompression(raw) {
 		sessionId: raw.sessionId,
 		timestamp: raw.timestamp,
 		type: inferType(toolName, raw.hookType),
-		title: truncate$1(toolName || "observation", 80),
-		subtitle: inputStr ? truncate$1(inputStr, 120) : void 0,
+		title: truncate$2(toolName || "observation", 80),
+		subtitle: inputStr ? truncate$2(inputStr, 120) : void 0,
 		facts: [],
-		narrative: truncate$1(narrativeParts.join(" | "), 400),
+		narrative: truncate$2(narrativeParts.join(" | "), 400),
 		concepts: [],
 		files: extractFiles$1(raw.toolInput),
 		importance: 5,
@@ -2565,16 +2573,16 @@ function buildCompressionPrompt(observation) {
 	if (observation.toolName) parts.push(`Tool: ${observation.toolName}`);
 	if (observation.toolInput) {
 		const input = typeof observation.toolInput === "string" ? observation.toolInput : JSON.stringify(observation.toolInput, null, 2);
-		parts.push(`Input:\n${truncate(input, 4e3)}`);
+		parts.push(`Input:\n${truncate$1(input, 4e3)}`);
 	}
 	if (observation.toolOutput) {
 		const output = typeof observation.toolOutput === "string" ? observation.toolOutput : JSON.stringify(observation.toolOutput, null, 2);
-		parts.push(`Output:\n${truncate(output, 4e3)}`);
+		parts.push(`Output:\n${truncate$1(output, 4e3)}`);
 	}
-	if (observation.userPrompt) parts.push(`User prompt:\n${truncate(observation.userPrompt, 2e3)}`);
+	if (observation.userPrompt) parts.push(`User prompt:\n${truncate$1(observation.userPrompt, 2e3)}`);
 	return parts.join("\n\n");
 }
-function truncate(s, max) {
+function truncate$1(s, max) {
 	return s.length > max ? s.slice(0, max) + "\n[...truncated]" : s;
 }
 
@@ -3739,25 +3747,40 @@ function registerRememberFunction(sdk, kv) {
 	});
 	sdk.registerFunction("mem::forget", async (data) => {
 		let deleted = 0;
+		const deletedMemoryIds = [];
+		const deletedObservationIds = [];
+		let deletedSession = false;
 		if (data.memoryId) {
 			await kv.delete(KV.memories, data.memoryId);
 			await deleteAccessLog(kv, data.memoryId);
+			deletedMemoryIds.push(data.memoryId);
 			deleted++;
 		}
 		if (data.sessionId && data.observationIds && data.observationIds.length > 0) for (const obsId of data.observationIds) {
 			await kv.delete(KV.observations(data.sessionId), obsId);
+			deletedObservationIds.push(obsId);
 			deleted++;
 		}
 		if (data.sessionId && (!data.observationIds || data.observationIds.length === 0) && !data.memoryId) {
 			const observations = await kv.list(KV.observations(data.sessionId));
 			for (const obs of observations) {
 				await kv.delete(KV.observations(data.sessionId), obs.id);
+				deletedObservationIds.push(obs.id);
 				deleted++;
 			}
 			await kv.delete(KV.sessions, data.sessionId);
 			await kv.delete(KV.summaries, data.sessionId);
+			deletedSession = true;
 			deleted += 2;
 		}
+		if (deleted > 0) await recordAudit(kv, "forget", "mem::forget", [...deletedMemoryIds, ...deletedObservationIds], {
+			sessionId: data.sessionId,
+			deleted,
+			memoriesDeleted: deletedMemoryIds.length,
+			observationsDeleted: deletedObservationIds.length,
+			sessionDeleted: deletedSession,
+			reason: "user-initiated forget"
+		});
 		logger.info("Memory forgotten", { deleted });
 		return {
 			success: true,
@@ -4477,7 +4500,7 @@ function registerAutoForgetFunction(sdk, kv) {
 
 //#endregion
 //#region src/version.ts
-const VERSION = "0.8.12";
+const VERSION = "0.9.0";
 
 //#endregion
 //#region src/functions/export-import.ts
@@ -4593,7 +4616,9 @@ function registerExportImportFunction(sdk, kv) {
 			"0.8.9",
 			"0.8.10",
 			"0.8.11",
-			"0.8.12"
+			"0.8.12",
+			"0.8.13",
+			"0.9.0"
 		]).has(importData.version)) return {
 			success: false,
 			error: `Unsupported export version: ${importData.version}`
@@ -10965,8 +10990,8 @@ function registerRetentionFunctions(sdk, kv) {
 		let evictedSemantic = 0;
 		const evictedIds = [];
 		for (const candidate of candidates) try {
-			let scope;
-			let resolvedSource;
+			let scope = null;
+			let resolvedSource = null;
 			if (candidate.source === "semantic") {
 				scope = KV.semantic;
 				resolvedSource = "semantic";
@@ -10976,10 +11001,11 @@ function registerRetentionFunctions(sdk, kv) {
 			} else if (await kv.get(KV.memories, candidate.memoryId) !== null) {
 				scope = KV.memories;
 				resolvedSource = "episodic";
-			} else {
+			} else if (await kv.get(KV.semantic, candidate.memoryId) !== null) {
 				scope = KV.semantic;
 				resolvedSource = "semantic";
 			}
+			if (!scope || !resolvedSource) continue;
 			await kv.delete(scope, candidate.memoryId);
 			await kv.delete(KV.retentionScores, candidate.memoryId);
 			await deleteAccessLog(kv, candidate.memoryId);
@@ -11066,7 +11092,7 @@ function validateCompression(original, compressed) {
 }
 function resolveBackupPath(filePath) {
 	const base = basename(filePath, extname(filePath));
-	const name = base.endsWith(".original") ? base : `${base}.original`;
+	const name = base.endsWith(".original") ? `${base}.backup` : `${base}.original`;
 	return join(dirname(filePath), `${name}.md`);
 }
 function registerCompressFileFunction(sdk, kv, provider) {
@@ -11085,6 +11111,17 @@ function registerCompressFileFunction(sdk, kv, provider) {
 			success: false,
 			error: "refusing to process sensitive-looking path"
 		};
+		try {
+			if ((await lstat(absolutePath)).isSymbolicLink()) return {
+				success: false,
+				error: "symlinks are not supported"
+			};
+		} catch {
+			return {
+				success: false,
+				error: "file not found"
+			};
+		}
 		let original;
 		try {
 			original = await readFile(absolutePath, "utf-8");
@@ -11108,7 +11145,23 @@ function registerCompressFileFunction(sdk, kv, provider) {
 		};
 		const backupPath = resolveBackupPath(absolutePath);
 		await writeFile(backupPath, original, "utf-8");
-		await writeFile(absolutePath, compressed, "utf-8");
+		let fd = null;
+		try {
+			fd = await open(absolutePath, constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC | constants.O_NOFOLLOW);
+			await fd.writeFile(compressed, "utf-8");
+		} catch (err) {
+			const code = err.code;
+			if (code === "ELOOP" || code === "EINVAL") return {
+				success: false,
+				error: "symlinks are not supported"
+			};
+			return {
+				success: false,
+				error: "failed to write compressed file"
+			};
+		} finally {
+			await fd?.close().catch(() => {});
+		}
 		try {
 			await recordAudit(kv, "compress", "mem::compress-file", [], {
 				filePath: absolutePath,
@@ -11127,6 +11180,419 @@ function registerCompressFileFunction(sdk, kv, provider) {
 	});
 }
 
+//#endregion
+//#region src/replay/jsonl-parser.ts
+function deriveProject(cwd) {
+	if (!cwd) return "unknown";
+	const parts = cwd.split("/").filter(Boolean);
+	return parts[parts.length - 1] || "unknown";
+}
+function toText(content) {
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	const parts = [];
+	for (const item of content) {
+		if (!item || typeof item !== "object") continue;
+		const entry = item;
+		if (entry.type === "text" && typeof entry.text === "string") parts.push(entry.text);
+	}
+	return parts.join("\n");
+}
+function extractToolUses(content) {
+	if (!Array.isArray(content)) return [];
+	const out = [];
+	for (const item of content) {
+		if (!item || typeof item !== "object") continue;
+		const entry = item;
+		if (entry.type === "tool_use") out.push({
+			id: typeof entry.id === "string" ? entry.id : "",
+			name: typeof entry.name === "string" ? entry.name : "unknown",
+			input: entry.input
+		});
+	}
+	return out;
+}
+function extractToolResults(content) {
+	if (!Array.isArray(content)) return [];
+	const out = [];
+	for (const item of content) {
+		if (!item || typeof item !== "object") continue;
+		const entry = item;
+		if (entry.type === "tool_result") out.push({
+			toolUseId: typeof entry.tool_use_id === "string" ? entry.tool_use_id : "",
+			output: entry.content,
+			isError: entry.is_error === true
+		});
+	}
+	return out;
+}
+function parseJsonlText(text, fallbackSessionId) {
+	const lines = text.split("\n").filter((l) => l.trim().length > 0);
+	const entries = [];
+	for (const line of lines) try {
+		const parsed = JSON.parse(line);
+		if (parsed && typeof parsed === "object") entries.push(parsed);
+	} catch {}
+	let sessionId = fallbackSessionId || "";
+	let cwd = "";
+	let firstTs = "";
+	let lastTs = "";
+	const observations = [];
+	for (const entry of entries) {
+		if (entry.sessionId && !sessionId) sessionId = entry.sessionId;
+		if (entry.cwd && !cwd) cwd = entry.cwd;
+		const ts = entry.timestamp || (/* @__PURE__ */ new Date()).toISOString();
+		if (!firstTs) firstTs = ts;
+		lastTs = ts;
+		const role = entry.message?.role;
+		const content = entry.message?.content;
+		if (entry.type === "user" && role === "user") {
+			const toolResults = extractToolResults(content);
+			if (toolResults.length > 0) for (const result of toolResults) observations.push({
+				id: generateId("obs"),
+				sessionId: sessionId || "imported",
+				timestamp: ts,
+				hookType: result.isError ? "post_tool_failure" : "post_tool_use",
+				toolName: void 0,
+				toolInput: { toolUseId: result.toolUseId },
+				toolOutput: result.output,
+				raw: entry
+			});
+			else {
+				const text = toText(content);
+				if (text.trim().length > 0) observations.push({
+					id: generateId("obs"),
+					sessionId: sessionId || "imported",
+					timestamp: ts,
+					hookType: "prompt_submit",
+					userPrompt: text,
+					raw: entry
+				});
+			}
+		} else if (entry.type === "assistant" && role === "assistant") {
+			const text = toText(content);
+			const tools = extractToolUses(content);
+			if (text.trim().length > 0) observations.push({
+				id: generateId("obs"),
+				sessionId: sessionId || "imported",
+				timestamp: ts,
+				hookType: "stop",
+				assistantResponse: text,
+				raw: entry
+			});
+			for (const tool of tools) observations.push({
+				id: generateId("obs"),
+				sessionId: sessionId || "imported",
+				timestamp: ts,
+				hookType: "pre_tool_use",
+				toolName: tool.name,
+				toolInput: tool.input,
+				raw: {
+					toolUseId: tool.id,
+					entry
+				}
+			});
+		} else if (entry.type === "summary" || entry.type === "system") {}
+	}
+	const effectiveSessionId = sessionId || generateId("sess");
+	for (const obs of observations) if (obs.sessionId === "imported") obs.sessionId = effectiveSessionId;
+	const nowIso = (/* @__PURE__ */ new Date()).toISOString();
+	return {
+		sessionId: effectiveSessionId,
+		project: deriveProject(cwd),
+		cwd: cwd || process.cwd(),
+		startedAt: firstTs || nowIso,
+		endedAt: lastTs || nowIso,
+		observations
+	};
+}
+
+//#endregion
+//#region src/replay/timeline.ts
+const DEFAULT_CHARS_PER_SEC = 40;
+const MIN_EVENT_MS = 300;
+const MAX_EVENT_MS = 2e4;
+function kindFromHook(obs) {
+	switch (obs.hookType) {
+		case "session_start": return "session_start";
+		case "session_end": return "session_end";
+		case "prompt_submit": return "prompt";
+		case "stop": return obs.assistantResponse ? "response" : "hook";
+		case "pre_tool_use": return "tool_call";
+		case "post_tool_use": return "tool_result";
+		case "post_tool_failure": return "tool_error";
+		default: return "hook";
+	}
+}
+function labelFor(obs, kind) {
+	switch (kind) {
+		case "prompt": return truncate(obs.userPrompt || "User prompt", 80);
+		case "response": return truncate(obs.assistantResponse || "Assistant response", 80);
+		case "tool_call": return `${obs.toolName || "tool"} ▸ call`;
+		case "tool_result": return `${obs.toolName || "tool"} ▸ result`;
+		case "tool_error": return `${obs.toolName || "tool"} ▸ error`;
+		case "session_start": return "Session start";
+		case "session_end": return "Session end";
+		default: return obs.hookType;
+	}
+}
+function truncate(text, max) {
+	if (text.length <= max) return text;
+	return text.slice(0, max - 1) + "…";
+}
+function bodyFor(obs, kind) {
+	if (kind === "prompt") return obs.userPrompt;
+	if (kind === "response") return obs.assistantResponse;
+}
+function estimateDurationMs(ev) {
+	const chars = (ev.body?.length || 0) + (typeof ev.toolInput === "string" ? ev.toolInput.length : 0) + (typeof ev.toolOutput === "string" ? ev.toolOutput.length : 0);
+	if (chars === 0) return MIN_EVENT_MS;
+	const ms = Math.round(chars / DEFAULT_CHARS_PER_SEC * 1e3);
+	return Math.max(MIN_EVENT_MS, Math.min(MAX_EVENT_MS, ms));
+}
+function projectTimeline(observations) {
+	if (observations.length === 0) {
+		const now = (/* @__PURE__ */ new Date()).toISOString();
+		return {
+			sessionId: "",
+			startedAt: now,
+			endedAt: now,
+			totalDurationMs: 0,
+			eventCount: 0,
+			events: []
+		};
+	}
+	const sorted = [...observations].sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+	const startedAt = sorted[0].timestamp;
+	const startMs = Date.parse(startedAt);
+	const events = [];
+	let syntheticOffset = 0;
+	const allSameTs = sorted.every((o) => o.timestamp === startedAt);
+	for (const obs of sorted) {
+		const kind = kindFromHook(obs);
+		const body = bodyFor(obs, kind);
+		const obsMs = Date.parse(obs.timestamp);
+		const offsetMs = allSameTs ? syntheticOffset : Number.isFinite(obsMs) && Number.isFinite(startMs) ? Math.max(0, obsMs - startMs) : syntheticOffset;
+		const event = {
+			id: obs.id,
+			sessionId: obs.sessionId,
+			ts: obs.timestamp,
+			offsetMs,
+			durationMs: 0,
+			kind,
+			label: labelFor(obs, kind),
+			body,
+			toolName: obs.toolName,
+			toolInput: obs.toolInput,
+			toolOutput: obs.toolOutput
+		};
+		event.durationMs = estimateDurationMs(event);
+		events.push(event);
+		syntheticOffset += event.durationMs;
+	}
+	const last = events[events.length - 1];
+	const totalDurationMs = last.offsetMs + last.durationMs;
+	return {
+		sessionId: sorted[0].sessionId,
+		startedAt,
+		endedAt: sorted[sorted.length - 1].timestamp,
+		totalDurationMs,
+		eventCount: events.length,
+		events
+	};
+}
+
+//#endregion
+//#region src/functions/replay.ts
+const SENSITIVE_PATH_PATTERNS = [
+	/(^|[\\/_.-])secret([\\/_.-]|s?$)/i,
+	/(^|[\\/_.-])credentials?([\\/_.-]|$)/i,
+	/(^|[\\/_.-])private[_-]?key([\\/_.-]|$)/i,
+	/(^|[\\/])\.env(\.[\w-]+)?$/i,
+	/(^|[\\/_.-])id_rsa([\\/_.-]|$)/i,
+	/(^|[\\/])auth[_-]?token([\\/_.-]|$)/i,
+	/(^|[\\/])bearer[_-]?token([\\/_.-]|$)/i,
+	/(^|[\\/])access[_-]?token([\\/_.-]|$)/i,
+	/(^|[\\/])api[_-]?token([\\/_.-]|$)/i
+];
+function isSensitive(path) {
+	return SENSITIVE_PATH_PATTERNS.some((re) => re.test(path));
+}
+async function isSymlink(path) {
+	try {
+		return (await lstat(path)).isSymbolicLink();
+	} catch {
+		return false;
+	}
+}
+function rawFromCompressed(obs) {
+	return {
+		id: obs.id,
+		sessionId: obs.sessionId,
+		timestamp: obs.timestamp,
+		hookType: "post_tool_use",
+		toolName: void 0,
+		toolInput: void 0,
+		toolOutput: void 0,
+		userPrompt: obs.type === "conversation" ? obs.narrative : void 0,
+		assistantResponse: void 0,
+		raw: {
+			title: obs.title,
+			narrative: obs.narrative,
+			facts: obs.facts
+		}
+	};
+}
+function isRawShape(o) {
+	if (!o || typeof o !== "object") return false;
+	return typeof o.hookType === "string";
+}
+async function loadObservations(kv, sessionId) {
+	return (await kv.list(KV.observations(sessionId))).map((r) => isRawShape(r) ? r : rawFromCompressed(r));
+}
+async function findJsonlFiles(root, limit = 200) {
+	const out = [];
+	async function walk(dir) {
+		if (out.length >= limit) return;
+		let names;
+		try {
+			names = await readdir(dir);
+		} catch {
+			return;
+		}
+		for (const name of names) {
+			if (out.length >= limit) return;
+			const full = join(dir, name);
+			let st;
+			try {
+				st = await lstat(full);
+			} catch {
+				continue;
+			}
+			if (st.isSymbolicLink()) continue;
+			if (st.isDirectory()) await walk(full);
+			else if (st.isFile() && name.endsWith(".jsonl")) out.push(full);
+		}
+	}
+	await walk(root);
+	return out;
+}
+function registerReplayFunctions(sdk, kv) {
+	sdk.registerFunction("mem::replay::load", async (data) => {
+		if (!data?.sessionId || typeof data.sessionId !== "string") return {
+			success: false,
+			error: "sessionId is required"
+		};
+		const session = await kv.get(KV.sessions, data.sessionId);
+		return {
+			success: true,
+			timeline: projectTimeline(await loadObservations(kv, data.sessionId)),
+			session
+		};
+	});
+	sdk.registerFunction("mem::replay::sessions", async () => {
+		const sessions = await kv.list(KV.sessions);
+		sessions.sort((a, b) => (b.startedAt || "").localeCompare(a.startedAt || ""));
+		return {
+			success: true,
+			sessions
+		};
+	});
+	sdk.registerFunction("mem::replay::import-jsonl", async (data = {}) => {
+		const defaultRoot = join(homedir(), ".claude", "projects");
+		const rawPath = data.path || defaultRoot;
+		if (typeof rawPath !== "string" || rawPath.length === 0) return {
+			success: false,
+			error: "path must be a non-empty string"
+		};
+		const abs = resolve(rawPath.startsWith("~") ? join(homedir(), rawPath.slice(1)) : rawPath);
+		if (isSensitive(abs)) return {
+			success: false,
+			error: "refusing to process sensitive-looking path"
+		};
+		if (await isSymlink(abs)) return {
+			success: false,
+			error: "symlinks are not supported"
+		};
+		let stat;
+		try {
+			stat = await lstat(abs);
+		} catch {
+			return {
+				success: false,
+				error: "path not found"
+			};
+		}
+		let files = [];
+		if (stat.isDirectory()) files = await findJsonlFiles(abs, data.maxFiles || 200);
+		else if (stat.isFile() && abs.endsWith(".jsonl")) files = [abs];
+		else return {
+			success: false,
+			error: "path must be a .jsonl file or directory"
+		};
+		if (files.length === 0) return {
+			success: true,
+			imported: 0,
+			sessionIds: [],
+			observations: 0
+		};
+		const sessionIds = [];
+		let observationCount = 0;
+		for (const file of files) {
+			if (isSensitive(file)) continue;
+			if (await isSymlink(file)) continue;
+			let text;
+			try {
+				text = await readFile(file, "utf-8");
+			} catch (err) {
+				logger.warn("replay: failed to read jsonl", {
+					file,
+					error: err instanceof Error ? err.message : String(err)
+				});
+				continue;
+			}
+			const parsed = parseJsonlText(text, generateId("sess"));
+			if (parsed.observations.length === 0) continue;
+			const existing = await kv.get(KV.sessions, parsed.sessionId);
+			if (existing) {
+				existing.observationCount = (existing.observationCount || 0) + parsed.observations.length;
+				if (parsed.endedAt > (existing.endedAt || "")) existing.endedAt = parsed.endedAt;
+				if (existing.status === "active") existing.status = "completed";
+				const existingTags = existing.tags || [];
+				if (!existingTags.includes("jsonl-import")) existing.tags = [...existingTags, "jsonl-import"];
+				await kv.set(KV.sessions, existing.id, existing);
+			} else {
+				const session = {
+					id: parsed.sessionId,
+					project: parsed.project,
+					cwd: parsed.cwd,
+					startedAt: parsed.startedAt,
+					endedAt: parsed.endedAt,
+					status: "completed",
+					observationCount: parsed.observations.length,
+					tags: ["jsonl-import"]
+				};
+				await kv.set(KV.sessions, session.id, session);
+			}
+			await Promise.all(parsed.observations.map((obs) => kv.set(KV.observations(parsed.sessionId), obs.id, obs)));
+			observationCount += parsed.observations.length;
+			sessionIds.push(parsed.sessionId);
+		}
+		await safeAudit(kv, "import", "mem::replay::import-jsonl", sessionIds, {
+			source: "jsonl",
+			path: abs,
+			files: files.length,
+			observations: observationCount
+		});
+		return {
+			success: true,
+			imported: files.length,
+			sessionIds,
+			observations: observationCount
+		};
+	});
+}
+
 //#endregion
 //#region src/health/thresholds.ts
 const DEFAULTS = {
@@ -11135,7 +11601,8 @@ const DEFAULTS = {
 	cpuWarnPercent: 80,
 	cpuCriticalPercent: 90,
 	memoryWarnPercent: 80,
-	memoryCriticalPercent: 95
+	memoryCriticalPercent: 95,
+	memoryRssFloorBytes: 512 * 1024 * 1024
 };
 function evaluateHealth(snapshot, config = {}) {
 	const cfg = {
@@ -11167,13 +11634,16 @@ function evaluateHealth(snapshot, config = {}) {
 		degraded = true;
 	}
 	const memPercent = snapshot.memory.heapTotal > 0 ? snapshot.memory.heapUsed / snapshot.memory.heapTotal * 100 : 0;
-	if (memPercent > cfg.memoryCriticalPercent) {
-		alerts.push(`memory_critical_${Math.round(memPercent)}%`);
+	const rss = snapshot.memory.rss ?? 0;
+	const rssAboveFloor = rss >= cfg.memoryRssFloorBytes;
+	const memMb = Math.round(rss / (1024 * 1024));
+	if (memPercent > cfg.memoryCriticalPercent && rssAboveFloor) {
+		alerts.push(`memory_critical_${Math.round(memPercent)}%_rss${memMb}mb`);
 		critical = true;
-	} else if (memPercent > cfg.memoryWarnPercent) {
-		alerts.push(`memory_warn_${Math.round(memPercent)}%`);
+	} else if (memPercent > cfg.memoryWarnPercent && rssAboveFloor) {
+		alerts.push(`memory_warn_${Math.round(memPercent)}%_rss${memMb}mb`);
 		degraded = true;
-	}
+	} else if (memPercent > cfg.memoryWarnPercent) alerts.push(`memory_heap_tight_${Math.round(memPercent)}%_rss${memMb}mb`);
 	return {
 		status: critical ? "critical" : degraded ? "degraded" : "healthy",
 		alerts
@@ -11568,6 +12038,81 @@ function registerApiTriggers(sdk, kv, secret, metricsStore, provider) {
 			http_method: "POST"
 		}
 	});
+	sdk.registerFunction("api::replay::load", async (req) => {
+		const authErr = checkAuth(req, secret);
+		if (authErr) return authErr;
+		const sessionId = asNonEmptyString$1(req.query_params?.["sessionId"]);
+		if (!sessionId) return {
+			status_code: 400,
+			body: { error: "sessionId is required" }
+		};
+		return {
+			status_code: 200,
+			body: await sdk.trigger({
+				function_id: "mem::replay::load",
+				payload: { sessionId }
+			})
+		};
+	});
+	sdk.registerTrigger({
+		type: "http",
+		function_id: "api::replay::load",
+		config: {
+			api_path: "/agentmemory/replay/load",
+			http_method: "GET"
+		}
+	});
+	sdk.registerFunction("api::replay::sessions", async (req) => {
+		const authErr = checkAuth(req, secret);
+		if (authErr) return authErr;
+		return {
+			status_code: 200,
+			body: await sdk.trigger({ function_id: "mem::replay::sessions" })
+		};
+	});
+	sdk.registerTrigger({
+		type: "http",
+		function_id: "api::replay::sessions",
+		config: {
+			api_path: "/agentmemory/replay/sessions",
+			http_method: "GET"
+		}
+	});
+	sdk.registerFunction("api::replay::import", async (req) => {
+		const authErr = checkAuth(req, secret);
+		if (authErr) return authErr;
+		const body = req.body ?? {};
+		const payload = {};
+		if (body.path !== void 0) {
+			if (typeof body.path !== "string" || body.path.trim().length === 0) return {
+				status_code: 400,
+				body: { error: "path must be a non-empty string" }
+			};
+			payload.path = body.path.trim();
+		}
+		if (body.maxFiles !== void 0) {
+			if (!Number.isInteger(body.maxFiles) || body.maxFiles < 1) return {
+				status_code: 400,
+				body: { error: "maxFiles must be a positive integer" }
+			};
+			payload.maxFiles = body.maxFiles;
+		}
+		return {
+			status_code: 202,
+			body: await sdk.trigger({
+				function_id: "mem::replay::import-jsonl",
+				payload
+			})
+		};
+	});
+	sdk.registerTrigger({
+		type: "http",
+		function_id: "api::replay::import",
+		config: {
+			api_path: "/agentmemory/replay/import-jsonl",
+			http_method: "POST"
+		}
+	});
 	sdk.registerFunction("api::session::start", async (req) => {
 		const body = req.body ?? {};
 		const sessionId = asNonEmptyString$1(body.sessionId);
@@ -16759,6 +17304,7 @@ async function main() {
 	registerTemporalGraphFunctions(sdk, kv, provider);
 	registerRetentionFunctions(sdk, kv);
 	registerCompressFileFunction(sdk, kv, provider);
+	registerReplayFunctions(sdk, kv);
 	console.log(`[agentmemory] v0.6 advanced retrieval: sliding-window, query-expansion, temporal-graph, retention-scoring`);
 	console.log(`[agentmemory] Orchestration layer: actions, frontier, leases, routines, signals, checkpoints, flow-compress, mesh, branch-aware, sentinels, sketches, crystallize, diagnostics, facets`);
 	const snapshotConfig = loadSnapshotConfig();
@@ -16798,7 +17344,7 @@ async function main() {
 		}
 	}
 	console.log(`[agentmemory] Ready. ${embeddingProvider ? "Triple-stream (BM25+Vector+Graph)" : "BM25+Graph"} search active.`);
-	console.log(`[agentmemory] Endpoints: 104 REST + 44 MCP tools + 6 MCP resources + 3 MCP prompts`);
+	console.log(`[agentmemory] Endpoints: 107 REST + 44 MCP tools + 6 MCP resources + 3 MCP prompts`);
 	const viewerServer = startViewerServer(config.restPort + 2, kv, sdk, secret, config.restPort);
 	const autoForgetIntervalMs = parseInt(process.env.AUTO_FORGET_INTERVAL_MS || "3600000", 10);
 	const consolidationIntervalMs = parseInt(process.env.CONSOLIDATION_INTERVAL_MS || "7200000", 10);