@agentmemory/agentmemory 0.8.11 → 0.9.0

package/dist/index.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { TriggerAction, registerWorker } from "iii-sdk";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join, resolve, sep } from "node:path";
+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";
 import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
@@ -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, 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,
@@ -2267,6 +2275,17 @@ function registerSearchFunction(sdk, kv) {
 		}
 		const projectFilter = typeof data.project === "string" && data.project.length > 0 ? data.project : void 0;
 		const cwdFilter = typeof data.cwd === "string" && data.cwd.length > 0 ? data.cwd : void 0;
+		const format = typeof data.format === "string" ? data.format : "full";
+		if (![
+			"full",
+			"compact",
+			"narrative"
+		].includes(format)) throw new Error("mem::search: format must be one of 'full', 'compact', or 'narrative'");
+		let tokenBudget;
+		if (data.token_budget !== void 0) {
+			if (!Number.isInteger(data.token_budget) || data.token_budget < 1) throw new Error("mem::search: token_budget must be a positive integer");
+			tokenBudget = data.token_budget;
+		}
 		if (idx.size === 0) {
 			const count = await rebuildIndex(kv);
 			logger.info("Search index rebuilt", { entries: count });
@@ -2303,13 +2322,81 @@ function registerSearchFunction(sdk, kv) {
 			});
 		}
 		recordAccessBatch(kv, enriched.map((r) => r.observation.id));
+		const estimateTokens = (value) => Math.max(1, Math.ceil(JSON.stringify(value).length / 3));
+		const applyTokenBudget = (items) => {
+			if (!tokenBudget) return {
+				items,
+				used: items.reduce((sum, item) => sum + estimateTokens(item), 0),
+				truncated: false
+			};
+			const selected = [];
+			let used = 0;
+			for (const item of items) {
+				const itemTokens = estimateTokens(item);
+				if (used + itemTokens > tokenBudget) return {
+					items: selected,
+					used,
+					truncated: selected.length < items.length
+				};
+				selected.push(item);
+				used += itemTokens;
+			}
+			return {
+				items: selected,
+				used,
+				truncated: false
+			};
+		};
+		if (format === "compact") {
+			const packed = applyTokenBudget(enriched.map((r) => ({
+				obsId: r.observation.id,
+				sessionId: r.sessionId,
+				title: r.observation.title,
+				type: r.observation.type,
+				score: r.score,
+				timestamp: r.observation.timestamp
+			})));
+			return {
+				format,
+				results: packed.items,
+				tokens_used: packed.used,
+				tokens_budget: tokenBudget,
+				truncated: packed.truncated
+			};
+		}
+		if (format === "narrative") {
+			const packed = applyTokenBudget(enriched.map((r) => ({
+				obsId: r.observation.id,
+				sessionId: r.sessionId,
+				title: r.observation.title,
+				narrative: r.observation.narrative,
+				score: r.score,
+				timestamp: r.observation.timestamp
+			})));
+			const text = packed.items.map((r, index) => `${index + 1}. ${r.title}\n${r.narrative}`).join("\n\n");
+			return {
+				format,
+				results: packed.items,
+				text,
+				tokens_used: packed.used,
+				tokens_budget: tokenBudget,
+				truncated: packed.truncated
+			};
+		}
+		const packed = applyTokenBudget(enriched);
 		logger.info("Search completed", {
 			query,
-			results: enriched.length,
+			results: packed.items.length,
 			hasProjectFilter: !!projectFilter,
 			hasCwdFilter: !!cwdFilter
 		});
-		return { results: enriched };
+		return {
+			format,
+			results: packed.items,
+			tokens_used: packed.used,
+			tokens_budget: tokenBudget,
+			truncated: packed.truncated
+		};
 	});
 }
 
@@ -2486,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;
 }
 
@@ -3660,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,
@@ -4398,7 +4500,7 @@ function registerAutoForgetFunction(sdk, kv) {
 
 //#endregion
 //#region src/version.ts
-const VERSION = "0.8.11";
+const VERSION = "0.9.0";
 
 //#endregion
 //#region src/functions/export-import.ts
@@ -4513,7 +4615,10 @@ function registerExportImportFunction(sdk, kv) {
 			"0.8.8",
 			"0.8.9",
 			"0.8.10",
-			"0.8.11"
+			"0.8.11",
+			"0.8.12",
+			"0.8.13",
+			"0.9.0"
 		]).has(importData.version)) return {
 			success: false,
 			error: `Unsupported export version: ${importData.version}`
@@ -10885,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";
@@ -10896,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);
@@ -10932,6 +11038,561 @@ function registerRetentionFunctions(sdk, kv) {
 	});
 }
 
