@elizaos/plugin-local-inference 2.0.0-beta.1 → 2.0.11-beta.7

package/src/services/memory-monitor.d.ts

@@ -0,0 +1,119 @@
+/**
+ * RAM-pressure monitor for the local-inference path (W10 / J2).
+ *
+ * Polls `os.freemem()` / `os.totalmem()` on an interval. When free RAM
+ * crosses a low-water threshold, the monitor walks the
+ * `SharedResourceRegistry`'s evictable model roles in *ascending priority*
+ * — `vision/mmproj < embedding < vad < ASR < TTS < text-target` —
+ * and evicts the cheapest one. Cheap evictions are the voice TTS/ASR weights
+ * (`MmapRegionHandle.evictPages()`), the vision projector, and unloading the
+ * embedding model. Every eviction is logged (observable) and reversible
+ * (roles re-load lazily on next use).
+ *
+ * The monitor never *loads* anything — it only frees memory. Re-load is the
+ * caller's job, on demand. It also never evicts the text target (priority
+ * 100) unless it's literally the only resident role and pressure persists,
+ * which is the intended "nothing left to give" behaviour.
+ *
+ * No fallback sludge: when there is nothing to evict and pressure persists,
+ * the monitor logs a warning and stops trying for a back-off window — it does
+ * not pretend it fixed anything.
+ */
+import type { ResidentModelRole, SharedResourceRegistry } from "./voice/shared-resources";
+/** Minimal structural logger — keeps this module dependency-free. */
+export interface MemoryMonitorLogger {
+    debug?(message: string): void;
+    info?(message: string): void;
+    warn?(message: string): void;
+}
+export interface MemorySample {
+    totalMb: number;
+    freeMb: number;
+    /**
+     * Resident-set size in MB of the inference host. On the in-process FFI path
+     * this is the current process's RSS (`process.memoryUsage().rss`); the
+     * device-bridge path injects a phone-sourced figure. `null` only when no
+     * probe could read it.
+     */
+    serverRssMb: number | null;
+    /** Effective free memory used for the pressure decision (min of OS-free and total-minus-RSS-style headroom). */
+    effectiveFreeMb: number;
+    /** Free as a fraction of total (0..1), based on `effectiveFreeMb`. */
+    freeFraction: number;
+}
+export interface MemoryMonitorConfig {
+    /** Poll interval, ms. Default 30 s; min 1 s. */
+    intervalMs: number;
+    /**
+     * Evict when free RAM drops below `max(lowWaterMb, lowWaterFraction*total)`.
+     * Defaults: 768 MB / 8% of total.
+     */
+    lowWaterMb: number;
+    lowWaterFraction: number;
+    /**
+     * After an eviction, wait this long before the next eviction so the OS
+     * has time to reflect the reclaimed pages. Default 5 s.
+     */
+    evictionCooldownMs: number;
+    /**
+     * After "nothing left to evict", back off for this long before warning
+     * again. Default 60 s.
+     */
+    exhaustedBackoffMs: number;
+}
+export declare function resolveMemoryMonitorConfig(overrides?: Partial<MemoryMonitorConfig>): MemoryMonitorConfig;
+/** Pluggable sources so the monitor stays unit-testable without OS state. */
+export interface MemoryMonitorSources {
+    /** OS free/total memory in bytes. Defaults to `os.freemem()/os.totalmem()`. */
+    osMemory?: () => {
+        freeBytes: number;
+        totalBytes: number;
+    };
+    /** Running external runtime RSS in MB, or null. */
+    serverRssMb?: () => Promise<number | null>;
+}
+export interface MemoryPressureAction {
+    sample: MemorySample;
+    /** What got evicted this tick, if anything. */
+    evicted: {
+        id: string;
+        role: ResidentModelRole;
+        estimatedMb: number;
+    } | null;
+    /** True when pressure was detected but nothing could be evicted. */
+    exhausted: boolean;
+}
+export declare class MemoryMonitor {
+    private readonly config;
+    private readonly registry;
+    private readonly log?;
+    private readonly osMemory;
+    private readonly serverRssMb;
+    private timer;
+    private ticking;
+    private lastEvictionAtMs;
+    private exhaustedUntilMs;
+    constructor(args: {
+        registry: SharedResourceRegistry;
+        config?: Partial<MemoryMonitorConfig>;
+        logger?: MemoryMonitorLogger;
+        sources?: MemoryMonitorSources;
+    });
+    /** Begin polling. Idempotent. The interval is unref'd so it never holds the process open. */
+    start(): void;
+    stop(): void;
+    /** Whether the polling timer is running. */
+    isRunning(): boolean;
+    /** Take a memory sample now (no side effects). */
+    sample(): Promise<MemorySample>;
+    /** Low-water line for the current sample, in MB. */
+    private lowWaterMb;
+    isUnderPressure(sample: MemorySample): boolean;
+    /**
+     * One monitor step: sample, and if under pressure (and not in cooldown),
+     * evict the lowest-priority resident role. Returns what it did so callers
+     * (and tests) can assert. Public so tests don't have to wait on a timer.
+     */
+    tick(now?: number): Promise<MemoryPressureAction>;
+}
+//# sourceMappingURL=memory-monitor.d.ts.map

