@hasna/mementos 0.14.68 → 0.14.69

package/dist/cli/index.js

@@ -2101,9 +2101,9 @@ var require_commander = __commonJS((exports) => {
 
 // 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";
@@ -2371,7 +2371,7 @@ function normalizeStorageMode(value) {
   return null;
 }
 function readConfigFile() {
-  if (!existsSync2(STORAGE_CONFIG_PATH)) {
+  if (!existsSync(STORAGE_CONFIG_PATH)) {
     return {};
   }
   try {
@@ -2831,12 +2831,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 +2911,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 +2927,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 +2958,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 +2969,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 +3015,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 +3046,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 +3072,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 +3113,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 +3151,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;
@@ -4022,13 +4086,13 @@ __export(exports_database, {
   shortUuid: () => shortUuid,
   resolvePartialId: () => resolvePartialId,
   resetDatabase: () => resetDatabase,
-  now: () => now2,
+  now: () => now,
   getDbPath: () => getDbPath,
   getDatabase: () => getDatabase,
   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 +4101,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 +4114,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 +4125,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 +4144,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 +4254,7 @@ function resetDatabase() {
   _db = null;
   _pg = null;
 }
-function now2() {
+function now() {
   return new Date().toISOString();
 }
 function uuid() {
@@ -4236,8 +4300,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 +4469,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 +4675,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 +4801,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 +4943,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 +5010,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 +5042,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,7 +5375,7 @@ 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);
     return data;
@@ -5283,7 +5406,7 @@ function updateMemory(id, input, db) {
     ]);
   } 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));
@@ -5360,7 +5483,7 @@ 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();
@@ -5393,14 +5516,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 +5540,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 +5635,7 @@ var init_memories = __esm(() => {
   init_types();
   init_database();
   init_redact();
+  init_enum_validation();
   init_hooks();
   init_poisoning();
   init_entity_memories();
@@ -5547,7 +5671,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 +5687,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 +5737,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 +5780,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 +5863,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 +5913,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 +6578,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 +6627,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;
@@ -6541,7 +6665,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 +6680,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 +6689,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 +7526,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 +7579,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;
@@ -8367,7 +8491,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 +8509,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 +8545,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 +8576,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 +8674,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 +8775,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 +8834,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 +8848,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 +9102,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);
@@ -9456,7 +9580,7 @@ async function buildCorpus(options) {
     duplicateCandidates,
     lowImportanceHighRecall,
     highImportanceLowRecall,
-    generatedAt: now2()
+    generatedAt: now()
   };
 }
 var init_corpus_builder = __esm(() => {
@@ -9789,7 +9913,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 +9962,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 +9977,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 +9994,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 +10009,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 +10042,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 +10062,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 +10094,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 +10103,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 +10112,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 +10121,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 +10136,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 +10274,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 +10301,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 +10317,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 +10383,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 +10402,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 +10532,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 (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
@@ -58701,15 +58825,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 +58971,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 +58981,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 +59055,7 @@ class JsonEventsStore {
     };
   }
   async ensureArrayFile(path) {
-    if (!existsSync(path)) {
+    if (!existsSync3(path)) {
       await writeFile(path, `[]
 `, { encoding: "utf-8", mode: 384 });
     }
@@ -58876,7 +59093,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 +59120,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 +59136,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 +59146,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 +59156,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 +59172,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 +59190,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 +59203,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 +59223,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 +59602,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 +59658,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 +59701,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 +59740,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 +59807,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 +59931,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 +59956,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 +59981,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 +60000,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 +60042,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").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) => {
     try {
       const globalOpts = program2.opts();
       const jsonMode = !!globalOpts.json;
@@ -59955,7 +60156,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 +60417,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 +60474,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 +60532,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 +61181,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 +61497,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 +61508,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 +61519,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 +61547,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 +61840,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);
@@ -64060,7 +64263,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").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) => {
     try {
       const globalOpts = program2.opts();
       const agentId = opts.agent || globalOpts.agent;
@@ -64656,6 +64859,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,6 +64912,26 @@ function printSyncResult(result) {
   }
 }
 function installStorageSubcommands(storage, program2) {
+  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);
+    const report = resolveStoreBackend();
+    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 and remote storage sync status").option("--json", "Output JSON").action((opts) => {
     const useJson = Boolean(opts.json || program2.opts().json);
     const status = getStorageSyncStatus();
@@ -65140,7 +65392,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 +65478,7 @@ function createRun(options, db) {
     options.projectId ?? null,
     options.agentId ?? null,
     options.dryRun ?? true ? 1 : 0,
-    now2()
+    now()
   ]);
   return getRun(id, db);
 }
@@ -65271,7 +65523,7 @@ function persistAction(action, db) {
     action.reason,
     JSON.stringify(action.plannedChanges),
     action.applied ? 1 : 0,
-    now2()
+    now()
   ]);
 }
 function markActionApplied(action, db) {
@@ -65646,11 +65898,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 +65975,7 @@ function createRun2(options, memoryIds, db) {
     options.provider ?? null,
     options.model ?? null,
     JSON.stringify(memoryIds),
-    now2()
+    now()
   ]);
   return getRun2(id, db);
 }
@@ -65766,7 +66018,7 @@ function insertLessonRow(runId, lesson, db) {
     lesson.lesson,
     JSON.stringify(lesson.evidence),
     lesson.importance,
-    now2()
+    now()
   ]);
 }
 function listToolEventsForTrajectory(options, db) {
@@ -66059,7 +66311,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 +66325,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 +66741,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 +66772,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 +66788,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);