Skip to content

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

fix: decouple import per-session obs ceiling from MAX_OBS_PER_SESSION env (#1556)

akushonkamena79fe1df833a
diff --git a/src/config.ts b/src/config.ts
index 649917f9..bfc95390 100644
--- a/src/config.ts
+++ b/src/config.ts
@@ -17,11 +17,19 @@ function safeParseInt(value: string | undefined, fallback: number): number {
return Number.isNaN(parsed) ? fallback : parsed;
}
+// Import-side ceiling for observations in a single session (enforced by
+// mem::import). Deliberately NOT named MAX_OBS_PER_SESSION — that env var is
+// the runtime write cap and the two are independent; loadConfig() warns when
+// the runtime cap is raised past this ceiling, which would let a session grow
+// past the point where export→import round-trips can restore the store.
+export const MAX_IMPORT_OBS_PER_SESSION = 5_000;
+
const DATA_DIR = join(homedir(), ".agentmemory");
const ENV_FILE = join(DATA_DIR, ".env");
let warnPremiumModelShown = false;
let providerNoticeShown = false;
+let obsCapImportCeilingWarned = false;
function writeProviderNoticeOnce(text: string): void {
if (providerNoticeShown) return;
@@ -220,6 +228,30 @@ export function loadConfig(): AgentMemoryConfig {
parseInt(env["III_ENGINE_PORT"] || "", 10) || restPort + 46023
}`;
+ const maxObservationsPerSession = safeParseInt(
+ env["MAX_OBS_PER_SESSION"],
+ 500,
+ );
+ if (
+ !obsCapImportCeilingWarned &&
+ (maxObservationsPerSession === 0 ||
+ maxObservationsPerSession > MAX_IMPORT_OBS_PER_SESSION)
+ ) {
+ obsCapImportCeilingWarned = true;
+ const capDesc =
+ maxObservationsPerSession === 0
+ ? "uncapped (0)"
+ : String(maxObservationsPerSession);
+ process.stderr.write(
+ `[agentmemory] WARNING: MAX_OBS_PER_SESSION is ${capDesc}, above the ` +
+ `${MAX_IMPORT_OBS_PER_SESSION}-per-session import ceiling ` +
+ `(MAX_IMPORT_OBS_PER_SESSION). Sessions past that ceiling make every ` +
+ `mem::export -> mem::import restore fail wholesale. Keep ` +
+ `MAX_OBS_PER_SESSION at or below ${MAX_IMPORT_OBS_PER_SESSION} if you ` +
+ `rely on export/import backups.\n`,
+ );
+ }
+
return {
engineUrl,
restPort,
@@ -227,7 +259,7 @@ export function loadConfig(): AgentMemoryConfig {
viewerPort,
provider,
tokenBudget: safeParseInt(env["TOKEN_BUDGET"], 2000),
- maxObservationsPerSession: safeParseInt(env["MAX_OBS_PER_SESSION"], 500),
+ maxObservationsPerSession,
compressionModel: provider.model,
dataDir: DATA_DIR,
};
diff --git a/src/functions/export-import.ts b/src/functions/export-import.ts
index 1987180e..7acc12cd 100644
--- a/src/functions/export-import.ts
+++ b/src/functions/export-import.ts
@@ -1,5 +1,6 @@
import { pinGraphState } from "../state/graph-generation.js";
import { persistGraphRecords, validateGraphRecords } from "../state/graph-ingestion.js";
+import { MAX_IMPORT_OBS_PER_SESSION } from "../config.js";
import type { IIIClient } from "iii-sdk";
import { markCaptureEventDeleted } from "../capture/event-record.js";
import type {
@@ -331,7 +332,6 @@ export function registerExportImportFunction(sdk: IIIClient, state: StateKV): vo
const MAX_SESSIONS = 10_000;
const MAX_MEMORIES = 50_000;
const MAX_SUMMARIES = 10_000;
- const MAX_OBS_PER_SESSION = 5_000;
const MAX_TOTAL_OBSERVATIONS = 500_000;
const MAX_ACCESS_LOGS = 50_000;
@@ -380,14 +380,18 @@ export function registerExportImportFunction(sdk: IIIClient, state: StateKV): vo
}
let totalObservations = 0;
- for (const [, obs] of Object.entries(importData.observations)) {
+ for (const [sessionId, obs] of Object.entries(importData.observations)) {
if (!Array.isArray(obs)) {
return { success: false, error: "observation values must be arrays" };
}
- if (obs.length > MAX_OBS_PER_SESSION) {
+ if (obs.length > MAX_IMPORT_OBS_PER_SESSION) {
return {
success: false,
- error: `Too many observations per session (max ${MAX_OBS_PER_SESSION})`,
+ error:
+ `Too many observations in session ${sessionId}: ${obs.length} ` +
+ `(max ${MAX_IMPORT_OBS_PER_SESSION}). MAX_OBS_PER_SESSION may be ` +
+ `configured above this import ceiling; lower it to at most ` +
+ `${MAX_IMPORT_OBS_PER_SESSION} or split the session before exporting.`,
};
}
totalObservations += obs.length;
diff --git a/test/import-session-cap.test.ts b/test/import-session-cap.test.ts
new file mode 100644
index 00000000..9319ef49
--- /dev/null
+++ b/test/import-session-cap.test.ts
@@ -0,0 +1,124 @@
+import { describe, it, expect, vi } from "vitest";
+
+vi.mock("../src/logger.js", () => ({
+ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+
+import { registerExportImportFunction } from "../src/functions/export-import.js";
+import type {
+ ExportData,
+ Session,
+ CompressedObservation,
+} from "../src/types.js";
+
+function mockKV() {
+ const store = new Map<string, Map<string, unknown>>();
+ return {
+ get: async <T>(scope: string, key: string): Promise<T | null> => {
+ return (store.get(scope)?.get(key) as T) ?? null;
+ },
+ set: async <T>(scope: string, key: string, data: T): Promise<T> => {
+ if (!store.has(scope)) store.set(scope, new Map());
+ store.get(scope)!.set(key, data);
+ return data;
+ },
+ delete: async (scope: string, key: string): Promise<void> => {
+ store.get(scope)?.delete(key);
+ },
+ list: async <T>(scope: string): Promise<T[]> => {
+ const entries = store.get(scope);
+ return entries ? (Array.from(entries.values()) as T[]) : [];
+ },
+ };
+}
+
+function mockSdk() {
+ const functions = new Map<string, Function>();
+ return {
+ registerFunction: (idOrOpts: string | { id: string }, handler: Function) => {
+ const id = typeof idOrOpts === "string" ? idOrOpts : idOrOpts.id;
+ functions.set(id, handler);
+ },
+ registerTrigger: () => {},
+ trigger: async (
+ idOrInput: string | { function_id: string; payload: unknown },
+ data?: unknown,
+ ) => {
+ const id =
+ typeof idOrInput === "string" ? idOrInput : idOrInput.function_id;
+ const payload = typeof idOrInput === "string" ? data : idOrInput.payload;
+ const fn = functions.get(id);
+ if (!fn) throw new Error(`No function: ${id}`);
+ return fn(payload);
+ },
+ };
+}
+
+const hotSession: Session = {
+ id: "ses_hot",
+ project: "my-project",
+ cwd: "/tmp",
+ startedAt: "2026-02-01T00:00:00Z",
+ status: "active",
+ observationCount: 0,
+};
+
+function obsFor(sessionId: string, i: number): CompressedObservation {
+ return {
+ id: `${sessionId}_obs_${i}`,
+ sessionId,
+ timestamp: "2026-02-01T10:00:00Z",
+ type: "file_edit",
+ title: `Observation ${i}`,
+ facts: [`fact ${i}`],
+ narrative: `Narrative ${i}`,
+ concepts: ["cap"],
+ files: [],
+ importance: 5,
+ };
+}
+
+function exportWith(sessionId: string, obsCount: number): ExportData {
+ return {
+ version: "0.9.30",
+ exportedAt: new Date().toISOString(),
+ sessions: [{ ...hotSession, id: sessionId, observationCount: obsCount }],
+ observations: {
+ [sessionId]: Array.from({ length: obsCount }, (_, i) =>
+ obsFor(sessionId, i),
+ ),
+ },
+ memories: [],
+ summaries: [],
+ };
+}
+
+describe("import per-session observation ceiling", () => {
+ it("names the offending session and its count when a session is over the ceiling", async () => {
+ const sdk = mockSdk();
+ registerExportImportFunction(sdk as never, mockKV() as never);
+
+ const result = (await sdk.trigger("mem::import", {
+ exportData: exportWith("ses_hot", 5001),
+ strategy: "merge",
+ })) as { success: boolean; error?: string };
+
+ expect(result.success).toBe(false);
+ expect(result.error).toContain("ses_hot");
+ expect(result.error).toContain("5001");
+ });
+
+ it("accepts a session at exactly the ceiling", async () => {
+ const sdk = mockSdk();
+ const kv = mockKV();
+ registerExportImportFunction(sdk as never, kv as never);
+
+ const result = (await sdk.trigger("mem::import", {
+ exportData: exportWith("ses_at_cap", 5000),
+ strategy: "merge",
+ })) as { success: boolean; observations: number };
+
+ expect(result.success).toBe(true);
+ expect(result.observations).toBe(5000);
+ });
+});
diff --git a/test/session-cap-import-warning.test.ts b/test/session-cap-import-warning.test.ts
new file mode 100644
index 00000000..bb3a8afd
--- /dev/null
+++ b/test/session-cap-import-warning.test.ts
@@ -0,0 +1,55 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+async function capWarningsFor(
+ value: string | undefined,
+): Promise<string[]> {
+ if (value === undefined) delete process.env["MAX_OBS_PER_SESSION"];
+ else process.env["MAX_OBS_PER_SESSION"] = value;
+ const writes: string[] = [];
+ vi.spyOn(process.stderr, "write").mockImplementation(
+ (chunk: string | Uint8Array) => {
+ writes.push(String(chunk));
+ return true;
+ },
+ );
+ vi.resetModules();
+ const { loadConfig } = await import("../src/config.js");
+ loadConfig();
+ loadConfig();
+ return writes.filter((w) => w.includes("MAX_OBS_PER_SESSION"));
+}
+
+describe("MAX_OBS_PER_SESSION vs import ceiling boot warning", () => {
+ let saved: string | undefined;
+
+ beforeEach(() => {
+ saved = process.env["MAX_OBS_PER_SESSION"];
+ });
+
+ afterEach(() => {
+ if (saved === undefined) delete process.env["MAX_OBS_PER_SESSION"];
+ else process.env["MAX_OBS_PER_SESSION"] = saved;
+ vi.restoreAllMocks();
+ });
+
+ it("warns once when the runtime cap is raised past the import ceiling", async () => {
+ const warnings = await capWarningsFor("5001");
+ expect(warnings).toHaveLength(1);
+ expect(warnings[0]).toContain("5001");
+ expect(warnings[0]).toContain("5000");
+ expect(warnings[0]).toContain("import");
+ });
+
+ it("warns when the runtime cap is uncapped (0)", async () => {
+ const warnings = await capWarningsFor("0");
+ expect(warnings).toHaveLength(1);
+ });
+
+ it("stays quiet at exactly the import ceiling", async () => {
+ expect(await capWarningsFor("5000")).toHaveLength(0);
+ });
+
+ it("stays quiet for the default cap", async () => {
+ expect(await capWarningsFor(undefined)).toHaveLength(0);
+ });
+});