Skip to content

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

perf(stream): stop per-session stream groups and bound the viewer backlog (#1420)

Rohit Ghumare92d4500ff3ed
diff --git a/.env.example b/.env.example
index 60d201e5..98e21b90 100644
--- a/.env.example
+++ b/.env.example
@@ -133,6 +133,7 @@
# AGENTMEMORY_VECTOR_BUCKET_SIZE=500 # Vectors held per storage bucket before a new bucket opens; a save only rewrites buckets it changed.
# AGENTMEMORY_VECTOR_BACKFILL_MAX=500 # Cap on vectors embedded per boot to backfill ones missing since the last save.
# AGENTMEMORY_VECTOR_BACKFILL=all # Required to backfill an entire store's vectors at once (no prior vector save, or a stale legacy manifest); unset means that case waits for an explicit opt-in.
+# AGENTMEMORY_VIEWER_STREAM_MAX=500 # Max items kept in the persisted "viewer" live-stream group; older entries are pruned in batches. Floored at 200 (the viewer's reload window); negative values fall back to the default
# -----------------------------------------------------------------------------
# 6. CLI / runtime knobs
diff --git a/plugin/skills/agentmemory-config/REFERENCE.md b/plugin/skills/agentmemory-config/REFERENCE.md
index 44e300d1..086ab4df 100644
--- a/plugin/skills/agentmemory-config/REFERENCE.md
+++ b/plugin/skills/agentmemory-config/REFERENCE.md
@@ -3,7 +3,7 @@
Generated by scanning `src/` for `AGENTMEMORY_*` usage. Do not edit the block below by hand; run `npm run skills:gen` after adding or removing a variable. Internal markers ending in two underscores are excluded.
<!-- AUTOGEN:env START - generated by scripts/skills/generate.ts, do not edit by hand -->
-Configuration is read from the environment and from `~/.agentmemory/.env` (no `export` prefix). 47 recognized variables:
+Configuration is read from the environment and from `~/.agentmemory/.env` (no `export` prefix). 48 recognized variables:
- `AGENTMEMORY_AGENT_SCOPE`
- `AGENTMEMORY_ALLOW_AGENT_SDK`
@@ -51,5 +51,6 @@ Configuration is read from the environment and from `~/.agentmemory/.env` (no `e
- `AGENTMEMORY_VECTOR_BUCKET_SIZE`
- `AGENTMEMORY_VERBOSE`
- `AGENTMEMORY_VIEWER_HOST`
+- `AGENTMEMORY_VIEWER_STREAM_MAX`
- `AGENTMEMORY_VIEWER_URL`
<!-- AUTOGEN:env END -->
diff --git a/src/config.ts b/src/config.ts
index a7986f96..f76fe19a 100644
--- a/src/config.ts
+++ b/src/config.ts
@@ -399,6 +399,26 @@ export function getFollowupWindowSeconds(): number {
);
}
+const VIEWER_STREAM_MAX_DEFAULT = 500;
+const VIEWER_STREAM_MAX_FLOOR = 200;
+
+function parseExactInt(value: string | undefined, fallback: number): number {
+ if (!value) return fallback;
+ const trimmed = value.trim();
+ if (!/^-?\d+$/.test(trimmed)) return fallback;
+ const parsed = Number(trimmed);
+ return Number.isSafeInteger(parsed) ? parsed : fallback;
+}
+
+export function getViewerStreamMax(): number {
+ const parsed = parseExactInt(
+ getMergedEnv()["AGENTMEMORY_VIEWER_STREAM_MAX"],
+ VIEWER_STREAM_MAX_DEFAULT,
+ );
+ if (parsed < 0) return VIEWER_STREAM_MAX_DEFAULT;
+ return Math.max(parsed, VIEWER_STREAM_MAX_FLOOR);
+}
+
export function isConsolidationEnabled(): boolean {
const env = getMergedEnv();
const explicit = env["CONSOLIDATION_ENABLED"];
diff --git a/src/functions/compress.ts b/src/functions/compress.ts
index a87a5b4f..b6a389a1 100644
--- a/src/functions/compress.ts
+++ b/src/functions/compress.ts
@@ -195,15 +195,6 @@ export function registerCompressFunction(
);
const streamResults = await Promise.allSettled([
- sdk.trigger({
- function_id: "stream::set",
- payload: {
- stream_name: STREAM.name,
- group_id: STREAM.group(data.sessionId),
- item_id: data.observationId,
- data: { type: "compressed", observation: compressed },
- },
- }),
sdk.trigger({
function_id: "stream::send",
payload: {
diff --git a/src/functions/observe.ts b/src/functions/observe.ts
index 366dca7e..eb2ed345 100644
--- a/src/functions/observe.ts
+++ b/src/functions/observe.ts
@@ -4,6 +4,7 @@ import type { RawObservation, HookPayload, Origin } from "../types.js";
const TOOL_HOOKS = new Set(["pre_tool_use", "post_tool_use", "post_tool_failure"]);
import { KV, STREAM, generateId } from "../state/schema.js";
import { StateKV } from "../state/kv.js";
+import { trackViewerStreamItem, pruneViewerStreamIfDue } from "../state/viewer-stream.js";
import { addSessionToProjectIndex } from "../state/session-index.js";
import { indexObservationSession } from "../state/obs-index.js";
import { stripPrivateData } from "./privacy.js";
@@ -233,16 +234,6 @@ export function registerObserveFunction(
dedupMap.record(dedupHash);
}
- await sdk.trigger({
- function_id: "stream::set",
- payload: {
- stream_name: STREAM.name,
- group_id: STREAM.group(payload.sessionId),
- item_id: obsId,
- data: { type: "raw", observation: raw },
- },
- });
-
await sdk.trigger({
function_id: "stream::send",
payload: {
@@ -350,15 +341,6 @@ export function registerObserveFunction(
synthetic.title + " " + (synthetic.narrative || ""),
{ kind: "synthetic", logId: synthetic.id },
);
- await sdk.trigger({
- function_id: "stream::set",
- payload: {
- stream_name: STREAM.name,
- group_id: STREAM.group(payload.sessionId),
- item_id: obsId,
- data: { type: "compressed", observation: synthetic },
- },
- });
await sdk.trigger({
function_id: "stream::set",
payload: {
@@ -372,6 +354,8 @@ export function registerObserveFunction(
},
},
});
+ trackViewerStreamItem(obsId);
+ void pruneViewerStreamIfDue(sdk).catch(() => {});
}
logger.info("Observation captured", {
diff --git a/src/index.ts b/src/index.ts
index 9affa68d..cf8154a0 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -27,6 +27,7 @@ import { IndexPersistence } from "./state/index-persistence.js";
import { SHUTDOWN_FLUSH_TIMEOUT_MS, SHUTDOWN_HARD_EXIT_MS, settleWithin } from "./shutdown.js";
import { registerPrivacyFunction } from "./functions/privacy.js";
import { registerObserveFunction } from "./functions/observe.js";
+import { seedViewerStreamTracker } from "./state/viewer-stream.js";
import { registerImageQuotaCleanup } from "./functions/image-quota-cleanup.js";
import { registerVisionSearchFunctions } from "./functions/vision-search.js";
import { registerSlotsFunctions, isSlotsEnabled, isReflectEnabled } from "./functions/slots.js";
@@ -577,6 +578,8 @@ async function main() {
}, 60 * 60 * 1000);
recentSearchesSweepTimer.unref();
+ void seedViewerStreamTracker(sdk).catch(() => {});
+
if (isConsolidationEnabled()) {
const consolidationTimer = setInterval(async () => {
try {
diff --git a/src/state/schema.ts b/src/state/schema.ts
index e044f280..2e1588cb 100644
--- a/src/state/schema.ts
+++ b/src/state/schema.ts
@@ -79,7 +79,6 @@ export const KV = {
export const STREAM = {
name: "mem-live",
- group: (sessionId: string) => sessionId,
viewerGroup: "viewer",
} as const;
diff --git a/src/state/viewer-stream.ts b/src/state/viewer-stream.ts
new file mode 100644
index 00000000..d89d65a9
--- /dev/null
+++ b/src/state/viewer-stream.ts
@@ -0,0 +1,131 @@
+import type { IIIClient } from "iii-sdk";
+import { STREAM } from "./schema.js";
+import { getViewerStreamMax } from "../config.js";
+import { logger } from "../logger.js";
+
+const PRUNE_BATCH_INTERVAL = 50;
+const DELETE_BATCH_SIZE = 100;
+const UNSHIFT_CHUNK_SIZE = 1000;
+const SEED_TIMEOUT_MS = 5000;
+
+const trackedItemIds: string[] = [];
+const trackedItemIdSet = new Set<string>();
+let writesSincePrune = 0;
+let pruning = false;
+let pruneAgain = false;
+
+export function trackViewerStreamItem(itemId: string): void {
+ if (trackedItemIdSet.has(itemId)) return;
+ trackedItemIdSet.add(itemId);
+ trackedItemIds.push(itemId);
+ writesSincePrune += 1;
+}
+
+function unshiftMany(target: string[], items: string[]): void {
+ for (let end = items.length; end > 0; end -= UNSHIFT_CHUNK_SIZE) {
+ const start = Math.max(0, end - UNSHIFT_CHUNK_SIZE);
+ target.splice(0, 0, ...items.slice(start, end));
+ }
+}
+
+async function deleteItems(sdk: IIIClient, itemIds: string[]): Promise<string[]> {
+ const failedItemIds: string[] = [];
+ for (let start = 0; start < itemIds.length; start += DELETE_BATCH_SIZE) {
+ const batch = itemIds.slice(start, start + DELETE_BATCH_SIZE);
+ const results = await Promise.allSettled(
+ batch.map((itemId) =>
+ sdk.trigger({
+ function_id: "stream::delete",
+ payload: {
+ stream_name: STREAM.name,
+ group_id: STREAM.viewerGroup,
+ item_id: itemId,
+ },
+ }),
+ ),
+ );
+ for (let i = 0; i < results.length; i++) {
+ const result = results[i];
+ if (result.status === "rejected") {
+ logger.warn("Failed to prune viewer stream item", {
+ error:
+ result.reason instanceof Error
+ ? result.reason.message
+ : String(result.reason),
+ });
+ failedItemIds.push(batch[i]);
+ }
+ }
+ }
+ return failedItemIds;
+}
+
+async function pruneOverflow(sdk: IIIClient): Promise<void> {
+ if (pruning) {
+ pruneAgain = true;
+ return;
+ }
+ pruning = true;
+ try {
+ do {
+ pruneAgain = false;
+ const overflow = trackedItemIds.length - getViewerStreamMax();
+ if (overflow <= 0) break;
+ const candidates = trackedItemIds.splice(0, overflow);
+ for (const itemId of candidates) trackedItemIdSet.delete(itemId);
+ candidates.reverse();
+ const failedItemIds = await deleteItems(sdk, candidates);
+ if (failedItemIds.length > 0) {
+ for (const itemId of failedItemIds) trackedItemIdSet.add(itemId);
+ unshiftMany(trackedItemIds, failedItemIds);
+ }
+ } while (pruneAgain);
+ } finally {
+ pruning = false;
+ }
+}
+
+export async function pruneViewerStreamIfDue(sdk: IIIClient): Promise<void> {
+ if (writesSincePrune < PRUNE_BATCH_INTERVAL) return;
+ writesSincePrune = 0;
+ await pruneOverflow(sdk);
+}
+
+type StoredViewerItem = {
+ observation?: { id?: unknown };
+};
+
+export async function seedViewerStreamTracker(sdk: IIIClient): Promise<number> {
+ let items: StoredViewerItem[];
+ try {
+ items = await sdk.trigger<unknown, StoredViewerItem[]>({
+ function_id: "stream::list",
+ payload: { stream_name: STREAM.name, group_id: STREAM.viewerGroup },
+ timeoutMs: SEED_TIMEOUT_MS,
+ });
+ } catch (err) {
+ logger.warn("Could not read the viewer stream backlog", {
+ error: err instanceof Error ? err.message : String(err),
+ });
+ return 0;
+ }
+ if (!Array.isArray(items)) return 0;
+ const stored: string[] = [];
+ for (const item of items) {
+ const id = item?.observation?.id;
+ if (typeof id !== "string" || trackedItemIdSet.has(id)) continue;
+ trackedItemIdSet.add(id);
+ stored.push(id);
+ }
+ unshiftMany(trackedItemIds, stored);
+ await pruneOverflow(sdk);
+ return stored.length;
+}
+
+export function resetViewerStreamTracker(): void {
+ trackedItemIds.length = 0;
+ trackedItemIdSet.clear();
+ writesSincePrune = 0;
+ pruning = false;
+ pruneAgain = false;
+}
diff --git a/test/compress-viewer-stream.test.ts b/test/compress-viewer-stream.test.ts
new file mode 100644
index 00000000..bc20e467
--- /dev/null
+++ b/test/compress-viewer-stream.test.ts
@@ -0,0 +1,99 @@
+import { describe, it, expect, vi } from "vitest";
+
+vi.mock("../src/logger.js", () => ({
+ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+
+vi.mock("../src/functions/search.js", () => ({
+ getSearchIndex: () => ({ add: vi.fn() }),
+ vectorIndexAddGuarded: vi.fn().mockResolvedValue(false),
+ scheduleIndexSave: vi.fn(),
+}));
+
+import { registerCompressFunction } from "../src/functions/compress.js";
+import { STREAM } from "../src/state/schema.js";
+import type { MemoryProvider, RawObservation } from "../src/types.js";
+
+const VALID_COMPRESS_XML = `<type>command_run</type>
+<title>Ran a probe command</title>
+<facts><fact>Ran echo probe</fact></facts>
+<narrative>The agent ran a probe command</narrative>
+<concepts><concept>testing</concept></concepts>
+<files></files>
+<importance>5</importance>`;
+
+function mockKV() {
+ const store = new Map<string, Map<string, unknown>>();
+ return {
+ get: async () => null,
+ set: async (scope: string, key: string, data: unknown) => {
+ if (!store.has(scope)) store.set(scope, new Map());
+ store.get(scope)!.set(key, data);
+ return data;
+ },
+ delete: async () => {},
+ list: async () => [],
+ };
+}
+
+describe("compress no longer writes a per-session mem-live group", () => {
+ it("only targets the viewer group on stream:: calls", async () => {
+ const trigger = vi.fn(async () => undefined);
+ const sdk = { trigger } as never;
+ const kv = mockKV() as never;
+
+ const provider: MemoryProvider = {
+ name: "mock",
+ compress: async () => VALID_COMPRESS_XML,
+ summarize: async () => "",
+ };
+
+ let compressCallback:
+ | ((payload: {
+ observationId: string;
+ sessionId: string;
+ raw: RawObservation;
+ }) => Promise<unknown>)
+ | null = null;
+ const registerSdk = {
+ trigger,
+ registerFunction: (
+ idOrOpts: string | { id: string },
+ fn: typeof compressCallback,
+ ) => {
+ const id = typeof idOrOpts === "string" ? idOrOpts : idOrOpts.id;
+ if (id === "mem::compress") compressCallback = fn;
+ },
+ };
+ registerCompressFunction(registerSdk as never, kv, provider);
+ expect(compressCallback).not.toBeNull();
+
+ const sessionId = "ses_compress_stream_test";
+ const raw: RawObservation = {
+ id: "obs_1",
+ sessionId,
+ hookType: "post_tool_use",
+ toolName: "Bash",
+ toolInput: { command: "echo probe" },
+ toolOutput: "probe output",
+ timestamp: new Date().toISOString(),
+ raw: {},
+ };
+
+ await compressCallback!({
+ observationId: "obs_1",
+ sessionId,
+ raw,
+ });
+
+ const streamCalls = trigger.mock.calls
+ .map((c) => c[0] as { function_id: string; payload: { group_id?: string } })
+ .filter((c) => c.function_id.startsWith("stream::"));
+
+ expect(streamCalls.length).toBeGreaterThan(0);
+ for (const call of streamCalls) {
+ expect(call.payload.group_id).not.toBe(sessionId);
+ expect(call.payload.group_id).toBe(STREAM.viewerGroup);
+ }
+ });
+});
diff --git a/test/observe-viewer-stream.test.ts b/test/observe-viewer-stream.test.ts
new file mode 100644
index 00000000..0532c0fc
--- /dev/null
+++ b/test/observe-viewer-stream.test.ts
@@ -0,0 +1,133 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+vi.mock("../src/logger.js", () => ({
+ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+
+import { registerObserveFunction } from "../src/functions/observe.js";
+import { STREAM } from "../src/state/schema.js";
+import { resetViewerStreamTracker } from "../src/state/viewer-stream.js";
+
+function mockKV() {
+ const store = new Map<string, Map<string, unknown>>();
+ return {
+ store,
+ get: async <T>(scope: string, key: string): Promise<T | null> =>
+ (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;
+ },
+ update: async (
+ scope: string,
+ key: string,
+ updates: Array<{ path: string; value: unknown }>,
+ ) => {
+ const m = store.get(scope);
+ if (!m) return;
+ const v = (m.get(key) as Record<string, unknown>) ?? {};
+ for (const u of updates) v[u.path] = u.value;
+ m.set(key, v);
+ },
+ delete: async (scope: string, key: string) => {
+ store.get(scope)?.delete(key);
+ },
+ list: async <T>(scope: string): Promise<T[]> => {
+ const m = store.get(scope);
+ return m ? (Array.from(m.values()) as T[]) : [];
+ },
+ };
+}
+
+function mockSdk() {
+ const fns = new Map<string, (payload: unknown) => Promise<unknown>>();
+ const trigger = vi.fn(
+ async (input: { function_id: string; payload: unknown }) => {
+ const fn = fns.get(input.function_id);
+ return fn ? fn(input.payload) : null;
+ },
+ );
+ return {
+ registerFunction: (
+ idOrOpts: string | { id: string },
+ fn: (payload: unknown) => Promise<unknown>,
+ ) => {
+ fns.set(typeof idOrOpts === "string" ? idOrOpts : idOrOpts.id, fn);
+ },
+ registerTrigger: () => {},
+ trigger,
+ };
+}
+
+function observePayload(sessionId: string, i: number) {
+ return {
+ sessionId,
+ project: "agentmemory",
+ cwd: "/tmp/agentmemory",
+ hookType: "post_tool_use",
+ timestamp: new Date().toISOString(),
+ data: {
+ tool_name: "Bash",
+ tool_input: { command: `echo probe-${i}` },
+ tool_output: `probe-${i} output`,
+ },
+ };
+}
+
+type StreamCall = {
+ function_id: string;
+ payload: { stream_name?: string; group_id?: string; item_id?: string };
+};
+
+describe("observe no longer writes per-session mem-live groups", () => {
+ beforeEach(() => {
+ resetViewerStreamTracker();
+ delete process.env.AGENTMEMORY_VIEWER_STREAM_MAX;
+ });
+
+ afterEach(() => {
+ delete process.env.AGENTMEMORY_VIEWER_STREAM_MAX;
+ });
+
+ it("never targets group_id === sessionId on any stream:: call", async () => {
+ const sdk = mockSdk();
+ const kv = mockKV();
+ registerObserveFunction(sdk as never, kv as never);
+
+ const sessionId = "ses_no_per_session_stream";
+ await sdk.trigger({ function_id: "mem::observe", payload: observePayload(sessionId, 0) });
+ await sdk.trigger({ function_id: "mem::observe", payload: observePayload(sessionId, 1) });
+
+ const streamCalls = sdk.trigger.mock.calls
+ .map((c) => c[0] as StreamCall)
+ .filter((c) => c.function_id.startsWith("stream::"));
+
+ expect(streamCalls.length).toBeGreaterThan(0);
+ for (const call of streamCalls) {
+ expect(call.payload.group_id).not.toBe(sessionId);
+ expect(call.payload.group_id).toBe(STREAM.viewerGroup);
+ }
+ });
+
+ it("prunes the viewer group once enough observations accumulate past the configured cap", async () => {
+ process.env.AGENTMEMORY_VIEWER_STREAM_MAX = "200";
+ const sdk = mockSdk();
+ const kv = mockKV();
+ registerObserveFunction(sdk as never, kv as never);
+
+ const sessionId = "ses_prune_wiring";
+ for (let i = 0; i < 255; i++) {
+ await sdk.trigger({ function_id: "mem::observe", payload: observePayload(sessionId, i) });
+ }
+
+ const deleteCalls = sdk.trigger.mock.calls
+ .map((c) => c[0] as StreamCall)
+ .filter((c) => c.function_id === "stream::delete");
+
+ expect(deleteCalls.length).toBeGreaterThan(0);
+ for (const call of deleteCalls) {
+ expect(call.payload.group_id).toBe(STREAM.viewerGroup);
+ }
+ });
+});
diff --git a/test/schema.test.ts b/test/schema.test.ts
index 94941c42..7d6397a4 100644
--- a/test/schema.test.ts
+++ b/test/schema.test.ts
@@ -20,8 +20,8 @@ describe('STREAM', () => {
expect(STREAM.name).toBe('mem-live')
})
- it('group returns session ID', () => {
- expect(STREAM.group('ses_123')).toBe('ses_123')
+ it('has correct viewer group', () => {
+ expect(STREAM.viewerGroup).toBe('viewer')
})
})
diff --git a/test/viewer-stream.test.ts b/test/viewer-stream.test.ts
new file mode 100644
index 00000000..94716724
--- /dev/null
+++ b/test/viewer-stream.test.ts
@@ -0,0 +1,332 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+vi.mock("../src/logger.js", () => ({
+ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+
+import {
+ trackViewerStreamItem,
+ pruneViewerStreamIfDue,
+ resetViewerStreamTracker,
+ seedViewerStreamTracker,
+} from "../src/state/viewer-stream.js";
+import { STREAM } from "../src/state/schema.js";
+import { logger } from "../src/logger.js";
+import { getViewerStreamMax } from "../src/config.js";
+
+function mockSdk() {
+ return { trigger: vi.fn(async () => ({ old_value: { id: "x" } })) };
+}
+
+type DeleteCall = {
+ function_id: string;
+ payload: { stream_name: string; group_id: string; item_id: string };
+};
+
+describe("viewer stream bounding", () => {
+ beforeEach(() => {
+ resetViewerStreamTracker();
+ delete process.env.AGENTMEMORY_VIEWER_STREAM_MAX;
+ vi.mocked(logger.warn).mockClear();
+ });
+
+ afterEach(() => {
+ delete process.env.AGENTMEMORY_VIEWER_STREAM_MAX;
+ });
+
+ it("does not prune before 50 writes have been recorded", async () => {
+ const sdk = mockSdk();
+ for (let i = 0; i < 49; i++) {
+ trackViewerStreamItem(`obs_${i}`);
+ await pruneViewerStreamIfDue(sdk as never);
+ }
+ expect(sdk.trigger).not.toHaveBeenCalled();
+ });
+
+ it("does not prune when tracked items stay under the cap", async () => {
+ process.env.AGENTMEMORY_VIEWER_STREAM_MAX = "500";
+ const sdk = mockSdk();
+ for (let i = 0; i < 50; i++) {
+ trackViewerStreamItem(`obs_${i}`);
+ await pruneViewerStreamIfDue(sdk as never);
+ }
+ expect(sdk.trigger).not.toHaveBeenCalled();
+ });
+
+ it("deletes only the oldest items beyond the cap, newest-of-the-overflow first", async () => {
+ process.env.AGENTMEMORY_VIEWER_STREAM_MAX = "200";
+ const sdk = mockSdk();
+ for (let i = 0; i < 250; i++) {
+ trackViewerStreamItem(`obs_${i}`);
+ await pruneViewerStreamIfDue(sdk as never);
+ }
+
+ expect(sdk.trigger).toHaveBeenCalledTimes(50);
+ const calls = sdk.trigger.mock.calls.map((c) => c[0] as DeleteCall);
+ expect(calls.map((c) => c.payload.item_id)).toEqual(
+ Array.from({ length: 50 }, (_, i) => `obs_${49 - i}`),
+ );
+ for (const call of calls) {
+ expect(call.function_id).toBe("stream::delete");
+ expect(call.payload.stream_name).toBe(STREAM.name);
+ expect(call.payload.group_id).toBe(STREAM.viewerGroup);
+ }
+ });
+
+ it("only re-checks the cap every 50 writes, not on every write", async () => {
+ process.env.AGENTMEMORY_VIEWER_STREAM_MAX = "200";
+ const sdk = mockSdk();
+ for (let i = 0; i < 240; i++) {
+ trackViewerStreamItem(`obs_${i}`);
+ await pruneViewerStreamIfDue(sdk as never);
+ }
+ expect(sdk.trigger).not.toHaveBeenCalled();
+
+ for (let i = 240; i < 250; i++) {
+ trackViewerStreamItem(`obs_${i}`);
+ await pruneViewerStreamIfDue(sdk as never);
+ }
+ expect(sdk.trigger).toHaveBeenCalledTimes(50);
+
+ for (let i = 250; i < 260; i++) {
+ trackViewerStreamItem(`obs_${i}`);
+ await pruneViewerStreamIfDue(sdk as never);
+ }
+ expect(sdk.trigger).toHaveBeenCalledTimes(50);
+ });
+
+ it("defaults the cap to 500 when AGENTMEMORY_VIEWER_STREAM_MAX is unset", async () => {
+ const sdk = mockSdk();
+ for (let i = 0; i < 550; i++) {
+ trackViewerStreamItem(`obs_${i}`);
+ await pruneViewerStreamIfDue(sdk as never);
+ }
+ expect(sdk.trigger).toHaveBeenCalledTimes(50);
+ });
+
+ it("logs a warning but resolves cleanly when a delete call rejects", async () => {
+ process.env.AGENTMEMORY_VIEWER_STREAM_MAX = "0";
+ const sdk = { trigger: vi.fn(async () => { throw new Error("boom"); }) };
+ for (let i = 0; i < 250; i++) {
+ trackViewerStreamItem(`obs_${i}`);
+ }
+ await expect(pruneViewerStreamIfDue(sdk as never)).resolves.toBeUndefined();
+ expect(logger.warn).toHaveBeenCalled();
+ });
+
+ it("does not double-track the same id, avoiding an extra delete", async () => {
+ process.env.AGENTMEMORY_VIEWER_STREAM_MAX = "200";
+ const sdk = mockSdk();
+ trackViewerStreamItem("obs_dup");
+ trackViewerStreamItem("obs_dup");
+ for (let i = 0; i < 199; i++) trackViewerStreamItem(`obs_${i}`);
+ await pruneViewerStreamIfDue(sdk as never);
+ expect(sdk.trigger).not.toHaveBeenCalled();
+ });
+
+ it("seeds the tracker in the engine's listing order and prunes the overflow newest-first", async () => {
+ process.env.AGENTMEMORY_VIEWER_STREAM_MAX = "200";
+ const deleted: string[] = [];
+ const items = Array.from({ length: 205 }, (_, i) => ({
+ observation: { id: `obs_${i}`, timestamp: new Date(2026, 0, i + 1).toISOString() },
+ }));
+ const sdk = {
+ trigger: vi.fn(async (req: { function_id: string; payload: { item_id?: string } }) => {
+ if (req.function_id === "stream::list") return items;
+ if (req.payload.item_id) deleted.push(req.payload.item_id);
+ return {};
+ }),
+ };
+ await expect(seedViewerStreamTracker(sdk as never)).resolves.toBe(205);
+ expect(deleted).toEqual(["obs_4", "obs_3", "obs_2", "obs_1", "obs_0"]);
+ });
+
+ it("seeds using the engine's listing order, ignoring an unparseable client timestamp", async () => {
+ process.env.AGENTMEMORY_VIEWER_STREAM_MAX = "200";
+ const deleted: string[] = [];
+ const items: { observation: { id: string; timestamp: string } }[] = Array.from(
+ { length: 200 },
+ (_, i) => ({
+ observation: { id: `obs_${i}`, timestamp: new Date(2026, 0, i + 1).toISOString() },
+ }),
+ );
+ items.push({ observation: { id: "obs_bad_timestamp", timestamp: "not-a-date" } });
+ const sdk = {
+ trigger: vi.fn(async (req: { function_id: string; payload: { item_id?: string } }) => {
+ if (req.function_id === "stream::list") return items;
+ if (req.payload.item_id) deleted.push(req.payload.item_id);
+ return {};
+ }),
+ };
+ await expect(seedViewerStreamTracker(sdk as never)).resolves.toBe(201);
+ expect(deleted).toEqual(["obs_0"]);
+ });
+
+ it("does not re-track a seeded id the live path observes too", async () => {
+ process.env.AGENTMEMORY_VIEWER_STREAM_MAX = "200";
+ const deleted: string[] = [];
+ const sdk = {
+ trigger: vi.fn(async (req: { function_id: string; payload: { item_id?: string } }) => {
+ if (req.function_id === "stream::list") {
+ return [{ observation: { id: "obs_seeded", timestamp: "2026-01-01T00:00:00Z" } }];
+ }
+ if (req.payload.item_id) deleted.push(req.payload.item_id);
+ return {};
+ }),
+ };
+ await seedViewerStreamTracker(sdk as never);
+ trackViewerStreamItem("obs_seeded");
+ for (let i = 0; i < 249; i++) trackViewerStreamItem(`obs_${i}`);
+ await pruneViewerStreamIfDue(sdk as never);
+
+ expect(deleted).toHaveLength(50);
+ expect(deleted.filter((id) => id === "obs_seeded")).toHaveLength(1);
+ });
+
+ it("passes a short timeout on the boot stream::list call", async () => {
+ const sdk = { trigger: vi.fn(async () => []) };
+ await seedViewerStreamTracker(sdk as never);
+ expect(sdk.trigger).toHaveBeenCalledWith(
+ expect.objectContaining({
+ function_id: "stream::list",
+ timeoutMs: expect.any(Number),
+ }),
+ );
+ const call = sdk.trigger.mock.calls[0][0] as { timeoutMs: number };
+ expect(call.timeoutMs).toBeGreaterThan(0);
+ expect(call.timeoutMs).toBeLessThan(30000);
+ });
+
+ it("deletes a large backlog in bounded batches", async () => {
+ process.env.AGENTMEMORY_VIEWER_STREAM_MAX = "200";
+ let inFlight = 0;
+ let peak = 0;
+ const sdk = {
+ trigger: vi.fn(async (req: { function_id: string }) => {
+ if (req.function_id === "stream::list") {
+ return Array.from({ length: 450 }, (_, i) => ({ observation: { id: "obs_" + i, timestamp: new Date(i * 1000).toISOString() } }));
+ }
+ inFlight++;
+ peak = Math.max(peak, inFlight);
+ await new Promise((r) => setTimeout(r, 1));
+ inFlight--;
+ return {};
+ }),
+ };
+ await seedViewerStreamTracker(sdk as never);
+ expect(sdk.trigger).toHaveBeenCalledTimes(251);
+ expect(peak).toBeLessThanOrEqual(100);
+ });
+
+ it("keeps working when the backlog cannot be read", async () => {
+ const sdk = { trigger: vi.fn(async () => { throw new Error("no stream"); }) };
+ await expect(seedViewerStreamTracker(sdk as never)).resolves.toBe(0);
+ });
+
+ it("retries a failed delete on the next prune instead of losing the id", async () => {
+ process.env.AGENTMEMORY_VIEWER_STREAM_MAX = "200";
+ const sdk = {
+ trigger: vi.fn(async (req: DeleteCall) => {
+ if (req.payload.item_id === "obs_1") throw new Error("boom");
+ return {};
+ }),
+ };
+ for (let i = 0; i < 250; i++) trackViewerStreamItem(`obs_${i}`);
+ await pruneViewerStreamIfDue(sdk as never);
+
+ const firstRoundIds = sdk.trigger.mock.calls.map((c) => (c[0] as DeleteCall).payload.item_id);
+ expect(firstRoundIds).toContain("obs_1");
+
+ sdk.trigger.mockClear();
+ for (let i = 250; i < 300; i++) trackViewerStreamItem(`obs_${i}`);
+ await pruneViewerStreamIfDue(sdk as never);
+
+ const secondRoundIds = sdk.trigger.mock.calls.map((c) => (c[0] as DeleteCall).payload.item_id);
+ expect(secondRoundIds).toContain("obs_1");
+ });
+
+ it("runs another overflow check once an in-progress prune completes", async () => {
+ process.env.AGENTMEMORY_VIEWER_STREAM_MAX = "200";
+ let releaseFirstDelete: () => void = () => {};
+ const firstDeleteGate = new Promise<void>((resolve) => {
+ releaseFirstDelete = resolve;
+ });
+ let deleteCallCount = 0;
+ const sdk = {
+ trigger: vi.fn(async (req: { function_id: string }) => {
+ if (req.function_id !== "stream::delete") return {};
+ deleteCallCount += 1;
+ if (deleteCallCount === 1) await firstDeleteGate;
+ return {};
+ }),
+ };
+
+ for (let i = 0; i < 250; i++) trackViewerStreamItem(`obs_${i}`);
+ const firstPrune = pruneViewerStreamIfDue(sdk as never);
+
+ await Promise.resolve();
+ for (let i = 250; i < 500; i++) trackViewerStreamItem(`obs_${i}`);
+ await pruneViewerStreamIfDue(sdk as never);
+
+ releaseFirstDelete();
+ await firstPrune;
+
+ const deleteCalls = sdk.trigger.mock.calls.filter(
+ (c) => (c[0] as { function_id: string }).function_id === "stream::delete",
+ );
+ expect(deleteCalls).toHaveLength(300);
+ });
+
+ it("seeds a very large backlog without hitting the argument spread limit", async () => {
+ process.env.AGENTMEMORY_VIEWER_STREAM_MAX = "1000000";
+ const total = 200000;
+ const sdk = {
+ trigger: vi.fn(async (req: { function_id: string }) => {
+ if (req.function_id === "stream::list") {
+ return Array.from({ length: total }, (_, i) => ({
+ observation: { id: `obs_${i}`, timestamp: new Date(i * 1000).toISOString() },
+ }));
+ }
+ return {};
+ }),
+ };
+ await expect(seedViewerStreamTracker(sdk as never)).resolves.toBe(total);
+ expect(sdk.trigger).toHaveBeenCalledTimes(1);
+ });
+});
+
+describe("getViewerStreamMax validation", () => {
+ afterEach(() => {
+ delete process.env.AGENTMEMORY_VIEWER_STREAM_MAX;
+ });
+
+ it("falls back to the default when the value has trailing non-digit characters", () => {
+ process.env.AGENTMEMORY_VIEWER_STREAM_MAX = "500000junk";
+ expect(getViewerStreamMax()).toBe(500);
+ });
+
+ it("still parses a clean integer value", () => {
+ process.env.AGENTMEMORY_VIEWER_STREAM_MAX = "250";
+ expect(getViewerStreamMax()).toBe(250);
+ });
+
+ it("falls back to the default for an empty value", () => {
+ process.env.AGENTMEMORY_VIEWER_STREAM_MAX = "";
+ expect(getViewerStreamMax()).toBe(500);
+ });
+
+ it("rejects a negative value and falls back to the default", () => {
+ process.env.AGENTMEMORY_VIEWER_STREAM_MAX = "-5";
+ expect(getViewerStreamMax()).toBe(500);
+ });
+
+ it("clamps a positive value under the viewer's reload floor up to 200", () => {
+ process.env.AGENTMEMORY_VIEWER_STREAM_MAX = "50";
+ expect(getViewerStreamMax()).toBe(200);
+ });
+
+ it("clamps zero up to the floor instead of pruning everything", () => {
+ process.env.AGENTMEMORY_VIEWER_STREAM_MAX = "0";
+ expect(getViewerStreamMax()).toBe(200);
+ });
+});