@hasna/mementos 0.14.68 → 0.14.70

package/dist/cli/index.js

@@ -2099,11 +2099,32 @@ var require_commander = __commonJS((exports) => {
   exports.InvalidOptionArgumentError = InvalidArgumentError;
 });
 
+// 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, readFileSync, writeFileSync } from "fs";
-import { homedir as homedir2 } from "os";
-import { join as join2 } from "path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
 import { fileURLToPath } from "url";
 import { Worker } from "worker_threads";
 import pg from "pg";
@@ -2357,21 +2378,23 @@ 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)) {
+  if (!existsSync(STORAGE_CONFIG_PATH)) {
     return {};
   }
   try {
@@ -2398,7 +2421,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;
   }
@@ -2408,7 +2431,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,
@@ -2819,6 +2842,7 @@ CREATE TABLE IF NOT EXISTS _sync_meta (
   direction TEXT DEFAULT 'push'
 )`;
 var init_storage = __esm(() => {
+  init_mode();
   PgSyncPool = class PgSyncPool {
     worker;
     status;
@@ -2831,12 +2855,12 @@ var init_storage = __esm(() => {
       const ext = import.meta.url.endsWith(".ts") ? ".ts" : ".js";
       const here = fileURLToPath(new URL(".", import.meta.url));
       const candidates = [
-        join2(here, `pg-sync-worker${ext}`),
-        join2(here, "..", `pg-sync-worker${ext}`),
-        join2(here, "..", "..", `pg-sync-worker${ext}`)
+        join(here, `pg-sync-worker${ext}`),
+        join(here, "..", `pg-sync-worker${ext}`),
+        join(here, "..", "..", `pg-sync-worker${ext}`)
       ];
       for (const candidate of candidates) {
-        if (existsSync2(candidate))
+        if (existsSync(candidate))
           return candidate;
       }
       return candidates[0];
@@ -2911,7 +2935,7 @@ var init_storage = __esm(() => {
     databaseUrl: "MEMENTOS_DATABASE_URL",
     mode: "MEMENTOS_STORAGE_MODE"
   };
-  LOCAL_DATA_DIR = join2(homedir2(), ".hasna", "mementos");
+  LOCAL_DATA_DIR = join(homedir(), ".hasna", "mementos");
   DEFAULT_STORAGE_CONFIG = {
     rds: {
       host: "",
@@ -2927,8 +2951,8 @@ var init_storage = __esm(() => {
       schedule_minutes: 0
     }
   };
-  STORAGE_CONFIG_DIR = join2(LOCAL_DATA_DIR, "storage");
-  STORAGE_CONFIG_PATH = join2(STORAGE_CONFIG_DIR, "config.json");
+  STORAGE_CONFIG_DIR = join(LOCAL_DATA_DIR, "storage");
+  STORAGE_CONFIG_PATH = join(STORAGE_CONFIG_DIR, "config.json");
   DATABASE_ENV_NAMES = [
     { name: MEMENTOS_STORAGE_ENV.databaseUrl, deprecated: false },
     { name: MEMENTOS_STORAGE_FALLBACK_ENV.databaseUrl, deprecated: false }
@@ -2958,10 +2982,10 @@ var init_storage = __esm(() => {
 
 // src/db/api-mode.ts
 import { tmpdir } from "os";
-import { join as join3 } from "path";
+import { join as join2 } from "path";
 import { writeFileSync as writeFileSync2, unlinkSync } from "fs";
-import { randomUUID as randomUUID3 } from "crypto";
-function firstEnv(...keys) {
+import { randomUUID } from "crypto";
+function firstEnv(keys) {
   for (const k of keys) {
     const v = process.env[k]?.trim();
     if (v)
@@ -2969,8 +2993,45 @@ 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 getApiModeEnvSources() {
+  return {
+    urlKey: firstEnvKey(API_URL_ENV_KEYS),
+    keyKey: firstEnvKey(API_KEY_ENV_KEYS),
+    databaseUrlKey: firstEnvKey(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(/\/+$/, "");
@@ -2978,9 +3039,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 };
@@ -2994,6 +3070,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;
@@ -3019,7 +3096,7 @@ x-api-key: ${cfg.apiKey}
   ];
   let bodyFile;
   if (hasBody) {
-    bodyFile = join3(tmpdir(), `mem-req-${process.pid}-${randomUUID3()}.json`);
+    bodyFile = join2(tmpdir(), `mem-req-${process.pid}-${randomUUID()}.json`);
     writeFileSync2(bodyFile, JSON.stringify(body), { mode: 384 });
     args.push("--data-binary", `@${bodyFile}`);
   }
@@ -3060,13 +3137,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}`;
@@ -3098,8 +3175,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;
@@ -3113,7 +3201,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 = [
     `
@@ -4011,6 +4116,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);
 `
   ];
 });
@@ -4022,13 +4131,14 @@ __export(exports_database, {
   shortUuid: () => shortUuid,
   resolvePartialId: () => resolvePartialId,
   resetDatabase: () => resetDatabase,
-  now: () => now2,
+  now: () => now,
   getDbPath: () => getDbPath,
   getDatabase: () => getDatabase,
+  escapeLikePrefix: () => escapeLikePrefix,
   closeDatabase: () => closeDatabase
 });
-import { existsSync as existsSync3, mkdirSync as mkdirSync2, cpSync } from "fs";
-import { dirname, join as join4, resolve } from "path";
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, cpSync } from "fs";
+import { dirname, join as join3, resolve } from "path";
 function isInMemoryDb(path) {
   return path === ":memory:" || path.startsWith("file::memory:");
 }
