@pensar/apex 2.6.1 → 2.7.0-canary.6d9d1e0d

package/src/core/agents/offSecAgent/tools/listMemories.test.ts

@@ -0,0 +1,230 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  type Memory,
+  type MemoryBackend,
+  type MemorySummary,
+  withMemoryBackend,
+} from "../../../memory";
+import { type GetMemoryResult, getMemory } from "./getMemory";
+import { type ListMemoriesResult, listMemories } from "./listMemories";
+import type { ToolContext } from "./types";
+
+const ctx = { session: { id: "synthetic" } } as ToolContext;
+const options = { toolCallId: "synthetic-call", messages: [] };
+const list = listMemories(ctx).execute;
+const get = getMemory(ctx).execute;
+if (!list || !get) throw new Error("Memory tools must be executable");
+
+describe("list_memories pagination", () => {
+  it("continues from the first unreturned summary when the character budget fills", async () => {
+    const summaries: MemorySummary[] = Array.from({ length: 30 }, (_, i) => ({
+      id: `large-${i}`,
+      category: "general",
+      title: "t".repeat(300),
+      tags: Array.from({ length: 8 }, () => "tag".repeat(40)),
+      createdAt: new Date(Date.UTC(2026, 0, 1) - i * 1_000).toISOString(),
+    }));
+    const backend: MemoryBackend = {
+      add: vi.fn(async () => {
+        throw new Error("unexpected add");
+      }),
+      list: vi.fn(async () => summaries),
+      get: vi.fn(async () => null),
+    };
+    await withMemoryBackend(backend, async () => {
+      const first = (await list(
+        { toolCallDescription: "List large synthetic memories" },
+        options,
+      )) as ListMemoriesResult;
+      expect(first.memories.length).toBeLessThan(20);
+      expect(JSON.stringify(first).length).toBeLessThan(12_500);
+      expect(first.nextCursor).toEqual({
+        id: first.memories.at(-1)?.id,
+        category: first.memories.at(-1)?.category,
+        createdAt: first.memories.at(-1)?.createdAt,
+      });
+      const second = (await list(
+        {
+          cursor: first.nextCursor ?? undefined,
+          toolCallDescription: "Continue large synthetic memories",
+        },
+        options,
+      )) as ListMemoriesResult;
+      expect(second.memories[0]?.id).toBe(summaries[first.memories.length]?.id);
+    });
+  });
+
+  it("continues past the last returned memory when a newer one is added", async () => {
+    const original: MemorySummary[] = Array.from({ length: 30 }, (_, i) => ({
+      id: `memory-${i}`,
+      category: "general",
+      title: `Memory ${i}`,
+      tags: [],
+      createdAt: new Date(Date.UTC(2026, 0, 1) - i * 1_000).toISOString(),
+    }));
+    let summaries = original;
+    const backend: MemoryBackend = {
+      add: vi.fn(async () => {
+        throw new Error("unexpected add");
+      }),
+      list: vi.fn(async () => summaries),
+      get: vi.fn(async () => null),
+    };
+    await withMemoryBackend(backend, async () => {
+      const first = (await list(
+        { toolCallDescription: "List first memory page" },
+        options,
+      )) as ListMemoriesResult;
+      summaries = [
+        {
+          ...original[0],
+          id: "memory-new",
+          createdAt: new Date(Date.UTC(2026, 0, 2)).toISOString(),
+        },
+        ...original,
+      ];
+      const second = (await list(
+        {
+          cursor: first.nextCursor ?? undefined,
+          toolCallDescription: "Continue after an insertion",
+        },
+        options,
+      )) as ListMemoriesResult;
+
+      expect(first.memories.map((memory) => memory.id)).toEqual(
+        original.slice(0, 20).map((memory) => memory.id),
+      );
+      expect(second.memories.map((memory) => memory.id)).toEqual(
+        original.slice(20).map((memory) => memory.id),
+      );
+      expect(second.count).toBe(31);
+      expect(second.nextCursor).toBeNull();
+    });
+  });
+
+  it("uses stable tie ordering when the cursor memory is deleted", async () => {
+    const original: MemorySummary[] = Array.from({ length: 25 }, (_, i) => ({
+      id: `memory-${i.toString().padStart(2, "0")}`,
+      category: "general",
+      title: `Memory ${i}`,
+      tags: [],
+      createdAt: "2026-01-01T00:00:00.000Z",
+    }));
+    let summaries = [...original].reverse();
+    const backend: MemoryBackend = {
+      add: vi.fn(async () => {
+        throw new Error("unexpected add");
+      }),
+      list: vi.fn(async () => summaries),
+      get: vi.fn(async () => null),
+    };
+    await withMemoryBackend(backend, async () => {
+      const first = (await list(
+        { toolCallDescription: "List tied memories" },
+        options,
+      )) as ListMemoriesResult;
+      expect(first.memories.map((memory) => memory.id)).toEqual(
+        original.slice(0, 20).map((memory) => memory.id),
+      );
+      summaries = summaries.filter(
+        (memory) => memory.id !== first.nextCursor?.id,
+      );
+      const second = (await list(
+        {
+          cursor: first.nextCursor ?? undefined,
+          toolCallDescription: "Continue after anchor deletion",
+        },
+        options,
+      )) as ListMemoriesResult;
+      expect(second.memories.map((memory) => memory.id)).toEqual(
+        original.slice(20).map((memory) => memory.id),
+      );
+      expect(second.nextCursor).toBeNull();
+    });
+  });
+
+  it("bounds each result while keeping every older memory discoverable", async () => {
+    const summaries: MemorySummary[] = Array.from({ length: 200 }, (_, i) => ({
+      id: `memory-${i}`,
+      category: "general",
+      title: `Memory ${i} ${"x".repeat(480)}`,
+      tags: ["synthetic", "history"],
+      createdAt: new Date(Date.UTC(2026, 0, 1) - i * 1_000).toISOString(),
+    }));
+    const backend: MemoryBackend = {
+      add: vi.fn(async () => {
+        throw new Error("unexpected add");
+      }),
+      list: vi.fn(async () =>
+        summaries.map((summary, index) =>
+          index === 0 ? { ...summary, content: "full-body-marker" } : summary,
+        ),
+      ),
+      get: vi.fn(async (_category, id) => {
+        const summary = summaries.find((item) => item.id === id);
+        return summary
+          ? ({
+              ...summary,
+              content: `Full ${id}`,
+              updatedAt: summary.createdAt,
+            } satisfies Memory)
+          : null;
+      }),
+    };
+
+    await withMemoryBackend(backend, async () => {
+      const allIds: string[] = [];
+      let cursor: ListMemoriesResult["nextCursor"] = null;
+      let firstResultChars = 0;
+      let pages = 0;
+      for (;;) {
+        const result = (await list(
+          {
+            cursor: cursor ?? undefined,
+            toolCallDescription: "List synthetic memories",
+          },
+          options,
+        )) as ListMemoriesResult;
+        expect(result.success).toBe(true);
+        expect(result.count).toBe(200);
+        expect(result.memories.length).toBeGreaterThan(0);
+        expect(result.memories.length).toBeLessThanOrEqual(20);
+        expect(JSON.stringify(result).length).toBeLessThan(12_500);
+        if (pages === 0) {
+          firstResultChars = JSON.stringify(result).length;
+          expect(JSON.stringify(result)).not.toContain("full-body-marker");
+          expect(result.memories[0]?.truncated).toBe(true);
+          expect(result.memories[0]?.title.length).toBe(160);
+        }
+        allIds.push(...result.memories.map((memory) => memory.id));
+        pages++;
+        if (result.nextCursor === null) break;
+        expect(result.nextCursor.id).toBe(result.memories.at(-1)?.id);
+        cursor = result.nextCursor;
+      }
+
+      expect(allIds).toEqual(summaries.map((memory) => memory.id));
+      const oldest = (await get(
+        {
+          category: "general",
+          id: allIds.at(-1) ?? "",
+          toolCallDescription: "Read oldest synthetic memory",
+        },
+        options,
+      )) as GetMemoryResult;
+      expect(oldest.memory?.content).toBe("Full memory-199");
+      if (process.env.APEX_CONTEXT_BENCH === "1") {
+        const previousChars = JSON.stringify({
+          success: true,
+          error: "",
+          memories: summaries,
+          count: summaries.length,
+        }).length;
+        console.log(
+          "MEMORY_LIST_BENCH",
+          JSON.stringify({ previousChars, firstResultChars, pages }),
+        );
+      }
+    });
+  });
+});

