@hasna/mementos 0.14.74 → 0.14.75

package/dist/cli/commands/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/agent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAgBzC,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAsN5D"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/agent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAgBzC,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA4N5D"}

package/dist/cli/index.js

@@ -4130,6 +4130,39 @@ INSERT OR IGNORE INTO _migrations (id) VALUES (35);
     `
 ${MEMORY_VERSION_SNAPSHOT_TRIGGER}
 INSERT OR IGNORE INTO _migrations (id) VALUES (36);
+`,
+    `
+DROP TRIGGER IF EXISTS audit_memory_insert;
+CREATE TRIGGER audit_memory_insert AFTER INSERT ON memories BEGIN
+  INSERT INTO memory_audit_log (id, memory_id, memory_key, operation, agent_id, created_at)
+  VALUES (hex(randomblob(4)), new.id, new.key, 'create', new.agent_id, datetime('now'));
+END;
+
+DROP TRIGGER IF EXISTS audit_memory_update;
+CREATE TRIGGER audit_memory_update AFTER UPDATE ON memories BEGIN
+  INSERT INTO memory_audit_log (id, memory_id, memory_key, operation, agent_id, changes, created_at)
+  VALUES (hex(randomblob(4)), new.id, new.key, 'update', new.agent_id,
+    json_object('version_from', old.version, 'version_to', new.version, 'importance_from', old.importance, 'importance_to', new.importance),
+    datetime('now'));
+END;
+
+DROP TRIGGER IF EXISTS audit_memory_delete;
+CREATE TRIGGER audit_memory_delete AFTER DELETE ON memories BEGIN
+  INSERT INTO memory_audit_log (id, memory_id, memory_key, operation, agent_id, created_at)
+  VALUES (hex(randomblob(4)), old.id, old.key, 'delete', old.agent_id, datetime('now'));
+END;
+
+UPDATE memory_audit_log SET old_value_hash = NULL
+  WHERE old_value_hash IS NOT NULL
+    AND length(old_value_hash) = 32
+    AND old_value_hash NOT GLOB '*[^0-9A-F]*';
+
+UPDATE memory_audit_log SET new_value_hash = NULL
+  WHERE new_value_hash IS NOT NULL
+    AND length(new_value_hash) = 32
+    AND new_value_hash NOT GLOB '*[^0-9A-F]*';
+
+INSERT OR IGNORE INTO _migrations (id) VALUES (37);
 `
   ];
 });
@@ -6708,13 +6741,46 @@ function getAgent(idOrName, db) {
     return parseAgentRow(rows[0]);
   return null;
 }
