From 84651b178ede6c0978d49d55956bb3cd1c7c075a Mon Sep 17 00:00:00 2001 From: dilipna <163414135+dilipna@users.noreply.github.com> Date: Sat, 21 Nov 2026 21:35:09 -0500 Subject: [PATCH] The Memories page's Pinned and Conflicted filters cover the whole namespace Pinned, Conflicted and Verified read the newest 1,000 rows and kept the matching ones, so in a larger namespace an older pinned or conflicted memory was missing and the count was wrong. memory.list takes pinned_only (hidden from the MCP listing), passed to the recency and score reads, both counts and the count cache key. Conflicted reads the conflicted keys and their rows with memory.bulk_get, 1,000 keys at a time, and says when the keys read reach the 5,000-key cap. Verified is unchanged. Co-Authored-By: Claude Opus 5.5 Signed-off-by: dilipna <163414135+dilipna@users.noreply.github.com> --- docs/reference/operations/memory.md | 1 + frontend/src/api.ts | 12 +- frontend/src/views/Recent.lists.test.tsx | 119 ++++++++++++++++++- frontend/src/views/Recent.tsx | 40 +++++-- frontend/src/views/memoryListReads.ts | 68 ++++++++++- sdk/python/loom/ops.py | 2 + sdk/typescript/src/generated/ops.ts | 1 + server/memory/api/models_crud.py | 4 + server/memory/app/query.py | 41 +++++-- tests/integration/test_memory_delete_list.py | 28 +++++ 10 files changed, 275 insertions(+), 41 deletions(-) diff --git a/docs/reference/operations/memory.md b/docs/reference/operations/memory.md index 97e81689b2..9afc342038 100644 --- a/docs/reference/operations/memory.md +++ b/docs/reference/operations/memory.md @@ -1259,6 +1259,7 @@ List memory keys under this identity, optionally filtered. | `tags` | `list[str]` | *(computed)* | Only rows carrying any one of these tags, in any case; empty = no tag filter. | | `tags_every` | `bool` | `False` | Require every one of `tags` instead of any one; default off. | | `contains` | `str \| None` | `None` | Only rows whose value or key holds this text, any case (a high row by its key only) — the keyword filter of a browse page's search box, which must find every row that names a word (a ranked search returns its top k and misses the rest). | +| `pinned_only` | `bool` | `False` | Only pinned rows. | | `fields` | `list[str]` | *(computed)* | Whitelist of entry field names; every entry carries only those plus `memory_key` and `sensitivity`. | | `known_version` | `int \| str \| None` | `None` | The `namespace_version` a previous answer carried. | diff --git a/frontend/src/api.ts b/frontend/src/api.ts index 7ad71ac76a..a8ff102e8e 100644 --- a/frontend/src/api.ts +++ b/frontend/src/api.ts @@ -462,6 +462,8 @@ export async function listMemories( tags?: string[]; // Only rows this agent wrote; every agent's rows when unset. agent?: string; + // Only pinned rows. + pinnedOnly?: boolean; } & RequestOpts = {}, ): Promise { // Without an agent the Memories view shows every agent's rows, so it sends `agent=*` to @@ -482,6 +484,7 @@ export async function listMemories( ...(opts.fields ? { fields: opts.fields } : {}), ...(opts.previewChars ? { preview_chars: opts.previewChars } : {}), ...(opts.contains ? { contains: opts.contains } : {}), + ...(opts.pinnedOnly ? { pinned_only: true } : {}), // Tags as typed; the server matches them in any case. Two or more must all match (a // build that predates `tags_every` matches any one, and the page then requires every tag // itself). @@ -1036,9 +1039,12 @@ export async function countConflicts( return r.total ?? 0; } -/** The conflicted memory keys of a namespace, for the cards' chips - * — the same operation with `keys_only`, one FINAL read of the key columns and no value - * column. */ +/** The most keys one `keys_only` read returns: the server's cap. */ +export const CONFLICT_KEYS_CAP = 5000; + +/** The conflicted memory keys of a namespace, newest version first, for the cards' chips + * and the Conflicted list — the same operation with `keys_only`, one FINAL read of the key + * columns and no value column. At most `CONFLICT_KEYS_CAP` keys. */ export async function conflictKeys(id: Pick, opts: RequestOpts = {}): Promise { const r = await post<{ keys?: string[] | null }>( "/v1/conflicts.list", diff --git a/frontend/src/views/Recent.lists.test.tsx b/frontend/src/views/Recent.lists.test.tsx index ee09b1d0a7..15ce974639 100644 --- a/frontend/src/views/Recent.lists.test.tsx +++ b/frontend/src/views/Recent.lists.test.tsx @@ -27,6 +27,25 @@ const entry = (memory_key: string, over: Partial = {}): MemoryL ...over, }); +// A memory.bulk_get answer for each key asked. +const detail = (over: Partial = {}): MemoryDetail => ({ + found: true, + value: "a conflicted value", + memory_type: "semantic", + confidence: 1, + version: 1, + pinned: false, + created_at: "2026-09-18T09:00:00Z", + agent: "support-bot", + ...over, +}); +function bulkAnswers() { + vi.mocked(bulkGetMemories).mockImplementation(async (_id, keys) => ({ + results: Object.fromEntries(keys.map((k) => [k, detail()])), + missing: [], + })); +} + const ROWS = [ entry("a/pinned", { pinned: true }), entry("b/verified", { verification: "human", verified_by: "human:o@example.com", agent: "support-bot" }), @@ -47,7 +66,7 @@ vi.mock("../api", async (importOriginal) => { isAuthDisabled: () => false, }; }); -import { getMemory, listMemories, pinMemory } from "../api"; +import { bulkGetMemories, conflictKeys, getMemory, listMemories, pinMemory } from "../api"; const owner: WhoAmI = { authenticated: true, @@ -242,7 +261,7 @@ describe("Memories list chrome", () => { async (_id, limit = 50): Promise => limit === 1000 ? { - entries: Array.from({ length: 1000 }, (_, i) => entry(`p${i}`, { pinned: i < 60 })), + entries: Array.from({ length: 1000 }, (_, i) => entry(`p${i}`, i < 60 ? { verification: "human" } : {})), total: 5000, today: 0, truncated: true, @@ -251,9 +270,9 @@ describe("Memories list chrome", () => { ); render(); await screen.findByText("d/plain"); - await pick("Status", "pinned"); + await pick("Status", "verified"); await waitFor(() => expect(toolbar()).toHaveTextContent("60 matches")); - // 60 pinned among the newest rows read: not "the newest 60". + // 60 verified among the newest rows read: not "the newest 60". const pager = screen.getByRole("navigation", { name: "Memories pages" }); expect(pager).toHaveTextContent("1–50 of 60"); expect(pager).not.toHaveTextContent("newest"); @@ -265,7 +284,9 @@ describe("Memories list chrome", () => { async (_id, limit = 50): Promise => limit === 1000 ? { - entries: Array.from({ length: 100 }, (_, i) => entry(`t${i}`, { tags: ["api"], pinned: i < 60 })), + entries: Array.from({ length: 100 }, (_, i) => + entry(`t${i}`, { tags: ["api"], ...(i < 60 ? { verification: "human" as const } : {}) }), + ), total: 340, today: 0, truncated: true, @@ -276,7 +297,7 @@ describe("Memories list chrome", () => { await screen.findByText("d/plain"); await userEvent.type(screen.getByLabelText("Search memories"), "tag:api"); await waitFor(() => expect(toolbar()).toHaveTextContent("340 matches")); - await pick("Status", "pinned"); + await pick("Status", "verified"); await waitFor(() => expect(toolbar()).toHaveTextContent("60 matches")); expect(screen.getByRole("navigation", { name: "Memories pages" })).not.toHaveTextContent("newest"); }); @@ -391,6 +412,7 @@ describe("Memories list chrome", () => { }); it("filters by status: pinned, conflicted, verified", async () => { + bulkAnswers(); render(); await screen.findByText("d/plain"); // No chip row under the toolbar. @@ -529,3 +551,88 @@ describe("Memories list chrome", () => { expect(screen.getByText("request id req-f")).toBeInTheDocument(); }); }); + +describe("Memories status filters over the whole namespace", () => { + beforeEach(() => { + vi.clearAllMocks(); + localStorage.clear(); + resetNamespaceRoleCache(); + vi.mocked(listMemories).mockResolvedValue({ entries: ROWS, total: 1234, today: 2, truncated: false }); + useStore.setState({ + authed: true, + whoami: owner, + myNamespaces: [row], + identity: { org: "dev", namespace: "team", agent: "loom-ui" }, + view: "memories", + inspectedMemoryKey: null, + }); + }); + afterEach(() => { + cleanup(); + useStore.setState({ whoami: null, myNamespaces: null, identity: null }); + }); + + it("asks the server for pinned rows and counts them from its total", async () => { + vi.mocked(listMemories).mockImplementation( + async (_id, _limit, opts): Promise => + opts?.pinnedOnly + ? { + entries: Array.from({ length: 1000 }, (_, i) => entry(`pin${i}`, { pinned: true })), + total: 1500, + today: 0, + truncated: true, + } + : { entries: ROWS, total: 1234, today: 2, truncated: false }, + ); + render(); + await screen.findByText("d/plain"); + await pick("Status", "pinned"); + expect(await screen.findByText("pin0")).toBeInTheDocument(); + expect(vi.mocked(listMemories).mock.calls.at(-1)?.[2]).toMatchObject({ pinnedOnly: true }); + await waitFor(() => expect(toolbar()).toHaveTextContent("1,500 matches")); + expect( + screen.getByText("Showing the newest matches. Add a tag or a search word to narrow them."), + ).toBeInTheDocument(); + }); + + it("keeps the pinned rows among those read when the server does not know pinned_only", async () => { + vi.mocked(listMemories).mockResolvedValue({ + entries: ROWS, + total: 1234, + today: 2, + truncated: true, + ignored_args: ["pinned_only"], + }); + render(); + await screen.findByText("d/plain"); + await pick("Status", "pinned"); + await waitFor(() => expect(shown()).toEqual(["a/pinned"])); + expect(toolbar()).toHaveTextContent("1 match"); + expect(screen.getByText("Showing the pinned memories among the newest ones read.")).toBeInTheDocument(); + }); + + it("lists a conflicted key that is not among the newest rows, reading the rows in batches of 1,000", async () => { + const keys = ["z/old-conflict", ...Array.from({ length: 1499 }, (_, i) => `conflict${i}`)]; + vi.mocked(conflictKeys).mockResolvedValue(keys); + bulkAnswers(); + render(); + await screen.findByText("d/plain"); + await pick("Status", "conflicted"); + expect(await screen.findByText("z/old-conflict")).toBeInTheDocument(); + await waitFor(() => expect(toolbar()).toHaveTextContent("1,500 matches")); + expect(vi.mocked(bulkGetMemories).mock.calls.map((c) => c[1].length)).toEqual([1000, 500]); + // The list read beside them is one row, for the namespace version. + expect(vi.mocked(listMemories).mock.calls.at(-1)?.[1]).toBe(1); + expect(screen.queryByText(/conflicted keys\./)).toBeNull(); + }); + + it("says how many conflicted keys it covers when the read reaches the server's cap", async () => { + vi.mocked(conflictKeys).mockResolvedValue(Array.from({ length: 5000 }, (_, i) => `conflict${i}`)); + bulkAnswers(); + render(); + await screen.findByText("d/plain"); + await pick("Status", "conflicted"); + expect(await screen.findByText("Showing the memories of the newest 5,000 conflicted keys.")).toBeInTheDocument(); + expect(vi.mocked(bulkGetMemories)).toHaveBeenCalledTimes(5); + }); +}); diff --git a/frontend/src/views/Recent.tsx b/frontend/src/views/Recent.tsx index 6d4530d94a..18894c95c1 100644 --- a/frontend/src/views/Recent.tsx +++ b/frontend/src/views/Recent.tsx @@ -19,6 +19,7 @@ import { deleteMemory, restoreMemory, conflictKeys as fetchConflictKeys, + CONFLICT_KEYS_CAP, isAuthDisabled, type MemoryListEntry, } from "../api"; @@ -65,8 +66,8 @@ const MembersDialog = lazy(() => import("../flows/MembersDialog").then((m) => ({ // DOM, same scroll, same find-in-page once it settles. const FIRST_SCREEN_CARDS = 12; // A screen shows eight or nine -/** What the Status select shows. Every status but Live and Recently - * deleted reads the newest 1,000 and keeps the matching rows: none has a server filter. */ +/** What the Status select shows. Pinned is a server filter; Conflicted reads every + * conflicted row by key; Verified reads the newest 1,000 and keeps the matching rows. */ type Status = "live" | "pinned" | "conflicted" | "verified" | "deleted"; const STATUSES: ReadonlyArray<{ value: Status; label: string }> = [ { value: "live", label: "Live" }, @@ -199,8 +200,9 @@ function MemoryList() { // A filter covers the whole namespace, not the page on screen. A tag or agent filter is // asked of the server, which returns the rows carrying every tag, in any case (a server a // release behind matches any one tag exactly, and the list then requires every tag - // itself). Pinned, Conflicted and Verified have no server filter: the list reads the - // newest 1,000 and keeps the matching ones. What is typed is debounced, so `tag:…` sends + // itself). Pinned is asked of the server too, and Conflicted reads the conflicted rows by + // key; Verified reads the newest 1,000 and keeps the matching ones (a server a release + // behind lists Pinned the same way). What is typed is debounced, so `tag:…` sends // one read, not one per key; a chip applies at once. const typedNow = useSameFilter(filterOf(parsed)); const [typed, setTyped] = useState(typedNow); @@ -274,6 +276,7 @@ function MemoryList() { loadError, truncated, serverMatches, + statusServed, newKeys, bulkValues, refreshing, @@ -633,11 +636,15 @@ function MemoryList() { ? // What a search covers: the newest rows holding the word, when there are more. `${matches(flatList.length)}${keywordTotal > keywordKeys.size ? ` · the newest ${keywordKeys.size.toLocaleString()} of ${keywordTotal.toLocaleString()} holding "${keywordFor}"` : ""}${ranking ? " · finding related…" : ""}` : showDeleted || listFiltered - ? // A tag or agent filter is matched on the server, whose total is exact; a status - // is kept here among the rows read. + ? // A tag or agent filter, and Pinned, are matched on the server, whose total is + // exact; another status counts the rows kept here. matches( // Of the filter it read: not of a typed tag still on its way. - !showDeleted && listFilter.status === "live" && serverMatches !== null && filterRead && !filterPending + !showDeleted && + (listFilter.status === "live" || statusServed) && + serverMatches !== null && + filterRead && + !filterPending ? serverMatches : flatList.length, ) @@ -925,9 +932,11 @@ function MemoryList() { {truncated && (

- {listFilter.tags.length > 0 || listFilter.agent - ? "Showing the newest matches. Add a tag or a search word to narrow them." - : `Showing the ${filterNames.toLowerCase()} memories among the newest ones read.`} + {listFilter.status === "conflicted" && statusServed + ? `Showing the memories of the newest ${CONFLICT_KEYS_CAP.toLocaleString()} conflicted keys.` + : listFilter.tags.length > 0 || listFilter.agent || statusServed + ? "Showing the newest matches. Add a tag or a search word to narrow them." + : `Showing the ${filterNames.toLowerCase()} memories among the newest ones read.`}

)} {/* Where a page change takes the reader: a heading a screen reader announces. */} @@ -1033,9 +1042,14 @@ function MemoryList() { pageSize={pageSize} shown={(listFiltered && filterRead) || (!listFiltered && browsedCurrent) ? pageList.length : 0} total={listFiltered ? (filterRead ? listTotal : undefined) : browsedTotal} - // A tag or agent read the server cut short holds its newest matches, not every one. - // A status is kept among the rows read, which the note under the toolbar says. - capped={truncated && listFilter.status === "live" && (listFilter.tags.length > 0 || listFilter.agent !== "")} + // A tag, agent or Pinned read the server cut short holds its newest matches, not + // every one. Another status is kept among the rows read, which the note under the + // toolbar says. + capped={ + truncated && + ((listFilter.status === "live" && (listFilter.tags.length > 0 || listFilter.agent !== "")) || + (listFilter.status === "pinned" && statusServed)) + } onPage={setPage} onPageSize={(n) => { setPageSize(n); diff --git a/frontend/src/views/memoryListReads.ts b/frontend/src/views/memoryListReads.ts index 7420d5ef15..1cbe087aeb 100644 --- a/frontend/src/views/memoryListReads.ts +++ b/frontend/src/views/memoryListReads.ts @@ -1,11 +1,14 @@ import { useEffect, useRef, useState } from "react"; import { bulkGetMemories, + CONFLICT_KEYS_CAP, + conflictKeys, listMemories, searchMemory, type Identity, type MemoryDetail, type MemoryListEntry, + type MemoryListResponse, type SearchHit, } from "../api"; import { CARD_VALUE_CHARS } from "../components/MemoryCard"; @@ -84,6 +87,43 @@ function detailToEntry(key: string, d: MemoryDetail): MemoryListEntry { session_id: d.session_id, value: d.value, source_trace: d.source_trace, + verified_by: d.verified_by, + verification: d.verification, + }; +} + +// The most keys one memory.bulk_get reads (`memory_keys` in MemoryBulkGetInput). +const BULK_GET_KEYS = 1000; + +/** + * The Conflicted list: every conflicted row of the namespace, read by key. The conflicted + * keys come from one `conflicts.list` read and their rows from memory.bulk_get, a batch of + * 1,000 keys at a time, so a conflicted row older than the newest rows is listed too. + * `truncated` says the keys read reached the server's cap. + */ +export async function readConflicted( + identity: Identity, + namespaceVersion: string, + signal: AbortSignal, +): Promise { + const keys = await conflictKeys(identity, { signal }); + const entries: MemoryListEntry[] = []; + for (let i = 0; i < keys.length; i += BULK_GET_KEYS) { + const batch = keys.slice(i, i + BULK_GET_KEYS); + // agent="*" resolves each key whichever agent wrote it, as the search's reads do. + const b = await bulkGetMemories({ ...identity, agent: "*" }, batch, { signal }); + for (const k of batch) { + const d = b.results[k]; + // A profile section has its own view, as in listMemories. + if (d && d.memory_type !== "profile") entries.push(detailToEntry(k, d)); + } + } + return { + entries, + truncated: keys.length >= CONFLICT_KEYS_CAP, + total: entries.length, + today: 0, + namespace_version: namespaceVersion, }; } @@ -335,7 +375,8 @@ export function useMemorySearch( /** * The Memories list's server read: a page of the namespace, or, under a filter, its newest - * 1,000 matches in one read, refreshed every 8 s. `retry` reads the first page again. + * 1,000 matches in one read (Conflicted: every conflicted row, read by key), refreshed every + * 8 s. `retry` reads the first page again. */ export function useMemoryListRead({ identity, @@ -363,6 +404,9 @@ export function useMemoryListRead({ // the rows read: the read was cut short (a viewer token reads fewer rows than asked) and // the server matched the tags as the page does. Otherwise the rows on screen are the count. const [serverMatches, setServerMatches] = useState(null); + // The status filter was answered over the whole namespace (Pinned by the server, or the + // Conflicted rows read by key), not kept among the newest rows read. + const [statusServed, setStatusServed] = useState(false); const [newKeys, setNewKeys] = useState>(new Set()); const knownKeysRef = useRef>(new Set()); // Values the list response did not carry (a server predating the preview @@ -434,23 +478,34 @@ export function useMemoryListRead({ // A filtered list is one read of its newest 1,000 matches, with no pages. const lim = showDeleted ? 500 : filtered ? 1000 : readSize; const off = showDeleted || filtered ? 0 : readPage * readSize; - const r = await listMemories(identity, lim, { + // Conflicted reads its rows by key; the list read it starts with is one row, sent + // for the namespace version (a poll of an unchanged namespace stops there). + const conflicted = filter.status === "conflicted" && !showDeleted; + const listed = await listMemories(identity, conflicted ? 1 : lim, { include_tombstoned: showDeleted, offset: off, - tags: filter.tags, - agent: filter.agent || undefined, + tags: conflicted ? undefined : filter.tags, + agent: conflicted ? undefined : filter.agent || undefined, + pinnedOnly: filter.status === "pinned" && !showDeleted, signal, known_version: isFirst ? undefined : knownVersion || undefined, fields: MEMORIES_LIST_FIELDS, previewChars: CARD_VALUE_CHARS, }); if (!live()) return; - if (r.unchanged) return; + if (listed.unchanged) return; + const r = conflicted ? await readConflicted(identity, listed.namespace_version ?? "", signal) : listed; + if (!live()) return; knownVersion = r.namespace_version ?? ""; setTruncated(filtered && r.truncated); if (filtered) { const ignored = r.ignored_args ?? []; - setServerMatches(r.truncated && !ignored.includes("tags_every") ? r.total : null); + // A replica a release behind names `pinned_only` and lists every row: the page + // then keeps the pinned ones among the newest it read, as before. + const served = conflicted || (filter.status === "pinned" && !ignored.includes("pinned_only")); + setStatusServed(served); + const statusExact = filter.status === "live" || (served && !conflicted); + setServerMatches(r.truncated && statusExact && !ignored.includes("tags_every") ? r.total : null); } // The namespace's total follows every browsed answer, the 8 s refresh included. if (!filtered && !showDeleted) setBrowsedTotal(r.total); @@ -528,6 +583,7 @@ export function useMemoryListRead({ loadError, truncated, serverMatches, + statusServed, newKeys, bulkValues, refreshing, diff --git a/sdk/python/loom/ops.py b/sdk/python/loom/ops.py index 036811d7d9..f912271ae4 100644 --- a/sdk/python/loom/ops.py +++ b/sdk/python/loom/ops.py @@ -14605,6 +14605,7 @@ class MemoryListInput(TypedDict, total=False): tags: NotRequired[list[str]] tags_every: NotRequired[bool] contains: NotRequired[Optional[str]] + pinned_only: NotRequired[bool] fields: NotRequired[list[str]] known_version: NotRequired[Union[int, str, None]] @@ -14635,6 +14636,7 @@ class MemoryListBody(TypedDict, total=False): tags: NotRequired[list[str]] tags_every: NotRequired[bool] contains: NotRequired[Optional[str]] + pinned_only: NotRequired[bool] fields: NotRequired[list[str]] known_version: NotRequired[Union[int, str, None]] diff --git a/sdk/typescript/src/generated/ops.ts b/sdk/typescript/src/generated/ops.ts index c88b34f554..e3980a4eb6 100644 --- a/sdk/typescript/src/generated/ops.ts +++ b/sdk/typescript/src/generated/ops.ts @@ -6313,6 +6313,7 @@ export interface MemoryListInput { tags?: string[]; tags_every?: boolean; contains?: string | null; + pinned_only?: boolean; fields?: string[]; known_version?: number | string | null; } diff --git a/server/memory/api/models_crud.py b/server/memory/api/models_crud.py index 9a8c99b292..7e38cbc4a9 100644 --- a/server/memory/api/models_crud.py +++ b/server/memory/api/models_crud.py @@ -824,6 +824,10 @@ class MemoryListInput(_Identity): # A scan of the namespace's values; None or '' = no filter. Hidden from # the MCP listing: agents search with memory.search. contains: str | None = Field(default=None, max_length=200, json_schema_extra=MCP_HIDDEN) + # Only pinned rows. The dashboard's Pinned status reads with it so a pinned row older + # than the rows one read returns is still listed. Hidden from the MCP listing: + # agents get pinned rows from the session context. + pinned_only: bool = Field(default=False, json_schema_extra=MCP_HIDDEN) # Whitelist of entry field names; every entry carries only # those plus `memory_key` and `sensitivity`. Empty = every field. See # MemoryGetInput.fields. diff --git a/server/memory/app/query.py b/server/memory/app/query.py index 648b49e1e2..5491aa7ffc 100644 --- a/server/memory/app/query.py +++ b/server/memory/app/query.py @@ -212,6 +212,7 @@ async def _hidden_under_prefix( # The same tag match as `total`, so only the status filter makes the difference. tag_filter=tag_filter, contains=input.contains or None, + pinned_only=input.pinned_only, include_tombstoned=input.include_tombstoned, as_of=input.as_of, include_duplicates=True, @@ -293,6 +294,7 @@ async def _handle_memory_list(input: MemoryListInput) -> MemoryListOutput: source_trace=input.source_trace or None, tag_filter=tag_filter, contains=input.contains or None, + pinned_only=input.pinned_only, order_by="created_at_desc", limit=input.limit + 1, offset=input.offset, @@ -324,6 +326,7 @@ async def _handle_memory_list(input: MemoryListInput) -> MemoryListOutput: input.source_trace or "", tag_filter, input.contains or "", + bool(input.pinned_only), bool(input.include_tombstoned), str(input.as_of or ""), tuple(sorted(_served.items())), @@ -341,6 +344,7 @@ async def _handle_memory_list(input: MemoryListInput) -> MemoryListOutput: source_trace=input.source_trace or None, tag_filter=tag_filter, contains=input.contains or None, + pinned_only=input.pinned_only, include_tombstoned=input.include_tombstoned, as_of=input.as_of, **_served, @@ -355,6 +359,7 @@ async def _handle_memory_list(input: MemoryListInput) -> MemoryListOutput: source_trace=input.source_trace or None, tag_filter=tag_filter, contains=input.contains or None, + pinned_only=input.pinned_only, include_tombstoned=input.include_tombstoned, created_since=_today_start, **_served, @@ -487,6 +492,8 @@ async def _list_by_score( if input.contains: where.append(memory_repo.CONTAINS_PREDICATE) params["contains"] = input.contains + if input.pinned_only: + where.append("pinned = 1") if input.as_of is not None: where.append( "(valid_at IS NOT NULL AND valid_at <= {as_of:DateTime} " @@ -515,19 +522,7 @@ async def _list_by_score( """ rows_dict = await get_client().query_all(sql, params=params) if input.quotas: - per_type_counts: dict[str, int] = {} - kept: list[dict[str, Any]] = [] - for r in rows_dict: - t = r.get("memory_type", "") - cap = int(input.quotas.get(t, 0)) - used = per_type_counts.get(t, 0) - if cap > 0 and used >= cap: - continue - kept.append(r) - per_type_counts[t] = used + 1 - if len(kept) >= input.limit + 1: - break - rows_dict = kept + rows_dict = _within_quotas(rows_dict, input.quotas, input.limit + 1) truncated = len(rows_dict) > input.limit rows_dict = await memory_repo.served_rows( [{**r, "org": input.org, "namespace": input.namespace} for r in rows_dict[: input.limit]] @@ -545,6 +540,26 @@ async def _list_by_score( ) +def _within_quotas( + rows: list[dict[str, Any]], quotas: dict[str, int], keep: int +) -> list[dict[str, Any]]: + """The rows in order, at most `quotas[type]` of each memory type (a type not named, or + at 0, is uncapped), stopping at `keep` rows.""" + per_type_counts: dict[str, int] = {} + kept: list[dict[str, Any]] = [] + for r in rows: + t = r.get("memory_type", "") + cap = int(quotas.get(t, 0)) + used = per_type_counts.get(t, 0) + if cap > 0 and used >= cap: + continue + kept.append(r) + per_type_counts[t] = used + 1 + if len(kept) >= keep: + break + return kept + + def _score_entry(r: dict[str, Any]) -> _MemoryListEntry: """One score-ordered list row. A 'high' row's value, hash and entities are readable by key only, through an audited read.""" diff --git a/tests/integration/test_memory_delete_list.py b/tests/integration/test_memory_delete_list.py index efb39c2fa6..0228235fdb 100644 --- a/tests/integration/test_memory_delete_list.py +++ b/tests/integration/test_memory_delete_list.py @@ -159,3 +159,31 @@ def keys(page: dict) -> set[str]: every = await agent.memory.list(tags=["API", "docs"], tags_every=True) assert keys(every) == {"both"} assert every["total"] == 1 + + +@pytest.mark.asyncio +async def test_list_pinned_only_reaches_past_the_rows_read(agent) -> None: + """`pinned_only` finds a pinned row older than every row a short read returns, and + lists and counts only pinned rows, on the recency and the score paths.""" + # Written first, under a key that sorts after the others: the list orders by created_at + # in whole seconds, then by key, so the row is outside the newest three either way. + await agent.memory.pin( + "zz_ground_rule", "Every release is tagged from the main branch.", memory_type="semantic" + ) + for i in range(5): + await agent.memory.set(f"later{i:02d}", i, memory_type="semantic") + + async def page(**extra: object) -> dict: + body = {**agent.memory._identity(None, None), "limit": 3, **extra} + return await agent.transport.post("/v1/memory.list", body) + + newest = await page() + assert "zz_ground_rule" not in {e["memory_key"] for e in newest["entries"]} + + pinned = await page(pinned_only=True) + assert [e["memory_key"] for e in pinned["entries"]] == ["zz_ground_rule"] + assert pinned["entries"][0]["pinned"] is True + assert pinned["total"] == 1 and pinned["truncated"] is False + + scored = await page(pinned_only=True, sort_by="score") + assert [e["memory_key"] for e in scored["entries"]] == ["zz_ground_rule"]