@agentmemory/agentmemory 0.9.24 → 0.9.25

package/AGENTS.md

@@ -117,7 +117,7 @@ Hook scripts in `src/hooks/` are standalone Node.js scripts (no iii-sdk import).
 ## Current Stats (v0.9.16)
 
 - 53 MCP tools (8 visible by default, `AGENTMEMORY_TOOLS=all` for all)
-- 125 REST endpoints
+- 126 REST endpoints
 - 6 MCP resources, 3 MCP prompts
 - 12 hooks, 4 skills
 - 50+ iii functions

package/README.md

@@ -1429,7 +1429,7 @@ Create `~/.agentmemory/.env`:
 
 <h2 id="api"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-api.svg"><img src="assets/tags/section-api.svg" alt="API" height="32" /></picture></h2>
 
-125 endpoints on port `3111`. The REST API binds to `127.0.0.1` by default. Protected endpoints require `Authorization: Bearer <secret>` when `AGENTMEMORY_SECRET` is set, and mesh sync endpoints require `AGENTMEMORY_SECRET` on both peers.
+126 endpoints on port `3111`. The REST API binds to `127.0.0.1` by default. Protected endpoints require `Authorization: Bearer <secret>` when `AGENTMEMORY_SECRET` is set, and mesh sync endpoints require `AGENTMEMORY_SECRET` on both peers.
 
 <details>
 <summary>Key endpoints</summary>

package/dist/cli.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.mts","names":[],"sources":["../src/cli.ts"],"mappings":";iBAgNsB,kBAAA,CAAA,GAAsB,OAAA"}
+{"version":3,"file":"cli.d.mts","names":[],"sources":["../src/cli.ts"],"mappings":";iBAmNsB,kBAAA,CAAA,GAAsB,OAAA"}