package/src/core/agents/offSecAgent/tools/listMemories.ts

@@ -7,6 +7,9 @@ import {
 } from "../../../memory";
 import type { ToolContext } from "./types";
 
+const PAGE_SIZE = 20;
+const PAGE_CHAR_BUDGET = 12_000;
+
 const listMemoriesInputSchema = z.object({
   category: z
     .enum(MEMORY_CATEGORIES)
@@ -19,6 +22,14 @@ const listMemoriesInputSchema = z.object({
     .string()
     .optional()
     .describe("Optional tag to filter memories by (exact match)"),
+  cursor: z
+    .object({
+      createdAt: z.string(),
+      category: z.enum(MEMORY_CATEGORIES),
+      id: z.string(),
+    })
+    .optional()
+    .describe("Pass the previous nextCursor to continue a listing"),
   toolCallDescription: z
     .string()
     .describe(
@@ -27,24 +38,53 @@ const listMemoriesInputSchema = z.object({
 });
 
 type ListMemoriesInput = z.infer<typeof listMemoriesInputSchema>;
+type MemoryCursor = Pick<MemorySummary, "createdAt" | "category" | "id">;
 
 export type ListMemoriesResult = {
   success: boolean;
   error: string;
-  memories: MemorySummary[];
+  memories: Array<MemorySummary & { truncated?: true }>;
   count: number;
+  nextCursor: MemoryCursor | null;
 };
 
+function compareMemories(a: MemoryCursor, b: MemoryCursor): number {
+  const byCreatedAt = Date.parse(b.createdAt) - Date.parse(a.createdAt);
+  if (byCreatedAt > 0 || byCreatedAt < 0) return byCreatedAt;
+  return a.category.localeCompare(b.category) || a.id.localeCompare(b.id);
+}
+
+function previewSummary(memory: MemorySummary) {
+  const title = memory.title.slice(0, 160);
+  const tags = memory.tags.slice(0, 8).map((tag) => tag.slice(0, 48));
+  const truncated =
+    title.length < memory.title.length ||
+    tags.length < memory.tags.length ||
+    tags.some(
+      (tag, index) => tag.length < (memory.tags[index]?.length ?? tag.length),
+    );
+  return {
+    id: memory.id,
+    category: memory.category,
+    title,
+    tags,
+    createdAt: memory.createdAt,
+    ...(truncated ? { truncated: true as const } : {}),
+  };
+}
+
 export function listMemories(ctx: ToolContext) {
   return tool({
     description: `List saved memories, optionally filtered by category and/or tag.
 
-Returns lightweight summaries (id, category, title, tags, createdAt) sorted by
-most recent first. Use the returned category + id with get_memory to retrieve
-full content.`,
+Returns up to 20 lightweight summaries (id, category, title, tags, createdAt)
+sorted by most recent first. Use nextCursor to continue until it is null;
+count is the current total matching memories. A fresh listing includes newer
+memories added ahead of a cursor. Titles and tags may be abbreviated in the
+listing. Use category + id with get_memory to retrieve full content.`,
     inputSchema: listMemoriesInputSchema,
     execute: async (
-      { category, tag },
+      { category, tag, cursor },
       { toolCallId },
     ): Promise<ListMemoriesResult> => {
       try {
@@ -52,11 +92,37 @@ full content.`,
           { category, tag },
           { sessionId: ctx.session.id, toolCallId },
         );
+        const ordered = [...memories].sort(compareMemories);
+        let start = 0;
+        if (cursor) {
+          start = ordered.findIndex(
+            (memory) => compareMemories(memory, cursor) > 0,
+          );
+          if (start < 0) start = ordered.length;
+        }
+        const page: ListMemoriesResult["memories"] = [];
+        let pageChars = 0;
+        for (const memory of ordered.slice(start, start + PAGE_SIZE)) {
+          const summary = previewSummary(memory);
+          const chars = JSON.stringify(summary).length + 1;
+          if (page.length > 0 && pageChars + chars > PAGE_CHAR_BUDGET) break;
+          page.push(summary);
+          pageChars += chars;
+        }
+        const last = page.at(-1);
         return {
           success: true,
           error: "",
-          memories,
+          memories: page,
           count: memories.length,
+          nextCursor:
+            start + page.length < ordered.length && last
+              ? {
+                  createdAt: last.createdAt,
+                  category: last.category,
+                  id: last.id,
+                }
+              : null,
         };
       } catch (err: unknown) {
         return {
@@ -64,6 +130,7 @@ full content.`,
           error: err instanceof Error ? err.message : String(err),
           memories: [],
           count: 0,
+          nextCursor: null,
         };
       }
     },