+//#endregion
+//#region src/functions/compress-file.ts
+const SENSITIVE_PATH_TERMS = [
+	"secret",
+	"credential",
+	"private_key",
+	".env",
+	"id_rsa",
+	"token"
+];
+const COMPRESS_FILE_SYSTEM_PROMPT = `You compress markdown while preserving structure.
+Rules:
+- Keep all headings exactly as-is.
+- Keep all URLs exactly as-is.
+- Keep all fenced code blocks exactly as-is.
+- Do not remove sections; shorten prose under each section.
+- Output only markdown, no wrappers or explanations.`;
+function stripMarkdownFence(text) {
+	const trimmed = text.trim();
+	const match = trimmed.match(/^```(?:markdown|md)?\s*([\s\S]*?)\s*```$/i);
+	return match ? match[1].trim() : trimmed;
+}
+function extractUrls(text) {
+	return Array.from(new Set(text.match(/https?:\/\/[^\s)]+/g) || []));
+}
+function extractHeadings(text) {
+	return text.split("\n").map((line) => line.trim()).filter((line) => /^#{1,6}\s+/.test(line));
+}
+function extractCodeBlocks(text) {
+	return text.match(/```[\s\S]*?```/g) || [];
+}
+function validateCompression(original, compressed) {
+	const errors = [];
+	const originalHeadings = extractHeadings(original);
+	const compressedHeadings = extractHeadings(compressed);
+	for (const heading of originalHeadings) if (!compressedHeadings.includes(heading)) errors.push(`missing heading: ${heading}`);
+	const originalUrls = extractUrls(original).sort();
+	const compressedUrls = extractUrls(compressed).sort();
+	if (originalUrls.length !== compressedUrls.length) errors.push("url count changed");
+	else for (let i = 0; i < originalUrls.length; i++) if (originalUrls[i] !== compressedUrls[i]) {
+		errors.push("url set changed");
+		break;
+	}
+	const originalBlocks = extractCodeBlocks(original);
+	const compressedBlocks = extractCodeBlocks(compressed);
+	if (originalBlocks.length !== compressedBlocks.length) errors.push("code block count changed");
+	else for (let i = 0; i < originalBlocks.length; i++) if (originalBlocks[i] !== compressedBlocks[i]) {
+		errors.push("code block content changed");
+		break;
+	}
+	return errors;
+}
+function resolveBackupPath(filePath) {
+	const base = basename(filePath, extname(filePath));
+	const name = base.endsWith(".original") ? `${base}.backup` : `${base}.original`;
+	return join(dirname(filePath), `${name}.md`);
+}
+function registerCompressFileFunction(sdk, kv, provider) {
+	sdk.registerFunction("mem::compress-file", async (data) => {
+		if (!data?.filePath || typeof data.filePath !== "string") return {
+			success: false,
+			error: "filePath is required"
+		};
+		const absolutePath = resolve(data.filePath);
+		const lowerPath = absolutePath.toLowerCase();
+		if (extname(absolutePath).toLowerCase() !== ".md") return {
+			success: false,
+			error: "filePath must point to a .md file"
+		};
+		if (SENSITIVE_PATH_TERMS.some((term) => lowerPath.includes(term))) return {
+			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");
+		} catch {
+			return {
+				success: false,
+				error: "failed to read file"
+			};
+		}
+		if (!original.trim()) return {
+			success: true,
+			skipped: true,
+			reason: "file is empty"
+		};
+		const compressed = stripMarkdownFence(await provider.summarize(COMPRESS_FILE_SYSTEM_PROMPT, `Compress this markdown file while preserving structure and code blocks:\n\n${original}`));
+		const validationErrors = validateCompression(original, compressed);
+		if (validationErrors.length > 0) return {
+			success: false,
+			error: "compression validation failed",
+			details: validationErrors
+		};
+		const backupPath = resolveBackupPath(absolutePath);
+		await writeFile(backupPath, original, "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,
+				backupPath,
+				originalChars: original.length,
+				compressedChars: compressed.length
+			});
+		} catch {}
+		return {
+			success: true,
+			filePath: absolutePath,
+			backupPath,
+			originalChars: original.length,
+			compressedChars: compressed.length
+		};
+	});
+}
+
+//#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 = {
@@ -10940,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 = {
@@ -10972,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
@@ -11312,11 +11977,25 @@ function registerApiTriggers(sdk, kv, secret, metricsStore, provider) {
 			status_code: 400,
 			body: { error: "cwd must be a string" }
 		};
+		if (body.format !== void 0 && (typeof body.format !== "string" || ![
+			"full",
+			"compact",
+			"narrative"
+		].includes(body.format.trim().toLowerCase()))) return {
+			status_code: 400,
+			body: { error: "format must be one of: full, compact, narrative" }
+		};
+		if (body.token_budget !== void 0 && (!Number.isInteger(body.token_budget) || body.token_budget < 1)) return {
+			status_code: 400,
+			body: { error: "token_budget must be a positive integer" }
+		};
 		const payload = {
 			query: body.query.trim(),
 			limit: body.limit,
 			project: body.project,
-			cwd: body.cwd
+			cwd: body.cwd,
+			format: typeof body.format === "string" ? body.format.trim().toLowerCase() : void 0,
+			token_budget: body.token_budget
 		};
 		return {
 			status_code: 200,
@@ -11335,6 +12014,105 @@ function registerApiTriggers(sdk, kv, secret, metricsStore, provider) {
 			middleware_function_ids: ["middleware::api-auth"]
 		}
 	});