package/src/services/memory-monitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-monitor.d.ts","sourceRoot":"","sources":["memory-monitor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,KAAK,EACX,iBAAiB,EACjB,sBAAsB,EACtB,MAAM,0BAA0B,CAAC;AAElC,qEAAqE;AACrE,MAAM,WAAW,mBAAmB;IACnC,KAAK,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED,MAAM,WAAW,YAAY;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,gHAAgH;IAChH,eAAe,EAAE,MAAM,CAAC;IACxB,sEAAsE;IACtE,YAAY,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB;IACnC,gDAAgD;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,kBAAkB,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,kBAAkB,EAAE,MAAM,CAAC;CAC3B;AA4BD,wBAAgB,0BAA0B,CACzC,SAAS,GAAE,OAAO,CAAC,mBAAmB,CAAM,GAC1C,mBAAmB,CA0BrB;AAED,6EAA6E;AAC7E,MAAM,WAAW,oBAAoB;IACpC,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,MAAM;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3D,mDAAmD;IACnD,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,oBAAoB;IACpC,MAAM,EAAE,YAAY,CAAC;IACrB,+CAA+C;IAC/C,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,iBAAiB,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC7E,oEAAoE;IACpE,SAAS,EAAE,OAAO,CAAC;CACnB;AAED,qBAAa,aAAa;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsB;IAC7C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyB;IAClD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAsB;IAC3C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkD;IAC3E,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA+B;IAC3D,OAAO,CAAC,KAAK,CAA+B;IAC5C,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,gBAAgB,CAAK;gBAEjB,IAAI,EAAE;QACjB,QAAQ,EAAE,sBAAsB,CAAC;QACjC,MAAM,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAC;QACtC,MAAM,CAAC,EAAE,mBAAmB,CAAC;QAC7B,OAAO,CAAC,EAAE,oBAAoB,CAAC;KAC/B;IAWD,6FAA6F;IAC7F,KAAK,IAAI,IAAI;IAab,IAAI,IAAI,IAAI;IAOZ,4CAA4C;IAC5C,SAAS,IAAI,OAAO;IAIpB,kDAAkD;IAC5C,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC;IAuBrC,oDAAoD;IACpD,OAAO,CAAC,UAAU;IAOlB,eAAe,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO;IAI9C;;;;OAIG;IACG,IAAI,CAAC,GAAG,GAAE,MAAmB,GAAG,OAAO,CAAC,oBAAoB,CAAC;CAoCnE"}

package/src/services/memory-monitor.test.ts