-function listAgents(db) {
-  if (!db && isApiMode()) {
-    const { data } = apiJson("GET", "/agents");
+function normalizedAgentListFilter(filter) {
+  const limit = Number.isFinite(filter.limit) ? Math.max(0, Math.floor(filter.limit)) : undefined;
+  const offset = Number.isFinite(filter.offset) ? Math.max(0, Math.floor(filter.offset)) : undefined;
+  return { limit, offset };
+}
+function isDatabaseAdapter(value) {
+  return typeof value === "object" && value !== null && "query" in value && typeof value.query === "function";
+}
+function paginatedAgentQuery(baseSql, baseParams, filter) {
+  const { limit, offset } = normalizedAgentListFilter(filter);
+  let sql = `${baseSql} ORDER BY created_at ASC, id ASC`;
+  const params = [...baseParams];
+  if (limit !== undefined) {
+    sql += " LIMIT ?";
+    params.push(limit);
+  } else if ((offset ?? 0) > 0) {
+    sql += " LIMIT ?";
+    params.push(UNBOUNDED_AGENT_LIST_LIMIT);
+  }
+  if ((offset ?? 0) > 0) {
+    sql += " OFFSET ?";
+    params.push(offset);
+  }
+  return { sql, params };
+}
+function listAgents(filterOrDb = {}, db) {
+  const explicitDb = isDatabaseAdapter(filterOrDb) ? filterOrDb : db;
+  const filter = isDatabaseAdapter(filterOrDb) ? {} : filterOrDb;
+  const normalized = normalizedAgentListFilter(filter);
+  if (!explicitDb && isApiMode()) {
+    const q = toQuery({
+      limit: normalized.limit,
+      offset: normalized.offset
+    });
+    const { data } = apiJson("GET", `/agents${q}`);
     return data?.agents ?? [];
   }
-  const d = db || getDatabase();
-  const rows = d.query("SELECT * FROM agents ORDER BY last_seen_at DESC").all();
+  const d = explicitDb || getDatabase();
+  const { sql, params } = paginatedAgentQuery("SELECT * FROM agents", [], normalized);
+  const rows = d.query(sql).all(...params);
   return rows.map(parseAgentRow);
 }
 function touchAgent(idOrName, db) {
@@ -6731,15 +6797,19 @@ function touchAgent(idOrName, db) {
     return;
   d.run("UPDATE agents SET last_seen_at = ? WHERE id = ?", [now(), agent.id]);
 }
-function listAgentsByProject(projectId, db) {
-  if (!db && isApiMode()) {
-    const q = toQuery({ project_id: projectId });
+function listAgentsByProject(projectId, filterOrDb = {}, db) {
+  const explicitDb = isDatabaseAdapter(filterOrDb) ? filterOrDb : db;
+  const filter = isDatabaseAdapter(filterOrDb) ? {} : filterOrDb;
+  const normalized = normalizedAgentListFilter(filter);
+  if (!explicitDb && isApiMode()) {
+    const q = toQuery({ project_id: projectId, ...normalized });
     const { data } = apiJson("GET", `/agents${q}`);
     return data?.agents ?? [];
   }
-  const d = db || getDatabase();
+  const d = explicitDb || getDatabase();
   const resolvedId = resolvePartialId(d, "projects", projectId) || projectId;
-  const rows = d.query("SELECT * FROM agents WHERE active_project_id = ? ORDER BY last_seen_at DESC").all(resolvedId);
+  const { sql, params } = paginatedAgentQuery("SELECT * FROM agents WHERE active_project_id = ?", [resolvedId], normalized);
+  const rows = d.query(sql).all(...params);
   return rows.map(parseAgentRow);
 }
 function updateAgent(id, updates, db) {
@@ -6787,12 +6857,13 @@ function updateAgent(id, updates, db) {
   d.run("UPDATE agents SET last_seen_at = ? WHERE id = ?", [timestamp, agent.id]);
   return getAgent(agent.id, d);
 }
-var CONFLICT_WINDOW_MS;
+var CONFLICT_WINDOW_MS, UNBOUNDED_AGENT_LIST_LIMIT;
 var init_agents = __esm(() => {
   init_types();
   init_database();
   init_api_mode();
   CONFLICT_WINDOW_MS = 30 * 60 * 1000;
+  UNBOUNDED_AGENT_LIST_LIMIT = Number.MAX_SAFE_INTEGER;
 });
 
 // src/lib/poll.ts
@@ -12222,6 +12293,35 @@ var init_pg_migrations = __esm(() => {
     EXECUTE FUNCTION snapshot_memory_version();
 
   INSERT INTO _migrations (id) VALUES (36) ON CONFLICT DO NOTHING;
+  `,
+    `
+  CREATE OR REPLACE FUNCTION audit_memory_insert() RETURNS trigger AS $$
+  BEGIN
+    INSERT INTO memory_audit_log (id, memory_id, memory_key, operation, agent_id, new_value_hash, created_at)
+    VALUES (gen_random_uuid()::text, NEW.id, NEW.key, 'create', NEW.agent_id, md5(COALESCE(NEW.value, '')), NOW());
+    RETURN NEW;
+  END;
+  $$ LANGUAGE plpgsql;
+
+  CREATE OR REPLACE FUNCTION audit_memory_update() RETURNS trigger AS $$
+  BEGIN
+    INSERT INTO memory_audit_log (id, memory_id, memory_key, operation, agent_id, old_value_hash, new_value_hash, changes, created_at)
+    VALUES (gen_random_uuid()::text, NEW.id, NEW.key, 'update', NEW.agent_id, md5(COALESCE(OLD.value, '')), md5(COALESCE(NEW.value, '')),
+      json_build_object('version_from', OLD.version, 'version_to', NEW.version, 'importance_from', OLD.importance, 'importance_to', NEW.importance)::text,
+      NOW());
+    RETURN NEW;
+  END;
+  $$ LANGUAGE plpgsql;
+
+  CREATE OR REPLACE FUNCTION audit_memory_delete() RETURNS trigger AS $$
+  BEGIN
+    INSERT INTO memory_audit_log (id, memory_id, memory_key, operation, agent_id, old_value_hash, created_at)
+    VALUES (gen_random_uuid()::text, OLD.id, OLD.key, 'delete', OLD.agent_id, md5(COALESCE(OLD.value, '')), NOW());
+    RETURN OLD;
+  END;
+  $$ LANGUAGE plpgsql;
+
+  INSERT INTO _migrations (id) VALUES (37) ON CONFLICT DO NOTHING;
   `
   ];
 });
@@ -62050,14 +62150,17 @@ function registerAgentCommands(program2) {
   program2.command("agents").description("List all registered agents").option("--limit <n>", "Max results (compact default: 20)", parseInt).option("--cursor <n>", "Cursor offset for the next page", parseInt).option("--offset <n>", "Offset for pagination", parseInt).action((opts) => {
     try {
       const globalOpts = program2.opts();
-      const allAgents = listAgents();
       const limit = positiveIntOrDefault(opts.limit, DEFAULT_COMPACT_LIMIT);
       const offset = cursorOrOffset(opts.cursor, opts.offset) ?? 0;
-      const agents = globalOpts.json ? allAgents : allAgents.slice(offset, offset + limit + 1);
+      const explicitPagination = opts.limit !== undefined || opts.cursor !== undefined || opts.offset !== undefined;
+      const agents = listAgents({
+        limit: globalOpts.json ? explicitPagination ? limit : undefined : limit + 1,
+        offset
+      });
       const hasMore = !globalOpts.json && agents.length > limit;
       const displayAgents = hasMore ? agents.slice(0, limit) : agents;
       if (globalOpts.json) {
-        outputJson(allAgents);
+        outputJson(agents);
         return;
       }
       if (displayAgents.length === 0) {

package/dist/db/agents.d.ts

@@ -1,10 +1,16 @@
 import { SqliteAdapter as Database } from "../storage.js";
 import type { Agent } from "../types/index.js";
+export interface AgentListFilter {
+    limit?: number;
+    offset?: number;
+}
 export declare function registerAgent(name: string, sessionId?: string, description?: string, role?: string, projectId?: string, db?: Database): Agent;
 export declare function getAgent(idOrName: string, db?: Database): Agent | null;
 export declare function listAgents(db?: Database): Agent[];
+export declare function listAgents(filter: AgentListFilter, db?: Database): Agent[];
 export declare function touchAgent(idOrName: string, db?: Database): void;
 export declare function listAgentsByProject(projectId: string, db?: Database): Agent[];
+export declare function listAgentsByProject(projectId: string, filter: AgentListFilter, db?: Database): Agent[];
 export declare function updateAgent(id: string, updates: {
     name?: string;
     description?: string;

package/dist/db/agents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../src/db/agents.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,IAAI,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAqB/C,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,SAAS,CAAC,EAAE,MAAM,EAClB,WAAW,CAAC,EAAE,MAAM,EACpB,IAAI,CAAC,EAAE,MAAM,EACb,SAAS,CAAC,EAAE,MAAM,EAClB,EAAE,CAAC,EAAE,QAAQ,GACZ,KAAK,CA0EP;AAED,wBAAgB,QAAQ,CACtB,QAAQ,EAAE,MAAM,EAChB,EAAE,CAAC,EAAE,QAAQ,GACZ,KAAK,GAAG,IAAI,CA6Bd;AAED,wBAAgB,UAAU,CAAC,EAAE,CAAC,EAAE,QAAQ,GAAG,KAAK,EAAE,CAUjD;AAED,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,QAAQ,GAAG,IAAI,CAahE;AAED,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,QAAQ,GAAG,KAAK,EAAE,CAa7E;AAED,wBAAgB,WAAW,CACzB,EAAE,EAAE,MAAM,EACV,OAAO,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EACtI,EAAE,CAAC,EAAE,QAAQ,GACZ,KAAK,GAAG,IAAI,CAsDd"}
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../src/db/agents.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,IAAI,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAQ/C,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAgBD,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,SAAS,CAAC,EAAE,MAAM,EAClB,WAAW,CAAC,EAAE,MAAM,EACpB,IAAI,CAAC,EAAE,MAAM,EACb,SAAS,CAAC,EAAE,MAAM,EAClB,EAAE,CAAC,EAAE,QAAQ,GACZ,KAAK,CA0EP;AAED,wBAAgB,QAAQ,CACtB,QAAQ,EAAE,MAAM,EAChB,EAAE,CAAC,EAAE,QAAQ,GACZ,KAAK,GAAG,IAAI,CA6Bd;AA+CD,wBAAgB,UAAU,CAAC,EAAE,CAAC,EAAE,QAAQ,GAAG,KAAK,EAAE,CAAC;AACnD,wBAAgB,UAAU,CAAC,MAAM,EAAE,eAAe,EAAE,EAAE,CAAC,EAAE,QAAQ,GAAG,KAAK,EAAE,CAAC;AAsB5E,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,QAAQ,GAAG,IAAI,CAahE;AAED,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,QAAQ,GAAG,KAAK,EAAE,CAAC;AAC/E,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,eAAe,EACvB,EAAE,CAAC,EAAE,QAAQ,GACZ,KAAK,EAAE,CAAC;AA0BX,wBAAgB,WAAW,CACzB,EAAE,EAAE,MAAM,EACV,OAAO,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EACtI,EAAE,CAAC,EAAE,QAAQ,GACZ,KAAK,GAAG,IAAI,CAsDd"}

package/dist/db/audit.d.ts

@@ -9,7 +9,21 @@ export interface AuditEntry {
     memory_key: string | null;
     operation: "create" | "update" | "delete" | "archive" | "restore" | "read";
     agent_id: string | null;
+    /**
+     * md5 hex digest of the value the row held BEFORE the operation, or `null`.
+     *
+     * `null` means the digest is UNAVAILABLE, never that the value was empty. It is
+     * the honest answer on SQLite, which has no `md5()` and whose driver
+     * (`bun:sqlite`) exposes no user-defined-function API, so a trigger cannot
+     * compute one. Postgres computes `md5(COALESCE(...))` natively and populates it.
+     *
+     * So: compare `md5(candidate)` against a NON-NULL value to prove what a row
+     * held. A `null` is a statement about the BACKEND and must never be read as
+     * evidence about the content — treating it as a failed match is the confident
+     * wrong answer migration 37 exists to prevent.
+     */
     old_value_hash: string | null;
+    /** md5 hex digest of the value AFTER the operation, or `null`. See `old_value_hash`. */
     new_value_hash: string | null;
     changes: Record<string, unknown>;
     created_at: string;

package/dist/db/audit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../src/db/audit.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,aAAa,IAAI,QAAQ,EAAE,MAAM,eAAe,CAAC;AAG1D,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,SAAS,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,MAAM,CAAC;IAC3E,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,UAAU,EAAE,MAAM,CAAC;CACpB;AAgBD;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,KAAK,GAAE,MAAW,EAClB,EAAE,CAAC,EAAE,QAAQ,GACZ,UAAU,EAAE,CAMd;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,OAAO,GAAE;IACP,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CACX,EACN,EAAE,CAAC,EAAE,QAAQ,GACZ,UAAU,EAAE,CA6Bd;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,EAAE,CAAC,EAAE,QAAQ,GAAG;IAC5C,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,UAAU,EAAE,MAAM,CAAC;CACpB,CAkBA"}
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../src/db/audit.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,aAAa,IAAI,QAAQ,EAAE,MAAM,eAAe,CAAC;AAG1D,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,SAAS,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,MAAM,CAAC;IAC3E,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB;;;;;;;;;;;;OAYG;IACH,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,wFAAwF;IACxF,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,UAAU,EAAE,MAAM,CAAC;CACpB;AAgBD;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,KAAK,GAAE,MAAW,EAClB,EAAE,CAAC,EAAE,QAAQ,GACZ,UAAU,EAAE,CAMd;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,OAAO,GAAE;IACP,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CACX,EACN,EAAE,CAAC,EAAE,QAAQ,GACZ,UAAU,EAAE,CA6Bd;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,EAAE,CAAC,EAAE,QAAQ,GAAG;IAC5C,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,UAAU,EAAE,MAAM,CAAC;CACpB,CAkBA"}

package/dist/db/migrations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"migrations.d.ts","sourceRoot":"","sources":["../../src/db/migrations.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,+BAA+B,wqBAiB3C,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,MAAM,EAm9B9B,CAAC"}
+{"version":3,"file":"migrations.d.ts","sourceRoot":"","sources":["../../src/db/migrations.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,+BAA+B,wqBAiB3C,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,MAAM,EAkhC9B,CAAC"}

package/dist/db/pg-migrations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pg-migrations.d.ts","sourceRoot":"","sources":["../../src/db/pg-migrations.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,EA+xBjC,CAAC"}
+{"version":3,"file":"pg-migrations.d.ts","sourceRoot":"","sources":["../../src/db/pg-migrations.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,EAy0BjC,CAAC"}

package/dist/index.js

@@ -2098,6 +2098,39 @@ INSERT OR IGNORE INTO _migrations (id) VALUES (35);
     `
 ${MEMORY_VERSION_SNAPSHOT_TRIGGER}
 INSERT OR IGNORE INTO _migrations (id) VALUES (36);
+`,
+    `
+DROP TRIGGER IF EXISTS audit_memory_insert;
+CREATE TRIGGER audit_memory_insert AFTER INSERT ON memories BEGIN
+  INSERT INTO memory_audit_log (id, memory_id, memory_key, operation, agent_id, created_at)
+  VALUES (hex(randomblob(4)), new.id, new.key, 'create', new.agent_id, datetime('now'));
+END;
+
+DROP TRIGGER IF EXISTS audit_memory_update;
+CREATE TRIGGER audit_memory_update AFTER UPDATE ON memories BEGIN
+  INSERT INTO memory_audit_log (id, memory_id, memory_key, operation, agent_id, changes, created_at)
+  VALUES (hex(randomblob(4)), new.id, new.key, 'update', new.agent_id,
+    json_object('version_from', old.version, 'version_to', new.version, 'importance_from', old.importance, 'importance_to', new.importance),
+    datetime('now'));
+END;
+
+DROP TRIGGER IF EXISTS audit_memory_delete;
+CREATE TRIGGER audit_memory_delete AFTER DELETE ON memories BEGIN
+  INSERT INTO memory_audit_log (id, memory_id, memory_key, operation, agent_id, created_at)
+  VALUES (hex(randomblob(4)), old.id, old.key, 'delete', old.agent_id, datetime('now'));
+END;
+
+UPDATE memory_audit_log SET old_value_hash = NULL
+  WHERE old_value_hash IS NOT NULL
+    AND length(old_value_hash) = 32
+    AND old_value_hash NOT GLOB '*[^0-9A-F]*';
+
+UPDATE memory_audit_log SET new_value_hash = NULL
+  WHERE new_value_hash IS NOT NULL
+    AND length(new_value_hash) = 32
+    AND new_value_hash NOT GLOB '*[^0-9A-F]*';
+
+INSERT OR IGNORE INTO _migrations (id) VALUES (37);
 `
   ];
 });
@@ -49995,6 +50028,7 @@ function getMemoryVersions(memoryId, db) {
 init_database();
 init_api_mode();
 var CONFLICT_WINDOW_MS = 30 * 60 * 1000;
+var UNBOUNDED_AGENT_LIST_LIMIT = Number.MAX_SAFE_INTEGER;
 function parseAgentRow(row) {
   return {
     id: row["id"],
@@ -50086,13 +50120,46 @@ function getAgent(idOrName, db) {
     return parseAgentRow(rows[0]);
   return null;
 }
-function listAgents(db) {
-  if (!db && isApiMode()) {
-    const { data } = apiJson("GET", "/agents");
+function normalizedAgentListFilter(filter) {
+  const limit = Number.isFinite(filter.limit) ? Math.max(0, Math.floor(filter.limit)) : undefined;
+  const offset = Number.isFinite(filter.offset) ? Math.max(0, Math.floor(filter.offset)) : undefined;
+  return { limit, offset };
+}
+function isDatabaseAdapter(value) {
+  return typeof value === "object" && value !== null && "query" in value && typeof value.query === "function";
+}
+function paginatedAgentQuery(baseSql, baseParams, filter) {
+  const { limit, offset } = normalizedAgentListFilter(filter);
+  let sql = `${baseSql} ORDER BY created_at ASC, id ASC`;
+  const params = [...baseParams];
+  if (limit !== undefined) {
+    sql += " LIMIT ?";
+    params.push(limit);
+  } else if ((offset ?? 0) > 0) {
+    sql += " LIMIT ?";
+    params.push(UNBOUNDED_AGENT_LIST_LIMIT);
+  }
+  if ((offset ?? 0) > 0) {
+    sql += " OFFSET ?";
+    params.push(offset);
+  }
+  return { sql, params };
+}
+function listAgents(filterOrDb = {}, db) {
+  const explicitDb = isDatabaseAdapter(filterOrDb) ? filterOrDb : db;
+  const filter = isDatabaseAdapter(filterOrDb) ? {} : filterOrDb;
+  const normalized = normalizedAgentListFilter(filter);
+  if (!explicitDb && isApiMode()) {
+    const q = toQuery({
+      limit: normalized.limit,
+      offset: normalized.offset
+    });
+    const { data } = apiJson("GET", `/agents${q}`);
     return data?.agents ?? [];
   }
-  const d = db || getDatabase();
-  const rows = d.query("SELECT * FROM agents ORDER BY last_seen_at DESC").all();
+  const d = explicitDb || getDatabase();
+  const { sql, params } = paginatedAgentQuery("SELECT * FROM agents", [], normalized);
+  const rows = d.query(sql).all(...params);
   return rows.map(parseAgentRow);
 }
 function touchAgent(idOrName, db) {
@@ -50109,15 +50176,19 @@ function touchAgent(idOrName, db) {
     return;
   d.run("UPDATE agents SET last_seen_at = ? WHERE id = ?", [now(), agent.id]);
 }
-function listAgentsByProject(projectId, db) {
-  if (!db && isApiMode()) {
-    const q = toQuery({ project_id: projectId });
+function listAgentsByProject(projectId, filterOrDb = {}, db) {
+  const explicitDb = isDatabaseAdapter(filterOrDb) ? filterOrDb : db;
+  const filter = isDatabaseAdapter(filterOrDb) ? {} : filterOrDb;
+  const normalized = normalizedAgentListFilter(filter);
+  if (!explicitDb && isApiMode()) {
+    const q = toQuery({ project_id: projectId, ...normalized });
     const { data } = apiJson("GET", `/agents${q}`);
     return data?.agents ?? [];
   }
-  const d = db || getDatabase();
+  const d = explicitDb || getDatabase();
   const resolvedId = resolvePartialId(d, "projects", projectId) || projectId;
-  const rows = d.query("SELECT * FROM agents WHERE active_project_id = ? ORDER BY last_seen_at DESC").all(resolvedId);
+  const { sql, params } = paginatedAgentQuery("SELECT * FROM agents WHERE active_project_id = ?", [resolvedId], normalized);
+  const rows = d.query(sql).all(...params);
   return rows.map(parseAgentRow);
 }
 function updateAgent(id, updates, db) {

package/dist/mcp/index.js

@@ -2161,6 +2161,39 @@ INSERT OR IGNORE INTO _migrations (id) VALUES (35);
     `
 ${MEMORY_VERSION_SNAPSHOT_TRIGGER}
 INSERT OR IGNORE INTO _migrations (id) VALUES (36);
+`,
+    `
+DROP TRIGGER IF EXISTS audit_memory_insert;
+CREATE TRIGGER audit_memory_insert AFTER INSERT ON memories BEGIN
+  INSERT INTO memory_audit_log (id, memory_id, memory_key, operation, agent_id, created_at)
+  VALUES (hex(randomblob(4)), new.id, new.key, 'create', new.agent_id, datetime('now'));
+END;
+
+DROP TRIGGER IF EXISTS audit_memory_update;
+CREATE TRIGGER audit_memory_update AFTER UPDATE ON memories BEGIN
+  INSERT INTO memory_audit_log (id, memory_id, memory_key, operation, agent_id, changes, created_at)
+  VALUES (hex(randomblob(4)), new.id, new.key, 'update', new.agent_id,
+    json_object('version_from', old.version, 'version_to', new.version, 'importance_from', old.importance, 'importance_to', new.importance),
+    datetime('now'));
+END;
+
+DROP TRIGGER IF EXISTS audit_memory_delete;
+CREATE TRIGGER audit_memory_delete AFTER DELETE ON memories BEGIN
+  INSERT INTO memory_audit_log (id, memory_id, memory_key, operation, agent_id, created_at)
+  VALUES (hex(randomblob(4)), old.id, old.key, 'delete', old.agent_id, datetime('now'));
+END;
+
+UPDATE memory_audit_log SET old_value_hash = NULL
+  WHERE old_value_hash IS NOT NULL
+    AND length(old_value_hash) = 32
+    AND old_value_hash NOT GLOB '*[^0-9A-F]*';
+
+UPDATE memory_audit_log SET new_value_hash = NULL
+  WHERE new_value_hash IS NOT NULL
+    AND length(new_value_hash) = 32
+    AND new_value_hash NOT GLOB '*[^0-9A-F]*';
+
+INSERT OR IGNORE INTO _migrations (id) VALUES (37);
 `
   ];
 });
@@ -13016,6 +13049,35 @@ var init_pg_migrations = __esm(() => {
     EXECUTE FUNCTION snapshot_memory_version();
 
   INSERT INTO _migrations (id) VALUES (36) ON CONFLICT DO NOTHING;
+  `,
+    `
+  CREATE OR REPLACE FUNCTION audit_memory_insert() RETURNS trigger AS $$
+  BEGIN
+    INSERT INTO memory_audit_log (id, memory_id, memory_key, operation, agent_id, new_value_hash, created_at)
+    VALUES (gen_random_uuid()::text, NEW.id, NEW.key, 'create', NEW.agent_id, md5(COALESCE(NEW.value, '')), NOW());
+    RETURN NEW;
+  END;
+  $$ LANGUAGE plpgsql;
+
+  CREATE OR REPLACE FUNCTION audit_memory_update() RETURNS trigger AS $$
+  BEGIN
+    INSERT INTO memory_audit_log (id, memory_id, memory_key, operation, agent_id, old_value_hash, new_value_hash, changes, created_at)
+    VALUES (gen_random_uuid()::text, NEW.id, NEW.key, 'update', NEW.agent_id, md5(COALESCE(OLD.value, '')), md5(COALESCE(NEW.value, '')),
+      json_build_object('version_from', OLD.version, 'version_to', NEW.version, 'importance_from', OLD.importance, 'importance_to', NEW.importance)::text,
+      NOW());
+    RETURN NEW;
+  END;
+  $$ LANGUAGE plpgsql;
+
+  CREATE OR REPLACE FUNCTION audit_memory_delete() RETURNS trigger AS $$
+  BEGIN
+    INSERT INTO memory_audit_log (id, memory_id, memory_key, operation, agent_id, old_value_hash, created_at)
+    VALUES (gen_random_uuid()::text, OLD.id, OLD.key, 'delete', OLD.agent_id, md5(COALESCE(OLD.value, '')), NOW());
+    RETURN OLD;
+  END;
+  $$ LANGUAGE plpgsql;
+
+  INSERT INTO _migrations (id) VALUES (37) ON CONFLICT DO NOTHING;
   `
   ];
 });
@@ -55743,6 +55805,7 @@ init_types();
 init_database();
 init_api_mode();
 var CONFLICT_WINDOW_MS = 30 * 60 * 1000;
+var UNBOUNDED_AGENT_LIST_LIMIT = Number.MAX_SAFE_INTEGER;
 function parseAgentRow(row) {
   return {
     id: row["id"],
@@ -55834,13 +55897,46 @@ function getAgent(idOrName, db) {
     return parseAgentRow(rows[0]);
   return null;
 }
-function listAgents(db) {
-  if (!db && isApiMode()) {
-    const { data } = apiJson("GET", "/agents");
+function normalizedAgentListFilter(filter) {
+  const limit = Number.isFinite(filter.limit) ? Math.max(0, Math.floor(filter.limit)) : undefined;
+  const offset = Number.isFinite(filter.offset) ? Math.max(0, Math.floor(filter.offset)) : undefined;
+  return { limit, offset };
+}
+function isDatabaseAdapter(value) {
+  return typeof value === "object" && value !== null && "query" in value && typeof value.query === "function";
+}
+function paginatedAgentQuery(baseSql, baseParams, filter) {
+  const { limit, offset } = normalizedAgentListFilter(filter);
+  let sql = `${baseSql} ORDER BY created_at ASC, id ASC`;
+  const params = [...baseParams];
+  if (limit !== undefined) {
+    sql += " LIMIT ?";
+    params.push(limit);
+  } else if ((offset ?? 0) > 0) {
+    sql += " LIMIT ?";
+    params.push(UNBOUNDED_AGENT_LIST_LIMIT);
+  }
+  if ((offset ?? 0) > 0) {
+    sql += " OFFSET ?";
+    params.push(offset);
+  }
+  return { sql, params };
+}
+function listAgents(filterOrDb = {}, db) {
+  const explicitDb = isDatabaseAdapter(filterOrDb) ? filterOrDb : db;
+  const filter = isDatabaseAdapter(filterOrDb) ? {} : filterOrDb;
+  const normalized = normalizedAgentListFilter(filter);
+  if (!explicitDb && isApiMode()) {
+    const q = toQuery({
+      limit: normalized.limit,
+      offset: normalized.offset
+    });
+    const { data } = apiJson("GET", `/agents${q}`);
     return data?.agents ?? [];
   }
-  const d = db || getDatabase();
-  const rows = d.query("SELECT * FROM agents ORDER BY last_seen_at DESC").all();
+  const d = explicitDb || getDatabase();
+  const { sql, params } = paginatedAgentQuery("SELECT * FROM agents", [], normalized);
+  const rows = d.query(sql).all(...params);
   return rows.map(parseAgentRow);
 }
 function touchAgent(idOrName, db) {
@@ -55857,15 +55953,19 @@ function touchAgent(idOrName, db) {
     return;
   d.run("UPDATE agents SET last_seen_at = ? WHERE id = ?", [now(), agent.id]);
 }
-function listAgentsByProject(projectId, db) {
-  if (!db && isApiMode()) {
-    const q = toQuery({ project_id: projectId });
+function listAgentsByProject(projectId, filterOrDb = {}, db) {
+  const explicitDb = isDatabaseAdapter(filterOrDb) ? filterOrDb : db;
+  const filter = isDatabaseAdapter(filterOrDb) ? {} : filterOrDb;
+  const normalized = normalizedAgentListFilter(filter);
+  if (!explicitDb && isApiMode()) {
+    const q = toQuery({ project_id: projectId, ...normalized });
     const { data } = apiJson("GET", `/agents${q}`);
     return data?.agents ?? [];
   }
-  const d = db || getDatabase();
+  const d = explicitDb || getDatabase();
   const resolvedId = resolvePartialId(d, "projects", projectId) || projectId;
-  const rows = d.query("SELECT * FROM agents WHERE active_project_id = ? ORDER BY last_seen_at DESC").all(resolvedId);
+  const { sql, params } = paginatedAgentQuery("SELECT * FROM agents WHERE active_project_id = ?", [resolvedId], normalized);
+  const rows = d.query(sql).all(...params);
   return rows.map(parseAgentRow);
 }
 function updateAgent(id, updates, db) {

package/dist/server/index.js

@@ -1722,6 +1722,39 @@ INSERT OR IGNORE INTO _migrations (id) VALUES (35);
     `
 ${MEMORY_VERSION_SNAPSHOT_TRIGGER}
 INSERT OR IGNORE INTO _migrations (id) VALUES (36);
+`,
+    `
+DROP TRIGGER IF EXISTS audit_memory_insert;
+CREATE TRIGGER audit_memory_insert AFTER INSERT ON memories BEGIN
+  INSERT INTO memory_audit_log (id, memory_id, memory_key, operation, agent_id, created_at)
+  VALUES (hex(randomblob(4)), new.id, new.key, 'create', new.agent_id, datetime('now'));
+END;
+
+DROP TRIGGER IF EXISTS audit_memory_update;
+CREATE TRIGGER audit_memory_update AFTER UPDATE ON memories BEGIN
+  INSERT INTO memory_audit_log (id, memory_id, memory_key, operation, agent_id, changes, created_at)
+  VALUES (hex(randomblob(4)), new.id, new.key, 'update', new.agent_id,
+    json_object('version_from', old.version, 'version_to', new.version, 'importance_from', old.importance, 'importance_to', new.importance),
+    datetime('now'));
+END;
+
+DROP TRIGGER IF EXISTS audit_memory_delete;
+CREATE TRIGGER audit_memory_delete AFTER DELETE ON memories BEGIN
+  INSERT INTO memory_audit_log (id, memory_id, memory_key, operation, agent_id, created_at)
+  VALUES (hex(randomblob(4)), old.id, old.key, 'delete', old.agent_id, datetime('now'));
+END;
+
+UPDATE memory_audit_log SET old_value_hash = NULL
+  WHERE old_value_hash IS NOT NULL
+    AND length(old_value_hash) = 32
+    AND old_value_hash NOT GLOB '*[^0-9A-F]*';
+
+UPDATE memory_audit_log SET new_value_hash = NULL
+  WHERE new_value_hash IS NOT NULL
+    AND length(new_value_hash) = 32
+    AND new_value_hash NOT GLOB '*[^0-9A-F]*';
+
+INSERT OR IGNORE INTO _migrations (id) VALUES (37);
 `
   ];
 });
@@ -56147,6 +56180,7 @@ init_types();
 init_database();
 init_api_mode();
 var CONFLICT_WINDOW_MS = 30 * 60 * 1000;
+var UNBOUNDED_AGENT_LIST_LIMIT = Number.MAX_SAFE_INTEGER;
 function parseAgentRow(row) {
   return {
     id: row["id"],
@@ -56238,24 +56272,61 @@ function getAgent(idOrName, db) {
     return parseAgentRow(rows[0]);
   return null;
 }
-function listAgents(db) {
-  if (!db && isApiMode()) {
-    const { data } = apiJson("GET", "/agents");
+function normalizedAgentListFilter(filter) {
+  const limit = Number.isFinite(filter.limit) ? Math.max(0, Math.floor(filter.limit)) : undefined;
+  const offset = Number.isFinite(filter.offset) ? Math.max(0, Math.floor(filter.offset)) : undefined;
+  return { limit, offset };
+}
+function isDatabaseAdapter(value) {
+  return typeof value === "object" && value !== null && "query" in value && typeof value.query === "function";
+}
+function paginatedAgentQuery(baseSql, baseParams, filter) {
+  const { limit, offset } = normalizedAgentListFilter(filter);
+  let sql = `${baseSql} ORDER BY created_at ASC, id ASC`;
+  const params = [...baseParams];
+  if (limit !== undefined) {
+    sql += " LIMIT ?";
+    params.push(limit);
+  } else if ((offset ?? 0) > 0) {
+    sql += " LIMIT ?";
+    params.push(UNBOUNDED_AGENT_LIST_LIMIT);
+  }
+  if ((offset ?? 0) > 0) {
+    sql += " OFFSET ?";
+    params.push(offset);
+  }
+  return { sql, params };
+}
+function listAgents(filterOrDb = {}, db) {
+  const explicitDb = isDatabaseAdapter(filterOrDb) ? filterOrDb : db;
+  const filter = isDatabaseAdapter(filterOrDb) ? {} : filterOrDb;
+  const normalized = normalizedAgentListFilter(filter);
+  if (!explicitDb && isApiMode()) {
+    const q = toQuery({
+      limit: normalized.limit,
+      offset: normalized.offset
+    });
+    const { data } = apiJson("GET", `/agents${q}`);
     return data?.agents ?? [];
   }
-  const d = db || getDatabase();
-  const rows = d.query("SELECT * FROM agents ORDER BY last_seen_at DESC").all();
+  const d = explicitDb || getDatabase();
+  const { sql, params } = paginatedAgentQuery("SELECT * FROM agents", [], normalized);
+  const rows = d.query(sql).all(...params);
   return rows.map(parseAgentRow);
 }
-function listAgentsByProject(projectId, db) {
-  if (!db && isApiMode()) {
-    const q = toQuery({ project_id: projectId });
+function listAgentsByProject(projectId, filterOrDb = {}, db) {
+  const explicitDb = isDatabaseAdapter(filterOrDb) ? filterOrDb : db;
+  const filter = isDatabaseAdapter(filterOrDb) ? {} : filterOrDb;
+  const normalized = normalizedAgentListFilter(filter);
+  if (!explicitDb && isApiMode()) {
+    const q = toQuery({ project_id: projectId, ...normalized });
     const { data } = apiJson("GET", `/agents${q}`);
     return data?.agents ?? [];
   }
-  const d = db || getDatabase();
+  const d = explicitDb || getDatabase();
   const resolvedId = resolvePartialId(d, "projects", projectId) || projectId;
-  const rows = d.query("SELECT * FROM agents WHERE active_project_id = ? ORDER BY last_seen_at DESC").all(resolvedId);
+  const { sql, params } = paginatedAgentQuery("SELECT * FROM agents WHERE active_project_id = ?", [resolvedId], normalized);
+  const rows = d.query(sql).all(...params);
   return rows.map(parseAgentRow);
 }
 function updateAgent(id, updates, db) {
@@ -56418,9 +56489,21 @@ function cleanExpiredLocks(db) {
 
 // src/server/routes/agents.ts
 init_router();
+function paginationInt(value) {
+  if (value === undefined)
+    return;
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed < 0)
+    return;
+  return Math.floor(parsed);
+}
 addRoute("GET", "/api/agents", (_req, url) => {
   const q = getSearchParams(url);
-  const agents = q["project_id"] ? listAgentsByProject(q["project_id"]) : listAgents();
+  const pagination = {
+    limit: paginationInt(q["limit"]),
+    offset: paginationInt(q["cursor"] ?? q["offset"])
+  };
+  const agents = q["project_id"] ? listAgentsByProject(q["project_id"], pagination) : listAgents(pagination);
   if (q["fields"]) {
     const fields = q["fields"].split(",").map((f) => f.trim());
     const filtered = agents.map((a) => Object.fromEntries(fields.map((f) => [f, a[f]]).filter(([, v]) => v !== undefined)));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/mementos",
-  "version": "0.14.74",
+  "version": "0.14.75",
   "description": "Universal memory system for AI agents - CLI + MCP server + library API",
   "type": "module",
   "main": "dist/index.js",