#1 Persistent memory for AI coding agents based on real-world benchmarks
TypeScript agentmemoryagentsaiclaudeclaudecodecodexcopilotcursorgenaiharnesshermesmemoryompopenclawopencodepi
perf(stream): stop per-session stream groups and bound the viewer backlog (#1420)
Rohit Ghumare92d4500ff3ed
diff --git a/.env.example b/.env.exampleindex 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 knobsdiff --git a/plugin/skills/agentmemory-config/REFERENCE.md b/plugin/skills/agentmemory-config/REFERENCE.mdindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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);+ });+});