@hasna/mementos 0.14.84 → 0.14.86

package/dist/pg-sync-worker.js

@@ -20,7 +20,7 @@ async function ensureConnected() {
   }
   await connecting;
 }
-function respond(statusCode, payload) {
+function respond(gen, statusCode, payload) {
   const bytes = encoder.encode(JSON.stringify(payload));
   if (bytes.length > dataView.length) {
     const errBytes = encoder.encode(JSON.stringify({
@@ -28,21 +28,23 @@ function respond(statusCode, payload) {
     }));
     dataView.set(errBytes, 0);
     Atomics.store(status, 1, errBytes.length);
-    Atomics.store(status, 0, 2);
+    Atomics.store(status, 2, 2);
+    Atomics.store(status, 0, gen);
     Atomics.notify(status, 0);
     return;
   }
   dataView.set(bytes, 0);
   Atomics.store(status, 1, bytes.length);
-  Atomics.store(status, 0, statusCode);
+  Atomics.store(status, 2, statusCode);
+  Atomics.store(status, 0, gen);
   Atomics.notify(status, 0);
 }
 parentPort?.on("message", async (msg) => {
   try {
     await ensureConnected();
     const result = await client.query(msg.sql, msg.params);
-    respond(1, { rows: result.rows, rowCount: result.rowCount });
+    respond(msg.gen, 1, { rows: result.rows, rowCount: result.rowCount });
   } catch (error) {
-    respond(2, { message: error instanceof Error ? error.message : String(error) });
+    respond(msg.gen, 2, { message: error instanceof Error ? error.message : String(error) });
   }
 });

package/dist/project-registration.js

@@ -235,6 +235,7 @@ function translateSql(sql) {
   let translated = sql.replace(/\?/g, () => `$${++parameterIndex}`);
   const ISO_FMT = `'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"'`;
   translated = translated.replace(/datetime\s*\(\s*'now'\s*\)/gi, `to_char(now() AT TIME ZONE 'UTC', ${ISO_FMT})`);
+  translated = translated.replace(/strftime\s*\(\s*'%Y-%m-%dT%H:%M:%fZ'\s*,\s*'now'\s*\)/gi, `to_char(now() AT TIME ZONE 'UTC', ${ISO_FMT})`);
   translated = translated.replace(/datetime\s*\(\s*'now'\s*,\s*'(-?\d+)\s+(minutes?|hours?|days?|seconds?)'\s*\)/gi, (_match, amount, unit) => {
     const parsed = parseInt(String(amount), 10);
     const absolute = Math.abs(parsed);
@@ -736,16 +737,24 @@ function transferRows(target, table, rows, options) {
   const conflictColumn = options.conflictColumn ?? "updated_at";
   let written = 0;
   let skipped = 0;
+  let maxSyncedAt = null;
   const errors = [];
+  const bumpMaxSyncedAt = (row) => {
+    const value = row[conflictColumn];
+    if (typeof value === "string" && (maxSyncedAt === null || value > maxSyncedAt)) {
+      maxSyncedAt = value;
+    }
+  };
   if (rows.length === 0) {
-    return { written, skipped, errors };
+    return { written, skipped, errors, maxSyncedAt };
   }
   const columns = Object.keys(rows[0] ?? {});
   if (!columns.includes(primaryKey)) {
     return {
       written,
       skipped,
-      errors: [`Table "${table}" has no "${primaryKey}" column; skipping`]
+      errors: [`Table "${table}" has no "${primaryKey}" column; skipping`],
+      maxSyncedAt
     };
   }
   const hasConflictColumn = columns.includes(conflictColumn);
@@ -758,6 +767,7 @@ function transferRows(target, table, rows, options) {
           const incomingTime = Date.parse(String(row[conflictColumn]));
           if (Number.isFinite(existingTime) && Number.isFinite(incomingTime) && existingTime >= incomingTime) {
             skipped++;
+            bumpMaxSyncedAt(row);
             continue;
           }
         }
@@ -770,11 +780,12 @@ function transferRows(target, table, rows, options) {
         target.run(`INSERT INTO "${table}" (${columnList}) VALUES (${placeholders})`, ...columns.map((column) => row[column]));
       }
       written++;
+      bumpMaxSyncedAt(row);
     } catch (error) {
       errors.push(`Row ${String(row[primaryKey] ?? "unknown")}: ${error instanceof Error ? error.message : String(error)}`);
     }
   }
-  return { written, skipped, errors };
+  return { written, skipped, errors, maxSyncedAt };
 }
 function incrementalSyncPush(local, remote, tables, options = {}) {
   return runIncrementalSync("push", local, remote, local, tables, options);
@@ -812,22 +823,29 @@ function runIncrementalSync(direction, source, target, metaDb, tables, options)
         rows = source.all(`SELECT * FROM "${table}"`);
         stat.first_sync = true;
       }
+      let maxSyncedAt = null;
       for (let offset = 0;offset < rows.length; offset += batchSize) {
         const batch = rows.slice(offset, offset + batchSize);
         const result = transferRows(target, table, batch, options);
         stat.synced_rows += result.written;
         stat.skipped_rows += result.skipped;
         stat.errors.push(...result.errors);
+        if (result.maxSyncedAt !== null && (maxSyncedAt === null || result.maxSyncedAt > maxSyncedAt)) {
+          maxSyncedAt = result.maxSyncedAt;
+        }
       }
       if (rows.length === 0) {
         stat.skipped_rows = stat.total_rows;
       }
-      upsertSyncMeta(metaDb, {
-        table_name: table,
-        last_synced_at: new Date().toISOString(),
-        last_synced_row_count: stat.synced_rows,
-        direction
-      });
+      const nextCursor = maxSyncedAt ?? meta?.last_synced_at ?? null;
+      if (rows.length > 0 && stat.errors.length === 0 && nextCursor !== null) {
+        upsertSyncMeta(metaDb, {
+          table_name: table,
+          last_synced_at: nextCursor,
+          last_synced_row_count: stat.synced_rows,
+          direction
+        });
+      }
     } catch (error) {
       stat.errors.push(`Table "${table}": ${error instanceof Error ? error.message : String(error)}`);
     }
@@ -866,8 +884,13 @@ var init_storage = __esm(() => {
     data;
     closed = false;
     lastError = null;
+    generation = 0;
     static DATA_BYTES = 128 * 1024 * 1024;
-    static QUERY_TIMEOUT_MS = 60000;
+    static queryTimeoutMs() {
+      const raw = process.env["MEMENTOS_PGSYNC_QUERY_TIMEOUT_MS"]?.trim();
+      const parsed = raw ? Number(raw) : Number.NaN;
+      return Number.isFinite(parsed) && parsed > 0 ? parsed : 60000;
+    }
     static resolveWorkerPath() {
       const ext = import.meta.url.endsWith(".ts") ? ".ts" : ".js";
       const here = fileURLToPath(new URL(".", import.meta.url));
@@ -882,12 +905,12 @@ var init_storage = __esm(() => {
       }
       return candidates[0];
     }
-    constructor(connectionString) {
-      const control = new SharedArrayBuffer(8);
+    constructor(connectionString, workerPath) {
+      const control = new SharedArrayBuffer(12);
       const dataSab = new SharedArrayBuffer(PgSyncPool.DATA_BYTES);
       this.status = new Int32Array(control);
       this.data = new Uint8Array(dataSab);
-      this.worker = new Worker(PgSyncPool.resolveWorkerPath(), {
+      this.worker = new Worker(workerPath ?? PgSyncPool.resolveWorkerPath(), {
         workerData: {
           dsn: stripSslParams(connectionString),
           ssl: sslConfigFor(connectionString),
@@ -905,21 +928,35 @@ var init_storage = __esm(() => {
         throw new Error("PgSyncPool is closed");
       if (this.lastError)
         throw this.lastError;
+      const timeoutMs = PgSyncPool.queryTimeoutMs();
+      const gen = ++this.generation;
       Atomics.store(this.status, 0, 0);
-      this.worker.postMessage({ sql, params });
-      const waitResult = Atomics.wait(this.status, 0, 0, PgSyncPool.QUERY_TIMEOUT_MS);
-      const code = Atomics.load(this.status, 0);
-      if (code === 0 || waitResult === "timed-out") {
-        if (this.lastError)
-          throw this.lastError;
-        throw new Error("PostgreSQL query timed out after 60s");
-      }
-      const len = Atomics.load(this.status, 1);
-      const payload = JSON.parse(new TextDecoder().decode(this.data.subarray(0, len)));
-      if (code === 2) {
-        throw new Error(payload.message ?? "PostgreSQL error");
+      Atomics.store(this.status, 2, 0);
+      this.worker.postMessage({ sql, params, gen });
+      const deadline = Date.now() + timeoutMs;
+      for (;; ) {
+        const remaining = deadline - Date.now();
+        const responding = Atomics.load(this.status, 0);
+        if (responding === gen) {
+          const code = Atomics.load(this.status, 2);
+          const len = Atomics.load(this.status, 1);
+          const payload = JSON.parse(new TextDecoder().decode(this.data.subarray(0, len)));
+          if (code === 2) {
+            throw new Error(payload.message ?? "PostgreSQL error");
+          }
+          return payload;
+        }
+        if (responding !== 0) {
+          Atomics.compareExchange(this.status, 0, responding, 0);
+          continue;
+        }
+        if (remaining <= 0) {
+          if (this.lastError)
+            throw this.lastError;
+          throw new Error(`PostgreSQL query timed out after ${timeoutMs}ms`);
+        }
+        Atomics.wait(this.status, 0, 0, remaining);
       }
-      return payload;
     }
     end() {
       if (this.closed)
@@ -1147,7 +1184,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) {
@@ -2886,6 +2932,90 @@ class MementosProjectRegistrationError extends Error {
   }
 }
 
+// src/project-registration/historical-receipt.ts
+var ROOT_TENANT_ID = "adfd95c7-ee8b-52cb-ae47-4ae65dae3313";
+var 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"
+};
+var 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
+};
+var FLEET_RESOURCES_CURRENT_PROJECT_REGISTRATION_IDENTITY = {
+  authority_id: "mementos",
+  tenant_id: ROOT_TENANT_ID,
+  corpus_id: "mementos:postgresql"
+};
+var 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
+};
+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;
+}
+
 // src/project-registration/identity.ts
 var MEMENTOS_PROJECT_AUTHORITY_ENV = {
   authorityId: "MEMENTOS_PROJECT_AUTHORITY_ID",
@@ -2927,12 +3057,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,
@@ -2951,6 +3082,12 @@ 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;
 }
 
 // src/db/projects.ts
@@ -4028,12 +4165,21 @@ function assertInverseRequest(request, capability) {
   }
   return accepted;
 }
+function matchesCurrentLookupIdentity(request, capability) {
+  return request.authority_route === capability.route && request.package_version === capability.package_version && request.authority_id === capability.authority_id && request.tenant_id === capability.tenant_id && request.corpus_id === capability.corpus_id;
+}
+function matchesFleetResourcesHistoricalLookup(request, capability) {
+  if (!supportsFleetResourcesHistoricalReceiptLookup(capability))
+    return false;
+  const source = FLEET_RESOURCES_HISTORICAL_LOOKUP_IDENTITY.source;
+  return request.authority === source.authority && request.authority_route === source.authority_route && request.package_version === source.package_version && request.authority_id === source.authority_id && request.tenant_id === source.tenant_id && request.corpus_id === source.corpus_id && request.operation_id === source.operation_id && request.step_id === source.step_id && request.resource_kind === source.resource_kind && request.direction === source.direction && request.target_selector === source.target_selector && request.target_id === source.target_id && request.idempotency_key === source.idempotency_key;
+}
 function assertLookup(request, capability) {
   assertBounds(request);
   if (request.max_items !== 1) {
     throw new MementosProjectRegistrationError("MEMENTOS_PROJECT_REGISTRATION_INVALID_BOUNDS", "terminal receipt lookup requires max_items exactly 1");
   }
-  if (request.authority !== "mementos" || request.resource_kind !== "project" || request.authority_route !== capability.route || request.package_version !== capability.package_version || request.authority_id !== capability.authority_id || request.tenant_id !== capability.tenant_id || request.corpus_id !== capability.corpus_id) {
+  if (request.authority !== "mementos" || request.resource_kind !== "project" || !matchesCurrentLookupIdentity(request, capability) && !matchesFleetResourcesHistoricalLookup(request, capability)) {
     throw new MementosProjectRegistrationError("MEMENTOS_PROJECT_REGISTRATION_CAPABILITY_MISMATCH", "receipt lookup does not match this authority capability identity");
   }
   requireString(request.operation_id, "operation_id", { pattern: OPERATION_PATTERN });
@@ -4051,6 +4197,7 @@ function assertLookup(request, capability) {
       pattern: PROJECT_ID_PATTERN
     });
   }
+  return matchesCurrentLookupIdentity(request, capability) ? "current" : "fleet_resources_historical";
 }
 
 class PackageOwnedMementosProjectRegistrationAuthority {
@@ -4315,11 +4462,14 @@ class PackageOwnedMementosProjectRegistrationAuthority {
   }
   async lookupReceipt(request) {
     const startedAt = Date.now();
-    assertLookup(request, this.capabilityValue);
+    const lookupIdentity = assertLookup(request, this.capabilityValue);
     const receipt = getReceiptForLookup(this.db, request);
     if (!receipt || request.target_id !== undefined && receipt.target_id !== request.target_id) {
       throw new MementosProjectRegistrationError("MEMENTOS_PROJECT_REGISTRATION_RECEIPT_NOT_FOUND", "exact immutable terminal receipt was not found");
     }
+    if (lookupIdentity === "fleet_resources_historical" && (receipt.receipt_id !== FLEET_RESOURCES_HISTORICAL_LOOKUP_IDENTITY.source.receipt_id || canonicalMementosProjectRegistrationJson(publicReceipt(receipt)) !== canonicalMementosProjectRegistrationJson(FLEET_RESOURCES_HISTORICAL_RECEIPT))) {
+      throw new MementosProjectRegistrationError("MEMENTOS_PROJECT_REGISTRATION_RECEIPT_NOT_FOUND", "exact immutable historical terminal receipt was not found");
+    }
     return withResponseControl(publicReceipt(receipt), request, startedAt);
   }
   async compensate(request) {
@@ -5242,7 +5392,26 @@ function parseMemoryRow(row) {
     accessed_at: row["accessed_at"] || null
   };
 }
+var RESERVED_AGENT_IDS = new Set([
+  "agent-a",
+  "agent-x",
+  "agent-z",
+  "nonexistent-agent"
+]);
+function reservedAgentIdViolation(agentId) {
+  if (!agentId)
+    return null;
+  const normalized = agentId.trim().toLowerCase();
+  if (RESERVED_AGENT_IDS.has(normalized)) {
+    return `Reserved placeholder agent id "${agentId}" cannot own a memory. ` + `Refusing to write: test harnesses must not write memories under placeholder agent ` + `identities. Register a real agent (mementos register-agent <name>) and pass its id.`;
+  }
+  return null;
+}
 function createMemory(input, dedupeMode = "merge", db) {
+  const reservedViolation = reservedAgentIdViolation(input.agent_id);
+  if (reservedViolation) {
+    throw new Error(reservedViolation);
+  }
   if (!db && isApiMode()) {
     const { status, data } = apiJson("POST", "/memories", { ...input, dedupe: dedupeMode });
     if (!data || !data.id) {
@@ -5292,7 +5461,8 @@ function createMemory(input, dedupeMode = "merge", db) {
            importance = ?, metadata = ?, expires_at = ?,
            when_to_use = ?,
            pinned = COALESCE(pinned, 0),
-           version = version + 1, updated_at = ?
+           version = version + 1, updated_at = ?,
+           updated_by_agent = ?
          WHERE id = ?`, [
         safeValue,
         input.category || "knowledge",
@@ -5303,6 +5473,7 @@ function createMemory(input, dedupeMode = "merge", db) {
         expiresAt,
         input.when_to_use || null,
         timestamp,
+        input.agent_id || null,
         existing.id
       ]);
       d.run("DELETE FROM memory_tags WHERE memory_id = ?", [existing.id]);
@@ -5476,29 +5647,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) {
@@ -5610,21 +5759,104 @@ 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,
+      machine_id: f.machine_id,
+      visible_to_machine_id: f.visible_to_machine_id,
+      search: f.search,
+      source: f.source,
+      flag: f.flag,
+      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 updateMemory(id, input, db) {
   if (!db && isApiMode()) {
@@ -5690,20 +5922,29 @@ function updateMemory(id, input, db) {
     sets.push("when_to_use = ?");
     params.push(input.when_to_use ?? null);
   }
+  if (input.updated_by_agent !== undefined) {
+    sets.push("updated_by_agent = ?");
+    params.push(input.updated_by_agent ?? null);
+  }
   if (input.tags !== undefined) {
     sets.push("tags = ?");
     params.push(JSON.stringify(input.tags));
-    d.run("DELETE FROM memory_tags WHERE memory_id = ?", [memoryId]);
-    const insertTag = d.prepare("INSERT OR IGNORE INTO memory_tags (memory_id, tag) VALUES (?, ?)");
-    for (const tag of input.tags) {
-      insertTag.run(memoryId, tag);
-    }
   }
   params.push(memoryId);
-  const result = d.run(`UPDATE memories SET ${sets.join(", ")} WHERE id = ?`, params);
-  if (result.changes === 0) {
-    throw new Error(`Update affected no rows for memory ${memoryId}: the record was read but not written. ` + `This is a bug in @hasna/mementos, not a bad argument \u2014 please report it.`);
-  }
+  d.transaction(() => {
+    const res = d.run(`UPDATE memories SET ${sets.join(", ")} WHERE id = ?`, params);
+    if (res.changes === 0) {
+      throw new Error(`Update affected no rows for memory ${memoryId}: the record was read but not written. ` + `This is a bug in @hasna/mementos, not a bad argument \u2014 please report it.`);
+    }
+    if (input.tags !== undefined) {
+      d.run("DELETE FROM memory_tags WHERE memory_id = ?", [memoryId]);
+      const insertTag = d.prepare("INSERT OR IGNORE INTO memory_tags (memory_id, tag) VALUES (?, ?)");
+      for (const tag of input.tags) {
+        insertTag.run(memoryId, tag);
+      }
+    }
+    return res;
+  });
   const updated = getMemory(memoryId, d);
   if (input.value !== undefined) {
     try {