Skip to content

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

fix(health): gate memory severity on RSS floor (#158)

Rohit Ghumarec57acd7f93d5
diff --git a/src/health/thresholds.ts b/src/health/thresholds.ts
index e64b848d..24387ed8 100644
--- a/src/health/thresholds.ts
+++ b/src/health/thresholds.ts
@@ -7,6 +7,7 @@ interface ThresholdConfig {
cpuCriticalPercent: number;
memoryWarnPercent: number;
memoryCriticalPercent: number;
+ memoryRssFloorBytes: number;
}
const DEFAULTS: ThresholdConfig = {
@@ -16,6 +17,7 @@ const DEFAULTS: ThresholdConfig = {
cpuCriticalPercent: 90,
memoryWarnPercent: 80,
memoryCriticalPercent: 95,
+ memoryRssFloorBytes: 512 * 1024 * 1024,
};
export function evaluateHealth(
@@ -60,12 +62,17 @@ export function evaluateHealth(
snapshot.memory.heapTotal > 0
? (snapshot.memory.heapUsed / snapshot.memory.heapTotal) * 100
: 0;
- if (memPercent > cfg.memoryCriticalPercent) {
- alerts.push(`memory_critical_${Math.round(memPercent)}%`);
+ const rss = snapshot.memory.rss ?? 0;
+ const rssAboveFloor = rss >= cfg.memoryRssFloorBytes;
+ const memMb = Math.round(rss / (1024 * 1024));
+ if (memPercent > cfg.memoryCriticalPercent && rssAboveFloor) {
+ alerts.push(`memory_critical_${Math.round(memPercent)}%_rss${memMb}mb`);
critical = true;
- } else if (memPercent > cfg.memoryWarnPercent) {
- alerts.push(`memory_warn_${Math.round(memPercent)}%`);
+ } else if (memPercent > cfg.memoryWarnPercent && rssAboveFloor) {
+ alerts.push(`memory_warn_${Math.round(memPercent)}%_rss${memMb}mb`);
degraded = true;
+ } else if (memPercent > cfg.memoryCriticalPercent) {
+ alerts.push(`memory_heap_tight_${Math.round(memPercent)}%_rss${memMb}mb`);
}
const status = critical ? "critical" : degraded ? "degraded" : "healthy";
diff --git a/test/health-thresholds.test.ts b/test/health-thresholds.test.ts
new file mode 100644
index 00000000..0b876248
--- /dev/null
+++ b/test/health-thresholds.test.ts
@@ -0,0 +1,79 @@
+import { describe, expect, it } from "vitest";
+import { evaluateHealth } from "../src/health/thresholds.js";
+import type { HealthSnapshot } from "../src/types.js";
+
+function snap(over: Partial<HealthSnapshot> = {}): HealthSnapshot {
+ return {
+ connectionState: "connected",
+ workers: [],
+ memory: { heapUsed: 0, heapTotal: 1, rss: 0, external: 0 },
+ cpu: { userMicros: 0, systemMicros: 0, percent: 0 },
+ eventLoopLagMs: 0,
+ uptimeSeconds: 1,
+ kvConnectivity: { status: "ok", latencyMs: 1 },
+ status: "healthy",
+ alerts: [],
+ ...over,
+ };
+}
+
+describe("evaluateHealth memory severity", () => {
+ it("stays healthy when heap fills a tiny steady-state process (issue #158)", () => {
+ const s = snap({
+ memory: {
+ heapUsed: 45 * 1024 * 1024,
+ heapTotal: 46 * 1024 * 1024,
+ rss: 120 * 1024 * 1024,
+ external: 0,
+ },
+ });
+ const { status, alerts } = evaluateHealth(s);
+ expect(status).toBe("healthy");
+ expect(alerts.find((a) => a.startsWith("memory_critical_"))).toBeUndefined();
+ expect(alerts.find((a) => a.startsWith("memory_warn_"))).toBeUndefined();
+ expect(alerts.find((a) => a.startsWith("memory_heap_tight_"))).toBeDefined();
+ });
+
+ it("goes critical when heap ratio is high AND RSS is above the floor", () => {
+ const s = snap({
+ memory: {
+ heapUsed: 970 * 1024 * 1024,
+ heapTotal: 1000 * 1024 * 1024,
+ rss: 1100 * 1024 * 1024,
+ external: 0,
+ },
+ });
+ const { status, alerts } = evaluateHealth(s);
+ expect(status).toBe("critical");
+ expect(alerts.some((a) => a.startsWith("memory_critical_"))).toBe(true);
+ });
+
+ it("goes degraded when heap is above warn AND RSS is above the floor", () => {
+ const s = snap({
+ memory: {
+ heapUsed: 850 * 1024 * 1024,
+ heapTotal: 1000 * 1024 * 1024,
+ rss: 900 * 1024 * 1024,
+ external: 0,
+ },
+ });
+ const { status, alerts } = evaluateHealth(s, { memoryRssFloorBytes: 800 * 1024 * 1024 });
+ expect(status).toBe("degraded");
+ expect(alerts.some((a) => a.startsWith("memory_warn_"))).toBe(true);
+ });
+
+ it("respects caller-supplied memoryRssFloorBytes", () => {
+ const s = snap({
+ memory: {
+ heapUsed: 98,
+ heapTotal: 100,
+ rss: 50 * 1024 * 1024,
+ external: 0,
+ },
+ });
+ const loose = evaluateHealth(s, { memoryRssFloorBytes: 10 * 1024 * 1024 });
+ expect(loose.status).toBe("critical");
+ const strict = evaluateHealth(s, { memoryRssFloorBytes: 1024 * 1024 * 1024 });
+ expect(strict.status).toBe("healthy");
+ });
+});