@agentmemory/agentmemory 0.8.6 → 0.8.8

package/README.md

@@ -181,15 +181,6 @@ npx @agentmemory/agentmemory
 </tr>
 </table>
 
-<p align="center">
-  <picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/stat-recall.svg"><img src="assets/tags/stat-recall.svg" alt="95.2% retrieval R@5" height="48" /></picture>
-  <picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/stat-tokens.svg"><img src="assets/tags/stat-tokens.svg" alt="92% fewer tokens" height="48" /></picture>
-  <picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/stat-tools.svg"><img src="assets/tags/stat-tools.svg" alt="43 MCP tools" height="48" /></picture>
-  <picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/stat-hooks.svg"><img src="assets/tags/stat-hooks.svg" alt="12 auto hooks" height="48" /></picture>
-  <picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/stat-deps.svg"><img src="assets/tags/stat-deps.svg" alt="0 external DBs" height="48" /></picture>
-  <picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/stat-tests.svg"><img src="assets/tags/stat-tests.svg" alt="654 tests passing" height="48" /></picture>
-</p>
-
 > Embedding model: `all-MiniLM-L6-v2` (local, free, no API key). Full reports: [`benchmark/LONGMEMEVAL.md`](benchmark/LONGMEMEVAL.md), [`benchmark/QUALITY.md`](benchmark/QUALITY.md), [`benchmark/SCALE.md`](benchmark/SCALE.md). Competitor comparison: [`benchmark/COMPARISON.md`](benchmark/COMPARISON.md) — agentmemory vs mem0, Letta, Khoj, claude-mem, Hippo.
 
 ---
@@ -727,6 +718,11 @@ Create `~/.agentmemory/.env`:
 # III_REST_PORT=3111
 
 # Features
+# AGENTMEMORY_AUTO_COMPRESS=false  # OFF by default (#138). When on,
+                                   # every PostToolUse hook calls your
+                                   # LLM provider to compress the
+                                   # observation — expect significant
+                                   # token spend on active sessions.
 # GRAPH_EXTRACTION_ENABLED=false
 # CONSOLIDATION_ENABLED=true
 # LESSON_DECAY_ENABLED=true

package/dist/cli.mjs

