@hasna/mementos 0.14.68 → 0.14.70

package/dist/server/index.js

@@ -65,6 +65,27 @@ var __export = (target, all) => {
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 var __require = import.meta.require;
 
+// src/generated/storage-kit/mode.ts
+function normalizeStorageMode(value) {
+  const normalized = value.trim().toLowerCase().replace(/-/g, "_");
+  if (normalized === "local")
+    return { mode: "local", deprecatedAlias: null };
+  if (normalized === "cloud")
+    return { mode: "cloud", deprecatedAlias: null };
+  if (DEPRECATED_STORAGE_MODE_ALIASES.includes(normalized)) {
+    return { mode: "cloud", deprecatedAlias: normalized };
+  }
+  throw new Error(`Unknown storage mode: ${value}. Use local or cloud.`);
+}
+var DEPRECATED_STORAGE_MODE_ALIASES;
+var init_mode = __esm(() => {
+  DEPRECATED_STORAGE_MODE_ALIASES = [
+    "remote",
+    "hybrid",
+    "self_hosted"
+  ];
+});
+
 // src/storage.ts
 import { Database } from "bun:sqlite";
 import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
@@ -281,18 +302,20 @@ function warnDeprecatedStorageMode(alias) {
   warnedDeprecatedModes.add(alias);
   process.emitWarning(`${MEMENTOS_STORAGE_ENV.mode}="${alias}" is deprecated; use "cloud". ` + `"${alias}" now maps to pure-remote cloud storage. The local<->remote ` + `sync path is deprecated and is not the fleet cutover path.`, { type: "DeprecationWarning", code: "MEMENTOS_STORAGE_MODE_ALIAS" });
 }
-function normalizeStorageMode(value) {
-  if (!value)
+function normalizeStorageMode2(value, source) {
+  if (!value || !value.trim())
     return null;
-  const normalized = value.trim().toLowerCase();
-  if (normalized === "local" || normalized === "cloud") {
-    return normalized;
+  let normalized;
+  try {
+    normalized = normalizeStorageMode(value);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`mementos: ${source}=${value} is not a valid mode. ${detail}`);
   }
-  if (normalized === "remote" || normalized === "hybrid") {
-    warnDeprecatedStorageMode(normalized);
-    return "cloud";
+  if (normalized.deprecatedAlias) {
+    warnDeprecatedStorageMode(normalized.deprecatedAlias);
   }
-  return null;
+  return normalized.mode;
 }
 function readConfigFile() {
   if (!existsSync2(STORAGE_CONFIG_PATH)) {
@@ -317,7 +340,7 @@ function getStorageDatabaseUrl() {
 }
 function getStorageModeOverride() {
   for (const env of MODE_ENV_NAMES) {
-    const value = normalizeStorageMode(readEnv(env.name) ?? undefined);
+    const value = normalizeStorageMode2(readEnv(env.name) ?? undefined, env.name);
     if (value)
       return value;
   }
@@ -327,7 +350,7 @@ function getStorageConfig() {
   const fileConfig = readConfigFile();
   const modeOverride = getStorageModeOverride();
   const envConnectionString = getConfiguredConnectionString();
-  const fileMode = normalizeStorageMode(fileConfig.mode);
+  const fileMode = normalizeStorageMode2(fileConfig.mode, `${STORAGE_CONFIG_PATH} "mode"`);
   const merged = {
     ...DEFAULT_STORAGE_CONFIG,
     ...fileConfig,
@@ -449,6 +472,7 @@ function getStorageConnectionString(dbName = "mementos") {
 }
 var _serverContext = false, PgSyncPool, MEMENTOS_STORAGE_ENV, MEMENTOS_STORAGE_FALLBACK_ENV, LOCAL_DATA_DIR, DEFAULT_STORAGE_CONFIG, STORAGE_CONFIG_DIR, STORAGE_CONFIG_PATH, DATABASE_ENV_NAMES, MODE_ENV_NAMES, warnedDeprecatedModes, SECRET_QUERY_PARAMS;
 var init_storage = __esm(() => {
+  init_mode();
   PgSyncPool = class PgSyncPool {
     worker;
     status;
@@ -568,7 +592,7 @@ import { tmpdir } from "os";
 import { join as join3 } from "path";
 import { writeFileSync as writeFileSync3, unlinkSync as unlinkSync2 } from "fs";
 import { randomUUID } from "crypto";
-function firstEnv(...keys) {
+function firstEnv(keys) {
   for (const k of keys) {
     const v = process.env[k]?.trim();
     if (v)
@@ -576,8 +600,38 @@ function firstEnv(...keys) {
   }
   return;
 }
+function firstEnvKey(keys) {
+  for (const k of keys) {
+    if (process.env[k]?.trim())
+      return k;
+  }
+  return null;
+}
 function hasDatabaseUrl() {
-  return Boolean(firstEnv("HASNA_MEMENTOS_DATABASE_URL", "MEMENTOS_DATABASE_URL"));
+  return Boolean(firstEnv(DATABASE_URL_ENV_KEYS));
+}
+function isLoopbackHost(rawHost) {
+  const host = rawHost.replace(/^\[/, "").replace(/\]$/, "").toLowerCase();
+  return host === "localhost" || host === "::1" || /^127\./.test(host);
+}
+function assertRequestAllowedUnderTest(baseUrl) {
+  if (process.env["NODE_ENV"] !== "test")
+    return;
+  if (process.env[ALLOW_REMOTE_API_IN_TESTS_ENV]?.trim())
+    return;
+  let host;
+  try {
+    host = new URL(baseUrl).hostname;
+  } catch {
+    host = "";
+  }
+  if (host && isLoopbackHost(host))
+    return;
+  throw new Error("api-mode: REFUSING to make a cloud request from a test process \u2014 this would write to or read " + "from the SHARED PRODUCTION memory store, where test fixtures are indistinguishable from real " + `memories.
+` + `  host           : ${host || "(unparseable base URL)"}
+` + `  how this happens: a selector set at module scope (after the bun test preload ran), or \`bun test\` ` + `invoked from a directory with no bunfig.toml so the preload never loaded.
+` + "  fix            : build the child/process env via src/test-support/store-isolation.ts, or point the " + `suite at a loopback stub.
+` + `  override       : set ${ALLOW_REMOTE_API_IN_TESTS_ENV}=1 only for a test that must reach a remote endpoint.`);
 }
 function normalizeBase(raw) {
   let base = raw.trim().replace(/\/+$/, "");
@@ -585,9 +639,24 @@ function normalizeBase(raw) {
     return base;
   return `${base}/v1`;
 }
+function assertUnambiguousStoreEnv() {
+  if (firstEnvKey(DB_PATH_ENV_KEYS))
+    return;
+  if (hasDatabaseUrl())
+    return;
+  const urlKey = firstEnvKey(API_URL_ENV_KEYS);
+  const keyKey = firstEnvKey(API_KEY_ENV_KEYS);
+  if (urlKey && !keyKey) {
+    throw new MementosStoreConfigError(`${urlKey} points at the cloud memory store but ${API_KEY_ENV_KEYS[0]} is not set. ` + `Refusing to serve the on-box SQLite store in its place, because it holds a different ` + `dataset. Set ${API_KEY_ENV_KEYS[0]} to reach the cloud store. If you meant to use the ` + `on-box SQLite store, unset ${urlKey} or set ${DB_PATH_ENV_KEYS[0]} explicitly.`);
+  }
+  if (keyKey && !urlKey) {
+    throw new MementosStoreConfigError(`${keyKey} is set but ${API_URL_ENV_KEYS[0]} is not, so the cloud memory store cannot be ` + `reached. Refusing to serve the on-box SQLite store in its place, because it holds a ` + `different dataset. Set ${API_URL_ENV_KEYS[0]} to reach the cloud store. If you meant to ` + `use the on-box SQLite store, unset ${keyKey} or set ${DB_PATH_ENV_KEYS[0]} explicitly.`);
+  }
+}
 function getApiConfig() {
-  const rawBase = firstEnv("HASNA_MEMENTOS_API_URL", "MEMENTOS_API_URL");
-  const apiKey = firstEnv("HASNA_MEMENTOS_API_KEY", "MEMENTOS_API_KEY");
+  assertUnambiguousStoreEnv();
+  const rawBase = firstEnv(API_URL_ENV_KEYS);
+  const apiKey = firstEnv(API_KEY_ENV_KEYS);
   if (!rawBase || !apiKey)
     return null;
   return { baseUrl: normalizeBase(rawBase), apiKey };
@@ -601,6 +670,7 @@ function apiRequestRaw(method, path, body) {
   const cfg = getApiConfig();
   if (!cfg)
     throw new Error("api-mode: not configured (HASNA_MEMENTOS_API_URL / HASNA_MEMENTOS_API_KEY)");
+  assertRequestAllowedUnderTest(cfg.baseUrl);
   const url = `${cfg.baseUrl}${path.startsWith("/") ? path : `/${path}`}`;
   const hasBody = body !== undefined && body !== null;
   const timeout = process.env["HASNA_MEMENTOS_API_TIMEOUT"] || DEFAULT_TIMEOUT_S;
@@ -667,13 +737,13 @@ x-api-key: ${cfg.apiKey}
   }
   return { status, body: respBody };
 }
-function apiJson(method, path, body) {
+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;
     return { status: raw.status, data };
   }
-  if (raw.status === 404) {
+  if (raw.status === 404 && options?.allow404) {
     return { status: 404, data: undefined };
   }
   let msg = `mementos cloud ${method} ${path} \u2192 ${raw.status}`;
@@ -705,8 +775,19 @@ function toQuery(params) {
   const s = sp.toString();
   return s ? `?${s}` : "";
 }
-var ApiRequestError, DEFAULT_TIMEOUT_S = "45";
+var API_URL_ENV_KEYS, API_KEY_ENV_KEYS, DATABASE_URL_ENV_KEYS, ALLOW_REMOTE_API_IN_TESTS_ENV = "MEMENTOS_ALLOW_REMOTE_API_IN_TESTS", DB_PATH_ENV_KEYS, MementosStoreConfigError, ApiRequestError, DEFAULT_TIMEOUT_S = "45";
 var init_api_mode = __esm(() => {
+  API_URL_ENV_KEYS = ["HASNA_MEMENTOS_API_URL", "MEMENTOS_API_URL"];
+  API_KEY_ENV_KEYS = ["HASNA_MEMENTOS_API_KEY", "MEMENTOS_API_KEY"];
+  DATABASE_URL_ENV_KEYS = ["HASNA_MEMENTOS_DATABASE_URL", "MEMENTOS_DATABASE_URL"];
+  DB_PATH_ENV_KEYS = ["HASNA_MEMENTOS_DB_PATH", "MEMENTOS_DB_PATH"];
+  MementosStoreConfigError = class MementosStoreConfigError extends Error {
+    code = "MEMENTOS_STORE_CONFIG";
+    constructor(message) {
+      super(message);
+      this.name = "MementosStoreConfigError";
+    }
+  };
   ApiRequestError = class ApiRequestError extends Error {
     status;
     body;
@@ -720,7 +801,24 @@ var init_api_mode = __esm(() => {
 });
 
 // src/db/migrations.ts
-var MIGRATIONS;
+var MEMORY_VERSION_SNAPSHOT_TRIGGER = `
+CREATE TRIGGER IF NOT EXISTS memories_version_snapshot
+BEFORE UPDATE ON memories
+WHEN NEW.version > OLD.version
+BEGIN
+  INSERT OR IGNORE INTO memory_versions (
+    id, memory_id, version, value, importance, scope, category, tags,
+    summary, pinned, status, when_to_use, created_at
+  ) VALUES (
+    lower(hex(randomblob(4))) || '-' || lower(hex(randomblob(2))) || '-' ||
+      lower(hex(randomblob(2))) || '-' || lower(hex(randomblob(2))) || '-' ||
+      lower(hex(randomblob(6))),
+    OLD.id, OLD.version, OLD.value, OLD.importance, OLD.scope, OLD.category,
+    OLD.tags, OLD.summary, OLD.pinned, OLD.status, OLD.when_to_use,
+    OLD.updated_at
+  );
+END;
+`, MIGRATIONS;
 var init_migrations = __esm(() => {
   MIGRATIONS = [
     `
@@ -1618,6 +1716,10 @@ CREATE INDEX IF NOT EXISTS idx_memory_reflection_lessons_memory ON memory_reflec
 CREATE INDEX IF NOT EXISTS idx_memory_reflection_lessons_kind ON memory_reflection_lessons(kind);
 
 INSERT OR IGNORE INTO _migrations (id) VALUES (35);
+`,
+    `
+${MEMORY_VERSION_SNAPSHOT_TRIGGER}
+INSERT OR IGNORE INTO _migrations (id) VALUES (36);
 `
   ];
 });
@@ -1632,6 +1734,7 @@ __export(exports_database, {
   now: () => now,
   getDbPath: () => getDbPath2,
   getDatabase: () => getDatabase,
+  escapeLikePrefix: () => escapeLikePrefix,
   closeDatabase: () => closeDatabase
 });
 import { existsSync as existsSync3, mkdirSync as mkdirSync3, cpSync as cpSync2 } from "fs";
@@ -1806,15 +1909,20 @@ function uuid() {
 function shortUuid() {
   return crypto.randomUUID().slice(0, 8);
 }
+function escapeLikePrefix(s) {
+  return s.replace(/\\/g, "\\\\").replace(/%/g, "\\%").replace(/_/g, "\\_");
+}
 function resolvePartialId(db, table, partialId) {
   if (!ALLOWED_TABLES.has(table)) {
     throw new Error(`Invalid table name: ${table}`);
   }
+  if (partialId === "")
+    return null;
   if (partialId.length >= 36) {
     const row = db.query(`SELECT id FROM ${table} WHERE id = ?`).get(partialId);
     return row?.id ?? null;
   }
-  const rows = db.query(`SELECT id FROM ${table} WHERE id LIKE ?`).all(`${partialId}%`);
+  const rows = db.query(`SELECT id FROM ${table} WHERE id LIKE ? ESCAPE '\\'`).all(`${escapeLikePrefix(partialId)}%`);
   if (rows.length === 1) {
     return rows[0].id;
   }
@@ -1926,8 +2034,19 @@ var init_hooks = __esm(() => {
 });
 
 // src/types/index.ts
-var AgentConflictError, EntityNotFoundError, MemoryNotFoundError, DuplicateMemoryError, VersionConflictError, MemoryConflictError;
+var MEMORY_SCOPES, MEMORY_CATEGORIES, MEMORY_SOURCES, MEMORY_STATUSES, AgentConflictError, EntityNotFoundError, MemoryNotFoundError, DuplicateMemoryError, VersionConflictError, MemoryConflictError;
 var init_types = __esm(() => {
+  MEMORY_SCOPES = ["global", "shared", "private", "working"];
+  MEMORY_CATEGORIES = [
+    "preference",
+    "fact",
+    "knowledge",
+    "history",
+    "procedural",
+    "resource"
+  ];
+  MEMORY_SOURCES = ["user", "agent", "system", "auto", "imported"];
+  MEMORY_STATUSES = ["active", "archived", "expired"];
   AgentConflictError = class AgentConflictError extends Error {
     conflict = true;
     existing_id;
@@ -2090,6 +2209,41 @@ var init_redact = __esm(() => {
   ];
 });
 
+// src/lib/enum-validation.ts
+function formatEnumViolation(v) {
+  return `Invalid ${v.field}: "${v.value}". Allowed values: ${v.allowed.join(", ")}.`;
+}
+function validateEnumField(field, value) {
+  const allowed = ENUM_FIELDS[field];
+  if (!allowed)
+    return null;
+  if (value === undefined || value === null || value === "")
+    return null;
+  if (typeof value === "string" && allowed.includes(value))
+    return null;
+  return { field, value: String(value), allowed };
+}
+function validateMemoryEnums(input) {
+  for (const field of Object.keys(ENUM_FIELDS)) {
+    if (!(field in input))
+      continue;
+    const violation = validateEnumField(field, input[field]);
+    if (violation)
+      return violation;
+  }
+  return null;
+}
+var ENUM_FIELDS;
+var init_enum_validation = __esm(() => {
+  init_types();
+  ENUM_FIELDS = {
+    category: MEMORY_CATEGORIES,
+    scope: MEMORY_SCOPES,
+    source: MEMORY_SOURCES,
+    status: MEMORY_STATUSES
+  };
+});
+
 // src/lib/poisoning.ts
 function computeTrustScore(value, key, existingMemories, claimedImportance) {
   let score = 1;
@@ -2320,7 +2474,10 @@ function parseMemoryRow(row) {
 }
 function createMemory(input, dedupeMode = "merge", db) {
   if (!db && isApiMode()) {
-    const { data } = apiJson("POST", "/memories", { ...input, dedupe: dedupeMode });
+    const { status, data } = apiJson("POST", "/memories", { ...input, dedupe: dedupeMode });
+    if (!data || !data.id) {
+      throw new ApiRequestError(`mementos cloud POST /memories \u2192 ${status} but no memory was returned; the write did not persist (key: ${input.key})`, status, "");
+    }
     return data;
   }
   const d = db || getDatabase();
@@ -2459,16 +2616,25 @@ function bulkUpsertMemories(memories, db) {
   const d = db || getDatabase();
   let inserted = 0;
   let skipped = 0;
+  let rejected = 0;
   const errors = [];
-  const insert = d.prepare(`INSERT OR IGNORE INTO memories (id, key, value, category, scope, summary, tags, importance, source, status, pinned, agent_id, project_id, session_id, machine_id, namespace, created_by_agent, when_to_use, sequence_group, sequence_order, metadata, access_count, version, expires_at, valid_from, valid_until, ingested_at, created_at, updated_at)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+  const insert = d.prepare(`INSERT INTO memories (id, key, value, category, scope, summary, tags, importance, source, status, pinned, agent_id, project_id, session_id, machine_id, namespace, created_by_agent, when_to_use, sequence_group, sequence_order, metadata, access_count, version, expires_at, valid_from, valid_until, ingested_at, created_at, updated_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT DO NOTHING`);
   const insertTag = d.prepare("INSERT OR IGNORE INTO memory_tags (memory_id, tag) VALUES (?, ?)");
   for (const mem of memories) {
     const key = mem["key"];
     const id = mem["id"] || uuid();
     try {
       if (!key) {
-        errors.push(`skipped row without key (id=${id})`);
+        rejected++;
+        errors.push(`rejected row without key (id=${id})`);
+        continue;
+      }
+      const violation = validateMemoryEnums(mem);
+      if (violation) {
+        rejected++;
+        errors.push(`Rejected "${key}": ${formatEnumViolation(violation)}`);
         continue;
       }
       const timestamp = now();
@@ -2517,10 +2683,11 @@ function bulkUpsertMemories(memories, db) {
         skipped++;
       }
     } catch (e) {
+      rejected++;
       errors.push(`Failed "${String(key)}": ${e instanceof Error ? e.message : String(e)}`);
     }
   }
-  return { inserted, skipped, errors, total: memories.length };
+  return { inserted, skipped, rejected, errors, total: memories.length };
 }
 function ensureMemoryReferences(d, input) {
   const t = now();
@@ -2548,7 +2715,7 @@ function listMemoriesByKey(key, db) {
 }
 function getMemory(id, db) {
   if (!db && isApiMode()) {
-    const { status, data } = apiJson("GET", `/memories/${encodeURIComponent(id)}`);
+    const { status, data } = apiJson("GET", `/memories/${encodeURIComponent(id)}`, undefined, { allow404: true });
     return status === 404 ? null : data ?? null;
   }
   const d = db || getDatabase();
@@ -2881,36 +3048,22 @@ function getMemoryEmbeddings(ids, db) {
 }
 function updateMemory(id, input, db) {
   if (!db && isApiMode()) {
-    const { status, data } = apiJson("PATCH", `/memories/${encodeURIComponent(id)}`, input);
+    const { status, data } = apiJson("PATCH", `/memories/${encodeURIComponent(id)}`, input, { allow404: true });
     if (status === 404)
       throw new MemoryNotFoundError(id);
+    if (data && typeof input.version === "number" && typeof data.version === "number" && data.version <= input.version) {
+      throw new Error(`Update did not persist for memory ${id}: the server returned success but the record is unchanged ` + `(version still ${data.version}). Your data was NOT written. ` + `The server is likely running a build predating the partial-id fix \u2014 pass the full 36-character id as a workaround.`);
+    }
     return data;
   }
   const d = db || getDatabase();
   const existing = getMemory(id, d);
   if (!existing)
     throw new MemoryNotFoundError(id);
+  const memoryId = existing.id;
   if (existing.version !== input.version) {
     throw new VersionConflictError(id, input.version, existing.version);
   }
-  try {
-    d.run(`INSERT OR IGNORE INTO memory_versions (id, memory_id, version, value, importance, scope, category, tags, summary, pinned, status, when_to_use, created_at)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
-      uuid(),
-      existing.id,
-      existing.version,
-      existing.value,
-      existing.importance,
-      existing.scope,
-      existing.category,
-      JSON.stringify(existing.tags),
-      existing.summary,
-      existing.pinned ? 1 : 0,
-      existing.status,
-      existing.when_to_use || null,
-      existing.updated_at
-    ]);
-  } catch {}
   const sets = ["version = version + 1", "updated_at = ?"];
   const params = [now()];
   if (input.value !== undefined) {
@@ -2960,15 +3113,18 @@ function updateMemory(id, input, db) {
   if (input.tags !== undefined) {
     sets.push("tags = ?");
     params.push(JSON.stringify(input.tags));
-    d.run("DELETE FROM memory_tags WHERE memory_id = ?", [id]);
+    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(id, tag);
+      insertTag.run(memoryId, tag);
     }
   }
-  params.push(id);
-  d.run(`UPDATE memories SET ${sets.join(", ")} WHERE id = ?`, params);
-  const updated = getMemory(id, d);
+  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.`);
+  }
+  const updated = getMemory(memoryId, d);
   if (input.value !== undefined) {
     try {
       const oldLinks = getEntityMemoryLinks(undefined, updated.id, d);
@@ -2989,14 +3145,15 @@ function updateMemory(id, input, db) {
 }
 function deleteMemory(id, db) {
   if (!db && isApiMode()) {
-    const { status } = apiJson("DELETE", `/memories/${encodeURIComponent(id)}`);
+    const { status } = apiJson("DELETE", `/memories/${encodeURIComponent(id)}`, undefined, { allow404: true });
     return status !== 404;
   }
   const d = db || getDatabase();
-  const result = d.run("DELETE FROM memories WHERE id = ?", [id]);
+  const memoryId = resolvePartialId(d, "memories", id) ?? id;
+  const result = d.run("DELETE FROM memories WHERE id = ?", [memoryId]);
   if (result.changes > 0) {
     hookRegistry.runHooks("PostMemoryDelete", {
-      memoryId: id,
+      memoryId,
       timestamp: Date.now()
     });
   }
@@ -3010,11 +3167,12 @@ function bulkDeleteMemories(ids, db) {
     return data?.deleted ?? 0;
   }
   const d = db || getDatabase();
-  const placeholders = ids.map(() => "?").join(",");
-  const countRow = d.query(`SELECT COUNT(*) as c FROM memories WHERE id IN (${placeholders})`).get(...ids);
+  const resolvedIds = ids.map((id) => resolvePartialId(d, "memories", id) ?? id);
+  const placeholders = resolvedIds.map(() => "?").join(",");
+  const countRow = d.query(`SELECT COUNT(*) as c FROM memories WHERE id IN (${placeholders})`).get(...resolvedIds);
   const count = countRow.c;
   if (count > 0) {
-    d.run(`DELETE FROM memories WHERE id IN (${placeholders})`, ids);
+    d.run(`DELETE FROM memories WHERE id IN (${placeholders})`, resolvedIds);
   }
   return count;
 }
@@ -3141,6 +3299,7 @@ var init_memories = __esm(() => {
   init_types();
   init_database();
   init_redact();
+  init_enum_validation();
   init_hooks();
   init_poisoning();
   init_entity_memories();
@@ -3209,7 +3368,7 @@ function createEntity(input, db) {
 }
 function getEntity(id, db) {
   if (!db && isApiMode()) {
-    const { status, data } = apiJson("GET", `/entities/${encodeURIComponent(id)}`);
+    const { status, data } = apiJson("GET", `/entities/${encodeURIComponent(id)}`, undefined, { allow404: true });
     if (status === 404 || !data)
       throw new EntityNotFoundError(id);
     return data;
@@ -3292,7 +3451,7 @@ function listEntities(filter = {}, db) {
 }
 function updateEntity(id, input, db) {
   if (!db && isApiMode()) {
-    const { status, data } = apiJson("PATCH", `/entities/${encodeURIComponent(id)}`, input);
+    const { status, data } = apiJson("PATCH", `/entities/${encodeURIComponent(id)}`, input, { allow404: true });
     if (status === 404 || !data)
       throw new EntityNotFoundError(id);
     return data;
@@ -3325,7 +3484,7 @@ function updateEntity(id, input, db) {
 }
 function deleteEntity(id, db) {
   if (!db && isApiMode()) {
-    const { status } = apiJson("DELETE", `/entities/${encodeURIComponent(id)}`);
+    const { status } = apiJson("DELETE", `/entities/${encodeURIComponent(id)}`, undefined, { allow404: true });
     if (status === 404)
       throw new EntityNotFoundError(id);
     return;
@@ -4253,7 +4412,7 @@ function createRelation(input, db) {
 }
 function getRelation(id, db) {
   if (!db && isApiMode()) {
-    const { status, data } = apiJson("GET", `/relations/${encodeURIComponent(id)}`);
+    const { status, data } = apiJson("GET", `/relations/${encodeURIComponent(id)}`, undefined, { allow404: true });
     if (status === 404 || !data)
       throw new Error(`Relation not found: ${id}`);
     return data;
@@ -4298,7 +4457,7 @@ function listRelations(filter, db) {
 }
 function deleteRelation(id, db) {
   if (!db && isApiMode()) {
-    const { status } = apiJson("DELETE", `/relations/${encodeURIComponent(id)}`);
+    const { status } = apiJson("DELETE", `/relations/${encodeURIComponent(id)}`, undefined, { allow404: true });
     if (status === 404)
       throw new Error(`Relation not found: ${id}`);
     return;
@@ -4947,6 +5106,32 @@ class AutoMemoryQueue {
   getStats() {
     return { ...this.stats, pending: this.queue.length };
   }
+  async waitForIdleForTests(timeoutMs = 3000) {
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+      if (this.queue.length === 0 && this.activeCount === 0)
+        return;
+      await new Promise((r) => setTimeout(r, 20));
+    }
+    throw new Error("autoMemoryQueue did not become idle before test reset");
+  }
+  resetForTests(handler) {
+    if (this.activeCount !== 0) {
+      throw new Error("Cannot reset autoMemoryQueue while jobs are processing");
+    }
+    this.queue = [];
+    this.running = false;
+    this.stats = {
+      pending: 0,
+      processing: 0,
+      processed: 0,
+      failed: 0,
+      dropped: 0
+    };
+    if (handler !== undefined) {
+      this.handler = handler;
+    }
+  }
   startLoop() {
     this.running = true;
     this.loop();
@@ -4992,6 +5177,7 @@ var init_auto_memory_queue = __esm(() => {
 // src/lib/auto-memory.ts
 var exports_auto_memory = {};
 __export(exports_auto_memory, {
+  resetAutoMemoryForTests: () => resetAutoMemoryForTests,
   processConversationTurn: () => processConversationTurn,
   getAutoMemoryStats: () => getAutoMemoryStats,
   configureAutoMemory: () => configureAutoMemory
@@ -5152,6 +5338,12 @@ function getAutoMemoryStats() {
 function configureAutoMemory(config) {
   providerRegistry.configure(config);
 }
+async function resetAutoMemoryForTests() {
+  if (autoMemoryQueue.getStats().processing > 0) {
+    await autoMemoryQueue.waitForIdleForTests();
+  }
+  autoMemoryQueue.resetForTests(processJob);
+}
 var DEDUP_SIMILARITY_THRESHOLD = 0.85;
 var init_auto_memory = __esm(() => {
   init_memories();
@@ -52822,7 +53014,7 @@ function createWebhookHook(input, db) {
 }
 function getWebhookHook(id, db) {
   if (!db && isApiMode()) {
-    const { status, data } = apiJson("GET", `/webhooks/${encodeURIComponent(id)}`);
+    const { status, data } = apiJson("GET", `/webhooks/${encodeURIComponent(id)}`, undefined, { allow404: true });
     if (status === 404 || !data)
       return null;
     return data;
@@ -52858,7 +53050,7 @@ function updateWebhookHook(id, updates, db) {
       enabled: updates.enabled,
       priority: updates.priority,
       description: updates.description
-    });
+    }, { allow404: true });
     if (status === 404 || !data)
       return null;
     return data;
@@ -52889,7 +53081,7 @@ function updateWebhookHook(id, updates, db) {
 }
 function deleteWebhookHook(id, db) {
   if (!db && isApiMode()) {
-    const { status } = apiJson("DELETE", `/webhooks/${encodeURIComponent(id)}`);
+    const { status } = apiJson("DELETE", `/webhooks/${encodeURIComponent(id)}`, undefined, { allow404: true });
     return status === 204 || status === 200;
   }
   const d = db || getDatabase();
@@ -52924,6 +53116,8 @@ hookRegistry.register({
   priority: 100,
   description: "Trigger async LLM entity extraction when a memory is saved",
   handler: async (ctx) => {
+    if (process.env["NODE_ENV"] === "test")
+      return;
     if (ctx.wasUpdated)
       return;
     const processConversationTurn2 = await getAutoMemory();
@@ -53161,7 +53355,7 @@ function createSessionJob(input, db) {
 }
 function getSessionJob(id, db) {
   if (!db && isApiMode()) {
-    const { status, data } = apiJson("GET", `/sessions/jobs/${encodeURIComponent(id)}`);
+    const { status, data } = apiJson("GET", `/sessions/jobs/${encodeURIComponent(id)}`, undefined, { allow404: true });
     if (status === 404 || !data)
       return null;
     return data;
@@ -54296,6 +54490,16 @@ function errorResponse(message, status, details) {
     body["details"] = details;
   return json(body, status);
 }
+function describeConstraintViolation(e) {
+  if (!e || typeof e !== "object")
+    return null;
+  const code = String(e.code ?? "");
+  const message = String(e.message ?? "");
+  const isConstraint = code.startsWith("SQLITE_CONSTRAINT") || /^23\d{3}$/.test(code) || /constraint failed/i.test(message);
+  if (!isConstraint)
+    return null;
+  return `Request rejected by a database constraint: ${message || code}. Check that enum fields (category, scope, source, status) and referenced ids are valid.`;
+}
 var MAX_BODY_BYTES = 1 * 1024 * 1024;
 async function readJson(req) {
   try {
@@ -54496,6 +54700,7 @@ var FORMAT_UNITS = [
 
 // src/server/routes/memories-crud.ts
 init_router();
+init_enum_validation();
 init_types();
 addRoute("GET", "/api/memories", (_req, url) => {
   const q = getSearchParams(url);
@@ -54544,6 +54749,14 @@ addRoute("POST", "/api/memories", async (req) => {
   if (!body["key"] || !body["value"]) {
     return errorResponse("Missing required fields: key, value", 400);
   }
+  const violation = validateMemoryEnums(body);
+  if (violation) {
+    return errorResponse(formatEnumViolation(violation), 400, {
+      field: violation.field,
+      value: violation.value,
+      allowed: violation.allowed
+    });
+  }
   try {
     if (body["ttl_ms"] !== undefined && typeof body["ttl_ms"] === "string") {
       body["ttl_ms"] = parseDuration(body["ttl_ms"]);
@@ -54573,6 +54786,14 @@ addRoute("PATCH", "/api/memories/:id", async (req, _url, params) => {
   if (!body) {
     return errorResponse("Invalid JSON body", 400);
   }
+  const patchViolation = validateMemoryEnums(body);
+  if (patchViolation) {
+    return errorResponse(formatEnumViolation(patchViolation), 400, {
+      field: patchViolation.field,
+      value: patchViolation.value,
+      allowed: patchViolation.allowed
+    });
+  }
   const updateBody = { ...body };
   if (updateBody["version"] === undefined) {
     const existing = getMemory(params["id"]);
@@ -55602,6 +55823,12 @@ addRoute("POST", "/api/memories/bulk-upsert", async (req) => {
   }
   const memoriesArr = body["memories"];
   const result = bulkUpsertMemories(memoriesArr);
+  if (result.rejected > 0) {
+    return json({
+      ...result,
+      error: `${result.rejected} of ${result.total} memories were rejected and did not persist. See errors.`
+    }, 400);
+  }
   return json(result, 201);
 });
 
@@ -55985,7 +56212,7 @@ function registerAgent(name, sessionId, description, role, projectId, db) {
 }
 function getAgent(idOrName, db) {
   if (!db && isApiMode()) {
-    const { status, data } = apiJson("GET", `/agents/${encodeURIComponent(idOrName)}`);
+    const { status, data } = apiJson("GET", `/agents/${encodeURIComponent(idOrName)}`, undefined, { allow404: true });
     if (status === 404 || !data)
       return null;
     return data;
@@ -55997,7 +56224,7 @@ function getAgent(idOrName, db) {
   row = d.query("SELECT * FROM agents WHERE LOWER(name) = ?").get(idOrName.trim().toLowerCase());
   if (row)
     return parseAgentRow(row);
-  const rows = d.query("SELECT * FROM agents WHERE id LIKE ?").all(`${idOrName}%`);
+  const rows = d.query("SELECT * FROM agents WHERE id LIKE ? ESCAPE '\\'").all(`${escapeLikePrefix(idOrName)}%`);
   if (rows.length === 1)
     return parseAgentRow(rows[0]);
   return null;
@@ -56024,7 +56251,7 @@ function listAgentsByProject(projectId, db) {
 }
 function updateAgent(id, updates, db) {
   if (!db && isApiMode()) {
-    const { status, data } = apiJson("PATCH", `/agents/${encodeURIComponent(id)}`, updates);
+    const { status, data } = apiJson("PATCH", `/agents/${encodeURIComponent(id)}`, updates, { allow404: true });
     if (status === 404 || !data)
       return null;
     return data;
@@ -56132,7 +56359,7 @@ function acquireLock(agentId, resourceType, resourceId, lockType = "exclusive",
 }
 function releaseLock(lockId, agentId, db) {
   if (!db && isApiMode()) {
-    const { status } = apiJson("DELETE", `/locks/${encodeURIComponent(lockId)}`, { agent_id: agentId });
+    const { status } = apiJson("DELETE", `/locks/${encodeURIComponent(lockId)}`, { agent_id: agentId }, { allow404: true });
     return status !== 404;
   }
   const d = db || getDatabase();
@@ -56315,7 +56542,7 @@ function registerProject(name, path, description, memoryPrefix, db) {
 }
 function getProject(idOrPath, db) {
   if (!db && isApiMode()) {
-    const { status, data } = apiJson("GET", `/projects/${encodeURIComponent(idOrPath)}`);
+    const { status, data } = apiJson("GET", `/projects/${encodeURIComponent(idOrPath)}`, undefined, { allow404: true });
     if (status === 404 || !data)
       return null;
     return data;
@@ -59043,7 +59270,7 @@ function createSubscription(input, db) {
 }
 function deleteSubscription(id, db) {
   if (!db && isApiMode()) {
-    const { status } = apiJson("DELETE", `/subscriptions/${encodeURIComponent(id)}`);
+    const { status } = apiJson("DELETE", `/subscriptions/${encodeURIComponent(id)}`, undefined, { allow404: true });
     return status !== 404;
   }
   const d = db || getDatabase();
@@ -59337,6 +59564,11 @@ function startServer(port) {
       try {
         return await matched.handler(req, url2, matched.params);
       } catch (e) {
+        const constraint = describeConstraintViolation(e);
+        if (constraint) {
+          console.warn(`[mementos-serve] ${req.method} ${pathname}: rejected \u2014 ${constraint}`);
+          return errorResponse(constraint, 400);
+        }
         console.error(`[mementos-serve] ${req.method} ${pathname}:`, e);
         return errorResponse("Internal server error", 500);
       }