+	sdk.registerFunction("api::compress-file", async (req) => {
+		const authErr = checkAuth(req, secret);
+		if (authErr) return authErr;
+		const filePath = asNonEmptyString$1((req.body ?? {}).filePath);
+		if (!filePath) return {
+			status_code: 400,
+			body: { error: "filePath is required and must be a non-empty string" }
+		};
+		return {
+			status_code: 200,
+			body: await sdk.trigger({
+				function_id: "mem::compress-file",
+				payload: { filePath }
+			})
+		};
+	});
+	sdk.registerTrigger({
+		type: "http",
+		function_id: "api::compress-file",
+		config: {
+			api_path: "/agentmemory/compress-file",
+			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);
@@ -13799,11 +14577,31 @@ const CORE_TOOLS = [
 				limit: {
 					type: "number",
 					description: "Max results to return (default 10)"
+				},
+				format: {
+					type: "string",
+					description: "Result format: full, compact, or narrative (default full)"
+				},
+				token_budget: {
+					type: "number",
+					description: "Optional token budget to trim returned results"
 				}
 			},
 			required: ["query"]
 		}
 	},
+	{
+		name: "memory_compress_file",
+		description: "Compress a markdown file to reduce token usage while preserving headings, URLs, and code blocks. Creates a .original.md backup before writing.",
+		inputSchema: {
+			type: "object",
+			properties: { filePath: {
+				type: "string",
+				description: "Path to the markdown file to compress"
+			} },
+			required: ["filePath"]
+		}
+	},
 	{
 		name: "memory_save",
 		description: "Explicitly save an important insight, decision, or pattern to long-term memory.",
@@ -14758,13 +15556,46 @@ function registerMcpEndpoints(sdk, kv, secret) {
 						status_code: 400,
 						body: { error: "query is required for memory_recall" }
 					};
+					const format = typeof args.format === "string" ? args.format.trim().toLowerCase() : "full";
+					if (![
+						"full",
+						"compact",
+						"narrative"
+					].includes(format)) return {
+						status_code: 400,
+						body: { error: "format must be one of: full, compact, narrative" }
+					};
+					const tokenBudget = asNumber(args.token_budget);
+					if (args.token_budget !== void 0 && (!Number.isInteger(tokenBudget) || (tokenBudget ?? 0) < 1)) return {
+						status_code: 400,
+						body: { error: "token_budget must be a positive integer" }
+					};
 					const result = await sdk.trigger({
 						function_id: "mem::search",
 						payload: {
 							query: args.query,
-							limit: typeof args.limit === "number" ? args.limit : 10
+							limit: typeof args.limit === "number" ? args.limit : 10,
+							format,
+							token_budget: tokenBudget
 						}
 					});
+					return {
+						status_code: 200,
+						body: { content: [{
+							type: "text",
+							text: format === "narrative" && result && typeof result === "object" && "text" in result && typeof result.text === "string" ? result.text : JSON.stringify(result, null, 2)
+						}] }
+					};
+				}
+				case "memory_compress_file": {
+					if (typeof args.filePath !== "string" || !args.filePath.trim()) return {
+						status_code: 400,
+						body: { error: "filePath is required for memory_compress_file" }
+					};
+					const result = await sdk.trigger({
+						function_id: "mem::compress-file",
+						payload: { filePath: args.filePath.trim() }
+					});
 					return {
 						status_code: 200,
 						body: { content: [{
@@ -16472,6 +17303,8 @@ async function main() {
 	registerQueryExpansionFunction(sdk, provider);
 	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();
@@ -16511,7 +17344,7 @@ async function main() {
 		}
 	}
 	console.log(`[agentmemory] Ready. ${embeddingProvider ? "Triple-stream (BM25+Vector+Graph)" : "BM25+Graph"} search active.`);
-	console.log(`[agentmemory] Endpoints: 103 REST + 43 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);