@agentmemory/agentmemory 0.9.2 → 0.9.4

package/README.md

@@ -8,7 +8,7 @@
 </p>
 
 <p align="center">
-  <a href="https://gist.github.com/rohitg00/2067ab416f7bbe447c1977edaaa681e2"><img src="https://img.shields.io/badge/Viral%20GitHub%20Gist-825%20stars%20%2F%20110%20forks-FF6B35?style=for-the-badge&logo=github&logoColor=white&labelColor=1a1a1a" alt="Design doc: 825 stars / 110 forks on the gist" /></a>
+  <a href="https://gist.github.com/rohitg00/2067ab416f7bbe447c1977edaaa681e2"><img src="https://img.shields.io/badge/Viral%20GitHub%20Gist-1050%20stars%20%2F%20150%20forks-FF6B35?style=for-the-badge&logo=github&logoColor=white&labelColor=1a1a1a" alt="Design doc: 1050 stars / 150 forks on the gist" /></a>
 </p>
 
 <p align="center">
@@ -370,7 +370,7 @@ mcp_servers:
     command: npx
     args: ["-y", "@agentmemory/mcp"]
 
-Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper 6-hook memory provider integration (pre-LLM context injection, turn capture, MEMORY.md mirroring, system prompt block), copy integrations/hermes from the agentmemory repo to ~/.hermes/plugins/memory/agentmemory.
+Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper 6-hook memory provider integration (pre-LLM context injection, turn capture, MEMORY.md mirroring, system prompt block), copy integrations/hermes from the agentmemory repo to ~/.hermes/plugins/agentmemory.
 ```
 
 Full guide: [`integrations/hermes/`](integrations/hermes/)
@@ -506,7 +506,12 @@ PostToolUse hook fires
   -> Store raw observation
   -> LLM compress -> structured facts + concepts + narrative
   -> Vector embedding (6 providers + local)
-  -> Index in BM25 + vector + knowledge graph
+  -> Index in BM25 + vector
+
+Stop / SessionEnd hook fires
+  -> Summarize session
+  -> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
+  -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
 
 SessionStart hook fires
   -> Load project profile (top concepts, files, patterns)

package/dist/cli.mjs

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 import { execFileSync, spawn, spawnSync } from "node:child_process";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, readlinkSync, statSync } from "node:fs";
 import { delimiter, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { platform } from "node:os";
+import { homedir, platform } from "node:os";
 import * as p from "@clack/prompts";
 import { createHash } from "node:crypto";
 
@@ -92,11 +92,14 @@ Usage: agentmemory [command] [options]
 
 Commands:
   (default)          Start agentmemory worker
-  status             Show connection status, memory count, and health
+  status             Show connection status, memory count, flags, and health
+  doctor             Run diagnostic checks (server, flags, graph, providers)
   demo               Seed sample sessions and show recall in action
   upgrade            Upgrade local deps + iii runtime (best effort)
   mcp                Start standalone MCP server (no engine required)
   import-jsonl [p]   Import Claude Code JSONL transcripts (default: ~/.claude/projects)
+                     --max-files <N> | --max-files=<N>: override scan cap (default 200, max 1000;
+                     out-of-range is rejected; for trees >1000 files, batch by subdirectory)
 
 Options:
   --help, -h         Show this help
@@ -105,10 +108,15 @@ Options:
   --no-engine        Skip auto-starting iii-engine
   --port <N>         Override REST port (default: 3111)
 
+Environment:
+  AGENTMEMORY_URL    Full REST base URL (e.g. http://localhost:3111).
+                     Honored by status, doctor, and MCP shim commands.
+
 Quick start:
   npx @agentmemory/agentmemory          # start with local iii-engine or Docker
-  npx @agentmemory/agentmemory status   # check health
-  npx @agentmemory/agentmemory demo     # try it in 30 seconds (needs server running)
+  npx @agentmemory/agentmemory demo     # see semantic recall in 30 seconds
+  npx @agentmemory/agentmemory doctor   # diagnose config + feature flags
+  npx @agentmemory/agentmemory status   # health + memory count + flags
   npx @agentmemory/agentmemory upgrade  # upgrade agentmemory + iii runtime
   npx @agentmemory/agentmemory mcp      # standalone MCP server (no engine)
   npx @agentmemory/mcp                  # same as above (shim package)
@@ -121,11 +129,32 @@ const portIdx = args.indexOf("--port");
 if (portIdx !== -1 && args[portIdx + 1]) process.env["III_REST_PORT"] = args[portIdx + 1];
 const skipEngine = args.includes("--no-engine");
 function getRestPort() {
+	const url = process.env["AGENTMEMORY_URL"];
+	if (url) try {
+		const parsed = new URL(url).port;
+		if (parsed) return parseInt(parsed, 10);
+	} catch {}
 	return parseInt(process.env["III_REST_PORT"] || "3111", 10) || 3111;
 }
+function getBaseUrl() {
+	const url = process.env["AGENTMEMORY_URL"];
+	if (url) return url.replace(/\/+$/, "");
+	return `http://localhost:${getRestPort()}`;
+}
+function getViewerUrl() {
+	const envUrl = process.env["AGENTMEMORY_VIEWER_URL"];
+	if (envUrl) return envUrl.replace(/\/+$/, "");
+	try {
+		const u = new URL(getBaseUrl());
+		const vPort = (parseInt(u.port || "3111", 10) || 3111) + 2;
+		return `${u.protocol}//${u.hostname}:${vPort}`;
+	} catch {
+		return `http://localhost:${getRestPort() + 2}`;
+	}
+}
 async function isEngineRunning() {
 	try {
-		await fetch(`http://localhost:${getRestPort()}/`, { signal: AbortSignal.timeout(2e3) });
+		await fetch(`${getBaseUrl()}/`, { signal: AbortSignal.timeout(2e3) });
 		return true;
 	} catch {
 		return false;
@@ -133,7 +162,7 @@ async function isEngineRunning() {
 }
 async function isAgentmemoryReady() {
 	try {
-		return (await fetch(`http://localhost:${getRestPort()}/agentmemory/livez`, { signal: AbortSignal.timeout(2e3) })).ok;
+		return (await fetch(`${getBaseUrl()}/agentmemory/livez`, { signal: AbortSignal.timeout(2e3) })).ok;
 	} catch {
 		return false;
 	}
@@ -299,12 +328,12 @@ async function main() {
 	p.intro("agentmemory");
 	if (skipEngine) {
 		p.log.info("Skipping engine check (--no-engine)");
-		await import("./src-tmuZyobT.mjs");
+		await import("./src-uDy2jLO-.mjs");
 		return;
 	}
 	if (await isEngineRunning()) {
 		p.log.success("iii-engine is running");
-		await import("./src-tmuZyobT.mjs");
+		await import("./src-uDy2jLO-.mjs");
 		return;
 	}
 	if (!await startEngine()) {
@@ -348,30 +377,38 @@ async function main() {
 		process.exit(1);
 	}
 	s.stop("iii-engine is ready");
-	await import("./src-tmuZyobT.mjs");
+	await import("./src-uDy2jLO-.mjs");
+}
+async function apiFetch(base, path, timeoutMs = 5e3) {
+	try {
+		return await (await fetch(`${base}/agentmemory/${path}`, { signal: AbortSignal.timeout(timeoutMs) })).json();
+	} catch {
+		return null;
+	}
 }
 async function runStatus() {
-	const port = getRestPort();
-	const base = `http://localhost:${port}`;
+	getRestPort();
+	const base = getBaseUrl();
 	p.intro("agentmemory status");
 	if (!await isEngineRunning()) {
-		p.log.error(`Not running — no response on port ${port}`);
+		p.log.error(`Not running — no response at ${base}`);
 		p.log.info("Start with: npx @agentmemory/agentmemory");
 		process.exit(1);
 	}
 	try {
-		const [healthRes, sessionsRes, graphRes, memoriesRes] = await Promise.all([
-			fetch(`${base}/agentmemory/health`, { signal: AbortSignal.timeout(5e3) }).then((r) => r.json()).catch(() => null),
-			fetch(`${base}/agentmemory/sessions`, { signal: AbortSignal.timeout(5e3) }).then((r) => r.json()).catch(() => null),
-			fetch(`${base}/agentmemory/graph/stats`, { signal: AbortSignal.timeout(5e3) }).then((r) => r.json()).catch(() => null),
-			fetch(`${base}/agentmemory/export`, { signal: AbortSignal.timeout(5e3) }).then((r) => r.json()).catch(() => null)
+		const [healthRes, sessionsRes, graphRes, memoriesRes, flagsRes] = await Promise.all([
+			apiFetch(base, "health"),
+			apiFetch(base, "sessions"),
+			apiFetch(base, "graph/stats"),
+			apiFetch(base, "export"),
+			apiFetch(base, "config/flags")
 		]);
 		const h = healthRes?.health;
 		const status = healthRes?.status || "unknown";
 		const version = healthRes?.version || "?";
 		const sessions = Array.isArray(sessionsRes?.sessions) ? sessionsRes.sessions.length : 0;
-		const nodes = graphRes?.nodes || 0;
-		const edges = graphRes?.edges || 0;
+		const nodes = Number(graphRes?.totalNodes ?? graphRes?.nodes ?? graphRes?.nodeCount ?? 0);
+		const edges = Number(graphRes?.totalEdges ?? graphRes?.edges ?? graphRes?.edgeCount ?? 0);
 		const cb = healthRes?.circuitBreaker?.state || "closed";
 		const heapMB = h?.memory ? Math.round(h.memory.heapUsed / 1048576) : 0;
 		const uptime = h?.uptimeSeconds ? Math.round(h.uptimeSeconds) : 0;
@@ -381,7 +418,7 @@ async function runStatus() {
 		const estInjectedTokens = Math.min(obsCount, 50) * 38;
 		const tokensSaved = estFullTokens - estInjectedTokens;
 		const pctSaved = estFullTokens > 0 ? Math.round(tokensSaved / estFullTokens * 100) : 0;
-		p.log.success(`Connected — v${version} on port ${port}`);
+		p.log.success(`Connected — v${version} at ${base}`);
 		const lines = [
 			`Health:       ${status === "healthy" ? "✓ healthy" : status}`,
 			`Sessions:     ${sessions}`,
@@ -391,7 +428,7 @@ async function runStatus() {
 			`Circuit:      ${cb}`,
 			`Heap:         ${heapMB} MB`,
 			`Uptime:       ${uptime}s`,
-			`Viewer:       http://localhost:${port + 2}`
+			`Viewer:       ${getViewerUrl()}`
 		];
 		if (obsCount > 0) {
 			lines.push("");
@@ -399,12 +436,143 @@ async function runStatus() {
 			lines.push(`  Full context: ~${estFullTokens.toLocaleString()} tokens`);
 			lines.push(`  Injected:     ~${estInjectedTokens.toLocaleString()} tokens`);
 		}
+		if (flagsRes) {
+			const provider = flagsRes.provider === "llm" ? "✓ llm" : "✗ noop (no key)";
+			const embed = flagsRes.embeddingProvider === "embeddings" ? "✓ embeddings" : "bm25-only";
+			const flagRows = (flagsRes.flags || []).map((f) => `  ${f.enabled ? "✓" : "✗"} ${f.key.padEnd(32)} ${f.label}`);
+			lines.push("");
+			lines.push(`Provider:     ${provider}`);
+			lines.push(`Embeddings:   ${embed}`);
+			lines.push(`Flags:`);
+			flagRows.forEach((r) => lines.push(r));
+		}
 		p.note(lines.join("\n"), "agentmemory");
 	} catch (err) {
 		p.log.error(err instanceof Error ? err.message : String(err));
 		process.exit(1);
 	}
 }
+function formatChecks(checks) {
+	return checks.map((c) => `${c.ok ? "✓" : "✗"} ${c.name}${c.hint ? `\n   ${c.hint}` : ""}`).join("\n");
+}
+function findLatestDebugLog(debugDir) {
+	const latestLink = join(debugDir, "latest");
+	try {
+		if (existsSync(latestLink)) {
+			const target = readlinkSync(latestLink);
+			const resolved = target.startsWith("/") ? target : join(debugDir, target);
+			if (existsSync(resolved)) return resolved;
+		}
+	} catch {}
+	try {
+		const newest = readdirSync(debugDir).filter((f) => f.endsWith(".txt")).map((f) => ({
+			f,
+			m: statSync(join(debugDir, f)).mtimeMs
+		})).sort((a, b) => b.m - a.m)[0];
+		if (newest) return join(debugDir, newest.f);
+	} catch {}
+}
+function checkClaudeCodeHooks() {
+	const debugDir = join(homedir(), ".claude", "debug");
+	if (!existsSync(debugDir)) return { state: "no-cc-dir" };
+	const logPath = findLatestDebugLog(debugDir);
+	if (!logPath) return { state: "no-debug-log" };
+	let content;
+	try {
+		content = readFileSync(logPath, "utf8");
+	} catch {
+		return { state: "no-debug-log" };
+	}
+	const match = content.match(/Loaded hooks from standard location for plugin agentmemory:\s*(\S+)/);
+	if (match) return {
+		state: "loaded",
+		manifestPath: match[1]
+	};
+	if (content.includes("Loading hooks from plugin: agentmemory")) return { state: "loaded" };
+	return { state: "not-loaded" };
+}
+async function runDoctor() {
+	p.intro("agentmemory doctor");
+	const base = getBaseUrl();
+	const viewerUrl = getViewerUrl();
+	const checks = [];
+	const serverUp = await isEngineRunning();
+	checks.push({
+		name: "Server reachable",
+		ok: serverUp,
+		hint: serverUp ? void 0 : `Start with: npx @agentmemory/agentmemory (tried ${base})`
+	});
+	if (!serverUp) {
+		p.note(formatChecks(checks), "server unreachable");
+		process.exit(1);
+	}
+	const [health, flags, graph] = await Promise.all([
+		apiFetch(base, "health", 3e3),
+		apiFetch(base, "config/flags", 3e3),
+		apiFetch(base, "graph/stats", 3e3)
+	]);
+	const viewerUp = await fetch(viewerUrl, { signal: AbortSignal.timeout(2e3) }).then((r) => r.ok).catch(() => false);
+	const hasLlm = flags?.provider === "llm";
+	const hasEmbed = flags?.embeddingProvider === "embeddings";
+	const graphHas = Number(graph?.totalNodes ?? graph?.nodes ?? graph?.nodeCount ?? 0) > 0;
+	checks.push({
+		name: "Health status",
+		ok: health?.status === "healthy",
+		hint: health?.status === "healthy" ? void 0 : `Status: ${health?.status || "unknown"}`
+	}, {
+		name: "Viewer reachable",
+		ok: viewerUp,
+		hint: viewerUp ? void 0 : `${viewerUrl} not responding`
+	}, {
+		name: "LLM provider",
+		ok: hasLlm,
+		hint: hasLlm ? void 0 : "export ANTHROPIC_API_KEY=sk-ant-... (or GEMINI/OPENROUTER/MINIMAX) then restart"
+	}, {
+		name: "Embedding provider",
+		ok: hasEmbed,
+		hint: hasEmbed ? void 0 : "Running BM25-only. Add OPENAI_API_KEY / VOYAGE_API_KEY / COHERE_API_KEY / OLLAMA_HOST for semantic recall"
+	});
+	for (const f of flags?.flags || []) checks.push({
+		name: f.label,
+		ok: f.enabled,
+		hint: f.enabled ? void 0 : f.enableHow
+	});
+	const cc = checkClaudeCodeHooks();
+	const ccCheck = (() => {
+		switch (cc.state) {
+			case "loaded": return {
+				ok: true,
+				hint: cc.manifestPath ? `manifest: ${cc.manifestPath}` : void 0
+			};
+			case "not-loaded": return {
+				ok: false,
+				hint: "Plugin enabled but hooks not loaded by Claude Code. Try: /plugin uninstall agentmemory@agentmemory && /plugin install agentmemory@agentmemory, then restart the session. CC must be >= 2.1.x for plugin-hook auto-load."
+			};
+			case "no-debug-log": return {
+				ok: false,
+				hint: "Cannot verify — no Claude Code debug log found. Run once with `claude --debug -p \"x\"`, then re-run doctor."
+			};
+			case "no-cc-dir": return;
+		}
+	})();
+	if (ccCheck) checks.push({
+		name: "Claude Code plugin hooks registered",
+		...ccCheck
+	});
+	checks.push({
+		name: "Knowledge graph populated",
+		ok: graphHas,
+		hint: graphHas ? void 0 : "Graph is empty. Run a session with GRAPH_EXTRACTION_ENABLED=true, or POST /agentmemory/graph/extract"
+	});
+	const passed = checks.filter((c) => c.ok).length;
+	const total = checks.length;
+	p.note(formatChecks(checks), `${passed}/${total} checks passing`);
+	if (passed === total) p.outro("✓ All checks passed. agentmemory is healthy.");
+	else {
+		p.outro(`${total - passed} issue(s) — follow hints above to fix.`);
+		process.exit(1);
+	}
+}
 function buildDemoSessions() {
 	return [
 		{
@@ -565,7 +733,7 @@ async function runDemo() {
 		`Notice: searching "database performance optimization"`,
 		`found the N+1 query fix — keyword matching can't do that.`,
 		"",
-		`Viewer:        http://localhost:${port + 2}`,
+		`Viewer:        ${getViewerUrl()}`,
 		`Clean up with: curl -X DELETE "${base}/agentmemory/sessions?project=${demoProject}"`
 	];
 	p.note(lines.join("\n"), "demo complete");
@@ -657,10 +825,38 @@ async function runUpgrade() {
 	].join("\n"), "agentmemory upgrade");
 }
 async function runMcp() {
-	await import("./standalone-BiwX0rdC.mjs");
+	await import("./standalone-CqqEcfNR.mjs");
 }
 async function runImportJsonl() {
-	const pathArg = args.slice(1).filter((a) => !a.startsWith("-"))[0];
+	const VALUE_FLAGS = new Set(["--port", "--tools"]);
+	let maxFiles;
+	const tail = args.slice(1);
+	const positional = [];
+	for (let i = 0; i < tail.length; i++) {
+		const a = tail[i];
+		if (a === "--max-files") {
+			const raw = tail[i + 1];
+			const parsed = raw !== void 0 ? parseInt(raw, 10) : NaN;
+			if (Number.isInteger(parsed) && parsed > 0) maxFiles = parsed;
+			else if (raw !== void 0) p.log.warn(`Ignoring --max-files ${raw}: expected a positive integer.`);
+			i++;
+			continue;
+		}
+		if (a.startsWith("--max-files=")) {
+			const raw = a.slice(12);
+			const parsed = parseInt(raw, 10);
+			if (Number.isInteger(parsed) && parsed > 0) maxFiles = parsed;
+			else p.log.warn(`Ignoring --max-files=${raw}: expected a positive integer.`);
+			continue;
+		}
+		if (VALUE_FLAGS.has(a)) {
+			i++;
+			continue;
+		}
+		if (a.startsWith("-")) continue;
+		positional.push(a);
+	}
+	const pathArg = positional[0];
 	const port = getRestPort();
 	const base = `http://localhost:${port}`;
 	let probeOk = false;
@@ -682,6 +878,7 @@ async function runImportJsonl() {
 	}
 	const body = {};
 	if (pathArg) body["path"] = pathArg;
+	if (maxFiles !== void 0) body["maxFiles"] = maxFiles;
 	const headers = { "content-type": "application/json" };
 	const secret = process.env["AGENTMEMORY_SECRET"];
 	if (secret) headers["authorization"] = `Bearer ${secret}`;
@@ -713,7 +910,18 @@ async function runImportJsonl() {
 			process.exit(1);
 		}
 		spinner.stop(`imported ${json.imported ?? 0} file(s), ${json.observations ?? 0} observation(s) across ${json.sessionIds?.length || 0} session(s)`);
-		if (json.sessionIds && json.sessionIds.length > 0) p.log.info(`View at http://localhost:${port + 2} → Replay tab`);
+		if (json.truncated) {
+			const cap = json.maxFiles ?? 200;
+			const upper = json.maxFilesUpperBound ?? 1e3;
+			const discovered = json.discovered ?? 0;
+			const baseMsg = `Hit the ${cap}-file scan cap; ${discovered - (json.imported ?? 0)} of ${json.traversalCapped ? `${discovered}+ (traversal halted at safety cap)` : String(discovered)} discovered file(s) were skipped.`;
+			if (discovered > upper || json.traversalCapped) p.log.warn(`${baseMsg} Tree exceeds the server's --max-files limit of ${upper}; batch by subdirectory (run import-jsonl once per project under ~/.claude/projects).`);
+			else {
+				const suggested = Math.min(Math.max((discovered || cap) + 100, cap * 2), upper);
+				p.log.warn(`${baseMsg} Re-run with --max-files=${suggested} (max ${upper}) or batch by subdirectory.`);
+			}
+		}
+		if (json.sessionIds && json.sessionIds.length > 0) p.log.info(`View at ${getViewerUrl()} → Replay tab`);
 	} catch (err) {
 		spinner.stop("failed");
 		if (err instanceof Error && err.name === "TimeoutError") p.log.error("import timed out after 2 minutes");
@@ -723,6 +931,7 @@ async function runImportJsonl() {
 }
 ({
 	status: runStatus,
+	doctor: runDoctor,
 	demo: runDemo,
 	upgrade: runUpgrade,
 	mcp: runMcp,