package/dist/cli.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-import { n as resolveAdapter, r as runAdapter } from "./connect-Cf9bmBqO.mjs";
-import { i as generateId } from "./schema-BkALl7Z_.mjs";
-import { r as setBootVerbose } from "./logger-xlVlvCWX.mjs";
-import { t as VERSION } from "./version-BWEBnKAp.mjs";
+import { i as generateId } from "./schema-Dsr_V2Wp.mjs";
+import { n as resolveAdapter, r as runAdapter } from "./connect-bmZ5eqYN.mjs";
+import { r as setBootVerbose } from "./logger-yHTcEBAI.mjs";
+import { t as VERSION } from "./version-C3hZKw8n.mjs";
 import { execFileSync, spawn, spawnSync } from "node:child_process";
 import { closeSync, constants, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readdirSync, readlinkSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
 import { delimiter, dirname, join } from "node:path";
@@ -10,7 +10,6 @@ import { fileURLToPath } from "node:url";
 import { homedir, platform } from "node:os";
 import * as p from "@clack/prompts";
 import { copyFile, mkdir } from "node:fs/promises";
-
 //#region src/cli/doctor-diagnostics.ts
 /** Common placeholder values shipped in .env.example. */
 const PLACEHOLDER_VALUES = new Set([
@@ -183,9 +182,9 @@ function buildDiagnostics(effects) {
 		},
 		{
 			id: "iii-on-path-not-local-bin",
-			message: "iii is on PATH but not in ~/.local/bin/iii (where we install).",
-			fixPreview: "Suggest re-installing the pinned version via the installer — won't touch your PATH.",
-			moreInfo: "agentmemory's installer writes to ~/.local/bin/iii. When a user-managed iii lives somewhere else (homebrew, cargo, $XDG_BIN) we don't auto-overwrite it. If you want our pinned build, run the installer; otherwise this is informational.",
+			message: "iii is on PATH but not at agentmemory's private install path.",
+			fixPreview: "Install the pinned version to ~/.agentmemory/bin — won't touch your PATH.",
+			moreInfo: "agentmemory installs its pinned engine to ~/.agentmemory/bin/iii so a user-managed iii on PATH (homebrew, cargo, manual install) stays untouched. When agentmemory needs the pin and PATH doesn't have it, it falls back to the private install. If neither exists, run the installer.",
 			manualOnly: true,
 			check: async () => {
 				const bin = effects.findIiiBinary();
@@ -201,7 +200,7 @@ function buildDiagnostics(effects) {
 			},
 			fix: async () => effects.runIiiInstaller().then((r) => ({
 				ok: r.ok,
-				message: r.message ?? "Installer wrote to ~/.local/bin/iii. Your PATH wasn't modified — adjust it yourself if needed."
+				message: r.message ?? "Installer wrote to ~/.agentmemory/bin/iii. Your PATH wasn't modified."
 			}))
 		}
 	];
@@ -223,7 +222,6 @@ function dryRunPlan(ctx, results) {
 	if (lines.length === 0) lines.push(`All checks passing for ${ctx.baseUrl} — no fixes to run.`);
 	return lines;
 }
-
 //#endregion
 //#region src/cli/remove-plan.ts
 function pidfilePath(home) {
@@ -244,8 +242,14 @@ function backupsDir(home) {
 function dataDir(home) {
 	return join(home, ".agentmemory", "data");
 }
-function localBinIii(home) {
-	return join(home, ".local", "bin", "iii");
+function iiiBinFile() {
+	return process.platform === "win32" ? "iii.exe" : "iii";
+}
+function legacyLocalBinIii(home) {
+	return join(home, ".local", "bin", iiiBinFile());
+}
+function privateIiiBin(home) {
+	return join(home, ".agentmemory", "bin", iiiBinFile());
 }
 function safeSize(path) {
 	try {
@@ -327,16 +331,25 @@ function buildRemovePlan(ctx, options) {
 		applicable: pathExists(entry.target),
 		sizeBytes: safeSize(entry.target)
 	});
-	const localIii = localBinIii(home);
-	if (pathExists(localIii)) {
+	const privIii = privateIiiBin(home);
+	if (pathExists(privIii)) plan.push({
+		id: "private-bin-iii",
+		description: `Delete ~/.agentmemory/bin/iii (agentmemory's private install)`,
+		path: privIii,
+		alwaysAsk: false,
+		applicable: true,
+		sizeBytes: safeSize(privIii)
+	});
+	const legacyIii = legacyLocalBinIii(home);
+	if (pathExists(legacyIii)) {
 		const matches = localBinIiiVersion === pinnedVersion;
 		plan.push({
-			id: "local-bin-iii",
-			description: matches ? `Delete ~/.local/bin/iii (matches pinned v${pinnedVersion})` : `Delete ~/.local/bin/iii (version ${localBinIiiVersion ?? "unknown"} != pinned v${pinnedVersion}) — will ask`,
-			path: localIii,
+			id: "legacy-local-bin-iii",
+			description: matches ? `Delete ~/.local/bin/iii (legacy install location, matches pinned v${pinnedVersion})` : `Delete ~/.local/bin/iii (legacy install location, version ${localBinIiiVersion ?? "unknown"} != pinned v${pinnedVersion}) — will ask`,
+			path: legacyIii,
 			alwaysAsk: !matches,
 			applicable: true,
-			sizeBytes: safeSize(localIii)
+			sizeBytes: safeSize(legacyIii)
 		});
 	}
 	plan.push({
@@ -362,7 +375,6 @@ function humanBytes(n) {
 	if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
 	return `${(n / (1024 * 1024)).toFixed(1)} MB`;
 }
-
 //#endregion
 //#region src/cli/splash.ts
 const IS_COLOR_TTY = !!process.stdout.isTTY && !process.env["NO_COLOR"];
@@ -413,7 +425,6 @@ function renderSplash(version) {
 	else out = minimalBanner(version);
 	process.stdout.write(out + "\n");
 }
-
 //#endregion
 //#region src/cli/preferences.ts
 const DEFAULTS = {
@@ -478,7 +489,6 @@ function isFirstRun() {
 	if (!existsSync(prefsPath())) return true;
 	return readPrefs().firstRunAt === null;
 }
-
 //#endregion
 //#region src/cli/onboarding.ts
 const __dirname$1 = dirname(fileURLToPath(import.meta.url));
@@ -797,7 +807,6 @@ async function wireSelectedAgents(agents) {
 	if (summary.length === 0) summary.push("No agents were wired.");
 	p.note(summary.join("\n"), "wire summary");
 }
-
 //#endregion
 //#region src/cli.ts
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -877,6 +886,9 @@ Environment:
   AGENTMEMORY_USE_DOCKER=1     Prefer the bundled docker-compose path over the
                                native iii-engine binary on first run.
   AGENTMEMORY_III_VERSION      Override pinned iii-engine version (default ${IIPINNED_VERSION}).
+  AGENTMEMORY_FOLLOWUP_WINDOW_SECONDS
+                               Window (seconds) for the smart-search follow-up diagnostic
+                               (default 30). Long values overcount, short values undercount.
 
 Quick start:
   npx @agentmemory/agentmemory          # start with local iii-engine or Docker
@@ -1002,15 +1014,29 @@ function whichBinary(name) {
 		return null;
 	}
 }
+function agentmemoryBinDir() {
+	if (IS_WINDOWS) {
+		const userProfile = process.env["USERPROFILE"];
+		if (!userProfile) return join(homedir(), ".agentmemory", "bin");
+		return join(userProfile, ".agentmemory", "bin");
+	}
+	return join(homedir(), ".agentmemory", "bin");
+}
+function privateIiiPath() {
+	return join(agentmemoryBinDir(), IS_WINDOWS ? "iii.exe" : "iii");
+}
 function fallbackIiiPaths() {
 	if (IS_WINDOWS) {
 		const userProfile = process.env["USERPROFILE"];
-		if (!userProfile) return [];
-		return [join(userProfile, ".local", "bin", "iii.exe"), join(userProfile, "bin", "iii.exe")];
+		const paths = [privateIiiPath()];
+		if (userProfile) paths.push(join(userProfile, ".local", "bin", "iii.exe"), join(userProfile, "bin", "iii.exe"));
+		return paths;
 	}
 	const home = process.env["HOME"];
-	if (!home) return ["/usr/local/bin/iii"];
-	return [join(home, ".local", "bin", "iii"), "/usr/local/bin/iii"];
+	const paths = [privateIiiPath()];
+	if (home) paths.push(join(home, ".local", "bin", "iii"));
+	paths.push("/usr/local/bin/iii");
+	return paths;
 }
 function iiiBinVersion(binPath) {
 	try {
@@ -1028,14 +1054,18 @@ function iiiBinVersion(binPath) {
 		return null;
 	}
 }
-function enforceEngineVersionPin(iiiBinPath) {
-	if (!iiiBinPath) return;
+function resolveCompatibleIii(iiiBinPath) {
+	if (!iiiBinPath) return null;
 	const detected = iiiBinVersion(iiiBinPath);
-	if (!detected || detected === IIPINNED_VERSION) return;
-	const asset = iiiReleaseAsset();
-	const downloadHint = asset ? `curl -fsSL https://github.com/iii-hq/iii/releases/download/iii/v${IIPINNED_VERSION}/${asset} | tar -xz -C ~/.local/bin` : `download v${IIPINNED_VERSION} from https://github.com/iii-hq/iii/releases/tag/iii%2Fv${IIPINNED_VERSION}`;
-	p.log.error(`iii-engine on PATH is v${detected} but agentmemory v${VERSION} hard-pins v${IIPINNED_VERSION}. Engine API drift causes runtime failures (e.g. state::list-not-found on v0.13.0). Downgrade with: \`${downloadHint}\`. Or set AGENTMEMORY_III_VERSION=${detected} to override at your own risk.`);
-	process.exit(1);
+	if (detected && detected === IIPINNED_VERSION) return iiiBinPath;
+	const privatePath = privateIiiPath();
+	if (iiiBinPath !== privatePath && existsSync(privatePath)) {
+		if (iiiBinVersion(privatePath) === IIPINNED_VERSION) {
+			vlog(`iii at ${iiiBinPath} ${detected ? `v${detected} mismatches pin` : "probe failed"} v${IIPINNED_VERSION}; using private install at ${privatePath}.`);
+			return privatePath;
+		}
+	}
+	return null;
 }
 function enginePidfilePath() {
 	return join(homedir(), ".agentmemory", "iii.pid");
@@ -1145,8 +1175,8 @@ async function maybeOfferGlobalInstall() {
 	if (runCommand(npmBin, [
 		"install",
 		"-g",
-		`@agentmemory/agentmemory@${VERSION}`
-	], { label: `Installing @agentmemory/agentmemory@${VERSION} globally` })) {
+		`@agentmemory/agentmemory@0.9.25`
+	], { label: `Installing @agentmemory/agentmemory@0.9.25 globally` })) {
 		p.log.success("Installed globally. `agentmemory stop` etc. will now work in new shells.");
 		writePrefs({ skipGlobalInstall: true });
 	} else p.log.warn("Global install failed. Try manually: npm install -g @agentmemory/agentmemory");
@@ -1235,8 +1265,8 @@ async function runIiiInstaller() {
 			binPath: null
 		};
 	}
-	const binDir = join(homedir(), ".local", "bin");
-	const binPath = join(binDir, "iii");
+	const binDir = agentmemoryBinDir();
+	const binPath = privateIiiPath();
 	if (!runCommand(shBin, ["-c", [
 		`mkdir -p "${binDir}"`,
 		`curl -fsSL "${releaseUrl}" | tar -xz -C "${binDir}"`,
@@ -1297,31 +1327,40 @@ function spawnEngineBackground(bin, spawnArgs, label) {
 	return child;
 }
 function startIiiBin(iiiBin, configPath) {
-	enforceEngineVersionPin(iiiBin);
 	const s = p.spinner();
 	s.start(`Starting iii-engine: ${iiiBin}`);
 	writeEngineState({
 		kind: "native",
-		configPath
+		configPath,
+		binPath: iiiBin
 	});
 	spawnEngineBackground(iiiBin, ["--config", configPath], "iii-engine");
 	s.stop("iii-engine process started");
 	return true;
 }
+function pickCompatibleIii(candidates) {
+	for (const c of candidates) {
+		if (!c) continue;
+		const resolved = resolveCompatibleIii(c);
+		if (resolved) return resolved;
+	}
+	return null;
+}
 async function startEngine() {
 	const configPath = findIiiConfig();
-	let iiiBin = whichBinary("iii");
-	vlog(`iii binary: ${iiiBin ?? "(not on PATH)"}, config: ${configPath || "(not found)"}`);
-	if (iiiBin && configPath) return startIiiBin(iiiBin, configPath);
-	for (const iiiPath of fallbackIiiPaths()) if (existsSync(iiiPath)) {
-		const v = iiiBinVersion(iiiPath);
-		vlog(`fallback iii at ${iiiPath} reports version: ${v ?? "unknown"}`);
-		p.log.info(`Found iii at: ${iiiPath}${v ? ` (v${v})` : ""}`);
-		process.env["PATH"] = `${dirname(iiiPath)}${delimiter}${process.env["PATH"] ?? ""}`;
-		iiiBin = iiiPath;
-		break;
-	}
-	if (iiiBin && configPath) return startIiiBin(iiiBin, configPath);
+	const pathIii = whichBinary("iii");
+	vlog(`iii binary: ${pathIii ?? "(not on PATH)"}, config: ${configPath || "(not found)"}`);
+	const fallbacks = fallbackIiiPaths().filter((p) => existsSync(p));
+	for (const f of fallbacks) vlog(`fallback iii at ${f} reports version: ${iiiBinVersion(f) ?? "unknown"}`);
+	let iiiBin = pickCompatibleIii([pathIii, ...fallbacks]);
+	if (iiiBin && configPath) {
+		if (iiiBin !== pathIii) {
+			p.log.info(`Using iii at: ${iiiBin} (v${IIPINNED_VERSION})`);
+			process.env["PATH"] = `${dirname(iiiBin)}${delimiter}${process.env["PATH"] ?? ""}`;
+		}
+		return startIiiBin(iiiBin, configPath);
+	}
+	if (pathIii && !iiiBin) vlog(`iii on PATH is v${iiiBinVersion(pathIii) ?? "unknown"}, pin is v${IIPINNED_VERSION}. Will install pinned engine to ${privateIiiPath()}.`);
 	if (!configPath) {
 		startupFailure = { kind: "no-engine" };
 		return false;
@@ -1337,15 +1376,20 @@ async function startEngine() {
 	const dockerOptIn = process.env["AGENTMEMORY_USE_DOCKER"] === "1" || process.env["AGENTMEMORY_USE_DOCKER"] === "true";
 	const interactive = !!process.stdin.isTTY && !process.env["CI"];
 	let choice;
+	const pathIiiMismatch = pathIii !== null && resolveCompatibleIii(pathIii) === null;
 	if (dockerOptIn && dockerBin && composeFile) choice = "docker";
-	else if (!interactive) {
+	else if (pathIiiMismatch) {
+		choice = "install";
+		const detected = iiiBinVersion(pathIii);
+		p.log.info(`iii on PATH is v${detected ?? "unknown"} but agentmemory pins v${IIPINNED_VERSION}. Installing pinned engine to ~/.agentmemory/bin (leaves your existing iii untouched).`);
+	} else if (!interactive) {
 		choice = "install";
 		p.log.info("Non-interactive environment detected — auto-installing iii-engine.");
 	} else {
 		p.log.warn(`iii-engine binary not found locally.`);
 		const options = [{
 			value: "install",
-			label: `Install iii v${IIPINNED_VERSION} to ~/.local/bin (~6MB, ~5s)`,
+			label: `Install iii v${IIPINNED_VERSION} to ~/.agentmemory/bin (~6MB, ~5s)`,
 			hint: "recommended"
 		}];
 		if (dockerBin && composeFile) options.push({
@@ -1441,7 +1485,7 @@ function installInstructions() {
 		"",
 		"Docs: https://iii.dev/docs"
 	];
-	const linuxInstall = releaseUrl ? `  A) curl -fsSL "${releaseUrl}" | tar -xz -C ~/.local/bin && chmod +x ~/.local/bin/iii` : `  A) Manual download: https://github.com/iii-hq/iii/releases/tag/iii%2Fv${IIPINNED_VERSION}`;
+	const linuxInstall = releaseUrl ? `  A) mkdir -p ~/.agentmemory/bin && curl -fsSL "${releaseUrl}" | tar -xz -C ~/.agentmemory/bin && chmod +x ~/.agentmemory/bin/iii` : `  A) Manual download: https://github.com/iii-hq/iii/releases/tag/iii%2Fv${IIPINNED_VERSION}`;
 	return [
 		`agentmemory needs iii-engine v${IIPINNED_VERSION}. Pick one:`,
 		"",
@@ -1504,7 +1548,7 @@ async function main() {
 	if (firstRun || IS_RESET) await runOnboarding();
 	if (skipEngine) {
 		if (IS_VERBOSE) p.log.info("Skipping engine check (--no-engine)");
-		await import("./src-B8J9Exum.mjs");
+		await import("./src-fQOMXeCp.mjs");
 		if (await waitForAgentmemoryReady(15e3)) {
 			const consoleState = await ensureIiiConsole();
 			await maybeOfferGlobalInstall();
@@ -1514,9 +1558,17 @@ async function main() {
 	}
 	if (await isEngineRunning()) {
 		if (IS_VERBOSE) p.log.success("iii-engine is running");
-		enforceEngineVersionPin(whichBinary("iii") ?? fallbackIiiPaths().find((p) => existsSync(p)) ?? null);
+		const persisted = readEngineState();
+		const attachedBin = (persisted?.kind === "native" && persisted.binPath && existsSync(persisted.binPath) ? persisted.binPath : null) ?? whichBinary("iii") ?? fallbackIiiPaths().find((p) => existsSync(p)) ?? null;
+		if (attachedBin) {
+			const detected = iiiBinVersion(attachedBin);
+			if (detected && detected !== IIPINNED_VERSION) {
+				p.log.error(`Attached iii-engine appears to be v${detected} (from ${attachedBin}) but agentmemory v${VERSION} hard-pins v${IIPINNED_VERSION}. Engine API drift causes runtime failures (e.g. state::list-not-found on v0.13.0+). Stop the running engine (\`agentmemory stop --force\`) and re-run \`agentmemory\` to install the pinned engine into ~/.agentmemory/bin without touching ${attachedBin}. Or set AGENTMEMORY_III_VERSION=${detected} to override at your own risk.`);
+				process.exit(1);
+			}
+		}
 		adoptRunningEngine();
-		await import("./src-B8J9Exum.mjs");
+		await import("./src-fQOMXeCp.mjs");
 		if (await waitForAgentmemoryReady(15e3)) {
 			const consoleState = await ensureIiiConsole();
 			await maybeOfferGlobalInstall();
@@ -1565,7 +1617,7 @@ async function main() {
 		process.exit(1);
 	}
 	s.stop("iii-engine is ready");
-	await import("./src-B8J9Exum.mjs");
+	await import("./src-fQOMXeCp.mjs");
 	if (await waitForAgentmemoryReady(15e3)) {
 		const consoleState = await ensureIiiConsole();
 		await maybeOfferGlobalInstall();
@@ -1596,12 +1648,13 @@ async function runStatus() {
 		process.exit(1);
 	}
 	try {
-		const [healthRes, sessionsRes, graphRes, memoriesRes, flagsRes] = await Promise.all([
+		const [healthRes, sessionsRes, graphRes, memoriesRes, flagsRes, followupRes] = await Promise.all([
 			apiFetch(base, "health"),
 			apiFetch(base, "sessions"),
 			apiFetch(base, "graph/stats"),
 			apiFetch(base, "memories?count=true"),
-			apiFetch(base, "config/flags")
+			apiFetch(base, "config/flags"),
+			apiFetch(base, "diagnostics/followup")
 		]);
 		if (typeof healthRes?.viewerPort === "number") discoveredViewerPort = healthRes.viewerPort;
 		const h = healthRes?.health;
@@ -1648,6 +1701,13 @@ async function runStatus() {
 			lines.push(`Flags:`);
 			flagRows.forEach((r) => lines.push(r));
 		}
+		if (followupRes && Number.isFinite(followupRes.agentInitiatedSearches)) {
+			const total = Number(followupRes.agentInitiatedSearches) || 0;
+			const hits = Number(followupRes.followupWithinWindow) || 0;
+			const pct = total > 0 ? Math.round(hits / total * 100) : 0;
+			lines.push("");
+			lines.push(`Followup rate: ${hits}/${total} (${pct}%) within ${followupRes.windowSeconds}s — directional, may overcount on refinement`);
+		}
 		p.note(lines.join("\n"), "agentmemory");
 	} catch (err) {
 		p.log.error(err instanceof Error ? err.message : String(err));
@@ -1720,7 +1780,7 @@ function buildDoctorEffects() {
 			return pidAlive(pid);
 		},
 		findIiiBinary: () => whichBinary("iii"),
-		localBinIiiPath: () => join(homedir(), ".local", "bin", IS_WINDOWS ? "iii.exe" : "iii"),
+		localBinIiiPath: () => privateIiiPath(),
 		iiiBinaryVersion: (binPath) => iiiBinVersion(binPath),
 		viewerReachable: async (timeoutMs = 2e3) => {
 			try {
@@ -2490,10 +2550,10 @@ async function runStop() {
 	p.outro("Stopped. Memories persisted to disk; restart anytime with: npx @agentmemory/agentmemory");
 }
 async function runMcp() {
-	await import("./standalone-CPfsVTBA.mjs");
+	await import("./standalone-BzfA1zu8.mjs");
 }
 async function runConnectCmd() {
-	const { runConnect } = await import("./connect-Cf9bmBqO.mjs").then((n) => n.t);
+	const { runConnect } = await import("./connect-bmZ5eqYN.mjs").then((n) => n.t);
 	await runConnect(args.slice(1));
 }
 async function runImportJsonl() {
@@ -2610,7 +2670,7 @@ function loadConnectManifest(home) {
 	}
 }
 function probeLocalBinIiiVersion(home) {
-	const path = localBinIii(home);
+	const path = legacyLocalBinIii(home);
 	if (!existsSync(path)) return null;
 	return iiiBinVersion(path);
 }
@@ -2724,7 +2784,7 @@ async function runRemove() {
 	p.log.error(err instanceof Error ? err.message : String(err));
 	process.exit(1);
 });
-
 //#endregion
 export { discoverViewerPort };
+
 //# sourceMappingURL=cli.mjs.map