@hasna/mementos 0.14.84 → 0.14.85

package/dist/cli/index.js

@@ -1011,7 +1011,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
         this._exitCallback = (err) => {
           if (err.code !== "commander.executeSubCommandAsync") {
             throw err;
-          } else {}
+          }
         };
       }
       return this;
@@ -3171,7 +3171,16 @@ x-api-key: ${cfg.apiKey}
 function apiJson(method, path, body, options) {
   const raw = apiRequestRaw(method, path, body);
   if (raw.status >= 200 && raw.status < 300) {
-    const data = raw.body.trim() ? JSON.parse(raw.body) : undefined;
+    let data;
+    if (raw.body.trim()) {
+      try {
+        data = JSON.parse(raw.body);
+      } catch (e) {
+        throw new ApiRequestError(`mementos cloud ${method} ${path} returned status ${raw.status} with a body that is not valid JSON (${e instanceof Error ? e.message : String(e)}) \u2014 the response is truncated or the server is unhealthy`, raw.status, raw.body.slice(0, 500));
+      }
+    } else {
+      data = undefined;
+    }
     return { status: raw.status, data };
   }
   if (raw.status === 404 && options?.allow404) {
@@ -5259,7 +5268,10 @@ __export(exports_memories, {
   touchMemory: () => touchMemory,
   semanticSearch: () => semanticSearch,
   parseMemoryRow: () => parseMemoryRow,
+  listMemoryHistoryPage: () => listMemoryHistoryPage,
   listMemoryHistory: () => listMemoryHistory,
+  listMemoriesPage: () => listMemoriesPage,
+  listMemoriesBounded: () => listMemoriesBounded,
   listMemories: () => listMemories,
   listLowTrustMemories: () => listLowTrustMemories,
   indexMemoryEmbedding: () => indexMemoryEmbedding,
@@ -5273,6 +5285,8 @@ __export(exports_memories, {
   getMemoriesByKey: () => getMemoriesByKey,
   deleteMemory: () => deleteMemory,
   createMemory: () => createMemory,
+  countMemoryHistory: () => countMemoryHistory,
+  countMemories: () => countMemories,
   cleanExpiredMemories: () => cleanExpiredMemories,
   bulkUpsertMemories: () => bulkUpsertMemories,
   bulkDeleteMemories: () => bulkDeleteMemories
@@ -5639,29 +5653,7 @@ function getMemoriesByKey(key, scope, agentId, projectId, db) {
   const rows = d.query(sql).all(...params);
   return rows.map(parseMemoryRow);
 }
-function listMemories(filter, db) {
-  if (!db && isApiMode()) {
-    const f = filter || {};
-    const q = toQuery({
-      key: f.key,
-      scope: f.scope,
-      category: f.category,
-      status: f.status,
-      tags: f.tags,
-      min_importance: f.min_importance,
-      pinned: f.pinned,
-      agent_id: f.agent_id,
-      project_id: f.project_id,
-      session_id: f.session_id,
-      namespace: f.namespace,
-      as_of: f.as_of,
-      limit: f.limit,
-      offset: f.offset
-    });
-    const { data } = apiJson("GET", `/memories${q}`);
-    return data?.memories ?? [];
-  }
-  const d = db || getDatabase();
+function buildMemoryListConditions(filter) {
   const conditions = [];
   const params = [];
   if (filter) {
@@ -5773,21 +5765,109 @@ function listMemories(filter, db) {
   } else {
     conditions.push("status = 'active'");
   }
+  return { conditions, params };
+}
+function listMemoriesPage(filter, db) {
+  const f = filter || {};
+  if (!db && isApiMode()) {
+    const q = toQuery({
+      key: f.key,
+      scope: f.scope,
+      category: f.category,
+      status: f.status,
+      tags: f.tags,
+      min_importance: f.min_importance,
+      pinned: f.pinned,
+      agent_id: f.agent_id,
+      project_id: f.project_id,
+      session_id: f.session_id,
+      namespace: f.namespace,
+      as_of: f.as_of,
+      limit: f.limit,
+      offset: f.offset
+    });
+    const { data } = apiJson("GET", `/memories${q}`);
+    return {
+      rows: data?.memories ?? [],
+      has_more: data?.has_more,
+      next_cursor: data?.next_cursor ?? null
+    };
+  }
+  const d = db || getDatabase();
+  const { conditions, params } = buildMemoryListConditions(f);
   let sql = "SELECT * FROM memories";
   if (conditions.length > 0) {
     sql += ` WHERE ${conditions.join(" AND ")}`;
   }
   sql += " ORDER BY importance DESC, created_at DESC";
-  if (filter?.limit) {
+  if (f.limit) {
     sql += " LIMIT ?";
-    params.push(filter.limit);
+    params.push(f.limit);
   }
-  if (filter?.offset) {
+  if (f.offset) {
     sql += " OFFSET ?";
-    params.push(filter.offset);
+    params.push(f.offset);
   }
   const rows = d.query(sql).all(...params);
-  return rows.map(parseMemoryRow);
+  const parsed = rows.map(parseMemoryRow);
+  const hasMore = f.limit !== undefined && parsed.length === f.limit;
+  return {
+    rows: parsed,
+    has_more: hasMore,
+    next_cursor: hasMore ? (f.offset ?? 0) + parsed.length : null
+  };
+}
+function listMemories(filter, db) {
+  return listMemoriesPage(filter, db).rows;
+}
+function listMemoriesBounded(filter = {}, target, db) {
+  const pageSize = 1000;
+  const maxPages = 1000;
+  const want = target === undefined ? undefined : target + 1;
+  const rows = [];
+  const seenCursors = new Set;
+  let cursor = filter.offset ?? 0;
+  let pages = 0;
+  for (;; ) {
+    if (want !== undefined && rows.length >= want)
+      break;
+    if (++pages > maxPages) {
+      throw new Error(`memories list traversal exceeded ${maxPages} pages while collecting rows \u2014 aborting (cursor cycle?)`);
+    }
+    const limit = Math.min(want === undefined ? pageSize : want - rows.length, pageSize);
+    const page = listMemoriesPage({ ...filter, limit, offset: cursor }, db);
+    rows.push(...page.rows);
+    if (page.has_more === false)
+      break;
+    if (page.has_more === undefined && page.rows.length < limit)
+      break;
+    if (page.has_more === true && (page.next_cursor === null || page.next_cursor === undefined)) {
+      throw new Error("memories list page claimed more results without a next cursor \u2014 aborting");
+    }
+    const next = page.next_cursor ?? cursor + page.rows.length;
+    if (seenCursors.has(next)) {
+      throw new Error("memories list traversal repeated a cursor \u2014 aborting");
+    }
+    seenCursors.add(next);
+    cursor = next;
+  }
+  const hasMore = target !== undefined && rows.length > target;
+  const trimmed = hasMore ? rows.slice(0, target) : rows;
+  return {
+    rows: trimmed,
+    has_more: hasMore,
+    next_cursor: hasMore ? (filter.offset ?? 0) + trimmed.length : null
+  };
+}
+function countMemories(filter, db) {
+  const d = db || getDatabase();
+  const { conditions, params } = buildMemoryListConditions(filter);
+  let sql = "SELECT COUNT(*) AS c FROM memories";
+  if (conditions.length > 0) {
+    sql += ` WHERE ${conditions.join(" AND ")}`;
+  }
+  const row = d.query(sql).get(...params);
+  return row?.c ?? 0;
 }
 function getMemoryBriefing(opts, db) {
   const limit = opts.limit ?? 20;
@@ -5849,13 +5929,17 @@ function listLowTrustMemories(opts = {}, db) {
   const rows = d.prepare(`SELECT * FROM memories WHERE ${conditions.join(" AND ")} ORDER BY trust_score ASC LIMIT ? OFFSET ?`).all(...params);
   return rows.map(parseMemoryRow);
 }
-function listMemoryHistory(opts = {}, db) {
+function listMemoryHistoryPage(opts = {}, db) {
   const limit = opts.limit ?? 20;
   const offset = opts.offset ?? 0;
   if (!db && isApiMode()) {
     const q = toQuery({ limit, offset });
     const { data } = apiJson("GET", `/memories/history${q}`);
-    return data?.memories ?? [];
+    return {
+      rows: data?.memories ?? [],
+      has_more: data?.has_more,
+      next_cursor: data?.next_cursor ?? null
+    };
   }
   const d = db || getDatabase();
   const params = [limit];
@@ -5865,7 +5949,21 @@ function listMemoryHistory(opts = {}, db) {
     params.push(offset);
   }
   const rows = d.query(sql).all(...params);
-  return rows.map(parseMemoryRow);
+  const parsed = rows.map(parseMemoryRow);
+  const hasMore = parsed.length === limit;
+  return {
+    rows: parsed,
+    has_more: hasMore,
+    next_cursor: hasMore ? offset + parsed.length : null
+  };
+}
+function listMemoryHistory(opts = {}, db) {
+  return listMemoryHistoryPage(opts, db).rows;
+}
+function countMemoryHistory(db) {
+  const d = db || getDatabase();
+  const row = d.query("SELECT COUNT(*) AS c FROM memories WHERE status = 'active' AND accessed_at IS NOT NULL").get();
+  return row?.c ?? 0;
 }
 function getMemoryChain(sequenceGroup, projectId, db) {
   if (!db && isApiMode()) {
@@ -6391,6 +6489,92 @@ var init_types2 = __esm(() => {
   ];
 });
 
+// src/project-registration/historical-receipt.ts
+function supportsFleetResourcesHistoricalReceiptLookup(capability) {
+  return capability.authority_id === FLEET_RESOURCES_CURRENT_PROJECT_REGISTRATION_IDENTITY.authority_id && capability.tenant_id === FLEET_RESOURCES_CURRENT_PROJECT_REGISTRATION_IDENTITY.tenant_id && capability.corpus_id === FLEET_RESOURCES_CURRENT_PROJECT_REGISTRATION_IDENTITY.corpus_id;
+}
+var ROOT_TENANT_ID = "adfd95c7-ee8b-52cb-ae47-4ae65dae3313", FLEET_RESOURCES_HISTORICAL_PROJECT_REGISTRATION, FLEET_RESOURCES_HISTORICAL_RECEIPT, FLEET_RESOURCES_CURRENT_PROJECT_REGISTRATION_IDENTITY, FLEET_RESOURCES_HISTORICAL_LOOKUP_IDENTITY;
+var init_historical_receipt = __esm(() => {
+  FLEET_RESOURCES_HISTORICAL_PROJECT_REGISTRATION = {
+    authority: "mementos",
+    authority_route: "mementos.project-registration.v1",
+    package_version: "1.0.0-rc.3",
+    authority_id: "mementos",
+    tenant_id: "default",
+    corpus_id: "default",
+    operation_id: "op-cli-register-full",
+    step_id: "mementos_project",
+    resource_kind: "project",
+    direction: "forward",
+    target_selector: "wks_005285827590a93b70e5",
+    target_id: "mm_project_f75606ef14e51fb577a15882ba0ab8ed333b2c29",
+    idempotency_key: "prk_786cdc6babddeae1be8d5078d0f75322d1ea1010ac5d8a50",
+    receipt_id: "mmpr_a647f9908a33bb64bf137f584202590f91b72a33",
+    request_digest: "8eb0e3fee26fdb7edb8a444aeddaaedb79a84a5a36e742ae03616f62b19f5c22",
+    precondition_digest: "0b6c22fcf75d835f9f27308b1a9d40e8902e48a97da370fd56df5acacfcd968e",
+    result_revision: "2026-08-09T13:37:43.068Z",
+    result_digest: "26fb0dd5c5e20909d3653ab0ddd8fa45e5142728e4e66d595e2419f7ed40b036",
+    created_at: "2026-08-09T13:37:43.068Z",
+    identity_digest: "1108dd972c90e4989036fb6ecec7dde10f54641a697bd53cfcd64017f589ace7",
+    target_digest: "72789fcd60668eeb66ee068936d3afa96deadcb007228830c64b6de783b6dcef",
+    operation_digest: "d7e37bfb2c0d28f8c4086c53224cd855d14694f32807b74c102b61a99963f3c0",
+    idempotency_digest: "b56d8ec37efb818759cdd2ee3b58bc1401ac13384c8d64c1813bb5c198b1e376",
+    receipt_digest: "52ce90c5de6817989f107d9d27e06156962a2b9c365e34e16a57aa37886501a2",
+    response_digest: "2fa3ed508f5f192c18753b1205ced996340fdf02f735420d32db897fc239805c"
+  };
+  FLEET_RESOURCES_HISTORICAL_RECEIPT = {
+    receipt_id: FLEET_RESOURCES_HISTORICAL_PROJECT_REGISTRATION.receipt_id,
+    authority: FLEET_RESOURCES_HISTORICAL_PROJECT_REGISTRATION.authority,
+    route: FLEET_RESOURCES_HISTORICAL_PROJECT_REGISTRATION.authority_route,
+    package_version: FLEET_RESOURCES_HISTORICAL_PROJECT_REGISTRATION.package_version,
+    authority_id: FLEET_RESOURCES_HISTORICAL_PROJECT_REGISTRATION.authority_id,
+    tenant_id: FLEET_RESOURCES_HISTORICAL_PROJECT_REGISTRATION.tenant_id,
+    corpus_id: FLEET_RESOURCES_HISTORICAL_PROJECT_REGISTRATION.corpus_id,
+    operation_id: FLEET_RESOURCES_HISTORICAL_PROJECT_REGISTRATION.operation_id,
+    step_id: FLEET_RESOURCES_HISTORICAL_PROJECT_REGISTRATION.step_id,
+    resource_kind: FLEET_RESOURCES_HISTORICAL_PROJECT_REGISTRATION.resource_kind,
+    direction: FLEET_RESOURCES_HISTORICAL_PROJECT_REGISTRATION.direction,
+    idempotency_key: FLEET_RESOURCES_HISTORICAL_PROJECT_REGISTRATION.idempotency_key,
+    request_digest: FLEET_RESOURCES_HISTORICAL_PROJECT_REGISTRATION.request_digest,
+    precondition_digest: FLEET_RESOURCES_HISTORICAL_PROJECT_REGISTRATION.precondition_digest,
+    outcome: "accepted",
+    reason: null,
+    target_id: FLEET_RESOURCES_HISTORICAL_PROJECT_REGISTRATION.target_id,
+    result_revision: FLEET_RESOURCES_HISTORICAL_PROJECT_REGISTRATION.result_revision,
+    result_digest: FLEET_RESOURCES_HISTORICAL_PROJECT_REGISTRATION.result_digest,
+    duplicate_of_receipt_id: null,
+    accepted_receipt_id: null,
+    created_by_operation: true,
+    created_at: FLEET_RESOURCES_HISTORICAL_PROJECT_REGISTRATION.created_at
+  };
+  FLEET_RESOURCES_CURRENT_PROJECT_REGISTRATION_IDENTITY = {
+    authority_id: "mementos",
+    tenant_id: ROOT_TENANT_ID,
+    corpus_id: "mementos:postgresql"
+  };
+  FLEET_RESOURCES_HISTORICAL_LOOKUP_IDENTITY = {
+    source: {
+      authority: FLEET_RESOURCES_HISTORICAL_PROJECT_REGISTRATION.authority,
+      authority_route: FLEET_RESOURCES_HISTORICAL_PROJECT_REGISTRATION.authority_route,
+      package_version: FLEET_RESOURCES_HISTORICAL_PROJECT_REGISTRATION.package_version,
+      authority_id: FLEET_RESOURCES_HISTORICAL_PROJECT_REGISTRATION.authority_id,
+      tenant_id: FLEET_RESOURCES_HISTORICAL_PROJECT_REGISTRATION.tenant_id,
+      corpus_id: FLEET_RESOURCES_HISTORICAL_PROJECT_REGISTRATION.corpus_id,
+      operation_id: FLEET_RESOURCES_HISTORICAL_PROJECT_REGISTRATION.operation_id,
+      step_id: FLEET_RESOURCES_HISTORICAL_PROJECT_REGISTRATION.step_id,
+      resource_kind: FLEET_RESOURCES_HISTORICAL_PROJECT_REGISTRATION.resource_kind,
+      direction: FLEET_RESOURCES_HISTORICAL_PROJECT_REGISTRATION.direction,
+      target_selector: FLEET_RESOURCES_HISTORICAL_PROJECT_REGISTRATION.target_selector,
+      target_id: FLEET_RESOURCES_HISTORICAL_PROJECT_REGISTRATION.target_id,
+      idempotency_key: FLEET_RESOURCES_HISTORICAL_PROJECT_REGISTRATION.idempotency_key,
+      receipt_id: FLEET_RESOURCES_HISTORICAL_PROJECT_REGISTRATION.receipt_id
+    },
+    destination: FLEET_RESOURCES_CURRENT_PROJECT_REGISTRATION_IDENTITY,
+    lookup_only: true,
+    immutable_receipt: true
+  };
+});
+
 // src/project-registration/identity.ts
 function configuredValue(override, envKey) {
   return override?.trim() || process.env[envKey]?.trim() || null;
@@ -6417,12 +6601,13 @@ function resolveMementosProjectAuthorityIdentity(options = {}) {
 }
 function buildMementosProjectRegistrationCapability(options = {}) {
   const identity = resolveMementosProjectAuthorityIdentity(options);
-  return {
+  const capability = {
     authority: "mementos",
     route: MEMENTOS_PROJECT_REGISTRATION_ROUTE,
     package_version: options.packageVersion ?? getMementosPackageVersion(),
     ...identity,
     supported_resources: ["project"],
+    supported_historical_lookup_identities: [],
     conditional_create: true,
     immutable_receipts: true,
     exact_terminal_lookup: true,
@@ -6441,11 +6626,18 @@ function buildMementosProjectRegistrationCapability(options = {}) {
     stable_keyset_pagination: true,
     explicit_membership_only: true
   };
+  if (supportsFleetResourcesHistoricalReceiptLookup(capability)) {
+    capability.supported_historical_lookup_identities = [
+      FLEET_RESOURCES_HISTORICAL_LOOKUP_IDENTITY
+    ];
+  }
+  return capability;
 }
 var MEMENTOS_PROJECT_AUTHORITY_ENV, MementosProjectAuthorityIdentityError;
 var init_identity = __esm(() => {
   init_package_version();
   init_types2();
+  init_historical_receipt();
   MEMENTOS_PROJECT_AUTHORITY_ENV = {
     authorityId: "MEMENTOS_PROJECT_AUTHORITY_ID",
     tenantId: "MEMENTOS_PROJECT_TENANT_ID",
@@ -7272,6 +7464,7 @@ __export(exports_helpers, {
   colorImportance: () => colorImportance,
   colorEntityType: () => colorEntityType,
   colorCategory: () => colorCategory,
+  collectPagedRows: () => collectPagedRows,
   VALID_SCOPES: () => VALID_SCOPES,
   VALID_CATEGORIES: () => VALID_CATEGORIES,
   DEFAULT_SNIPPET_LENGTH: () => DEFAULT_SNIPPET_LENGTH,
@@ -7358,6 +7551,39 @@ function truncateText(value, max = DEFAULT_SNIPPET_LENGTH) {
     return normalized.slice(0, max);
   return `${normalized.slice(0, max - 3)}...`;
 }
+function collectPagedRows(fetchPage, target, offset, opts = {}) {
+  const pageSize = opts.pageSize ?? 1000;
+  const maxPages = opts.maxPages ?? 1000;
+  const want = target === undefined ? undefined : target + 1;
+  const rows = [];
+  const seenCursors = new Set;
+  let cursor = offset;
+  let pages = 0;
+  for (;; ) {
+    if (want !== undefined && rows.length >= want)
+      break;
+    if (++pages > maxPages) {
+      throw new Error(`pagination exceeded ${maxPages} pages while collecting rows \u2014 aborting (cursor cycle?)`);
+    }
+    const limit = Math.min(want === undefined ? pageSize : want - rows.length, pageSize);
+    const page = fetchPage(cursor, limit);
+    rows.push(...page.rows);
+    if (page.has_more === false)
+      break;
+    if (page.has_more === undefined && page.rows.length < limit)
+      break;
+    if (page.has_more === true && (page.next_cursor === null || page.next_cursor === undefined)) {
+      throw new Error("pagination claimed more results without a next cursor \u2014 aborting");
+    }
+    const next = page.next_cursor ?? cursor + page.rows.length;
+    if (seenCursors.has(next)) {
+      throw new Error("pagination repeated a cursor \u2014 aborting");
+    }
+    seenCursors.add(next);
+    cursor = next;
+  }
+  return { rows, hasMore: target !== undefined && rows.length > target };
+}
 function printPageHint(opts) {
   const hints = [];
   const offset = opts.offset ?? 0;
@@ -27040,7 +27266,7 @@ class JSONSchemaGenerator {
               if (val === undefined) {
                 if (this.unrepresentable === "throw") {
                   throw new Error("Literal `undefined` cannot be represented in JSON Schema");
-                } else {}
+                }
               } else if (typeof val === "bigint") {
                 if (this.unrepresentable === "throw") {
                   throw new Error("BigInt literals cannot be represented in JSON Schema");
@@ -48690,7 +48916,7 @@ var require_tracestate_impl = __commonJS((exports) => {
           const value = listMember.slice(i + 1, part.length);
           if ((0, tracestate_validators_1.validateKey)(key) && (0, tracestate_validators_1.validateValue)(value)) {
             agg.set(key, value);
-          } else {}
+          }
         }
         return agg;
       }, new Map);
@@ -63487,6 +63713,7 @@ import { createHash as createHash3 } from "crypto";
 init_projects();
 init_types2();
 init_identity();
+init_historical_receipt();
 function canonicalMementosProjectRegistrationJson(value) {
   return JSON.stringify(canonicalize2(value));
 }
@@ -64878,15 +65105,17 @@ function registerListCommand(program2) {
       const fmt = getOutputFormat(program2, opts.format);
       const isStructured = fmt === "json" || fmt === "csv" || fmt === "yaml";
       const requestedLimit = opts.limit;
-      const limit = positiveIntOrDefault(requestedLimit, isStructured ? 50 : DEFAULT_COMPACT_LIMIT);
-      const offset = cursorOrOffset(opts.cursor, opts.offset);
+      const limit = requestedLimit === undefined ? isStructured ? undefined : DEFAULT_COMPACT_LIMIT : positiveIntOrDefault(requestedLimit, isStructured ? 50 : DEFAULT_COMPACT_LIMIT);
+      const offset = cursorOrOffset(opts.cursor, opts.offset) ?? 0;
       const agentId = resolveAgentFilter(opts.agent || globalOpts.agent);
       const projectPath = opts.project || globalOpts.project;
       let projectId;
       if (projectPath) {
         const project = getProject(resolve7(projectPath));
-        if (project)
-          projectId = project.id;
+        if (!project) {
+          throw new Error(`Project not found: ${projectPath}`);
+        }
+        projectId = project.id;
       }
       const filter = {
         scope: opts.scope,
@@ -64896,16 +65125,24 @@ function registerListCommand(program2) {
         pinned: opts.pinned ? true : undefined,
         agent_id: agentId,
         project_id: projectId,
-        limit: isStructured ? limit : limit + 1,
-        offset,
         status: opts.status,
         session_id: opts.session || globalOpts.session
       };
-      const fetched = listMemories(filter);
-      const hasMore = !isStructured && fetched.length > limit;
-      const memories = hasMore ? fetched.slice(0, limit) : fetched;
+      const { rows: collected, hasMore } = collectPagedRows((cursor, pageLimit) => {
+        const page = listMemoriesPage({
+          ...filter,
+          limit: pageLimit,
+          offset: cursor
+        });
+        return {
+          rows: page.rows,
+          has_more: page.has_more,
+          next_cursor: page.next_cursor
+        };
+      }, limit, offset);
+      const memories = hasMore && limit !== undefined ? collected.slice(0, limit) : collected;
       if (fmt === "json") {
-        outputJson(fetched);
+        outputJson(memories);
         return;
       }
       if (fmt === "csv") {
@@ -64933,7 +65170,7 @@ function registerListCommand(program2) {
       }
       printPageHint({
         shown: memories.length,
-        limit,
+        limit: limit ?? memories.length,
         offset,
         hasMore,
         command: "mementos list",
@@ -65068,14 +65305,20 @@ function getMemoryReport(filter = {}, db) {
     top_agents: topAgents
   };
 }
-function getStaleMemories(filter = {}, db) {
+function getStaleMemoriesPage(filter = {}, db) {
   const days = Math.min(filter.days || 30, 365);
   const limit = filter.limit ?? 20;
   const offset = filter.offset ?? 0;
   if (!db && isApiMode()) {
     const q = toQuery({ days, project_id: filter.project_id, agent_id: filter.agent_id, limit, offset });
     const { data } = apiJson("GET", `/memories/stale${q}`);
-    return data?.memories ?? [];
+    const rows2 = data?.memories ?? [];
+    return {
+      rows: rows2,
+      total: data?.total ?? rows2.length,
+      has_more: data?.has_more,
+      next_cursor: data?.next_cursor ?? null
+    };
   }
   const d = db || getDatabase();
   const cutoffDate = new Date(Date.now() - days * 86400000).toISOString();
@@ -65089,13 +65332,22 @@ function getStaleMemories(filter = {}, db) {
     conds.push("agent_id = ?");
     params.push(filter.agent_id);
   }
-  let sql = `SELECT id, key, value, importance, scope, category, accessed_at, access_count, created_at FROM memories WHERE ${conds.join(" AND ")} ORDER BY COALESCE(accessed_at, created_at) ASC LIMIT ?`;
+  const where = conds.join(" AND ");
+  const countRow = d.query(`SELECT COUNT(*) AS c FROM memories WHERE ${where}`).get(...params);
+  let sql = `SELECT id, key, value, importance, scope, category, accessed_at, access_count, created_at FROM memories WHERE ${where} ORDER BY COALESCE(accessed_at, created_at) ASC LIMIT ?`;
   params.push(limit);
   if (offset) {
     sql += " OFFSET ?";
     params.push(offset);
   }
-  return d.query(sql).all(...params);
+  const rows = d.query(sql).all(...params);
+  const hasMore = rows.length === limit;
+  return {
+    rows,
+    total: countRow?.c ?? 0,
+    has_more: hasMore,
+    next_cursor: hasMore ? offset + rows.length : null
+  };
 }
 
 // src/cli/commands/info-stats.ts
@@ -65255,7 +65507,7 @@ function registerStaleCommand(program2) {
       const fmt = getOutputFormat(program2, opts.format);
       const isJson = fmt === "json";
       const limit = positiveIntOrDefault(opts.limit, isJson ? 20 : DEFAULT_COMPACT_LIMIT);
-      const offset = cursorOrOffset(opts.cursor, opts.offset);
+      const offset = cursorOrOffset(opts.cursor, opts.offset) ?? 0;
       const projectPath = opts.project || globalOpts.project;
       let projectId;
       if (projectPath) {
@@ -65264,17 +65516,36 @@ function registerStaleCommand(program2) {
           projectId = project.id;
       }
       const agentId = resolveAgentFilter(opts.agent || globalOpts.agent);
-      const rows = getStaleMemories({
-        days,
-        project_id: projectId,
-        agent_id: agentId,
-        limit: isJson ? limit : limit + 1,
-        offset
-      });
-      const hasMore = !isJson && rows.length > limit;
-      const displayRows = hasMore ? rows.slice(0, limit) : rows;
+      let staleTotal = 0;
+      let firstPage = true;
+      const { rows: collected, hasMore } = collectPagedRows((cursor, pageLimit) => {
+        const page = getStaleMemoriesPage({
+          days,
+          project_id: projectId,
+          agent_id: agentId,
+          limit: pageLimit,
+          offset: cursor
+        });
+        if (firstPage) {
+          staleTotal = page.total;
+          firstPage = false;
+        }
+        return {
+          rows: page.rows,
+          has_more: page.has_more,
+          next_cursor: page.next_cursor
+        };
+      }, limit, offset);
+      const displayRows = hasMore ? collected.slice(0, limit) : collected;
       if (fmt === "json") {
-        outputJson({ stale_count: rows.length, threshold_days: days, memories: rows });
+        outputJson({
+          stale_count: staleTotal,
+          returned: displayRows.length,
+          threshold_days: days,
+          has_more: hasMore,
+          next_cursor: hasMore ? offset + displayRows.length : null,
+          memories: displayRows
+        });
         return;
       }
       if (displayRows.length === 0) {
@@ -65313,13 +65584,20 @@ function registerHistoryCommand(program2) {
     try {
       const globalOpts = program2.opts();
       const isJson = Boolean(globalOpts.json);
-      const limit = positiveIntOrDefault(opts.limit, isJson ? 20 : DEFAULT_SEARCH_LIMIT);
-      const offset = cursorOrOffset(opts.cursor, opts.offset);
-      const fetched = listMemoryHistory({ limit: isJson ? limit : limit + 1, offset });
-      const hasMore = !isJson && fetched.length > limit;
-      const memories = hasMore ? fetched.slice(0, limit) : fetched;
+      const requestedLimit = opts.limit;
+      const limit = requestedLimit === undefined ? isJson ? undefined : DEFAULT_SEARCH_LIMIT : positiveIntOrDefault(requestedLimit, isJson ? 20 : DEFAULT_SEARCH_LIMIT);
+      const offset = cursorOrOffset(opts.cursor, opts.offset) ?? 0;
+      const { rows: collected, hasMore } = collectPagedRows((cursor, pageLimit) => {
+        const page = listMemoryHistoryPage({ limit: pageLimit, offset: cursor });
+        return {
+          rows: page.rows,
+          has_more: page.has_more,
+          next_cursor: page.next_cursor
+        };
+      }, limit, offset);
+      const memories = hasMore && limit !== undefined ? collected.slice(0, limit) : collected;
       if (globalOpts.json) {
-        outputJson(fetched);
+        outputJson(memories);
         return;
       }
       if (memories.length === 0) {
@@ -65337,7 +65615,7 @@ function registerHistoryCommand(program2) {
       }
       printPageHint({
         shown: memories.length,
-        limit,
+        limit: limit ?? memories.length,
         offset,
         hasMore,
         command: "mementos history",
@@ -65529,10 +65807,9 @@ function registerExportCommand(program2) {
         scope: opts.scope,
         category: opts.category,
         agent_id: agentId,
-        project_id: projectId,
-        limit: 1e4
+        project_id: projectId
       };
-      const memories = listMemories(filter);
+      const memories = listMemoriesBounded(filter, 1e4).rows;
       outputJson(memories);
     } catch (e) {
       handleError(e);
@@ -71008,7 +71285,7 @@ ${matched.map((m) => `- ${m.key}: ${m.value.slice(0, 120)}${m.value.length > 120
   };
 }
 var gatherTrainingData = async (options = {}) => {
-  const allMemories = listMemories({ status: "active" });
+  const allMemories = listMemoriesBounded({ status: "active" }, undefined).rows;
   const filtered = options.since ? allMemories.filter((m) => new Date(m.created_at) >= options.since) : allMemories;
   const sorted = filtered.slice().sort((a, b) => b.importance - a.importance);
   const fetchSet = options.limit ? sorted.slice(0, options.limit * 3) : sorted;

package/dist/db/analytics.d.ts

@@ -71,6 +71,19 @@ export interface StaleMemory {
     access_count: number;
     created_at?: string;
 }
+export interface StalePage {
+    rows: StaleMemory[];
+    /** True total of stale memories matching the filter — never the page length. */
+    total: number;
+    has_more: boolean | undefined;
+    next_cursor: number | null;
+}
+/**
+ * One bounded page of the stale surface, with the TRUE total and an explicit
+ * pagination signal. The server caps single responses and answers with
+ * `total` / `has_more` / `next_cursor`, so a page never silently truncates.
+ */
+export declare function getStaleMemoriesPage(filter?: StaleFilter, db?: Database): StalePage;
 export declare function getStaleMemories(filter?: StaleFilter, db?: Database): StaleMemory[];
 export interface HealthFilter {
     stale_days?: number;