#1 Persistent memory for AI coding agents based on real-world benchmarks
TypeScript agentmemoryagentsaiclaudeclaudecodecodexcopilotcursorgenaiharnesshermesmemoryompopenclawopencodepi
fix(cli): auto-derive streams + engine ports from REST anchor (#750) (#815)
Rohit Ghumare334e5ad81aee
diff --git a/src/cli.ts b/src/cli.tsindex 62d39734..4a52e684 100644--- a/src/cli.ts+++ b/src/cli.ts@@ -154,7 +154,12 @@ Options:--reset Wipe ~/.agentmemory/preferences.json and re-run onboarding--tools all|core Tool visibility (default: all = 51 tools; core = 8 essentials)--no-engine Skip auto-starting iii-engine- --port <N> Override REST port (default: 3111)+ --port <N> Override REST port (default: 3111). Streams (N+1), viewer+ (N+2), and iii engine (N+46023) auto-derive from N so a+ single flag relocates the whole quartet.+ --instance <N> Shortcut for --port (3111 + N*100) to run multiple+ daemons side-by-side without env gymnastics.+ --instance 1 -> 3211/3212/3213/49234, etc. (max N=50)Environment:AGENTMEMORY_URL Full REST base URL (e.g. http://localhost:3111).@@ -188,6 +193,23 @@ if (portIdx !== -1 && args[portIdx + 1]) {process.env["III_REST_PORT"] = args[portIdx + 1];}+// `--instance N` picks a 100-port block off the 3111 base so multiple+// agentmemory daemons can coexist on one host without env-var+// gymnastics (#750). `--instance 0` keeps the canonical 3111/3112/3113/49134+// quartet; `--instance 1` → 3211/3212/3213/49234; etc. REST acts as the+// anchor — streams/viewer/engine derive from it via fixed offsets below+// unless an env explicitly pins each one.+const instanceIdx = args.indexOf("--instance");+if (instanceIdx !== -1 && args[instanceIdx + 1]) {+ const n = parseInt(args[instanceIdx + 1] || "", 10);+ if (Number.isFinite(n) && n >= 0 && n <= 50) {+ const base = 3111 + n * 100;+ if (!process.env["III_REST_PORT"]) {+ process.env["III_REST_PORT"] = String(base);+ }+ }+}+const skipEngine = args.includes("--no-engine");function getRestPort(): number {@@ -255,17 +277,20 @@ function getViewerUrl(): string {// 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.+// either form lights up the ready panel. Falls back to REST+1 so+// `--port 3211` auto-picks 3212 instead of colliding on 3112 (#750).function getStreamPort(): number {return (parseInt(process.env["III_STREAM_PORT"] || "", 10) ||parseInt(process.env["III_STREAMS_PORT"] || "", 10) ||- 3112+ getRestPort() + 1);}// Bridge WebSocket port — the iii engine's internal worker bus.-// Defaults to 49134 (engine convention) and is overridable via+// Defaults derived from REST as REST+46023 so the canonical 3111+// anchor yields 49134 and `--port 3211` auto-picks 49234 without a+// second-instance collision (#750). 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);@@ -277,7 +302,7 @@ function getEnginePort(): number {if (parsed) return parseInt(parsed, 10);} catch {}}- return 49134;+ return getRestPort() + 46023;}async function isEngineRunning(): Promise<boolean> {diff --git a/src/config.ts b/src/config.tsindex b3f8882d..f68da2e3 100644--- a/src/config.ts+++ b/src/config.ts@@ -161,10 +161,24 @@ export function loadConfig(): AgentMemoryConfig {const provider = detectProvider(env);+ // Port quartet: REST is the anchor; streams/engine derive from it+ // unless individually overridden. Default anchor 3111 yields the+ // canonical 3112 streams / 49134 engine pair, but `III_REST_PORT=3211`+ // auto-picks 3212 + 49234 so a second instance doesn't collide (#750).+ const restPort = parseInt(env["III_REST_PORT"] || "3111", 10) || 3111;+ const streamsPort =+ parseInt(env["III_STREAM_PORT"] || env["III_STREAMS_PORT"] || "", 10) ||+ restPort + 1;+ const engineUrl =+ env["III_ENGINE_URL"] ||+ `ws://localhost:${+ parseInt(env["III_ENGINE_PORT"] || "", 10) || restPort + 46023+ }`;+return {- engineUrl: env["III_ENGINE_URL"] || "ws://localhost:49134",- restPort: parseInt(env["III_REST_PORT"] || "3111", 10) || 3111,- streamsPort: parseInt(env["III_STREAMS_PORT"] || "3112", 10) || 3112,+ engineUrl,+ restPort,+ streamsPort,provider,tokenBudget: safeParseInt(env["TOKEN_BUDGET"], 2000),maxObservationsPerSession: safeParseInt(env["MAX_OBS_PER_SESSION"], 500),diff --git a/test/multi-instance-port.test.ts b/test/multi-instance-port.test.tsnew file mode 100644index 00000000..4343365b--- /dev/null+++ b/test/multi-instance-port.test.ts@@ -0,0 +1,85 @@+import { describe, it, expect, beforeEach, afterEach } from "vitest";+import { loadConfig } from "../src/config";++const PORT_ENVS = [+ "III_REST_PORT",+ "III_STREAM_PORT",+ "III_STREAMS_PORT",+ "III_ENGINE_PORT",+ "III_ENGINE_URL",+] as const;++describe("multi-instance port auto-derive (#750)", () => {+ const saved: Record<string, string | undefined> = {};++ beforeEach(() => {+ for (const k of PORT_ENVS) {+ saved[k] = process.env[k];+ delete process.env[k];+ }+ });++ afterEach(() => {+ for (const k of PORT_ENVS) {+ if (saved[k] === undefined) {+ delete process.env[k];+ } else {+ process.env[k] = saved[k];+ }+ }+ });++ it("default REST anchor yields canonical 3111/3112/49134 quartet", () => {+ const cfg = loadConfig();+ expect(cfg.restPort).toBe(3111);+ expect(cfg.streamsPort).toBe(3112);+ expect(cfg.engineUrl).toBe("ws://localhost:49134");+ });++ it("relocating REST drags streams + engine with it", () => {+ process.env["III_REST_PORT"] = "3211";+ const cfg = loadConfig();+ expect(cfg.restPort).toBe(3211);+ expect(cfg.streamsPort).toBe(3212);+ expect(cfg.engineUrl).toBe("ws://localhost:49234");+ });++ it("instance N=2 block (3311) lands on 3312 + 49334", () => {+ process.env["III_REST_PORT"] = "3311";+ const cfg = loadConfig();+ expect(cfg.restPort).toBe(3311);+ expect(cfg.streamsPort).toBe(3312);+ expect(cfg.engineUrl).toBe("ws://localhost:49334");+ });++ it("explicit III_STREAM_PORT pins streams without affecting REST/engine", () => {+ process.env["III_REST_PORT"] = "3211";+ process.env["III_STREAM_PORT"] = "9999";+ const cfg = loadConfig();+ expect(cfg.restPort).toBe(3211);+ expect(cfg.streamsPort).toBe(9999);+ expect(cfg.engineUrl).toBe("ws://localhost:49234");+ });++ it("legacy III_STREAMS_PORT still honored", () => {+ process.env["III_STREAMS_PORT"] = "9000";+ const cfg = loadConfig();+ expect(cfg.streamsPort).toBe(9000);+ });++ it("explicit III_ENGINE_PORT pins engine without affecting REST/streams", () => {+ process.env["III_REST_PORT"] = "3211";+ process.env["III_ENGINE_PORT"] = "55555";+ const cfg = loadConfig();+ expect(cfg.restPort).toBe(3211);+ expect(cfg.streamsPort).toBe(3212);+ expect(cfg.engineUrl).toBe("ws://localhost:55555");+ });++ it("legacy III_ENGINE_URL overrides derivation entirely", () => {+ process.env["III_REST_PORT"] = "3211";+ process.env["III_ENGINE_URL"] = "ws://remote-host:49999";+ const cfg = loadConfig();+ expect(cfg.engineUrl).toBe("ws://remote-host:49999");+ });+});