@@ -4037,8 +4147,8 @@ function findNearestMementosDb(startDir) {
   const home = process.env["HOME"] || process.env["USERPROFILE"] || "~";
   const legacyHomeDb = resolve(home, ".mementos", "mementos.db");
   while (true) {
-    const candidate = join4(dir, ".mementos", "mementos.db");
-    if (existsSync3(candidate) && resolve(candidate) !== legacyHomeDb)
+    const candidate = join3(dir, ".mementos", "mementos.db");
+    if (existsSync2(candidate) && resolve(candidate) !== legacyHomeDb)
       return candidate;
     const parent = dirname(dir);
     if (parent === dir)
@@ -4050,7 +4160,7 @@ function findNearestMementosDb(startDir) {
 function findGitRoot(startDir) {
   let dir = resolve(startDir);
   while (true) {
-    if (existsSync3(join4(dir, ".git")))
+    if (existsSync2(join3(dir, ".git")))
       return dir;
     const parent = dirname(dir);
     if (parent === dir)
@@ -4061,10 +4171,10 @@ function findGitRoot(startDir) {
 }
 function migrateGlobalDir() {
   const home = process.env["HOME"] || process.env["USERPROFILE"] || "~";
-  const newDir = join4(home, ".hasna", "mementos");
-  const oldDir = join4(home, ".mementos");
-  if (!existsSync3(newDir) && existsSync3(oldDir)) {
-    mkdirSync2(join4(home, ".hasna"), { recursive: true });
+  const newDir = join3(home, ".hasna", "mementos");
+  const oldDir = join3(home, ".mementos");
+  if (!existsSync2(newDir) && existsSync2(oldDir)) {
+    mkdirSync2(join3(home, ".hasna"), { recursive: true });
     cpSync(oldDir, newDir, { recursive: true });
   }
 }
@@ -4080,18 +4190,18 @@ function getDbPath() {
   if (process.env["MEMENTOS_DB_SCOPE"] === "project") {
     const gitRoot = findGitRoot(cwd);
     if (gitRoot) {
-      return join4(gitRoot, ".mementos", "mementos.db");
+      return join3(gitRoot, ".mementos", "mementos.db");
     }
   }
   migrateGlobalDir();
   const home = process.env["HOME"] || process.env["USERPROFILE"] || "~";
-  return join4(home, ".hasna", "mementos", "mementos.db");
+  return join3(home, ".hasna", "mementos", "mementos.db");
 }
 function ensureDir(filePath) {
   if (isInMemoryDb(filePath))
     return;
   const dir = dirname(resolve(filePath));
-  if (!existsSync3(dir)) {
+  if (!existsSync2(dir)) {
     mkdirSync2(dir, { recursive: true });
   }
 }
@@ -4190,7 +4300,7 @@ function resetDatabase() {
   _db = null;
   _pg = null;
 }
-function now2() {
+function now() {
   return new Date().toISOString();
 }
 function uuid() {
@@ -4199,15 +4309,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;
   }
@@ -4236,8 +4351,19 @@ var init_database = __esm(() => {
 });
 
 // src/types/index.ts
-var AgentConflictError, EntityNotFoundError, MemoryNotFoundError, VersionConflictError, MemoryConflictError;
+var MEMORY_SCOPES, MEMORY_CATEGORIES, MEMORY_SOURCES, MEMORY_STATUSES, AgentConflictError, EntityNotFoundError, MemoryNotFoundError, 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;
@@ -4394,6 +4520,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/hooks.ts
 var exports_hooks = {};
 __export(exports_hooks, {
@@ -4565,7 +4726,7 @@ function linkEntityToMemory(entityId, memoryId, role = "context", db) {
     return data;
   }
   const d = db || getDatabase();
-  const timestamp = now2();
+  const timestamp = now();
   d.run(`INSERT OR IGNORE INTO entity_memories (entity_id, memory_id, role, created_at)
      VALUES (?, ?, ?, ?)`, [entityId, memoryId, role, timestamp]);
   const row = d.query("SELECT * FROM entity_memories WHERE entity_id = ? AND memory_id = ?").get(entityId, memoryId);
@@ -4691,11 +4852,14 @@ 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();
-  const timestamp = now2();
+  const timestamp = now();
   if (input.project_id) {
     const resolved = resolvePartialId(d, "projects", input.project_id);
     if (resolved) {
@@ -4830,19 +4994,28 @@ 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 = now2();
+      const timestamp = now();
       let tags = [];
       const rawTags = mem["tags"];
       if (Array.isArray(rawTags)) {
@@ -4888,13 +5061,14 @@ 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 = now2();
+  const t = now();
   const tryRun = (sql, params) => {
     try {
       d.run(sql, params);
@@ -4919,7 +5093,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();
@@ -5252,38 +5426,24 @@ 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 = [now2()];
+  const params = [now()];
   if (input.value !== undefined) {
     sets.push("value = ?");
     params.push(redactSecrets(input.value));
@@ -5331,15 +5491,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);
@@ -5360,14 +5523,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()
     });
   }
@@ -5381,11 +5545,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;
 }
@@ -5393,14 +5558,14 @@ function touchMemory(id, db) {
   if (!db && isApiMode())
     return;
   const d = db || getDatabase();
-  d.run("UPDATE memories SET access_count = access_count + 1, accessed_at = ? WHERE id = ?", [now2(), id]);
+  d.run("UPDATE memories SET access_count = access_count + 1, accessed_at = ? WHERE id = ?", [now(), id]);
 }
 function incrementRecallCount(id, db) {
   if (!db && isApiMode())
     return;
   const d = db || getDatabase();
   try {
-    d.run("UPDATE memories SET recall_count = recall_count + 1, access_count = access_count + 1, accessed_at = ? WHERE id = ?", [now2(), id]);
+    d.run("UPDATE memories SET recall_count = recall_count + 1, access_count = access_count + 1, accessed_at = ? WHERE id = ?", [now(), id]);
     const row = d.query("SELECT recall_count, importance FROM memories WHERE id = ?").get(id);
     if (!row)
       return;
@@ -5417,7 +5582,7 @@ function cleanExpiredMemories(db) {
     return data?.cleaned ?? 0;
   }
   const d = db || getDatabase();
-  const timestamp = now2();
+  const timestamp = now();
   const countRow = d.query("SELECT COUNT(*) as c FROM memories WHERE expires_at IS NOT NULL AND expires_at < ?").get(timestamp);
   const count = countRow.c;
   if (count > 0) {
@@ -5512,6 +5677,7 @@ var init_memories = __esm(() => {
   init_types();
   init_database();
   init_redact();
+  init_enum_validation();
   init_hooks();
   init_poisoning();
   init_entity_memories();
@@ -5547,7 +5713,7 @@ function registerProject(name, path, description, memoryPrefix, db) {
     return data;
   }
   const d = db || getDatabase();
-  const timestamp = now2();
+  const timestamp = now();
   const existing = d.query("SELECT * FROM projects WHERE path = ?").get(path);
   if (existing) {
     const existingId = existing["id"];
@@ -5563,7 +5729,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;
@@ -5613,7 +5779,7 @@ function createEntity(input, db) {
     return data;
   }
   const d = db || getDatabase();
-  const timestamp = now2();
+  const timestamp = now();
   const metadataJson = JSON.stringify(input.metadata || {});
   const existing = d.query(`SELECT * FROM entities
        WHERE name = ? AND type = ? AND COALESCE(project_id, '') = ?`).get(input.name, input.type, input.project_id || "");
@@ -5656,7 +5822,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;
@@ -5739,7 +5905,7 @@ function listEntities(filter = {}, 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;
@@ -5789,7 +5955,7 @@ function mergeEntities(sourceId, targetId, db) {
   d.run(`UPDATE entity_memories SET entity_id = ? WHERE entity_id = ?`, [tgt, src]);
   d.run("DELETE FROM entity_memories WHERE entity_id = ?", [src]);
   d.run("DELETE FROM entities WHERE id = ?", [src]);
-  d.run("UPDATE entities SET updated_at = ? WHERE id = ?", [now2(), tgt]);
+  d.run("UPDATE entities SET updated_at = ? WHERE id = ?", [now(), tgt]);
   return getEntity(tgt, d);
 }
 var init_entities = __esm(() => {
@@ -6454,7 +6620,7 @@ function registerAgent(name, sessionId, description, role, projectId, db) {
     return data;
   }
   const d = db || getDatabase();
-  const timestamp = now2();
+  const timestamp = now();
   const normalizedName = name.trim().toLowerCase();
   if (projectId) {
     const resolvedProjectId = resolvePartialId(d, "projects", projectId);
@@ -6503,7 +6669,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;
@@ -6515,7 +6681,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;
@@ -6541,7 +6707,7 @@ function touchAgent(idOrName, db) {
   const agent = getAgent(idOrName, d);
   if (!agent)
     return;
-  d.run("UPDATE agents SET last_seen_at = ? WHERE id = ?", [now2(), agent.id]);
+  d.run("UPDATE agents SET last_seen_at = ? WHERE id = ?", [now(), agent.id]);
 }
 function listAgentsByProject(projectId, db) {
   if (!db && isApiMode()) {
@@ -6556,7 +6722,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;
@@ -6565,7 +6731,7 @@ function updateAgent(id, updates, db) {
   const agent = getAgent(id, d);
   if (!agent)
     return null;
-  const timestamp = now2();
+  const timestamp = now();
   if (updates.name) {
     const normalizedNewName = updates.name.trim().toLowerCase();
     if (normalizedNewName !== agent.name) {
@@ -7402,7 +7568,7 @@ function createRelation(input, db) {
   }
   const d = db || getDatabase();
   const id = shortUuid();
-  const timestamp = now2();
+  const timestamp = now();
   const weight = input.weight ?? 1;
   const metadata = JSON.stringify(input.metadata ?? {});
   d.run(`INSERT INTO relations (id, source_entity_id, target_entity_id, relation_type, weight, metadata, created_at)
@@ -7455,7 +7621,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;
@@ -8109,6 +8275,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();
@@ -8154,6 +8346,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
@@ -8314,6 +8507,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();
@@ -8367,7 +8566,7 @@ function createWebhookHook(input, db) {
   }
   const d = db || getDatabase();
   const id = shortUuid();
-  const timestamp = now2();
+  const timestamp = now();
   d.run(`INSERT INTO webhook_hooks
        (id, type, handler_url, priority, blocking, agent_id, project_id, description, enabled, created_at, invocation_count, failure_count)
      VALUES (?, ?, ?, ?, ?, ?, ?, ?, 1, ?, 0, 0)`, [
@@ -8385,7 +8584,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;
@@ -8421,7 +8620,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;
@@ -8452,7 +8651,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();
@@ -8550,7 +8749,7 @@ function parseEventRow(row) {
 function createSynthesisRun(input, db) {
   const d = db || getDatabase();
   const id = shortUuid();
-  const timestamp = now2();
+  const timestamp = now();
   d.run(`INSERT INTO synthesis_runs (id, triggered_by, project_id, agent_id, corpus_size, proposals_generated, proposals_accepted, proposals_rejected, status, started_at)
      VALUES (?, ?, ?, ?, ?, 0, 0, 0, 'pending', ?)`, [
     id,
@@ -8651,7 +8850,7 @@ function updateSynthesisRun(id, updates, db) {
 function createProposal(input, db) {
   const d = db || getDatabase();
   const id = shortUuid();
-  const timestamp = now2();
+  const timestamp = now();
   d.run(`INSERT INTO synthesis_proposals (id, run_id, proposal_type, memory_ids, target_memory_id, proposed_changes, reasoning, confidence, status, created_at)
      VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'pending', ?)`, [
     id,
@@ -8710,7 +8909,7 @@ function updateProposal(id, updates, db) {
 function createMetric(input, db) {
   const d = db || getDatabase();
   const id = shortUuid();
-  const timestamp = now2();
+  const timestamp = now();
   d.run(`INSERT INTO synthesis_metrics (id, run_id, metric_type, value, baseline, created_at)
      VALUES (?, ?, ?, ?, ?, ?)`, [id, input.run_id, input.metric_type, input.value, input.baseline ?? null, timestamp]);
   return { id, run_id: input.run_id, metric_type: input.metric_type, value: input.value, baseline: input.baseline ?? null, created_at: timestamp };
@@ -8724,7 +8923,7 @@ function recordSynthesisEvent(input, db) {
   try {
     const d = db || getDatabase();
     const id = shortUuid();
-    const timestamp = now2();
+    const timestamp = now();
     d.run(`INSERT INTO synthesis_events (id, event_type, memory_id, agent_id, project_id, session_id, query, importance_at_time, metadata, created_at)
        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
       id,
@@ -8978,7 +9177,7 @@ __export(exports_contradiction, {
 });
 function invalidateFact(oldMemoryId, newMemoryId, db) {
   const d = db || getDatabase();
-  const timestamp = now2();
+  const timestamp = now();
   d.run("UPDATE memories SET valid_until = ?, updated_at = ? WHERE id = ?", [timestamp, timestamp, oldMemoryId]);
   if (newMemoryId) {
     const row = d.query("SELECT metadata FROM memories WHERE id = ?").get(newMemoryId);
@@ -9151,6 +9350,8 @@ var init_built_in_hooks = __esm(() => {
     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();
@@ -9456,7 +9657,7 @@ async function buildCorpus(options) {
     duplicateCandidates,
     lowImportanceHighRecall,
     highImportanceLowRecall,
-    generatedAt: now2()
+    generatedAt: now()
   };
 }
 var init_corpus_builder = __esm(() => {
@@ -9789,7 +9990,7 @@ async function executeProposals(runId, proposals, db) {
       const rollback = executeProposal(proposal, d);
       updateProposal(proposal.id, {
         status: "accepted",
-        executed_at: now2(),
+        executed_at: now(),
         rollback_data: rollback
       }, d);
       rollbackData[proposal.id] = rollback;
@@ -9838,7 +10039,7 @@ function executeArchive(proposal, d) {
     if (!mem)
       continue;
     rollback[memId] = mem.status;
-    d.run("UPDATE memories SET status = 'archived', updated_at = ? WHERE id = ?", [now2(), memId]);
+    d.run("UPDATE memories SET status = 'archived', updated_at = ? WHERE id = ?", [now(), memId]);
   }
   return { old_status: rollback };
 }
@@ -9853,7 +10054,7 @@ function executePromote(proposal, d) {
     if (!mem)
       continue;
     rollback[memId] = mem.importance;
-    d.run("UPDATE memories SET importance = ?, updated_at = ? WHERE id = ?", [Math.max(1, Math.min(10, Math.round(newImportance))), now2(), memId]);
+    d.run("UPDATE memories SET importance = ?, updated_at = ? WHERE id = ?", [Math.max(1, Math.min(10, Math.round(newImportance))), now(), memId]);
   }
   return { old_importance: rollback };
 }
@@ -9870,7 +10071,7 @@ function executeUpdateValue(proposal, d) {
   if (!mem)
     throw new Error(`Memory ${memId} not found`);
   rollback[memId] = { value: mem.value, version: mem.version };
-  d.run("UPDATE memories SET value = ?, version = version + 1, updated_at = ? WHERE id = ?", [newValue, now2(), memId]);
+  d.run("UPDATE memories SET value = ?, version = version + 1, updated_at = ? WHERE id = ?", [newValue, now(), memId]);
   return { old_state: rollback };
 }
 function executeAddTag(proposal, d) {
@@ -9885,7 +10086,7 @@ function executeAddTag(proposal, d) {
       continue;
     rollback[memId] = [...mem.tags];
     const newTags = Array.from(new Set([...mem.tags, ...tagsToAdd]));
-    d.run("UPDATE memories SET tags = ?, updated_at = ? WHERE id = ?", [JSON.stringify(newTags), now2(), memId]);
+    d.run("UPDATE memories SET tags = ?, updated_at = ? WHERE id = ?", [JSON.stringify(newTags), now(), memId]);
     const insertTag = d.prepare("INSERT OR IGNORE INTO memory_tags (memory_id, tag) VALUES (?, ?)");
     for (const tag of tagsToAdd) {
       insertTag.run(memId, tag);
@@ -9918,11 +10119,11 @@ function executeMerge(proposal, d) {
   const mergedValue = proposal.proposed_changes["merged_value"] ?? [target.value, ...sourceValues].join(`
 ---
 `);
-  d.run("UPDATE memories SET value = ?, version = version + 1, updated_at = ? WHERE id = ?", [mergedValue, now2(), targetId]);
+  d.run("UPDATE memories SET value = ?, version = version + 1, updated_at = ? WHERE id = ?", [mergedValue, now(), targetId]);
   for (const memId of proposal.memory_ids) {
     if (memId === targetId)
       continue;
-    d.run("UPDATE memories SET status = 'archived', updated_at = ? WHERE id = ?", [now2(), memId]);
+    d.run("UPDATE memories SET status = 'archived', updated_at = ? WHERE id = ?", [now(), memId]);
   }
   return rollback;
 }
@@ -9938,7 +10139,7 @@ function executeRemoveDuplicate(proposal, d) {
     if (mem.id === keepId)
       continue;
     rollback[mem.id] = mem.status;
-    d.run("UPDATE memories SET status = 'archived', updated_at = ? WHERE id = ?", [now2(), mem.id]);
+    d.run("UPDATE memories SET status = 'archived', updated_at = ? WHERE id = ?", [now(), mem.id]);
   }
   return { old_status: rollback, kept_id: keepId };
 }
@@ -9970,7 +10171,7 @@ function rollbackProposal(proposal, d) {
         if (!oldStatus)
           break;
         for (const [memId, status] of Object.entries(oldStatus)) {
-          d.run("UPDATE memories SET status = ?, updated_at = ? WHERE id = ?", [status, now2(), memId]);
+          d.run("UPDATE memories SET status = ?, updated_at = ? WHERE id = ?", [status, now(), memId]);
         }
         break;
       }
@@ -9979,7 +10180,7 @@ function rollbackProposal(proposal, d) {
         if (!oldImportance)
           break;
         for (const [memId, importance] of Object.entries(oldImportance)) {
-          d.run("UPDATE memories SET importance = ?, updated_at = ? WHERE id = ?", [importance, now2(), memId]);
+          d.run("UPDATE memories SET importance = ?, updated_at = ? WHERE id = ?", [importance, now(), memId]);
         }
         break;
       }
@@ -9988,7 +10189,7 @@ function rollbackProposal(proposal, d) {
         if (!oldState)
           break;
         for (const [memId, state] of Object.entries(oldState)) {
-          d.run("UPDATE memories SET value = ?, version = ?, updated_at = ? WHERE id = ?", [state.value, state.version, now2(), memId]);
+          d.run("UPDATE memories SET value = ?, version = ?, updated_at = ? WHERE id = ?", [state.value, state.version, now(), memId]);
         }
         break;
       }
@@ -9997,7 +10198,7 @@ function rollbackProposal(proposal, d) {
         if (!oldTags)
           break;
         for (const [memId, tags] of Object.entries(oldTags)) {
-          d.run("UPDATE memories SET tags = ?, updated_at = ? WHERE id = ?", [JSON.stringify(tags), now2(), memId]);
+          d.run("UPDATE memories SET tags = ?, updated_at = ? WHERE id = ?", [JSON.stringify(tags), now(), memId]);
           d.run("DELETE FROM memory_tags WHERE memory_id = ?", [memId]);
           const insertTag = d.prepare("INSERT OR IGNORE INTO memory_tags (memory_id, tag) VALUES (?, ?)");
           for (const tag of tags) {
@@ -10012,11 +10213,11 @@ function rollbackProposal(proposal, d) {
         const archivedMemories = rb["archived_memories"];
         const targetId = proposal.target_memory_id;
         if (targetId && targetOldValue !== undefined && targetOldVersion !== undefined) {
-          d.run("UPDATE memories SET value = ?, version = ?, updated_at = ? WHERE id = ?", [targetOldValue, targetOldVersion, now2(), targetId]);
+          d.run("UPDATE memories SET value = ?, version = ?, updated_at = ? WHERE id = ?", [targetOldValue, targetOldVersion, now(), targetId]);
         }
         if (archivedMemories) {
           for (const [memId, status] of Object.entries(archivedMemories)) {
-            d.run("UPDATE memories SET status = ?, updated_at = ? WHERE id = ?", [status, now2(), memId]);
+            d.run("UPDATE memories SET status = ?, updated_at = ? WHERE id = ?", [status, now(), memId]);
           }
         }
         break;
@@ -10150,12 +10351,12 @@ async function runSynthesis(options = {}) {
         proposals_accepted: execResult.executed,
         proposals_rejected: validation.rejectedProposals.length + execResult.failed,
         status: "completed",
-        completed_at: now2()
+        completed_at: now()
       }, d);
     } else {
       updateSynthesisRun(run.id, {
         status: "completed",
-        completed_at: now2()
+        completed_at: now()
       }, d);
     }
     let effectivenessReport = null;
@@ -10177,7 +10378,7 @@ async function runSynthesis(options = {}) {
     updateSynthesisRun(run.id, {
       status: "failed",
       error: err instanceof Error ? err.message : String(err),
-      completed_at: now2()
+      completed_at: now()
     }, d);
     const failedRun = listSynthesisRuns({ project_id: projectId, limit: 1 }, d)[0] ?? run;
     return {
@@ -10193,7 +10394,7 @@ async function rollbackSynthesis(runId, db) {
   const d = db || getDatabase();
   const result = await rollbackRun(runId, d);
   if (result.errors.length === 0) {
-    updateSynthesisRun(runId, { status: "rolled_back", completed_at: now2() }, d);
+    updateSynthesisRun(runId, { status: "rolled_back", completed_at: now() }, d);
   }
   return result;
 }
@@ -10259,7 +10460,7 @@ function parseJobRow(row) {
 function createSessionJob(input, db) {
   const d = db || getDatabase();
   const id = uuid();
-  const timestamp = now2();
+  const timestamp = now();
   const source = input.source ?? "manual";
   const metadata = JSON.stringify(input.metadata ?? {});
   d.run(`INSERT INTO session_memory_jobs
@@ -10278,7 +10479,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;
@@ -10408,7 +10609,7 @@ function saveToolEvent(input, db) {
   }
   const d = db || getDatabase();
   const id = uuid();
-  const timestamp = now2();
+  const timestamp = now();
   const metadataJson = JSON.stringify(input.metadata || {});
   d.run(`INSERT INTO tool_events (id, tool_name, action, success, error_type, error_message, tokens_used, latency_ms, context, lesson, when_to_use, agent_id, project_id, session_id, metadata, created_at)
      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
@@ -11974,6 +12175,31 @@ var init_pg_migrations = __esm(() => {
   );
   CREATE INDEX IF NOT EXISTS idx_task_comments_task ON task_comments(task_id);
   CREATE INDEX IF NOT EXISTS idx_task_comments_agent ON task_comments(agent_id);
+  `,
+    `
+  CREATE OR REPLACE FUNCTION snapshot_memory_version() RETURNS trigger AS $$
+  BEGIN
+    INSERT INTO memory_versions (
+      id, memory_id, version, value, importance, scope, category, tags,
+      summary, pinned, status, when_to_use, created_at
+    ) VALUES (
+      gen_random_uuid()::text,
+      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
+    ) ON CONFLICT DO NOTHING;
+    RETURN NEW;
+  END;
+  $$ LANGUAGE plpgsql;
+
+  DROP TRIGGER IF EXISTS memories_version_snapshot ON memories;
+  CREATE TRIGGER memories_version_snapshot
+    BEFORE UPDATE ON memories
+    FOR EACH ROW
+    WHEN (NEW.version > OLD.version)
+    EXECUTE FUNCTION snapshot_memory_version();
+
+  INSERT INTO _migrations (id) VALUES (36) ON CONFLICT DO NOTHING;
   `
   ];
 });
@@ -58701,15 +58927,108 @@ var {
   Help
 } = import__.default;
 
+// src/cli/index.tsx
+init_database();
+import { readFileSync as readFileSync8 } from "fs";
+import { dirname as dirname7, join as join12 } from "path";
+import { fileURLToPath as fileURLToPath4 } from "url";
+
+// src/db/machines.ts
+init_database();
+import { hostname, platform } from "os";
+function parseMachine(row) {
+  if (!row)
+    return null;
+  return {
+    ...row,
+    is_primary: Boolean(row.is_primary)
+  };
+}
+function normalizeHostname(host) {
+  return host.replace(/\.(local|lan|home|internal)$/i, "");
+}
+function registerMachine(name, db = getDatabase()) {
+  const rawHost = hostname();
+  const host = normalizeHostname(rawHost);
+  const plat = platform();
+  const machineName = name?.trim() || host;
+  const existing = parseMachine(db.query("SELECT * FROM machines WHERE hostname = ?").get(host));
+  if (existing) {
+    db.run("UPDATE machines SET last_seen_at = ? WHERE id = ?", [now(), existing.id]);
+    return parseMachine(db.query("SELECT * FROM machines WHERE id = ?").get(existing.id));
+  }
+  let finalName = machineName;
+  let suffix = 2;
+  while (db.query("SELECT id FROM machines WHERE name = ?").get(finalName)) {
+    finalName = `${machineName}-${suffix++}`;
+  }
+  const id = uuid();
+  db.run("INSERT INTO machines (id, name, hostname, platform) VALUES (?, ?, ?, ?)", [id, finalName, host, plat]);
+  return parseMachine(db.query("SELECT * FROM machines WHERE id = ?").get(id));
+}
+function getPrimaryMachine(db = getDatabase()) {
+  return parseMachine(db.query("SELECT * FROM machines WHERE is_primary = 1 LIMIT 1").get());
+}
+function getPrimaryMachineCandidate(db = getDatabase()) {
+  if (getPrimaryMachine(db))
+    return null;
+  return parseMachine(db.query("SELECT * FROM machines ORDER BY created_at ASC, id ASC LIMIT 1").get());
+}
+function getPrimaryMachineStartupWarning(db = getDatabase()) {
+  if (getPrimaryMachine(db))
+    return null;
+  const candidate = getPrimaryMachineCandidate(db);
+  if (!candidate) {
+    return "No primary machine configured. Fallback sync target is unset because no machines are registered yet.";
+  }
+  return `No primary machine configured. Fallback sync target is unset. Candidate: ${candidate.name} (${candidate.id.slice(0, 8)} / ${candidate.hostname}). Confirm it with set_primary_machine.`;
+}
+function touchMachine(id, db = getDatabase()) {
+  db.run("UPDATE machines SET last_seen_at = ? WHERE id = ?", [now(), id]);
+}
+function getCurrentMachineId(db = getDatabase()) {
+  const host = normalizeHostname(hostname());
+  const m = db.query("SELECT id FROM machines WHERE hostname = ?").get(host);
+  if (m) {
+    touchMachine(m.id, db);
+    return m.id;
+  }
+  return registerMachine(undefined, db).id;
+}
+
+// src/cli/startup-side-effects.ts
+var NO_STARTUP_DB_ACCESS = new WeakSet;
+function withoutStartupDbAccess(command) {
+  NO_STARTUP_DB_ACCESS.add(command);
+  return command;
+}
+function skipsStartupDbAccess(command) {
+  return command !== undefined && NO_STARTUP_DB_ACCESS.has(command);
+}
+
+// src/cli/global-options.ts
+var GLOBAL_OPTIONS = [
+  ["-p, --project <path>", "Project path for scoping"],
+  ["-j, --json", "Output as JSON"],
+  ["-f, --format <fmt>", "Output format: compact, json, csv, yaml"],
+  ["-a, --agent <name>", "Agent name or ID"],
+  ["-s, --session <id>", "Session ID"]
+];
+function applyGlobalOptions(program2) {
+  for (const [flags, description] of GLOBAL_OPTIONS)
+    program2.option(flags, description);
+  return program2;
+}
+
 // node_modules/@hasna/events/dist/commander.js
 import { chmod, mkdir, readFile, rename, writeFile } from "fs/promises";
-import { existsSync } from "fs";
-import { homedir } from "os";
-import { join } from "path";
+import { existsSync as existsSync3 } from "fs";
+import { homedir as homedir2 } from "os";
+import { join as join4 } from "path";
 import { createHmac, timingSafeEqual } from "crypto";
-import { randomUUID } from "crypto";
-import { spawn } from "child_process";
 import { randomUUID as randomUUID2 } from "crypto";
+import { spawn } from "child_process";
+import { randomUUID as randomUUID22 } from "crypto";
 function getPathValue(input, path) {
   return path.split(".").reduce((value, part) => {
     if (value && typeof value === "object" && part in value) {
@@ -58754,7 +59073,7 @@ function channelMatchesEvent(channel, event) {
 var HASNA_EVENTS_DIR_ENV = "HASNA_EVENTS_DIR";
 var HASNA_EVENTS_HOME_ENV = "HASNA_EVENTS_HOME";
 function getEventsDataDir(override) {
-  return override || process.env[HASNA_EVENTS_DIR_ENV] || process.env[HASNA_EVENTS_HOME_ENV] || join(homedir(), ".hasna", "events");
+  return override || process.env[HASNA_EVENTS_DIR_ENV] || process.env[HASNA_EVENTS_HOME_ENV] || join4(homedir2(), ".hasna", "events");
 }
 
 class JsonEventsStore {
@@ -58764,9 +59083,9 @@ class JsonEventsStore {
   deliveriesPath;
   constructor(dataDir = getEventsDataDir()) {
     this.dataDir = dataDir;
-    this.channelsPath = join(dataDir, "channels.json");
-    this.eventsPath = join(dataDir, "events.json");
-    this.deliveriesPath = join(dataDir, "deliveries.json");
+    this.channelsPath = join4(dataDir, "channels.json");
+    this.eventsPath = join4(dataDir, "events.json");
+    this.deliveriesPath = join4(dataDir, "deliveries.json");
   }
   async init() {
     await mkdir(this.dataDir, { recursive: true, mode: 448 });
@@ -58838,7 +59157,7 @@ class JsonEventsStore {
     };
   }
   async ensureArrayFile(path) {
-    if (!existsSync(path)) {
+    if (!existsSync3(path)) {
       await writeFile(path, `[]
 `, { encoding: "utf-8", mode: 384 });
     }
@@ -58876,7 +59195,7 @@ function signPayload(secret, timestamp, body) {
   const digest = createHmac("sha256", secret).update(buildSignatureBase(timestamp, body)).digest("hex");
   return `sha256=${digest}`;
 }
-function now() {
+function now2() {
   return new Date().toISOString();
 }
 function truncate(value, max = 4096) {
@@ -58903,7 +59222,7 @@ function buildWebhookRequest(event, channel) {
 async function dispatchWebhook(event, channel, options = {}) {
   if (!channel.webhook)
     throw new Error(`Channel ${channel.id} has no webhook config`);
-  const startedAt = now();
+  const startedAt = now2();
   const { body, headers } = buildWebhookRequest(event, channel);
   const controller = new AbortController;
   const timeout = setTimeout(() => controller.abort(), channel.webhook.timeoutMs ?? 15000);
@@ -58919,7 +59238,7 @@ async function dispatchWebhook(event, channel, options = {}) {
       attempt: 1,
       status: response.ok ? "success" : "failed",
       startedAt,
-      completedAt: now(),
+      completedAt: now2(),
       responseStatus: response.status,
       responseBody,
       error: response.ok ? undefined : `Webhook returned HTTP ${response.status}`
@@ -58929,7 +59248,7 @@ async function dispatchWebhook(event, channel, options = {}) {
       attempt: 1,
       status: "failed",
       startedAt,
-      completedAt: now(),
+      completedAt: now2(),
       error: error instanceof Error ? error.message : String(error)
     };
   } finally {
@@ -58939,7 +59258,7 @@ async function dispatchWebhook(event, channel, options = {}) {
 async function dispatchCommand(event, channel) {
   if (!channel.command)
     throw new Error(`Channel ${channel.id} has no command config`);
-  const startedAt = now();
+  const startedAt = now2();
   const eventJson = JSON.stringify(event);
   const env = {
     ...process.env,
@@ -58955,7 +59274,7 @@ async function dispatchCommand(event, channel) {
     HASNA_EVENT_SCHEMA_VERSION: event.schemaVersion,
     HASNA_EVENT_JSON: eventJson
   };
-  return new Promise((resolve) => {
+  return new Promise((resolve2) => {
     const child = spawn(channel.command.command, channel.command.args ?? [], {
       cwd: channel.command.cwd,
       env,
@@ -58973,11 +59292,11 @@ async function dispatchCommand(event, channel) {
     });
     child.on("error", (error) => {
       clearTimeout(timeout);
-      resolve({
+      resolve2({
         attempt: 1,
         status: "failed",
         startedAt,
-        completedAt: now(),
+        completedAt: now2(),
         stdout: truncate(stdout),
         stderr: truncate(stderr),
         error: error.message
@@ -58986,11 +59305,11 @@ async function dispatchCommand(event, channel) {
     child.on("close", (code, signal) => {
       clearTimeout(timeout);
       const success = code === 0;
-      resolve({
+      resolve2({
         attempt: 1,
         status: success ? "success" : "failed",
         startedAt,
-        completedAt: now(),
+        completedAt: now2(),
         stdout: truncate(stdout),
         stderr: truncate(stderr),
         error: success ? undefined : `Command exited with ${signal ? `signal ${signal}` : `code ${code}`}`
@@ -59006,27 +59325,27 @@ async function dispatchChannel(event, channel, options = {}) {
   return {
     attempt: 1,
     status: "skipped",
-    startedAt: now(),
-    completedAt: now(),
+    startedAt: now2(),
+    completedAt: now2(),
     error: `Unsupported transport: ${channel.transport}`
   };
 }
 function createDeliveryResult(event, channel, attempts) {
   const status = attempts.some((attempt) => attempt.status === "success") ? "success" : attempts.every((attempt) => attempt.status === "skipped") ? "skipped" : "failed";
   return {
-    id: randomUUID(),
+    id: randomUUID2(),
     eventId: event.id,
     channelId: channel.id,
     transport: channel.transport,
     status,
     attempts,
-    createdAt: attempts[0]?.startedAt ?? now(),
-    completedAt: attempts.at(-1)?.completedAt ?? now()
+    createdAt: attempts[0]?.startedAt ?? now2(),
+    completedAt: attempts.at(-1)?.completedAt ?? now2()
   };
 }
 function createEvent(input) {
   return {
-    id: input.id ?? randomUUID2(),
+    id: input.id ?? randomUUID22(),
     source: input.source,
     type: input.type,
     time: normalizeTime(input.time),
@@ -59385,75 +59704,6 @@ function collectValues(value, previous) {
   return previous;
 }
 
-// src/cli/index.tsx
-init_database();
-import { readFileSync as readFileSync8 } from "fs";
-import { dirname as dirname7, join as join12 } from "path";
-import { fileURLToPath as fileURLToPath4 } from "url";
-
-// src/db/machines.ts
-init_database();
-import { hostname, platform } from "os";
-function parseMachine(row) {
-  if (!row)
-    return null;
-  return {
-    ...row,
-    is_primary: Boolean(row.is_primary)
-  };
-}
-function normalizeHostname(host) {
-  return host.replace(/\.(local|lan|home|internal)$/i, "");
-}
-function registerMachine(name, db = getDatabase()) {
-  const rawHost = hostname();
-  const host = normalizeHostname(rawHost);
-  const plat = platform();
-  const machineName = name?.trim() || host;
-  const existing = parseMachine(db.query("SELECT * FROM machines WHERE hostname = ?").get(host));
-  if (existing) {
-    db.run("UPDATE machines SET last_seen_at = ? WHERE id = ?", [now2(), existing.id]);
-    return parseMachine(db.query("SELECT * FROM machines WHERE id = ?").get(existing.id));
-  }
-  let finalName = machineName;
-  let suffix = 2;
-  while (db.query("SELECT id FROM machines WHERE name = ?").get(finalName)) {
-    finalName = `${machineName}-${suffix++}`;
-  }
-  const id = uuid();
-  db.run("INSERT INTO machines (id, name, hostname, platform) VALUES (?, ?, ?, ?)", [id, finalName, host, plat]);
-  return parseMachine(db.query("SELECT * FROM machines WHERE id = ?").get(id));
-}
-function getPrimaryMachine(db = getDatabase()) {
-  return parseMachine(db.query("SELECT * FROM machines WHERE is_primary = 1 LIMIT 1").get());
-}
-function getPrimaryMachineCandidate(db = getDatabase()) {
-  if (getPrimaryMachine(db))
-    return null;
-  return parseMachine(db.query("SELECT * FROM machines ORDER BY created_at ASC, id ASC LIMIT 1").get());
-}
-function getPrimaryMachineStartupWarning(db = getDatabase()) {
-  if (getPrimaryMachine(db))
-    return null;
-  const candidate = getPrimaryMachineCandidate(db);
-  if (!candidate) {
-    return "No primary machine configured. Fallback sync target is unset because no machines are registered yet.";
-  }
-  return `No primary machine configured. Fallback sync target is unset. Candidate: ${candidate.name} (${candidate.id.slice(0, 8)} / ${candidate.hostname}). Confirm it with set_primary_machine.`;
-}
-function touchMachine(id, db = getDatabase()) {
-  db.run("UPDATE machines SET last_seen_at = ? WHERE id = ?", [now2(), id]);
-}
-function getCurrentMachineId(db = getDatabase()) {
-  const host = normalizeHostname(hostname());
-  const m = db.query("SELECT id FROM machines WHERE hostname = ?").get(host);
-  if (m) {
-    touchMachine(m.id, db);
-    return m.id;
-  }
-  return registerMachine(undefined, db).id;
-}
-
 // src/cli/commands/memory.ts
 init_helpers();
 
@@ -59510,10 +59760,12 @@ var FORMAT_UNITS = [
 ];
 
 // src/cli/commands/memory-cmd-crud.ts
+init_enum_validation();
+init_types();
 init_helpers();
 function registerCrudCommands(program2) {
   const handleError = makeHandleError(program2);
-  program2.command("save <key> <value>").description("Save a memory (create or upsert)").option("-c, --category <cat>", "Category: preference, fact, knowledge, history").option("-s, --scope <scope>", "Scope: global, shared, private").option("--importance <n>", "Importance 1-10", parseInt).option("--tags <tags>", "Comma-separated tags").option("--summary <text>", "Brief summary").option("--ttl <duration>", "Time-to-live: 30s, 5m, 2h, 1d, 1w, or milliseconds").option("--source <src>", "Source: user, agent, system, auto, imported").option("--template <name>", "Apply a template: correction, preference, decision, learning").action((key, value, opts) => {
+  program2.command("save <key> <value>").description("Save a memory (create or upsert)").option("-c, --category <cat>", `Category: ${MEMORY_CATEGORIES.join(", ")}`).option("--scope <scope>", `Scope: ${MEMORY_SCOPES.join(", ")}`).option("--importance <n>", "Importance 1-10", parseInt).option("--tags <tags>", "Comma-separated tags").option("--summary <text>", "Brief summary").option("--ttl <duration>", "Time-to-live: 30s, 5m, 2h, 1d, 1w, or milliseconds").option("--source <src>", "Source: user, agent, system, auto, imported").option("--template <name>", "Apply a template: correction, preference, decision, learning").option("--dedupe <mode>", "Conflict handling: merge (default, upsert the matching row), create (fork a new row under the same key), error").action((key, value, opts) => {
     try {
       const globalOpts = program2.opts();
       const templates = {
@@ -59551,6 +59803,20 @@ function registerCrudCommands(program2) {
         }
         templateDefaults = tpl;
       }
+      for (const [flag, value2] of [
+        ["category", opts.category],
+        ["scope", opts.scope],
+        ["source", opts.source]
+      ]) {
+        const violation = validateEnumField(flag, value2);
+        if (!violation)
+          continue;
+        let msg = formatEnumViolation(violation);
+        if (flag === "category" && templates[violation.value]) {
+          msg += ` Did you mean --template ${violation.value}?`;
+        }
+        throw new Error(msg);
+      }
       const explicitTags = opts.tags ? opts.tags.split(",").map((t) => t.trim()) : undefined;
       const mergedTags = explicitTags ? explicitTags : templateDefaults?.tags && templateDefaults.tags.length > 0 ? templateDefaults.tags : undefined;
       let resolvedAgentId;
@@ -59576,17 +59842,40 @@ function registerCrudCommands(program2) {
         if (project)
           input.project_id = project.id;
       }
-      const memory = createMemory(input);
+      const bucket = (m) => [m.scope ?? "private", m.agent_id ?? "", m.project_id ?? "", m.session_id ?? ""].join("\x1F");
+      const targetBucket = bucket({
+        scope: input.scope ?? "private",
+        agent_id: input.agent_id,
+        project_id: input.project_id,
+        session_id: input.session_id
+      });
+      const dedupe = opts.dedupe;
+      const forkRequested = dedupe === "create" || dedupe === "version-fork";
+      let willUpdateExisting = false;
+      if (!forkRequested) {
+        const sameKey = getMemoriesByKey(key);
+        const match = sameKey.find((m) => bucket(m) === targetBucket);
+        willUpdateExisting = Boolean(match);
+        if (!match && sameKey.length > 0) {
+          const rows = sameKey.map((m) => `  ${m.id.slice(0, 8)}  scope=${m.scope}  project=${m.project_id ?? "none"}  session=${m.session_id ?? "none"}  agent=${m.agent_id ?? "none"}`).join(`
+`);
+          throw new Error(`Refusing to fork key "${key}": ${sameKey.length} active memor${sameKey.length === 1 ? "y" : "ies"} ` + `already ${sameKey.length === 1 ? "uses" : "use"} it, ` + `but none matches the scope/project/session this save targets ` + `(scope=${input.scope ?? "private"}, project=${input.project_id ?? "none"}, session=${input.session_id ?? "none"}).
+` + `${rows}
+` + `Saving would create a second active row under the same key. Either target the existing row ` + `(match its scope/project/session flags, or use \`mementos update <id>\`), or pass \`--dedupe create\` ` + `to fork deliberately.`);
+        }
+      }
+      const memory = forkRequested ? createMemory(input, dedupe) : createMemory(input);
+      const outcome = willUpdateExisting ? "Updated" : "Created";
       if (globalOpts.json) {
-        outputJson(memory);
+        outputJson({ ...memory, outcome: outcome.toLowerCase() });
       } else {
-        console.log(chalk2.green(`Saved: ${memory.key} (${memory.id.slice(0, 8)})`));
+        console.log(chalk2.green(`${outcome}: ${memory.key} (${memory.id.slice(0, 8)})`));
       }
     } catch (e) {
       handleError(e);
     }
   });
-  program2.command("update <id>").description("Update a memory by ID").option("--value <text>", "New value").option("--importance <n>", "New importance 1-10", parseInt).option("--tags <tags>", "New comma-separated tags").option("--summary <text>", "New summary").option("--pin", "Pin the memory").option("--unpin", "Unpin the memory").option("-c, --category <cat>", "New category").option("-s, --scope <scope>", "New scope").option("--status <status>", "New status: active, archived, expired").action((id, opts) => {
+  program2.command("update <id>").description("Update a memory by ID").option("--value <text>", "New value").option("--importance <n>", "New importance 1-10", parseInt).option("--tags <tags>", "New comma-separated tags").option("--summary <text>", "New summary").option("--pin", "Pin the memory").option("--unpin", "Unpin the memory").option("-c, --category <cat>", "New category").option("--scope <scope>", "New scope").option("--status <status>", "New status: active, archived, expired").action((id, opts) => {
     try {
       const globalOpts = program2.opts();
       const resolvedId = resolveMemoryId(id);
@@ -59620,17 +59909,31 @@ function registerCrudCommands(program2) {
         updateInput.scope = opts.scope;
       if (opts.status !== undefined)
         updateInput.status = opts.status;
+      for (const [flag, value] of [
+        ["category", opts.category],
+        ["scope", opts.scope],
+        ["status", opts.status]
+      ]) {
+        const violation = validateEnumField(flag, value);
+        if (violation)
+          throw new Error(formatEnumViolation(violation));
+      }
+      const changedFields = Object.keys(updateInput).filter((k) => k !== "version");
+      if (changedFields.length === 0) {
+        throw new Error(`Nothing to update: no fields were given for ${existing.key} (${existing.id.slice(0, 8)}). ` + `Pass at least one of --value, --scope, --category, --status, --importance, --tags, --summary, --pin/--unpin. ` + `Note that -s is the global --session, not --scope.`);
+      }
       const updated = updateMemory(resolvedId, updateInput);
       if (globalOpts.json) {
-        outputJson(updated);
+        outputJson({ ...updated, updated_fields: changedFields });
       } else {
-        console.log(chalk2.green(`Updated: ${updated.key} (${updated.id.slice(0, 8)})`));
+        const n = changedFields.length;
+        console.log(chalk2.green(`Updated ${n} field${n === 1 ? "" : "s"}: ${updated.key} (${updated.id.slice(0, 8)})`) + chalk2.dim(` [${changedFields.join(", ")}]`));
       }
     } catch (e) {
       handleError(e);
     }
   });
-  program2.command("forget <keyOrId>").description("Delete a memory by key or ID").option("-s, --scope <scope>", "Filter by scope (global, shared, private)").option("-a, --agent <agent>", "Filter by agent ID").option("-p, --project <project>", "Filter by project ID").option("--all", "Delete ALL matching memories (no disambiguation needed)").action((keyOrId, opts) => {
+  program2.command("forget <keyOrId>").description("Delete a memory by key or ID").option("--scope <scope>", "Filter by scope (global, shared, private)").option("--agent <agent>", "Filter by agent ID").option("--project <project>", "Filter by project ID").option("--all", "Delete ALL matching memories (no disambiguation needed)").action((keyOrId, opts) => {
     try {
       const globalOpts = program2.opts();
       const idMatch = isApiMode() ? null : resolvePartialId(getDatabase(), "memories", keyOrId);
@@ -59730,7 +60033,7 @@ function registerViewCommands(program2) {
       handleError(e);
     }
   });
-  program2.command("pin <keyOrId>").description("Pin a memory by key or partial ID").option("-s, --scope <scope>", "Scope filter for key lookup").option("--agent <name>", "Agent filter for key lookup").option("--project <path>", "Project filter for key lookup").action((keyOrId, opts) => {
+  program2.command("pin <keyOrId>").description("Pin a memory by key or partial ID").option("--scope <scope>", "Scope filter for key lookup").option("--agent <name>", "Agent filter for key lookup").option("--project <path>", "Project filter for key lookup").action((keyOrId, opts) => {
     try {
       const globalOpts = program2.opts();
       const memory = resolveKeyOrId(keyOrId, opts, globalOpts);
@@ -59755,7 +60058,7 @@ function registerViewCommands(program2) {
       handleError(e);
     }
   });
-  program2.command("unpin <keyOrId>").description("Unpin a memory by key or partial ID").option("-s, --scope <scope>", "Scope filter for key lookup").option("--agent <name>", "Agent filter for key lookup").option("--project <path>", "Project filter for key lookup").action((keyOrId, opts) => {
+  program2.command("unpin <keyOrId>").description("Unpin a memory by key or partial ID").option("--scope <scope>", "Scope filter for key lookup").option("--agent <name>", "Agent filter for key lookup").option("--project <path>", "Project filter for key lookup").action((keyOrId, opts) => {
     try {
       const globalOpts = program2.opts();
       const memory = resolveKeyOrId(keyOrId, opts, globalOpts);
@@ -59780,7 +60083,7 @@ function registerViewCommands(program2) {
       handleError(e);
     }
   });
-  program2.command("archive <keyOrId>").description("Archive a memory by key or ID (hides from lists, keeps history)").option("-s, --scope <scope>", "Scope filter for key lookup").action((keyOrId, opts) => {
+  program2.command("archive <keyOrId>").description("Archive a memory by key or ID (hides from lists, keeps history)").option("--scope <scope>", "Scope filter for key lookup").action((keyOrId, opts) => {
     try {
       const globalOpts = program2.opts();
       const memory = resolveKeyOrId(keyOrId, opts, globalOpts);
@@ -59799,7 +60102,7 @@ function registerViewCommands(program2) {
       process.exit(1);
     }
   });
-  program2.command("versions <keyOrId>").description("Show version history for a memory").option("-s, --scope <scope>", "Scope filter for key lookup").action((keyOrId, opts) => {
+  program2.command("versions <keyOrId>").description("Show version history for a memory").option("--scope <scope>", "Scope filter for key lookup").action((keyOrId, opts) => {
     try {
       const globalOpts = program2.opts();
       const memory = resolveKeyOrId(keyOrId, opts, globalOpts);
@@ -59841,7 +60144,7 @@ import chalk4 from "chalk";
 import { resolve as resolve4 } from "path";
 function registerTailCommand(program2) {
   const handleError = makeHandleError(program2);
-  program2.command("tail").description("Watch for new/updated memories in real-time (like tail -f)").option("-s, --scope <scope>", "Scope filter: global, shared, private").option("-c, --category <cat>", "Category filter: preference, fact, knowledge, history").option("--agent <name>", "Agent filter").option("--project <path>", "Project filter").option("--interval <ms>", "Poll interval in milliseconds (default: 2000)", parseInt).option("--notify", "Send macOS notifications for each change").action((opts) => {
+  program2.command("tail").description("Watch for new/updated memories in real-time (like tail -f)").option("--scope <scope>", "Scope filter: global, shared, private, working").option("-c, --category <cat>", "Category filter: preference, fact, knowledge, history, procedural, resource").option("--agent <name>", "Agent filter").option("--project <path>", "Project filter").option("--interval <ms>", "Poll interval in milliseconds (default: 2000)", parseInt).option("--notify", "Send macOS notifications for each change").action((opts) => {
     try {
       const globalOpts = program2.opts();
       const jsonMode = !!globalOpts.json;
@@ -59955,7 +60258,7 @@ import chalk6 from "chalk";
 import { resolve as resolve5 } from "path";
 function registerSearchCommand(program2) {
   const handleError = makeHandleError(program2);
-  program2.command("search <query>").description("Full-text search across memories").option("-s, --scope <scope>", "Scope filter").option("-c, --category <cat>", "Category filter").option("--tags <tags>", "Comma-separated tags filter").option("--project <path>", "Project filter (path or name)").option("--agent <name>", "Agent filter").option("--session <id>", "Session ID filter").option("--limit <n>", "Max results", parseInt).option("--offset <n>", "Offset for pagination", parseInt).option("--cursor <n>", "Cursor offset for the next page", parseInt).option("--format <fmt>", "Output format: compact (default), json, csv, yaml").option("--verbose", "Show match highlights and wider snippets").option("--history", "Show recent search queries instead of searching").option("--popular", "Show most popular search queries").action((query, opts) => {
+  program2.command("search <query>").description("Full-text search across memories").option("--scope <scope>", "Scope filter").option("-c, --category <cat>", "Category filter").option("--tags <tags>", "Comma-separated tags filter").option("--project <path>", "Project filter (path or name)").option("--agent <name>", "Agent filter").option("--session <id>", "Session ID filter").option("--limit <n>", "Max results", parseInt).option("--offset <n>", "Offset for pagination", parseInt).option("--cursor <n>", "Cursor offset for the next page", parseInt).option("--format <fmt>", "Output format: compact (default), json, csv, yaml").option("--verbose", "Show match highlights and wider snippets").option("--history", "Show recent search queries instead of searching").option("--popular", "Show most popular search queries").action((query, opts) => {
     try {
       const fmt = getOutputFormat(program2, opts.format);
       const isStructured = fmt === "json" || fmt === "csv" || fmt === "yaml";
@@ -60216,7 +60519,7 @@ init_memories();
 init_helpers();
 import chalk10 from "chalk";
 function registerRemoveCommand(program2) {
-  program2.command("remove <nameOrId>").description("Remove/delete a memory by name or ID (alias for memory forget)").option("--agent <id>", "Agent ID").option("-s, --scope <scope>", "Filter by scope (when looking up by key)").action((nameOrId, opts) => {
+  program2.command("remove <nameOrId>").description("Remove/delete a memory by name or ID (alias for memory forget)").option("--agent <id>", "Agent ID").option("--scope <scope>", "Filter by scope (when looking up by key)").action((nameOrId, opts) => {
     const globalOpts = program2.opts();
     const agentId = opts.agent || globalOpts.agent;
     let id = isApiMode() ? null : resolvePartialId(getDatabase(), "memories", nameOrId);
@@ -60273,7 +60576,7 @@ import chalk11 from "chalk";
 import { resolve as resolve6 } from "path";
 function registerRecallCommand(program2) {
   const handleError = makeHandleError(program2);
-  program2.command("recall <key>").description("Recall a memory by key").option("-s, --scope <scope>", "Scope filter").option("--agent <name>", "Agent filter").option("--project <path>", "Project filter").action((key, opts) => {
+  program2.command("recall <key>").description("Recall a memory by key").option("--scope <scope>", "Scope filter").option("--agent <name>", "Agent filter").option("--project <path>", "Project filter").action((key, opts) => {
     try {
       const globalOpts = program2.opts();
       const agentId = opts.agent || globalOpts.agent;
@@ -60331,7 +60634,7 @@ import chalk12 from "chalk";
 import { resolve as resolve7 } from "path";
 function registerListCommand(program2) {
   const handleError = makeHandleError(program2);
-  program2.command("list").description("List memories with optional filters").option("-s, --scope <scope>", "Scope filter").option("-c, --category <cat>", "Category filter").option("--tags <tags>", "Comma-separated tags filter").option("--importance-min <n>", "Minimum importance", parseInt).option("--pinned", "Show only pinned").option("--agent <name>", "Agent filter").option("--project <path>", "Project filter").option("--session <id>", "Session ID filter").option("--limit <n>", "Max results", parseInt).option("--offset <n>", "Offset for pagination", parseInt).option("--cursor <n>", "Cursor offset for the next page", parseInt).option("--status <status>", "Status filter: active, archived, expired").option("--format <fmt>", "Output format: compact (default), json, csv, yaml").option("--verbose", "Show wider memory snippets in human output").action((opts) => {
+  program2.command("list").description("List memories with optional filters").option("--scope <scope>", "Scope filter").option("-c, --category <cat>", "Category filter").option("--tags <tags>", "Comma-separated tags filter").option("--importance-min <n>", "Minimum importance", parseInt).option("--pinned", "Show only pinned").option("--agent <name>", "Agent filter").option("--project <path>", "Project filter").option("--session <id>", "Session ID filter").option("--limit <n>", "Max results", parseInt).option("--offset <n>", "Offset for pagination", parseInt).option("--cursor <n>", "Cursor offset for the next page", parseInt).option("--status <status>", "Status filter: active, archived, expired").option("--format <fmt>", "Output format: compact (default), json, csv, yaml").option("--verbose", "Show wider memory snippets in human output").action((opts) => {
     try {
       const globalOpts = program2.opts();
       const fmt = getOutputFormat(program2, opts.format);
@@ -60980,7 +61283,7 @@ init_helpers();
 import { resolve as resolve11 } from "path";
 function registerExportCommand(program2) {
   const handleError = makeHandleError(program2);
-  program2.command("export").description("Export memories as JSON").option("-s, --scope <scope>", "Scope filter").option("-c, --category <cat>", "Category filter").option("--agent <name>", "Agent filter").option("--project <path>", "Project filter").action((opts) => {
+  program2.command("export").description("Export memories as JSON").option("--scope <scope>", "Scope filter").option("-c, --category <cat>", "Category filter").option("--agent <name>", "Agent filter").option("--project <path>", "Project filter").action((opts) => {
     try {
       const globalOpts = program2.opts();
       const agentId = opts.agent || globalOpts.agent;
@@ -61296,7 +61599,7 @@ function enforceQuotas(config, db) {
 }
 function archiveStale(staleDays, db) {
   const d = db || getDatabase();
-  const timestamp = now2();
+  const timestamp = now();
   const cutoff = new Date(Date.now() - staleDays * 24 * 60 * 60 * 1000).toISOString();
   const archiveWhere = `status = 'active' AND pinned = 0 AND COALESCE(accessed_at, created_at) < ?`;
   const count = d.query(`SELECT COUNT(*) as c FROM memories WHERE ${archiveWhere}`).get(cutoff).c;
@@ -61307,7 +61610,7 @@ function archiveStale(staleDays, db) {
 }
 function archiveUnused(days, db) {
   const d = db || getDatabase();
-  const timestamp = now2();
+  const timestamp = now();
   const cutoff = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString();
   const unusedWhere = `status = 'active' AND pinned = 0 AND access_count = 0 AND created_at < ?`;
   const count = d.query(`SELECT COUNT(*) as c FROM memories WHERE ${unusedWhere}`).get(cutoff).c;
@@ -61318,7 +61621,7 @@ function archiveUnused(days, db) {
 }
 function deprioritizeStale(days, db) {
   const d = db || getDatabase();
-  const timestamp = now2();
+  const timestamp = now();
   const cutoff = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString();
   const deprioWhere = `status = 'active' AND pinned = 0 AND importance > 1 AND COALESCE(accessed_at, updated_at) < ?`;
   const count = d.query(`SELECT COUNT(*) as c FROM memories WHERE ${deprioWhere}`).get(cutoff).c;
@@ -61346,7 +61649,9 @@ init_api_mode();
 init_helpers();
 function runCleanupViaApi() {
   const empty = { expired: 0, evicted: 0, archived: 0, unused_archived: 0, deprioritized: 0 };
-  const { status, data } = apiJson("POST", "/maintenance/cleanup");
+  const { status, data } = apiJson("POST", "/maintenance/cleanup", undefined, {
+    allow404: true
+  });
   if (status !== 404 && data)
     return { ...empty, ...data };
   const legacy = apiJson("POST", "/memories/clean");
@@ -61637,7 +61942,7 @@ function getFocus(agentId) {
 init_helpers();
 function registerAgentCommands(program2) {
   const handleError = makeHandleError(program2);
-  program2.command("register-agent <name>").alias("init-agent").description("Register an agent (returns ID)").option("-d, --description <text>", "Agent description").option("-r, --role <role>", "Agent role").option("-p, --project <id>", "Lock agent to a project (sets active_project_id)").action((name, opts) => {
+  program2.command("register-agent <name>").alias("init-agent").description("Register an agent (returns ID)").option("-d, --description <text>", "Agent description").option("-r, --role <role>", "Agent role").option("--project <id>", "Lock agent to a project (sets active_project_id)").action((name, opts) => {
     try {
       const globalOpts = program2.opts();
       const agent = registerAgent(name, undefined, opts.description, opts.role, opts.project);
@@ -62810,12 +63115,12 @@ function registerDoctorCommand(program2) {
       const activeProfile = getActiveProfile();
       const profiles = listProfiles();
       if (activeProfile) {
-        checks.push({ name: "Active profile", status: "ok", detail: `${activeProfile} (${profiles.length} total)` });
+        checks.push({ name: "Profile metadata", status: "ok", detail: `${activeProfile} active (${profiles.length} total); verify runtime DB with storage mode` });
       } else {
-        checks.push({ name: "Active profile", status: "ok", detail: `default (~/.hasna/mementos/mementos.db) \u2014 ${profiles.length} profile(s) available` });
+        checks.push({ name: "Profile metadata", status: "ok", detail: `none active \u2014 ${profiles.length} profile(s) available; verify runtime DB with storage mode` });
       }
     } catch (e) {
-      checks.push({ name: "Active profile", status: "warn", detail: e instanceof Error ? e.message : String(e) });
+      checks.push({ name: "Profile metadata", status: "warn", detail: e instanceof Error ? e.message : String(e) });
     }
     try {
       const mementosUrl = process.env["MEMENTOS_URL"] || `http://127.0.0.1:19428`;
@@ -63124,7 +63429,7 @@ function registerConfigCommand(program2) {
 import chalk29 from "chalk";
 init_helpers();
 function registerProfileCommand(program2) {
-  const profileCmd = program2.command("profile").description("Manage memory profiles (isolated DBs per context)");
+  const profileCmd = program2.command("profile").description("Manage named profile files and active-profile metadata");
   profileCmd.command("list").description("List all available profiles").action(() => {
     const globalOpts = program2.opts();
     const profiles = listProfiles();
@@ -63144,7 +63449,7 @@ function registerProfileCommand(program2) {
     }
     if (!active) {
       console.log(chalk29.dim(`
-  (no active profile \u2014 using default DB)`));
+  (no active-profile metadata set)`));
     }
   });
   profileCmd.command("get").description("Show the currently active profile").action(() => {
@@ -63157,20 +63462,21 @@ function registerProfileCommand(program2) {
         console.log(chalk29.dim("(from MEMENTOS_PROFILE env var)"));
       }
     } else {
-      console.log(chalk29.dim("No active profile \u2014 using default DB (~/.hasna/mementos/mementos.db)"));
+      console.log(chalk29.dim("No active-profile metadata set."));
     }
   });
-  profileCmd.command("set <name>").description("Switch to a named profile (creates the DB on first use)").action((name) => {
+  profileCmd.command("set <name>").description("Set the active-profile metadata").action((name) => {
     const clean = name.trim().toLowerCase().replace(/[^a-z0-9_-]/g, "-");
     if (!clean) {
       console.error(chalk29.red("Invalid profile name. Use letters, numbers, hyphens, underscores."));
       process.exit(1);
     }
     setActiveProfile(clean);
-    console.log(chalk29.green(`\u2713 Switched to profile: ${clean}`));
-    console.log(chalk29.dim(`  DB: ~/.hasna/mementos/profiles/${clean}.db (created on first use)`));
+    console.log(chalk29.green(`\u2713 Active-profile metadata set: ${clean}`));
+    console.log(chalk29.dim(`  Profile file: ~/.hasna/mementos/profiles/${clean}.db`));
+    console.log(chalk29.dim("  Run `mementos storage mode` to verify the live runtime database."));
   });
-  profileCmd.command("unset").description("Clear the active profile (revert to default DB)").action(() => {
+  profileCmd.command("unset").description("Clear the active-profile metadata").action(() => {
     const was = getActiveProfile();
     setActiveProfile(null);
     if (was) {
@@ -63178,7 +63484,7 @@ function registerProfileCommand(program2) {
     } else {
       console.log(chalk29.dim("No active profile was set."));
     }
-    console.log(chalk29.dim("  Now using default DB: ~/.hasna/mementos/mementos.db"));
+    console.log(chalk29.dim("  Run `mementos storage mode` to verify the live runtime database."));
   });
   profileCmd.command("delete <name>").description("Delete a profile and its DB file (irreversible)").option("-y, --yes", "Skip confirmation prompt").action(async (name, opts) => {
     if (!opts.yes) {
@@ -63971,19 +64277,20 @@ function registerMiscCommands(program2) {
 // src/cli/commands/system-mcp.ts
 import chalk38 from "chalk";
 function registerMcpCommand(program2) {
-  program2.command("mcp").description("Install mementos MCP server into Claude Code, Codex, or Gemini").option("--claude", "Install into Claude Code (~/.claude/.mcp.json)").option("--codex", "Install into Codex (~/.codex/config.toml)").option("--gemini", "Install into Gemini (~/.gemini/settings.json)").option("--all", "Install into all supported agents").option("--uninstall", "Remove mementos MCP from config").action((opts) => {
-    const { readFileSync: _rfs, writeFileSync: _wfs, existsSync: fileExists } = __require("fs");
+  program2.command("mcp").description("Install mementos MCP server into Claude Code, Codex, Cursor, or Gemini").option("--claude", "Install into Claude Code (~/.claude/.mcp.json)").option("--codex", "Install into Codex (~/.codex/config.toml)").option("--cursor", "Install into Cursor (~/.cursor/mcp.json)").option("--gemini", "Install into Gemini (~/.gemini/settings.json)").option("--all", "Install into all supported agents").option("--uninstall", "Remove mementos MCP from config").action((opts) => {
+    const { readFileSync: _rfs, writeFileSync: _wfs, existsSync: fileExists, mkdirSync: makeDir } = __require("fs");
     const { join: pathJoin } = __require("path");
     const { homedir: getHome } = __require("os");
     const home = getHome();
     const mementosCmd = process.argv[0]?.includes("bun") ? pathJoin(home, ".bun", "bin", "mementos-mcp") : "mementos-mcp";
-    const targets = opts.all ? ["claude", "codex", "gemini"] : [
+    const targets = opts.all ? ["claude", "codex", "cursor", "gemini"] : [
       opts.claude ? "claude" : null,
       opts.codex ? "codex" : null,
+      opts.cursor ? "cursor" : null,
       opts.gemini ? "gemini" : null
     ].filter(Boolean);
     if (targets.length === 0) {
-      console.log(chalk38.yellow("Specify a target: --claude, --codex, --gemini, or --all"));
+      console.log(chalk38.yellow("Specify a target: --claude, --codex, --cursor, --gemini, or --all"));
       console.log(chalk38.gray("Example: mementos mcp --all"));
       return;
     }
@@ -64029,6 +64336,28 @@ args = []
             console.log(chalk38.yellow(`Codex config not found: ${configPath}`));
           }
         }
+        if (target === "cursor") {
+          const configDir = pathJoin(home, ".cursor");
+          const configPath = pathJoin(configDir, "mcp.json");
+          let config = {};
+          if (fileExists(configPath)) {
+            config = JSON.parse(_rfs(configPath, "utf-8"));
+          } else if (opts.uninstall) {
+            console.log(chalk38.yellow(`mementos was not installed in Cursor: ${configPath}`));
+            continue;
+          }
+          const servers = config["mcpServers"] || {};
+          if (opts.uninstall) {
+            delete servers["mementos"];
+          } else {
+            servers["mementos"] = { command: mementosCmd, args: [] };
+          }
+          config["mcpServers"] = servers;
+          makeDir(configDir, { recursive: true });
+          _wfs(configPath, JSON.stringify(config, null, 2) + `
+`, "utf-8");
+          console.log(chalk38.green(`${opts.uninstall ? "Removed from" : "Installed into"} Cursor: ${configPath}`));
+        }
         if (target === "gemini") {
           const configPath = pathJoin(home, ".gemini", "settings.json");
           let config = {};
@@ -64060,7 +64389,7 @@ import chalk39 from "chalk";
 import { resolve as resolve19 } from "path";
 function registerWatchCommand(program2) {
   const handleError = makeHandleError(program2);
-  program2.command("watch").description("Watch for new and changed memories in real-time").option("-s, --scope <scope>", "Scope filter: global, shared, private").option("-c, --category <cat>", "Category filter: preference, fact, knowledge, history").option("--agent <name>", "Agent filter").option("--project <path>", "Project filter").option("--interval <ms>", "Poll interval in milliseconds", parseInt).action((opts) => {
+  program2.command("watch").description("Watch for new and changed memories in real-time").option("--scope <scope>", "Scope filter: global, shared, private, working").option("-c, --category <cat>", "Category filter: preference, fact, knowledge, history, procedural, resource").option("--agent <name>", "Agent filter").option("--project <path>", "Project filter").option("--interval <ms>", "Poll interval in milliseconds", parseInt).action((opts) => {
     try {
       const globalOpts = program2.opts();
       const agentId = opts.agent || globalOpts.agent;
@@ -64656,6 +64985,35 @@ function getStorageSyncStatus(options = {}) {
   }
 }
 
+// src/db/store-backend.ts
+init_database();
+init_api_mode();
+init_storage();
+function resolveStoreBackend() {
+  const apiMode = isApiMode();
+  const apiConfig = getApiConfig();
+  const storageMode = getStorageMode();
+  const sources = getApiModeEnvSources();
+  const backend = apiMode ? "cloud-api" : storageMode === "cloud" ? "cloud-postgres" : "local-sqlite";
+  let selectedBy = "default";
+  if (apiMode) {
+    selectedBy = `${sources.urlKey} + ${sources.keyKey} (presence)`;
+  } else if (backend === "cloud-postgres") {
+    const modeKey = [MEMENTOS_STORAGE_ENV.mode, MEMENTOS_STORAGE_FALLBACK_ENV.mode].find((key) => process.env[key]?.trim());
+    selectedBy = modeKey ?? sources.databaseUrlKey ?? "storage config file";
+  }
+  return {
+    schema: "mementos.store_backend.v1",
+    backend,
+    api_mode: apiMode,
+    storage_mode: storageMode,
+    db_path: getDbPath(),
+    api_endpoint: apiConfig?.baseUrl ?? null,
+    api_key_present: Boolean(apiConfig?.apiKey),
+    selected_by: selectedBy
+  };
+}
+
 // src/cli/commands/storage.ts
 function parseTables(raw) {
   if (!raw) {
@@ -64680,7 +65038,38 @@ function printSyncResult(result) {
   }
 }
 function installStorageSubcommands(storage, program2) {
-  storage.command("status").description("Show local database and remote storage sync status").option("--json", "Output JSON").action((opts) => {
+  withoutStartupDbAccess(storage.command("mode").description("Show which store this process will actually read and write (no DB or network access)").option("--json", "Output JSON").action((opts) => {
+    const useJson = Boolean(opts.json || program2.opts().json);
+    let report;
+    try {
+      report = resolveStoreBackend();
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (useJson)
+        outputJson2(true, { ok: false, error: message });
+      else
+        console.error(chalk40.red(message));
+      process.exitCode = 1;
+      return;
+    }
+    if (useJson) {
+      outputJson2(true, report);
+      return;
+    }
+    const label = report.backend === "local-sqlite" ? chalk40.green(report.backend) : chalk40.yellow(report.backend);
+    console.log(`Backend: ${label}`);
+    console.log(`Selected by: ${report.selected_by}`);
+    console.log(`API mode: ${report.api_mode ? "yes" : "no"}`);
+    console.log(`Storage mode: ${report.storage_mode}`);
+    if (report.backend === "local-sqlite") {
+      console.log(`Database: ${report.db_path}`);
+    } else {
+      console.log(`API endpoint: ${report.api_endpoint ?? "(none)"}`);
+      console.log(`API key: ${report.api_key_present ? "configured" : "not configured"}`);
+      console.log(`Local SQLite (not authoritative): ${report.db_path}`);
+    }
+  }));
+  storage.command("status").description("Show local database, legacy sync, and storage runtime status").option("--json", "Output JSON").action((opts) => {
     const useJson = Boolean(opts.json || program2.opts().json);
     const status = getStorageSyncStatus();
     const config = getStorageConfig();
@@ -64837,7 +65226,7 @@ function installStorageSubcommands(storage, program2) {
       process.exitCode = 1;
     }
   });
-  storage.command("feedback").description("Save feedback locally").argument("<message>", "Feedback message").option("--email <email>", "Contact email").option("--category <category>", "Feedback category", "general").option("--json", "Output JSON").action((message, opts) => {
+  storage.command("feedback").description("Save feedback to the selected store").argument("<message>", "Feedback message").option("--email <email>", "Contact email").option("--category <category>", "Feedback category", "general").option("--json", "Output JSON").action((message, opts) => {
     const useJson = Boolean(opts.json || program2.opts().json);
     try {
       const { saveFeedback: saveFeedback2 } = (init_feedback(), __toCommonJS(exports_feedback));
@@ -64864,7 +65253,7 @@ function installStorageSubcommands(storage, program2) {
   });
 }
 function registerStorageCommands(program2) {
-  const storage = program2.command("storage").description("Manage mementos local/remote storage sync");
+  const storage = program2.command("storage").description("Inspect storage and manage migrations or legacy row sync");
   installStorageSubcommands(storage, program2);
 }
 
@@ -65140,7 +65529,7 @@ function parseMemoryLink(row) {
 function createMemoryLink(input, db) {
   const d = db || getDatabase();
   const id = shortUuid();
-  const timestamp = now2();
+  const timestamp = now();
   d.run(`INSERT OR IGNORE INTO memory_links (id, source_memory_id, target_memory_id, relation_type, run_id, metadata, created_at)
      VALUES (?, ?, ?, ?, ?, ?, ?)`, [
     id,
@@ -65226,7 +65615,7 @@ function createRun(options, db) {
     options.projectId ?? null,
     options.agentId ?? null,
     options.dryRun ?? true ? 1 : 0,
-    now2()
+    now()
   ]);
   return getRun(id, db);
 }
@@ -65271,7 +65660,7 @@ function persistAction(action, db) {
     action.reason,
     JSON.stringify(action.plannedChanges),
     action.applied ? 1 : 0,
-    now2()
+    now()
   ]);
 }
 function markActionApplied(action, db) {
@@ -65646,11 +66035,11 @@ async function runConsolidation(options = {}) {
       actions = applied;
     }
     const summary = buildSummary2(actions);
-    run = updateRun(run.id, { status: "completed", summary, completed_at: now2() }, db);
+    run = updateRun(run.id, { status: "completed", summary, completed_at: now() }, db);
     return { run, actions, dryRun, summary };
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    run = updateRun(run.id, { status: "failed", error: message, completed_at: now2() }, db);
+    run = updateRun(run.id, { status: "failed", error: message, completed_at: now() }, db);
     return {
       run,
       actions: [],
@@ -65723,7 +66112,7 @@ function createRun2(options, memoryIds, db) {
     options.provider ?? null,
     options.model ?? null,
     JSON.stringify(memoryIds),
-    now2()
+    now()
   ]);
   return getRun2(id, db);
 }
@@ -65766,7 +66155,7 @@ function insertLessonRow(runId, lesson, db) {
     lesson.lesson,
     JSON.stringify(lesson.evidence),
     lesson.importance,
-    now2()
+    now()
   ]);
 }
 function listToolEventsForTrajectory(options, db) {
@@ -66059,7 +66448,7 @@ async function reflectOnTrajectory(options) {
         }
       });
     }
-    run = updateRun2(run.id, { status: "completed", summary: criticResult.summary, completed_at: now2() }, db);
+    run = updateRun2(run.id, { status: "completed", summary: criticResult.summary, completed_at: now() }, db);
     return {
       run,
       dryRun,
@@ -66073,7 +66462,7 @@ async function reflectOnTrajectory(options) {
     };
   } catch (error40) {
     const message = error40 instanceof Error ? error40.message : String(error40);
-    run = updateRun2(run.id, { status: "failed", error: message, completed_at: now2() }, db);
+    run = updateRun2(run.id, { status: "failed", error: message, completed_at: now() }, db);
     return {
       run,
       dryRun,
@@ -66489,6 +66878,26 @@ function makeBrainsCommand() {
   return brains;
 }
 
+// src/cli/register-all.ts
+function registerAllCommands(program2) {
+  registerInitCommand(program2);
+  registerMemoryCommands(program2);
+  registerInfoCommands(program2);
+  registerIoCommands(program2);
+  registerAgentCommands(program2);
+  registerProjectCommands(program2);
+  registerProjectPanelCommand(program2);
+  registerEntityCommands(program2);
+  registerRelationCommands(program2);
+  registerGraphCommands(program2);
+  registerSystemCommands(program2);
+  registerStorageCommands(program2);
+  registerConsolidationCommands(program2);
+  program2.addCommand(makeBrainsCommand());
+  registerEventsCommands(program2, { source: "mementos" });
+  return program2;
+}
+
 // src/cli/index.tsx
 function getPackageVersion2() {
   try {
@@ -66500,9 +66909,12 @@ function getPackageVersion2() {
   }
 }
 var program2 = new Command;
-program2.name("mementos").description("Universal memory system for AI agents").version(getPackageVersion2()).option("-p, --project <path>", "Project path for scoping").option("-j, --json", "Output as JSON").option("-f, --format <fmt>", "Output format: compact, json, csv, yaml").option("-a, --agent <name>", "Agent name or ID").option("-s, --session <id>", "Session ID");
+program2.name("mementos").description("Universal memory system for AI agents").version(getPackageVersion2());
+applyGlobalOptions(program2);
 var startupWarningShown = false;
-program2.hook("preAction", () => {
+program2.hook("preAction", (_thisCommand, actionCommand) => {
+  if (skipsStartupDbAccess(actionCommand))
+    return;
   if (startupWarningShown)
     return;
   startupWarningShown = true;
@@ -66513,19 +66925,5 @@ program2.hook("preAction", () => {
     }
   } catch {}
 });
-registerInitCommand(program2);
-registerMemoryCommands(program2);
-registerInfoCommands(program2);
-registerIoCommands(program2);
-registerAgentCommands(program2);
-registerProjectCommands(program2);
-registerProjectPanelCommand(program2);
-registerEntityCommands(program2);
-registerRelationCommands(program2);
-registerGraphCommands(program2);
-registerSystemCommands(program2);
-registerStorageCommands(program2);
-registerConsolidationCommands(program2);
-program2.addCommand(makeBrainsCommand());
-registerEventsCommands(program2, { source: "mementos" });
+registerAllCommands(program2);
 program2.parse(process.argv);