#1 Persistent memory for AI coding agents based on real-world benchmarks
TypeScript agentmemoryagentsaiclaudeclaudecodecodexcopilotcursorgenaiharnesshermesmemoryompopenclawopencodepi
fix: decouple import per-session obs ceiling from MAX_OBS_PER_SESSION env (#1556)
akushonkamena79fe1df833a
diff --git a/src/config.ts b/src/config.tsindex 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.tsindex 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): voconst 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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);+ });+});