Skip to content

#1 Persistent memory for AI coding agents based on real-world benchmarks

feat(cli): 5-port ready panel + iii console install + global-install prompt + version-string fix (#410)

Rohit Ghumare7530339b4c33
diff --git a/src/cli.ts b/src/cli.ts
index 803c3b6d..7981b27f 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -200,11 +200,45 @@ function getViewerUrl(): string {
if (envUrl) return envUrl.replace(/\/+$/, "");
try {
const u = new URL(getBaseUrl());
- const vPort = (parseInt(u.port || "3111", 10) || 3111) + 2;
+ const vPort =
+ parseInt(process.env["III_VIEWER_PORT"] || "", 10) ||
+ (parseInt(u.port || "3111", 10) || 3111) + 2;
return `${u.protocol}//${u.hostname}:${vPort}`;
} catch {
- return `http://localhost:${getRestPort() + 2}`;
+ const vPort =
+ parseInt(process.env["III_VIEWER_PORT"] || "", 10) ||
+ getRestPort() + 2;
+ return `http://localhost:${vPort}`;
+ }
+}
+
+// WebSocket streams port. Engine writes here; the SDK and viewer
+// subscribe. Honors both `III_STREAM_PORT` (the singular name the
+// engine docs use post-0.11) and `III_STREAMS_PORT` (the name our
+// own config.ts has used since 0.7) so a single source of truth in
+// either form lights up the ready panel.
+function getStreamPort(): number {
+ return (
+ parseInt(process.env["III_STREAM_PORT"] || "", 10) ||
+ parseInt(process.env["III_STREAMS_PORT"] || "", 10) ||
+ 3112
+ );
+}
+
+// Bridge WebSocket port — the iii engine's internal worker bus.
+// Defaults to 49134 (engine convention) and is overridable via
+// `III_ENGINE_PORT` or the legacy `III_ENGINE_URL=ws://host:port`.
+function getEnginePort(): number {
+ const explicit = parseInt(process.env["III_ENGINE_PORT"] || "", 10);
+ if (explicit) return explicit;
+ const url = process.env["III_ENGINE_URL"];
+ if (url) {
+ try {
+ const parsed = new URL(url).port;
+ if (parsed) return parseInt(parsed, 10);
+ } catch {}
}
+ return 49134;
}
async function isEngineRunning(): Promise<boolean> {
@@ -297,7 +331,7 @@ function warnIfEngineVersionMismatch(iiiBinPath: string | null | undefined): voi
? `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.warn(
- `iii-engine on PATH is v${detected} but agentmemory v0.9.14+ pins v${IIPINNED_VERSION}. Set AGENTMEMORY_III_VERSION=${detected} to silence, or downgrade with: \`${downloadHint}\``,
+ `iii-engine on PATH is v${detected} but agentmemory v${VERSION} pins v${IIPINNED_VERSION}. Set AGENTMEMORY_III_VERSION=${detected} to silence, or downgrade with: \`${downloadHint}\``,
);
}
@@ -386,24 +420,125 @@ function isInvokedViaNpx(): boolean {
return false;
}
-function shouldSkipNpxHint(): boolean {
- try {
- const prefsPath = join(homedir(), ".agentmemory", "preferences.json");
- if (!existsSync(prefsPath)) return false;
- const raw = readFileSync(prefsPath, "utf-8");
- const prefs = JSON.parse(raw) as { skipNpxHint?: boolean };
- return prefs?.skipNpxHint === true;
- } catch {
- return false;
+// First-run global-install prompt. Replaces the previous passive
+// `p.log.info` hint that users ignored — typing `agentmemory stop`
+// in a new shell would then 404 with `command not found`. We now
+// ask once, persist the answer in preferences, and never ask again.
+async function maybeOfferGlobalInstall(): Promise<void> {
+ if (!isInvokedViaNpx()) return;
+ if (!process.stdin.isTTY) return;
+ if (process.env["CI"]) return;
+ const prefs = readPrefs();
+ if (prefs.skipGlobalInstall || prefs.skipNpxHint) return;
+
+ const answer = await p.confirm({
+ message:
+ "Install agentmemory globally so the bare `agentmemory` command works in any shell? [Y/n]",
+ initialValue: true,
+ });
+ if (p.isCancel(answer)) {
+ // Treat Ctrl+C as "not now" rather than "never". Don't persist.
+ return;
+ }
+ if (answer === false) {
+ writePrefs({ skipGlobalInstall: true });
+ p.log.info(
+ "Skipped. Re-run via `npx @agentmemory/agentmemory` or install later with: npm install -g @agentmemory/agentmemory",
+ );
+ return;
}
-}
-function maybeEmitNpxHint(): void {
- if (!isInvokedViaNpx()) return;
- if (shouldSkipNpxHint()) return;
- p.log.info(
- "Tip: install globally for the bare `agentmemory` command:\n npm install -g @agentmemory/agentmemory",
+ const npmBin = whichBinary("npm");
+ if (!npmBin) {
+ p.log.warn(
+ "npm not found on PATH. Install manually: npm install -g @agentmemory/agentmemory",
+ );
+ return;
+ }
+ const ok = runCommand(
+ npmBin,
+ ["install", "-g", `@agentmemory/agentmemory@${VERSION}`],
+ { label: `Installing @agentmemory/agentmemory@${VERSION} globally` },
);
+ if (ok) {
+ p.log.success(
+ "Installed globally. `agentmemory stop` etc. will now work in new shells.",
+ );
+ // Persist so we never re-prompt even if the user happens to npx
+ // again from a CI-less TTY.
+ writePrefs({ skipGlobalInstall: true });
+ } else {
+ p.log.warn(
+ "Global install failed. Try manually: npm install -g @agentmemory/agentmemory",
+ );
+ }
+}
+
+// iii-console install state.
+// "installed" — `iii-console` is on PATH or at `~/.local/bin/iii-console`
+// "missing" — binary not found anywhere we look
+// We deliberately do NOT probe the console's HTTP port: the binary
+// being on disk is the signal we care about (it's not auto-started by
+// agentmemory and its default port 3113 collides with our viewer, so
+// "is it listening?" is the wrong question at boot time).
+type IiiConsoleState =
+ | { kind: "installed"; binPath: string }
+ | { kind: "missing" };
+
+function detectIiiConsole(): IiiConsoleState {
+ const onPath = whichBinary("iii-console");
+ if (onPath) return { kind: "installed", binPath: onPath };
+ const fallback = IS_WINDOWS
+ ? join(process.env["USERPROFILE"] ?? "", ".local", "bin", "iii-console.exe")
+ : join(homedir(), ".local", "bin", "iii-console");
+ if (fallback && existsSync(fallback)) {
+ return { kind: "installed", binPath: fallback };
+ }
+ return { kind: "missing" };
+}
+
+const III_CONSOLE_INSTALL_CMD =
+ "curl -fsSL https://install.iii.dev/console/main/install.sh | sh";
+
+async function ensureIiiConsole(): Promise<IiiConsoleState> {
+ const state = detectIiiConsole();
+ if (state.kind === "installed") return state;
+
+ // Non-interactive contexts get the panel hint but no prompt.
+ if (!process.stdin.isTTY || process.env["CI"]) return state;
+ const prefs = readPrefs();
+ if (prefs.skipConsoleInstall) return state;
+
+ const answer = await p.confirm({
+ message:
+ "iii console gives engine-level visibility (workers, functions, queues, traces). Install now?",
+ initialValue: true,
+ });
+ if (p.isCancel(answer)) return state;
+ if (answer === false) {
+ writePrefs({ skipConsoleInstall: true });
+ return state;
+ }
+
+ const shBin = whichBinary("sh");
+ const curlBin = whichBinary("curl");
+ if (!shBin || !curlBin) {
+ p.log.warn(
+ `curl or sh not found. Install manually:\n ${III_CONSOLE_INSTALL_CMD}`,
+ );
+ return state;
+ }
+ const ok = runCommand(shBin, ["-c", III_CONSOLE_INSTALL_CMD], {
+ label: "Installing iii console",
+ });
+ if (!ok) {
+ p.log.warn(
+ `iii console install failed. Re-run manually:\n ${III_CONSOLE_INSTALL_CMD}`,
+ );
+ return state;
+ }
+ // Re-detect rather than trust install-script output paths.
+ return detectIiiConsole();
}
function adoptRunningEngine(): void {
@@ -738,13 +873,65 @@ async function waitForAgentmemoryReady(timeoutMs: number): Promise<boolean> {
return false;
}
-function printReadyHint(): void {
- const port = getRestPort();
- const viewer = getViewerUrl();
- const hint = `Memory ready on :${port} · viewer on ${viewer} · try: agentmemory demo`;
- // Use plain stdout (not p.outro) so the hint isn't decorated with
- // clack's closing line — it reads as a status, not an end-of-flow.
- process.stdout.write("\n" + hint + "\n");
+// Derive a host string for the streams/engine WebSocket lines from
+// the configured engine URL (`III_ENGINE_URL`) or REST base
+// (`AGENTMEMORY_URL`) so a remote-bind setup like
+// `III_ENGINE_URL=ws://my-host:49134` doesn't print misleading
+// localhost addresses. Falls back to localhost.
+function getEngineHost(): string {
+ for (const envKey of ["III_ENGINE_URL", "AGENTMEMORY_URL"]) {
+ const raw = process.env[envKey];
+ if (!raw) continue;
+ try {
+ const parsed = new URL(raw);
+ if (parsed.hostname) return parsed.hostname;
+ } catch {}
+ }
+ return "localhost";
+}
+
+function printReadyHint(consoleState: IiiConsoleState): void {
+ // REST goes through getBaseUrl which already honors AGENTMEMORY_URL
+ // for full host+protocol overrides. Streams/Engine are derived from
+ // III_ENGINE_URL so a remote bind reads correctly in the panel.
+ const restUrl = getBaseUrl();
+ const viewerUrl = getViewerUrl();
+ const engineHost = getEngineHost();
+ const streamUrl = `ws://${engineHost}:${getStreamPort()}`;
+ const engineUrl = `ws://${engineHost}:${getEnginePort()}`;
+
+ const consoleLine =
+ consoleState.kind === "installed"
+ ? // We can't safely probe iii-console's port (default 3113
+ // collides with our viewer) so we surface the binary location
+ // and let the user start it on a port of their choice. Use
+ // the detected binary path so `(run: ...)` is executable as-
+ // is, even when the binary isn't on PATH under the bare
+ // name `iii-console`.
+ `iii console ${consoleState.binPath} (run: ${consoleState.binPath} -p <port>)`
+ : `iii console (install: ${III_CONSOLE_INSTALL_CMD})`;
+
+ const lines = [
+ `REST API ${restUrl}`,
+ `Viewer ${viewerUrl}`,
+ `Streams ${streamUrl}`,
+ `Engine ${engineUrl}`,
+ consoleLine,
+ ];
+ // p.note renders a bordered panel with a title — same affordance
+ // used elsewhere in this CLI for "Troubleshooting" / "Setup
+ // required" blocks, so the visual language stays consistent.
+ p.note(lines.join("\n"), `agentmemory v${VERSION}`);
+
+ // Pick a runnable form for the suggested next-step. Users invoked
+ // via `npx` don't have the bare `agentmemory` command on PATH yet
+ // (unless they accepted the global-install prompt and the npm bin
+ // dir was already on PATH in this shell), so we suggest the npx
+ // form for them; everyone else gets the global form.
+ const demoCommand = isInvokedViaNpx()
+ ? "npx @agentmemory/agentmemory demo"
+ : "agentmemory demo";
+ process.stdout.write(`\nTry: ${demoCommand}\n`);
}
async function main() {
@@ -771,7 +958,11 @@ async function main() {
if (skipEngine) {
if (IS_VERBOSE) p.log.info("Skipping engine check (--no-engine)");
await import("./index.js");
- if (await waitForAgentmemoryReady(15000)) printReadyHint();
+ if (await waitForAgentmemoryReady(15000)) {
+ const consoleState = await ensureIiiConsole();
+ await maybeOfferGlobalInstall();
+ printReadyHint(consoleState);
+ }
return;
}
@@ -781,9 +972,12 @@ async function main() {
whichBinary("iii") ?? fallbackIiiPaths().find((p) => existsSync(p)) ?? null;
warnIfEngineVersionMismatch(attachedBin);
adoptRunningEngine();
- maybeEmitNpxHint();
await import("./index.js");
- if (await waitForAgentmemoryReady(15000)) printReadyHint();
+ if (await waitForAgentmemoryReady(15000)) {
+ const consoleState = await ensureIiiConsole();
+ await maybeOfferGlobalInstall();
+ printReadyHint(consoleState);
+ }
return;
}
@@ -851,9 +1045,12 @@ async function main() {
}
s.stop("iii-engine is ready");
- maybeEmitNpxHint();
await import("./index.js");
- if (await waitForAgentmemoryReady(15000)) printReadyHint();
+ if (await waitForAgentmemoryReady(15000)) {
+ const consoleState = await ensureIiiConsole();
+ await maybeOfferGlobalInstall();
+ printReadyHint(consoleState);
+ }
// Mark splash as something to skip on subsequent runs. This is a
// no-op if onboarding already flipped the flag (idempotent merge).
writePrefs({ skipSplash: true });
diff --git a/src/cli/preferences.ts b/src/cli/preferences.ts
index 903d28b6..ccebd1a3 100644
--- a/src/cli/preferences.ts
+++ b/src/cli/preferences.ts
@@ -45,6 +45,14 @@ export interface Prefs {
// tradeoff" toggle. Kept on the schema so we don't have to bump
// schemaVersion when we ship the flag.
skipNpxHint: boolean;
+ // Set to true when the user declines the "install agentmemory
+ // globally?" prompt on first npx run. We never ask again on this
+ // machine so the prompt stays a one-time DX nudge, not a nag.
+ skipGlobalInstall: boolean;
+ // Set to true when the user declines the "install iii console?"
+ // prompt. iii console is first-class engine UI but optional at the
+ // install step — once the user says no, we stop asking.
+ skipConsoleInstall: boolean;
// ISO timestamp of the first time onboarding completed. Set once,
// never updated, so we can show "you joined agentmemory N days ago"
// copy in /status later without keeping a separate file.
@@ -58,6 +66,8 @@ const DEFAULTS: Prefs = {
lastProvider: null,
skipSplash: false,
skipNpxHint: false,
+ skipGlobalInstall: false,
+ skipConsoleInstall: false,
firstRunAt: null,
};