@@ -0,0 +1,208 @@
+import { describe, expect, it } from "vitest";
+import { MemoryMonitor } from "./memory-monitor";
+import {
+	createEvictableModelRole,
+	type ResidentModelRole,
+	SharedResourceRegistry,
+} from "./voice/shared-resources";
+
+const MB = 1024 * 1024;
+
+/** A controllable evictable role for the eviction-order tests. */
+function fakeRole(
+	role: ResidentModelRole,
+	estimatedMb: number,
+): {
+	resource: ReturnType<typeof createEvictableModelRole>;
+	evictCount: () => number;
+	reload: () => void;
+} {
+	let resident = true;
+	let evictions = 0;
+	const resource = createEvictableModelRole({
+		id: `fake:${role}`,
+		role,
+		estimatedMb,
+		isResident: () => resident,
+		evict: async () => {
+			resident = false;
+			evictions += 1;
+		},
+	});
+	return {
+		resource,
+		evictCount: () => evictions,
+		reload: () => {
+			resident = true;
+		},
+	};
+}
+
+function monitorWithFreeMb(
+	registry: SharedResourceRegistry,
+	freeMb: number,
+	totalMb = 16 * 1024,
+): MemoryMonitor {
+	return new MemoryMonitor({
+		registry,
+		config: { lowWaterMb: 768, lowWaterFraction: 0.08, evictionCooldownMs: 0 },
+		sources: {
+			osMemory: () => ({ freeBytes: freeMb * MB, totalBytes: totalMb * MB }),
+			serverRssMb: async () => null,
+		},
+	});
+}
+
+describe("MemoryMonitor", () => {
+	it("does nothing while free RAM is above the low-water line", async () => {
+		const registry = new SharedResourceRegistry();
+		const text = fakeRole("text-target", 2000);
+		registry.acquire(text.resource);
+		const monitor = monitorWithFreeMb(registry, 8 * 1024); // plenty free
+		const action = await monitor.tick();
+		expect(action.evicted).toBeNull();
+		expect(action.exhausted).toBe(false);
+		expect(text.evictCount()).toBe(0);
+	});
+
+	it("under pressure, evicts the lowest-priority resident role first", async () => {
+		const registry = new SharedResourceRegistry();
+		const emotion = fakeRole("emotion", 800);
+		const tts = fakeRole("tts", 300);
+		const text = fakeRole("text-target", 4000);
+		// Register out of priority order on purpose.
+		registry.acquire(text.resource);
+		registry.acquire(tts.resource);
+		registry.acquire(emotion.resource);
+		const monitor = monitorWithFreeMb(registry, 200); // hard pressure
+
+		const first = await monitor.tick();
+		expect(first.evicted?.role).toBe("emotion");
+		expect(emotion.evictCount()).toBe(1);
+		expect(tts.evictCount()).toBe(0);
+		expect(text.evictCount()).toBe(0);
+
+		// Still under pressure → next-lowest (tts) goes.
+		const second = await monitor.tick();
+		expect(second.evicted?.role).toBe("tts");
+		expect(tts.evictCount()).toBe(1);
+		expect(text.evictCount()).toBe(0);
+
+		// Then the text target — the last thing to go.
+		const third = await monitor.tick();
+		expect(third.evicted?.role).toBe("text-target");
+		expect(text.evictCount()).toBe(1);
+
+		// Nothing left.
+		const fourth = await monitor.tick();
+		expect(fourth.evicted).toBeNull();
+		expect(fourth.exhausted).toBe(true);
+	});
+
+	it("re-loaded roles become evictable again on the next pressure tick", async () => {
+		const registry = new SharedResourceRegistry();
+		const emotion = fakeRole("emotion", 800);
+		registry.acquire(emotion.resource);
+		const monitor = monitorWithFreeMb(registry, 100);
+
+		const first = await monitor.tick();
+		expect(first.evicted?.role).toBe("emotion");
+		expect(emotion.evictCount()).toBe(1);
+
+		// Nothing else resident → exhausted now.
+		const exhausted = await monitor.tick();
+		expect(exhausted.evicted).toBeNull();
+
+		// Caller re-loads the drafter on demand; pressure persists → it can be evicted again.
+		emotion.reload();
+		const second = await monitor.tick();
+		expect(second.evicted?.role).toBe("emotion");
+		expect(emotion.evictCount()).toBe(2);
+	});
+
+	it("honours the eviction cooldown between ticks", async () => {
+		const registry = new SharedResourceRegistry();
+		registry.acquire(fakeRole("emotion", 100).resource);
+		registry.acquire(fakeRole("tts", 100).resource);
+		const monitor = new MemoryMonitor({
+			registry,
+			config: {
+				lowWaterMb: 768,
+				lowWaterFraction: 0,
+				evictionCooldownMs: 10_000,
+			},
+			sources: {
+				osMemory: () => ({ freeBytes: 100 * MB, totalBytes: 16 * 1024 * MB }),
+				serverRssMb: async () => null,
+			},
+		});
+		const t0 = 1_000_000;
+		const a = await monitor.tick(t0);
+		expect(a.evicted?.role).toBe("emotion");
+		// Within the cooldown — no further eviction even though still under pressure.
+		const b = await monitor.tick(t0 + 5_000);
+		expect(b.evicted).toBeNull();
+		// After the cooldown — the next role goes.
+		const c = await monitor.tick(t0 + 11_000);
+		expect(c.evicted?.role).toBe("tts");
+	});
+
+	it("treats a huge llama-server RSS as pressure even when OS free looks fine", async () => {
+		const registry = new SharedResourceRegistry();
+		const emotion = fakeRole("emotion", 800);
+		registry.acquire(emotion.resource);
+		const monitor = new MemoryMonitor({
+			registry,
+			config: {
+				lowWaterMb: 1024,
+				lowWaterFraction: 0.05,
+				evictionCooldownMs: 0,
+			},
+			sources: {
+				// OS reports 4 GB free (looks fine), but the server is 15 GB on a 16 GB box.
+				osMemory: () => ({
+					freeBytes: 4 * 1024 * MB,
+					totalBytes: 16 * 1024 * MB,
+				}),
+				serverRssMb: async () => 15 * 1024,
+			},
+		});
+		const sample = await monitor.sample();
+		expect(monitor.isUnderPressure(sample)).toBe(true);
+		const action = await monitor.tick();
+		expect(action.evicted?.role).toBe("emotion");
+	});
+
+	it("start()/stop() arm and disarm the polling timer", () => {
+		const registry = new SharedResourceRegistry();
+		const monitor = monitorWithFreeMb(registry, 8 * 1024);
+		expect(monitor.isRunning()).toBe(false);
+		monitor.start();
+		expect(monitor.isRunning()).toBe(true);
+		monitor.start(); // idempotent
+		expect(monitor.isRunning()).toBe(true);
+		monitor.stop();
+		expect(monitor.isRunning()).toBe(false);
+	});
+
+	it("defaults serverRssMb to the real in-process RSS on the FFI path", async () => {
+		// No `serverRssMb` source injected → the default probe reads
+		// `process.memoryUsage().rss`, the in-process FFI host's resident set.
+		const registry = new SharedResourceRegistry();
+		const monitor = new MemoryMonitor({
+			registry,
+			config: { lowWaterMb: 768, lowWaterFraction: 0.08 },
+			sources: {
+				osMemory: () => ({
+					freeBytes: 8 * 1024 * MB,
+					totalBytes: 16 * 1024 * MB,
+				}),
+			},
+		});
+		const sample = await monitor.sample();
+		expect(sample.serverRssMb).not.toBeNull();
+		expect(sample.serverRssMb as number).toBeGreaterThan(0);
+		// The in-process RSS is bounded by total RAM (sanity, not a fabricated value).
+		expect(sample.serverRssMb as number).toBeLessThan(sample.totalMb);
+	});
+});

