Skip to content

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

fix: prevent process crash on iii-engine state::set timeout (#204)

Rohit Ghumarebd4b74e067d7
diff --git a/src/index.ts b/src/index.ts
index b21a5116..484908e0 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -104,6 +104,25 @@ function hasGetMeter(
);
}
+// Top-level safety net for iii-engine invocation timeouts (issue #204).
+// Under sustained write load (e.g. Claude Code hooks across many
+// projects) `state::set` can occasionally exceed the SDK's 30s timeout.
+// We don't want one such timeout to terminate the long-lived memory
+// service — the rejection is surfaced to the relevant call site via
+// .catch() where it matters; everything else is logged-and-continued.
+// Throttle logs to avoid spamming on bursts.
+let lastUnhandledLogAt = 0;
+process.on("unhandledRejection", (reason) => {
+ const now = Date.now();
+ if (now - lastUnhandledLogAt < 60_000) return;
+ lastUnhandledLogAt = now;
+ const r = reason as { code?: string; function_id?: string; message?: string };
+ console.warn(
+ `[agentmemory] unhandledRejection (suppressed):`,
+ r?.code ? `${r.code} ${r.function_id ?? ""} ${r.message ?? ""}`.trim() : reason,
+ );
+});
+
async function main() {
const config = loadConfig();
const embeddingConfig = loadEmbeddingConfig();
diff --git a/src/state/index-persistence.ts b/src/state/index-persistence.ts
index 728013b3..7e484f57 100644
--- a/src/state/index-persistence.ts
+++ b/src/state/index-persistence.ts
@@ -2,11 +2,14 @@ import { SearchIndex } from "./search-index.js";
import { VectorIndex } from "./vector-index.js";
import type { StateKV } from "./kv.js";
import { KV } from "./schema.js";
+import { logger } from "../logger.js";
const DEBOUNCE_MS = 5000;
+const FAILURE_LOG_THROTTLE_MS = 60_000;
export class IndexPersistence {
private timer: ReturnType<typeof setTimeout> | null = null;
+ private lastFailureLogAt = 0;
constructor(
private kv: StateKV,
@@ -16,7 +19,13 @@ export class IndexPersistence {
scheduleSave(): void {
if (this.timer) clearTimeout(this.timer);
- this.timer = setTimeout(() => this.save(), DEBOUNCE_MS);
+ // setTimeout discards the returned promise, so any rejection inside
+ // save() would surface as unhandledRejection and crash the process
+ // under sustained iii-engine write timeouts (issue #204). Funnel
+ // rejections through logFailure() instead.
+ this.timer = setTimeout(() => {
+ this.save().catch((err) => this.logFailure(err));
+ }, DEBOUNCE_MS);
}
async save(): Promise<void> {
@@ -24,9 +33,13 @@ export class IndexPersistence {
clearTimeout(this.timer);
this.timer = null;
}
- await this.kv.set(KV.bm25Index, "data", this.bm25.serialize());
- if (this.vector && this.vector.size > 0) {
- await this.kv.set(KV.bm25Index, "vectors", this.vector.serialize());
+ try {
+ await this.kv.set(KV.bm25Index, "data", this.bm25.serialize());
+ if (this.vector && this.vector.size > 0) {
+ await this.kv.set(KV.bm25Index, "vectors", this.vector.serialize());
+ }
+ } catch (err) {
+ this.logFailure(err);
}
}
@@ -60,4 +73,23 @@ export class IndexPersistence {
this.timer = null;
}
}
+
+ private logFailure(err: unknown): void {
+ const now = Date.now();
+ // Throttle: persistence failures under load arrive in bursts
+ // (iii-engine queue pressure). Logging every debounce flush adds
+ // noise without information.
+ if (now - this.lastFailureLogAt < FAILURE_LOG_THROTTLE_MS) return;
+ this.lastFailureLogAt = now;
+ const code = (err as { code?: string })?.code;
+ const message = err instanceof Error ? err.message : String(err);
+ logger.warn("index persistence: failed to save BM25/vector index", {
+ code,
+ message,
+ hint:
+ code === "TIMEOUT"
+ ? "iii-engine state::set timed out; recent index updates remain in memory and will retry on the next debounce flush"
+ : undefined,
+ });
+ }
}
diff --git a/test/index-persistence.test.ts b/test/index-persistence.test.ts
index 7452ec09..fd60ab24 100644
--- a/test/index-persistence.test.ts
+++ b/test/index-persistence.test.ts
@@ -121,4 +121,53 @@ describe("IndexPersistence", () => {
expect(loaded.bm25).toBeNull();
expect(loaded.vector).toBeNull();
});
+
+ it("scheduled save swallows kv.set rejection without unhandledRejection (#204)", async () => {
+ const failingKv = {
+ ...mockKV(),
+ set: vi.fn(async () => {
+ const err = new Error(
+ "TIMEOUT: invocation timed out after 30000ms",
+ ) as Error & { code?: string; function_id?: string };
+ err.code = "TIMEOUT";
+ err.function_id = "state::set";
+ throw err;
+ }),
+ };
+ const bm25 = new SearchIndex();
+ bm25.add(makeObs({ id: "obs_1", title: "auth handler" }));
+ const persistence = new IndexPersistence(failingKv as never, bm25, null);
+
+ let unhandled = false;
+ const onUnhandled = () => {
+ unhandled = true;
+ };
+ process.on("unhandledRejection", onUnhandled);
+
+ try {
+ persistence.scheduleSave();
+ vi.advanceTimersByTime(5000);
+ await vi.runAllTimersAsync();
+ // give microtasks a chance to flush
+ await Promise.resolve();
+ expect(failingKv.set).toHaveBeenCalled();
+ expect(unhandled).toBe(false);
+ } finally {
+ process.off("unhandledRejection", onUnhandled);
+ }
+ });
+
+ it("save() does not throw when kv.set rejects (#204)", async () => {
+ const failingKv = {
+ ...mockKV(),
+ set: vi.fn(async () => {
+ throw new Error("TIMEOUT");
+ }),
+ };
+ const bm25 = new SearchIndex();
+ bm25.add(makeObs({ id: "obs_1", title: "auth handler" }));
+ const persistence = new IndexPersistence(failingKv as never, bm25, null);
+
+ await expect(persistence.save()).resolves.toBeUndefined();
+ });
});