@@ -284,12 +284,12 @@ async function main() {
 	p.intro("agentmemory");
 	if (skipEngine) {
 		p.log.info("Skipping engine check (--no-engine)");
-		await import("./src-DjVaT_sI.mjs");
+		await import("./src-CneY0pgf.mjs");
 		return;
 	}
 	if (await isEngineRunning()) {
 		p.log.success("iii-engine is running");
-		await import("./src-DjVaT_sI.mjs");
+		await import("./src-CneY0pgf.mjs");
 		return;
 	}
 	if (!await startEngine()) {
@@ -333,7 +333,7 @@ async function main() {
 		process.exit(1);
 	}
 	s.stop("iii-engine is ready");
-	await import("./src-DjVaT_sI.mjs");
+	await import("./src-CneY0pgf.mjs");
 }
 async function runStatus() {
 	const port = getRestPort();
@@ -557,7 +557,7 @@ async function runDemo() {
 	p.log.success("agentmemory is working. Point your agent at it and get back to coding.");
 }
 async function runMcp() {
-	await import("./standalone-C7tRDaiu.mjs");
+	await import("./standalone-Qmvspmgi.mjs");
 }
 ({
 	status: runStatus,

package/dist/index.mjs

@@ -156,6 +156,9 @@ function isGraphExtractionEnabled() {
 function isConsolidationEnabled() {
 	return getMergedEnv()["CONSOLIDATION_ENABLED"] === "true";
 }
+function isAutoCompressEnabled() {
+	return getMergedEnv()["AGENTMEMORY_AUTO_COMPRESS"] === "true";
+}
 function getConsolidationDecayDays() {
 	return safeParseInt(getMergedEnv()["CONSOLIDATION_DECAY_DAYS"], 30);
 }
@@ -1997,164 +2000,95 @@ function withKeyedLock(key, fn) {
 }
 
 //#endregion
-//#region src/functions/observe.ts
-function registerObserveFunction(sdk, kv, dedupMap, maxObservationsPerSession) {
-	sdk.registerFunction({
-		id: "mem::observe",
-		description: "Capture and store a tool-use observation"
-	}, async (payload) => {
-		const ctx = getContext();
-		if (!payload?.sessionId || typeof payload.sessionId !== "string" || !payload.hookType || typeof payload.hookType !== "string" || !payload.timestamp || typeof payload.timestamp !== "string") return {
-			success: false,
-			error: "Invalid payload: sessionId, hookType, and timestamp are required"
-		};
-		const obsId = generateId("obs");
-		let dedupHash;
-		if (dedupMap) {
-			const d = typeof payload.data === "object" && payload.data !== null ? payload.data : {};
-			const toolName = d["tool_name"] || payload.hookType;
-			dedupHash = dedupMap.computeHash(payload.sessionId, toolName, d["tool_input"]);
-			if (dedupMap.isDuplicate(dedupHash)) return {
-				deduplicated: true,
-				sessionId: payload.sessionId
-			};
-		}
-		let sanitizedRaw = payload.data;
-		try {
-			const sanitized = stripPrivateData(JSON.stringify(payload.data));
-			sanitizedRaw = JSON.parse(sanitized);
-		} catch {
-			sanitizedRaw = stripPrivateData(String(payload.data));
-		}
-		const raw = {
-			id: obsId,
-			sessionId: payload.sessionId,
-			timestamp: payload.timestamp,
-			hookType: payload.hookType,
-			raw: sanitizedRaw
-		};
-		if (typeof sanitizedRaw === "object" && sanitizedRaw !== null) {
-			const d = sanitizedRaw;
-			if (payload.hookType === "post_tool_use" || payload.hookType === "post_tool_failure") {
-				raw.toolName = d["tool_name"];
-				raw.toolInput = d["tool_input"];
-				raw.toolOutput = d["tool_output"] || d["error"];
-			}
-			if (payload.hookType === "prompt_submit") raw.userPrompt = d["prompt"];
-		}
-		return withKeyedLock(`obs:${payload.sessionId}`, async () => {
-			if (maxObservationsPerSession && maxObservationsPerSession > 0) {
-				if ((await kv.list(KV.observations(payload.sessionId))).length >= maxObservationsPerSession) return {
-					success: false,
-					error: `Session observation limit reached (${maxObservationsPerSession})`
-				};
-			}
-			await kv.set(KV.observations(payload.sessionId), obsId, raw);
-			if (dedupMap && dedupHash) dedupMap.record(dedupHash);
-			sdk.triggerVoid("stream::set", {
-				stream_name: STREAM.name,
-				group_id: STREAM.group(payload.sessionId),
-				item_id: obsId,
-				data: {
-					type: "raw",
-					observation: raw
-				}
-			});
-			sdk.triggerVoid("stream::set", {
-				stream_name: STREAM.name,
-				group_id: STREAM.viewerGroup,
-				item_id: obsId,
-				data: {
-					type: "raw",
-					observation: raw,
-					sessionId: payload.sessionId
-				}
-			});
-			const session = await kv.get(KV.sessions, payload.sessionId);
-			if (session) await kv.set(KV.sessions, payload.sessionId, {
-				...session,
-				observationCount: (session.observationCount || 0) + 1
-			});
-			sdk.triggerVoid("mem::compress", {
-				observationId: obsId,
-				sessionId: payload.sessionId,
-				raw
-			});
-			ctx.logger.info("Observation captured", {
-				obsId,
-				sessionId: payload.sessionId,
-				hook: payload.hookType
-			});
-			return { observationId: obsId };
-		});
-	});
-}
-
-//#endregion
-//#region src/prompts/compression.ts
-const COMPRESSION_SYSTEM = `You are a memory compression engine for an AI coding agent. Your job is to extract the essential information from a tool usage observation and compress it into structured data.
-
-Output EXACTLY this XML format with no additional text:
-
-<observation>
-  <type>one of: file_read, file_write, file_edit, command_run, search, web_fetch, conversation, error, decision, discovery, subagent, notification, task, other</type>
-  <title>Short descriptive title (max 80 chars)</title>
-  <subtitle>One-line context (optional)</subtitle>
-  <facts>
-    <fact>Specific factual detail 1</fact>
-    <fact>Specific factual detail 2</fact>
-  </facts>
-  <narrative>2-3 sentence summary of what happened and why it matters</narrative>
-  <concepts>
-    <concept>technical concept or pattern</concept>
-  </concepts>
-  <files>
-    <file>path/to/file</file>
-  </files>
-  <importance>1-10 scale, 10 being critical architectural decision</importance>
-</observation>
-
-Rules:
-- Be concise but preserve ALL technically relevant details
-- File paths must be exact
-- Importance: 1-3 for routine reads, 4-6 for edits/commands, 7-9 for architectural decisions, 10 for breaking changes
-- Concepts should be reusable search terms (e.g., "React hooks", "SQL migration", "auth middleware")
-- Strip any secrets, tokens, or credentials from the output`;
-function buildCompressionPrompt(observation) {
-	const parts = [`Timestamp: ${observation.timestamp}`, `Hook: ${observation.hookType}`];
-	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)}`);
-	}
-	if (observation.toolOutput) {
-		const output = typeof observation.toolOutput === "string" ? observation.toolOutput : JSON.stringify(observation.toolOutput, null, 2);
-		parts.push(`Output:\n${truncate(output, 4e3)}`);
+//#region src/functions/compress-synthetic.ts
+function inferType(toolName, hookType) {
+	if (hookType === "post_tool_failure") return "error";
+	if (hookType === "prompt_submit") return "conversation";
+	if (hookType === "subagent_stop" || hookType === "task_completed") return "subagent";
+	if (hookType === "notification") return "notification";
+	if (!toolName) return "other";
+	const n = toolName.replace(/([a-z])([A-Z])/g, "$1_$2").replace(/[-\s]+/g, "_").toLowerCase();
+	const hasWord = (word) => new RegExp(`(^|_)${word}(_|$)`).test(n) || n === word || n.endsWith(word) || n.startsWith(word);
+	if ([
+		"fetch",
+		"http",
+		"web"
+	].some(hasWord)) return "web_fetch";
+	if ([
+		"grep",
+		"search",
+		"glob",
+		"find"
+	].some(hasWord)) return "search";
+	if ([
+		"bash",
+		"shell",
+		"exec",
+		"run"
+	].some(hasWord)) return "command_run";
+	if ([
+		"edit",
+		"update",
+		"patch",
+		"replace"
+	].some(hasWord)) return "file_edit";
+	if (["write", "create"].some(hasWord)) return "file_write";
+	if (["read", "view"].some(hasWord)) return "file_read";
+	if (["task", "agent"].some(hasWord)) return "subagent";
+	return "other";
+}
+function extractFiles$1(input) {
+	if (!input || typeof input !== "object") return [];
+	const o = input;
+	const out = /* @__PURE__ */ new Set();
+	for (const key of [
+		"file_path",
+		"filepath",
+		"path",
+		"filePath",
+		"file",
+		"pattern"
+	]) {
+		const v = o[key];
+		if (typeof v === "string" && v.length > 0 && v.length < 512) out.add(v);
+	}
+	return [...out];
+}
+function stringifyForNarrative(v) {
+	if (v == null) return "";
+	if (typeof v === "string") return v;
+	try {
+		return JSON.stringify(v);
+	} catch {
+		return String(v);
 	}
-	if (observation.userPrompt) parts.push(`User prompt:\n${truncate(observation.userPrompt, 2e3)}`);
-	return parts.join("\n\n");
 }
-function truncate(s, max) {
-	return s.length > max ? s.slice(0, max) + "\n[...truncated]" : s;
-}
-
-//#endregion
-//#region src/prompts/xml.ts
-const VALID_TAG = /^[a-zA-Z_][a-zA-Z0-9_-]*$/;
-function getXmlTag(xml, tag) {
-	if (!VALID_TAG.test(tag)) return "";
-	const match = xml.match(new RegExp(`<${tag}>([\\s\\S]*?)</${tag}>`));
-	return match ? match[1].trim() : "";
+function truncate$1(s, n) {
+	return s.length > n ? s.slice(0, n - 1) + "…" : s;
 }
-function getXmlChildren(xml, parentTag, childTag) {
-	if (!VALID_TAG.test(parentTag) || !VALID_TAG.test(childTag)) return [];
-	const parentMatch = xml.match(new RegExp(`<${parentTag}>([\\s\\S]*?)</${parentTag}>`));
-	if (!parentMatch) return [];
-	const items = [];
-	const re = new RegExp(`<${childTag}>([\\s\\S]*?)</${childTag}>`, "g");
-	let m;
-	while ((m = re.exec(parentMatch[1])) !== null) items.push(m[1].trim());
-	return items;
+function buildSyntheticCompression(raw) {
+	const toolName = raw.toolName ?? raw.hookType;
+	const inputStr = stringifyForNarrative(raw.toolInput);
+	const outputStr = stringifyForNarrative(raw.toolOutput);
+	const narrativeParts = [
+		raw.userPrompt ?? "",
+		inputStr,
+		outputStr
+	].filter((s) => s.length > 0);
+	return {
+		id: raw.id,
+		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,
+		facts: [],
+		narrative: truncate$1(narrativeParts.join(" | "), 400),
+		concepts: [],
+		files: extractFiles$1(raw.toolInput),
+		importance: 5,
+		confidence: .3
+	};
 }
 
 //#endregion
@@ -2325,6 +2259,192 @@ function registerSearchFunction(sdk, kv) {
 	});
 }
 
+//#endregion
+//#region src/functions/observe.ts
+function registerObserveFunction(sdk, kv, dedupMap, maxObservationsPerSession) {
+	sdk.registerFunction({
+		id: "mem::observe",
+		description: "Capture and store a tool-use observation"
+	}, async (payload) => {
+		const ctx = getContext();
+		if (!payload?.sessionId || typeof payload.sessionId !== "string" || !payload.hookType || typeof payload.hookType !== "string" || !payload.timestamp || typeof payload.timestamp !== "string") return {
+			success: false,
+			error: "Invalid payload: sessionId, hookType, and timestamp are required"
+		};
+		const obsId = generateId("obs");
+		let dedupHash;
+		if (dedupMap) {
+			const d = typeof payload.data === "object" && payload.data !== null ? payload.data : {};
+			const toolName = d["tool_name"] || payload.hookType;
+			dedupHash = dedupMap.computeHash(payload.sessionId, toolName, d["tool_input"]);
+			if (dedupMap.isDuplicate(dedupHash)) return {
+				deduplicated: true,
+				sessionId: payload.sessionId
+			};
+		}
+		let sanitizedRaw = payload.data;
+		try {
+			const sanitized = stripPrivateData(JSON.stringify(payload.data));
+			sanitizedRaw = JSON.parse(sanitized);
+		} catch {
+			sanitizedRaw = stripPrivateData(String(payload.data));
+		}
+		const raw = {
+			id: obsId,
+			sessionId: payload.sessionId,
+			timestamp: payload.timestamp,
+			hookType: payload.hookType,
+			raw: sanitizedRaw
+		};
+		if (typeof sanitizedRaw === "object" && sanitizedRaw !== null) {
+			const d = sanitizedRaw;
+			if (payload.hookType === "post_tool_use" || payload.hookType === "post_tool_failure") {
+				raw.toolName = d["tool_name"];
+				raw.toolInput = d["tool_input"];
+				raw.toolOutput = d["tool_output"] || d["error"];
+			}
+			if (payload.hookType === "prompt_submit") raw.userPrompt = d["prompt"];
+		}
+		return withKeyedLock(`obs:${payload.sessionId}`, async () => {
+			if (maxObservationsPerSession && maxObservationsPerSession > 0) {
+				if ((await kv.list(KV.observations(payload.sessionId))).length >= maxObservationsPerSession) return {
+					success: false,
+					error: `Session observation limit reached (${maxObservationsPerSession})`
+				};
+			}
+			await kv.set(KV.observations(payload.sessionId), obsId, raw);
+			if (dedupMap && dedupHash) dedupMap.record(dedupHash);
+			sdk.triggerVoid("stream::set", {
+				stream_name: STREAM.name,
+				group_id: STREAM.group(payload.sessionId),
+				item_id: obsId,
+				data: {
+					type: "raw",
+					observation: raw
+				}
+			});
+			sdk.triggerVoid("stream::set", {
+				stream_name: STREAM.name,
+				group_id: STREAM.viewerGroup,
+				item_id: obsId,
+				data: {
+					type: "raw",
+					observation: raw,
+					sessionId: payload.sessionId
+				}
+			});
+			const session = await kv.get(KV.sessions, payload.sessionId);
+			if (session) await kv.set(KV.sessions, payload.sessionId, {
+				...session,
+				observationCount: (session.observationCount || 0) + 1
+			});
+			if (isAutoCompressEnabled()) sdk.triggerVoid("mem::compress", {
+				observationId: obsId,
+				sessionId: payload.sessionId,
+				raw
+			});
+			else {
+				const synthetic = buildSyntheticCompression(raw);
+				await kv.set(KV.observations(payload.sessionId), obsId, synthetic);
+				getSearchIndex().add(synthetic);
+				sdk.triggerVoid("stream::set", {
+					stream_name: STREAM.name,
+					group_id: STREAM.group(payload.sessionId),
+					item_id: obsId,
+					data: {
+						type: "compressed",
+						observation: synthetic
+					}
+				});
+				sdk.triggerVoid("stream::set", {
+					stream_name: STREAM.name,
+					group_id: STREAM.viewerGroup,
+					item_id: obsId,
+					data: {
+						type: "compressed",
+						observation: synthetic,
+						sessionId: payload.sessionId
+					}
+				});
+			}
+			ctx.logger.info("Observation captured", {
+				obsId,
+				sessionId: payload.sessionId,
+				hook: payload.hookType,
+				compress: isAutoCompressEnabled() ? "llm" : "synthetic"
+			});
+			return { observationId: obsId };
+		});
+	});
+}
+
+//#endregion
+//#region src/prompts/compression.ts
+const COMPRESSION_SYSTEM = `You are a memory compression engine for an AI coding agent. Your job is to extract the essential information from a tool usage observation and compress it into structured data.
+
+Output EXACTLY this XML format with no additional text:
+
+<observation>
+  <type>one of: file_read, file_write, file_edit, command_run, search, web_fetch, conversation, error, decision, discovery, subagent, notification, task, other</type>
+  <title>Short descriptive title (max 80 chars)</title>
+  <subtitle>One-line context (optional)</subtitle>
+  <facts>
+    <fact>Specific factual detail 1</fact>
+    <fact>Specific factual detail 2</fact>
+  </facts>
+  <narrative>2-3 sentence summary of what happened and why it matters</narrative>
+  <concepts>
+    <concept>technical concept or pattern</concept>
+  </concepts>
+  <files>
+    <file>path/to/file</file>
+  </files>
+  <importance>1-10 scale, 10 being critical architectural decision</importance>
+</observation>
+
+Rules:
+- Be concise but preserve ALL technically relevant details
+- File paths must be exact
+- Importance: 1-3 for routine reads, 4-6 for edits/commands, 7-9 for architectural decisions, 10 for breaking changes
+- Concepts should be reusable search terms (e.g., "React hooks", "SQL migration", "auth middleware")
+- Strip any secrets, tokens, or credentials from the output`;
+function buildCompressionPrompt(observation) {
+	const parts = [`Timestamp: ${observation.timestamp}`, `Hook: ${observation.hookType}`];
+	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)}`);
+	}
+	if (observation.toolOutput) {
+		const output = typeof observation.toolOutput === "string" ? observation.toolOutput : JSON.stringify(observation.toolOutput, null, 2);
+		parts.push(`Output:\n${truncate(output, 4e3)}`);
+	}
+	if (observation.userPrompt) parts.push(`User prompt:\n${truncate(observation.userPrompt, 2e3)}`);
+	return parts.join("\n\n");
+}
+function truncate(s, max) {
+	return s.length > max ? s.slice(0, max) + "\n[...truncated]" : s;
+}
+
+//#endregion
+//#region src/prompts/xml.ts
+const VALID_TAG = /^[a-zA-Z_][a-zA-Z0-9_-]*$/;
+function getXmlTag(xml, tag) {
+	if (!VALID_TAG.test(tag)) return "";
+	const match = xml.match(new RegExp(`<${tag}>([\\s\\S]*?)</${tag}>`));
+	return match ? match[1].trim() : "";
+}
+function getXmlChildren(xml, parentTag, childTag) {
+	if (!VALID_TAG.test(parentTag) || !VALID_TAG.test(childTag)) return [];
+	const parentMatch = xml.match(new RegExp(`<${parentTag}>([\\s\\S]*?)</${parentTag}>`));
+	if (!parentMatch) return [];
+	const items = [];
+	const re = new RegExp(`<${childTag}>([\\s\\S]*?)</${childTag}>`, "g");
+	let m;
+	while ((m = re.exec(parentMatch[1])) !== null) items.push(m[1].trim());
+	return items;
+}
+
 //#endregion
 //#region src/eval/schemas.ts
 const HookTypeEnum = z.enum([
@@ -4007,7 +4127,7 @@ function registerAutoForgetFunction(sdk, kv) {
 
 //#endregion
 //#region src/version.ts
-const VERSION = "0.8.6";
+const VERSION = "0.8.8";
 
 //#endregion
 //#region src/functions/export-import.ts
@@ -4121,7 +4241,9 @@ function registerExportImportFunction(sdk, kv) {
 			"0.8.3",
 			"0.8.4",
 			"0.8.5",
-			"0.8.6"
+			"0.8.6",
+			"0.8.7",
+			"0.8.8"
 		]).has(importData.version)) return {
 			success: false,
 			error: `Unsupported export version: ${importData.version}`
@@ -14957,6 +15079,8 @@ async function main() {
 	}
 	registerConsolidationPipelineFunction(sdk, kv, provider);
 	console.log(`[agentmemory] Consolidation pipeline: registered (CONSOLIDATION_ENABLED=${isConsolidationEnabled() ? "true" : "false"})`);
+	if (isAutoCompressEnabled()) console.log(`[agentmemory] WARNING: AGENTMEMORY_AUTO_COMPRESS=true — every PostToolUse observation will be sent to your LLM provider for compression. This spends API tokens proportional to your session tool-use frequency (see #138). Set AGENTMEMORY_AUTO_COMPRESS=false to disable.`);
+	else console.log(`[agentmemory] Auto-compress: OFF (default, #138) — observations indexed via zero-LLM synthetic compression. Set AGENTMEMORY_AUTO_COMPRESS=true to opt-in to LLM-powered summaries (uses your API key).`);
 	const teamConfig = loadTeamConfig();
 	if (teamConfig) {
 		registerTeamFunction(sdk, kv, teamConfig);