package/src/services/memory-monitor.ts

@@ -0,0 +1,296 @@
+/**
+ * RAM-pressure monitor for the local-inference path (W10 / J2).
+ *
+ * Polls `os.freemem()` / `os.totalmem()` on an interval. When free RAM
+ * crosses a low-water threshold, the monitor walks the
+ * `SharedResourceRegistry`'s evictable model roles in *ascending priority*
+ * — `vision/mmproj < embedding < vad < ASR < TTS < text-target` —
+ * and evicts the cheapest one. Cheap evictions are the voice TTS/ASR weights
+ * (`MmapRegionHandle.evictPages()`), the vision projector, and unloading the
+ * embedding model. Every eviction is logged (observable) and reversible
+ * (roles re-load lazily on next use).
+ *
+ * The monitor never *loads* anything — it only frees memory. Re-load is the
+ * caller's job, on demand. It also never evicts the text target (priority
+ * 100) unless it's literally the only resident role and pressure persists,
+ * which is the intended "nothing left to give" behaviour.
+ *
+ * No fallback sludge: when there is nothing to evict and pressure persists,
+ * the monitor logs a warning and stops trying for a back-off window — it does
+ * not pretend it fixed anything.
+ */
+
+import os from "node:os";
+import type {
+	ResidentModelRole,
+	SharedResourceRegistry,
+} from "./voice/shared-resources";
+
+/** Minimal structural logger — keeps this module dependency-free. */
+export interface MemoryMonitorLogger {
+	debug?(message: string): void;
+	info?(message: string): void;
+	warn?(message: string): void;
+}
+
+export interface MemorySample {
+	totalMb: number;
+	freeMb: number;
+	/**
+	 * Resident-set size in MB of the inference host. On the in-process FFI path
+	 * this is the current process's RSS (`process.memoryUsage().rss`); the
+	 * device-bridge path injects a phone-sourced figure. `null` only when no
+	 * probe could read it.
+	 */
+	serverRssMb: number | null;
+	/** Effective free memory used for the pressure decision (min of OS-free and total-minus-RSS-style headroom). */
+	effectiveFreeMb: number;
+	/** Free as a fraction of total (0..1), based on `effectiveFreeMb`. */
+	freeFraction: number;
+}
+
+export interface MemoryMonitorConfig {
+	/** Poll interval, ms. Default 30 s; min 1 s. */
+	intervalMs: number;
+	/**
+	 * Evict when free RAM drops below `max(lowWaterMb, lowWaterFraction*total)`.
+	 * Defaults: 768 MB / 8% of total.
+	 */
+	lowWaterMb: number;
+	lowWaterFraction: number;
+	/**
+	 * After an eviction, wait this long before the next eviction so the OS
+	 * has time to reflect the reclaimed pages. Default 5 s.
+	 */
+	evictionCooldownMs: number;
+	/**
+	 * After "nothing left to evict", back off for this long before warning
+	 * again. Default 60 s.
+	 */
+	exhaustedBackoffMs: number;
+}
+
+const DEFAULT_CONFIG: MemoryMonitorConfig = {
+	intervalMs: 30_000,
+	lowWaterMb: 768,
+	lowWaterFraction: 0.08,
+	evictionCooldownMs: 5_000,
+	exhaustedBackoffMs: 60_000,
+};
+
+const BYTES_PER_MB = 1024 * 1024;
+
+function envInt(name: string): number | undefined {
+	const raw = process.env[name]?.trim();
+	if (!raw) return undefined;
+	const parsed = Number.parseInt(raw, 10);
+	return Number.isFinite(parsed) && parsed >= 0 ? parsed : undefined;
+}
+
+function envFloat(name: string): number | undefined {
+	const raw = process.env[name]?.trim();
+	if (!raw) return undefined;
+	const parsed = Number.parseFloat(raw);
+	return Number.isFinite(parsed) && parsed >= 0 && parsed <= 1
+		? parsed
+		: undefined;
+}
+
+export function resolveMemoryMonitorConfig(
+	overrides: Partial<MemoryMonitorConfig> = {},
+): MemoryMonitorConfig {
+	const intervalMs = Math.max(
+		1_000,
+		overrides.intervalMs ??
+			envInt("ELIZA_LOCAL_MEMORY_MONITOR_INTERVAL_MS") ??
+			DEFAULT_CONFIG.intervalMs,
+	);
+	return {
+		intervalMs,
+		lowWaterMb:
+			overrides.lowWaterMb ??
+			envInt("ELIZA_LOCAL_MEMORY_LOW_WATER_MB") ??
+			DEFAULT_CONFIG.lowWaterMb,
+		lowWaterFraction:
+			overrides.lowWaterFraction ??
+			envFloat("ELIZA_LOCAL_MEMORY_LOW_WATER_FRACTION") ??
+			DEFAULT_CONFIG.lowWaterFraction,
+		evictionCooldownMs: Math.max(
+			0,
+			overrides.evictionCooldownMs ?? DEFAULT_CONFIG.evictionCooldownMs,
+		),
+		exhaustedBackoffMs: Math.max(
+			0,
+			overrides.exhaustedBackoffMs ?? DEFAULT_CONFIG.exhaustedBackoffMs,
+		),
+	};
+}
+
+/** Pluggable sources so the monitor stays unit-testable without OS state. */
+export interface MemoryMonitorSources {
+	/** OS free/total memory in bytes. Defaults to `os.freemem()/os.totalmem()`. */
+	osMemory?: () => { freeBytes: number; totalBytes: number };
+	/** Running external runtime RSS in MB, or null. */
+	serverRssMb?: () => Promise<number | null>;
+}
+
+export interface MemoryPressureAction {
+	sample: MemorySample;
+	/** What got evicted this tick, if anything. */
+	evicted: { id: string; role: ResidentModelRole; estimatedMb: number } | null;
+	/** True when pressure was detected but nothing could be evicted. */
+	exhausted: boolean;
+}
+
+export class MemoryMonitor {
+	private readonly config: MemoryMonitorConfig;
+	private readonly registry: SharedResourceRegistry;
+	private readonly log?: MemoryMonitorLogger;
+	private readonly osMemory: () => { freeBytes: number; totalBytes: number };
+	private readonly serverRssMb: () => Promise<number | null>;
+	private timer: NodeJS.Timeout | null = null;
+	private ticking = false;
+	private lastEvictionAtMs = 0;
+	private exhaustedUntilMs = 0;
+
+	constructor(args: {
+		registry: SharedResourceRegistry;
+		config?: Partial<MemoryMonitorConfig>;
+		logger?: MemoryMonitorLogger;
+		sources?: MemoryMonitorSources;
+	}) {
+		this.registry = args.registry;
+		this.config = resolveMemoryMonitorConfig(args.config);
+		this.log = args.logger;
+		this.osMemory =
+			args.sources?.osMemory ??
+			(() => ({ freeBytes: os.freemem(), totalBytes: os.totalmem() }));
+		this.serverRssMb =
+			args.sources?.serverRssMb ?? (async () => defaultServerRssMb());
+	}
+
+	/** Begin polling. Idempotent. The interval is unref'd so it never holds the process open. */
+	start(): void {
+		if (this.timer) return;
+		const timer = setInterval(() => {
+			void this.tick().catch((err) => {
+				this.log?.warn?.(
+					`[MemoryMonitor] tick failed: ${err instanceof Error ? err.message : String(err)}`,
+				);
+			});
+		}, this.config.intervalMs);
+		timer.unref();
+		this.timer = timer;
+	}
+
+	stop(): void {
+		if (this.timer) {
+			clearInterval(this.timer);
+			this.timer = null;
+		}
+	}
+
+	/** Whether the polling timer is running. */
+	isRunning(): boolean {
+		return this.timer !== null;
+	}
+
+	/** Take a memory sample now (no side effects). */
+	async sample(): Promise<MemorySample> {
+		const { freeBytes, totalBytes } = this.osMemory();
+		const totalMb = Math.round(totalBytes / BYTES_PER_MB);
+		const freeMb = Math.round(freeBytes / BYTES_PER_MB);
+		const serverRssMb = await this.serverRssMb().catch(() => null);
+		// If the server process is huge relative to total RAM, treat the
+		// headroom (total - RSS - what other things need) as a tighter free
+		// estimate than the OS free figure alone. We approximate "what other
+		// things need" by the configured low-water reserve so this only kicks
+		// in when the server itself is the problem.
+		const reserveMb = Math.max(
+			this.config.lowWaterMb,
+			Math.round(totalMb * this.config.lowWaterFraction),
+		);
+		const serverHeadroomMb =
+			serverRssMb !== null
+				? totalMb - serverRssMb - reserveMb
+				: Number.POSITIVE_INFINITY;
+		const effectiveFreeMb = Math.min(freeMb, serverHeadroomMb);
+		const freeFraction = totalMb > 0 ? effectiveFreeMb / totalMb : 1;
+		return { totalMb, freeMb, serverRssMb, effectiveFreeMb, freeFraction };
+	}
+
+	/** Low-water line for the current sample, in MB. */
+	private lowWaterMb(totalMb: number): number {
+		return Math.max(
+			this.config.lowWaterMb,
+			Math.round(totalMb * this.config.lowWaterFraction),
+		);
+	}
+
+	isUnderPressure(sample: MemorySample): boolean {
+		return sample.effectiveFreeMb < this.lowWaterMb(sample.totalMb);
+	}
+
+	/**
+	 * One monitor step: sample, and if under pressure (and not in cooldown),
+	 * evict the lowest-priority resident role. Returns what it did so callers
+	 * (and tests) can assert. Public so tests don't have to wait on a timer.
+	 */
+	async tick(now: number = Date.now()): Promise<MemoryPressureAction> {
+		if (this.ticking) {
+			const sample = await this.sample();
+			return { sample, evicted: null, exhausted: false };
+		}
+		this.ticking = true;
+		try {
+			const sample = await this.sample();
+			if (!this.isUnderPressure(sample)) {
+				this.exhaustedUntilMs = 0;
+				return { sample, evicted: null, exhausted: false };
+			}
+			if (now - this.lastEvictionAtMs < this.config.evictionCooldownMs) {
+				return { sample, evicted: null, exhausted: false };
+			}
+			const evicted = await this.registry.evictLowestPriorityRole();
+			if (evicted) {
+				this.lastEvictionAtMs = now;
+				this.exhaustedUntilMs = 0;
+				this.log?.info?.(
+					`[MemoryMonitor] RAM pressure (free ${sample.effectiveFreeMb} MB < ${this.lowWaterMb(sample.totalMb)} MB low-water) — evicted ${evicted.role} (~${evicted.estimatedMb} MB)`,
+				);
+				return { sample, evicted, exhausted: false };
+			}
+			// Nothing evictable. Warn (back-off so we don't spam the log).
+			if (now >= this.exhaustedUntilMs) {
+				this.exhaustedUntilMs = now + this.config.exhaustedBackoffMs;
+				this.log?.warn?.(
+					`[MemoryMonitor] RAM pressure (free ${sample.effectiveFreeMb} MB) but no evictable model role — only the text target is resident. Consider a smaller tier (ELIZA_LOCAL_RAM_HEADROOM_MB / model selection).`,
+				);
+			}
+			return { sample, evicted: null, exhausted: true };
+		} finally {
+			this.ticking = false;
+		}
+	}
+}
+
+/**
+ * Default RSS probe for the in-process FFI path.
+ *
+ * Text inference now runs in-process via FFI llama.cpp, so the inference
+ * weights live in *this* process's address space — `process.memoryUsage().rss`
+ * is therefore the real resident-set high-water of the inference host, not a
+ * separate server to scrape. Returning it (instead of the old `null` stub) gives
+ * the monitor a genuine on-device RSS signal on desktop and on a phone running
+ * the agent in-process.
+ *
+ * The device-bridge topology (agent in a container, inference on a paired phone)
+ * is the exception: there the container process RSS is *not* the phone's, so
+ * that bootstrap injects a device-sourced `serverRssMb` via
+ * `MemoryMonitorSources` rather than using this default.
+ */
+async function defaultServerRssMb(): Promise<number | null> {
+	const usage = process.memoryUsage?.();
+	if (!usage || !Number.isFinite(usage.rss)) return null;
+	return usage.rss / (1024 * 1024);
+}