@hasna/mementos 0.15.2 → 0.16.0

package/dist/cli/index.js

@@ -2176,312 +2176,6 @@ var init_local_opt_in = __esm(() => {
   CONTRACTS_AMBIENT_ENVIRONMENT = Symbol.for("hasna:contracts:ambientClientEnvironment");
 });
 
-// src/db/api-mode.ts
-import { tmpdir } from "os";
-import { join } from "path";
-import { writeFileSync, unlinkSync } from "fs";
-import { randomUUID } from "crypto";
-import {
-  clientTransportEnvKeys as clientTransportEnvKeys2,
-  resolveClientTransport,
-  resolveCredential,
-  toV1BaseUrl,
-  ClientTransportConfigurationError
-} from "@hasna/contracts/client";
-function firstEnv(keys, env = process.env) {
-  for (const k of keys) {
-    const v = env[k]?.trim();
-    if (v)
-      return v;
-  }
-  return;
-}
-function firstEnvKey(keys, env = process.env) {
-  for (const k of keys) {
-    if (env[k]?.trim())
-      return k;
-  }
-  return null;
-}
-function hasDatabaseUrl(env = process.env) {
-  return Boolean(firstEnv(DATABASE_URL_ENV_KEYS, env));
-}
-function getApiModeEnvSources(env = process.env) {
-  return {
-    urlKey: firstEnvKey(API_URL_ENV_KEYS, env),
-    keyKey: firstEnvKey(API_KEY_ENV_KEYS, env),
-    databaseUrlKey: firstEnvKey(DATABASE_URL_ENV_KEYS, env)
-  };
-}
-function assertCleanResolvedBase(baseUrl) {
-  if (/[?#]/.test(baseUrl)) {
-    throw new Error("mementos base URL must not contain userinfo, query, or fragment data");
-  }
-  return baseUrl;
-}
-function getConfiguredApiEnv(env = process.env, options = {}) {
-  const rawBase = firstEnv(API_URL_ENV_KEYS, env);
-  let baseUrl = null;
-  if (rawBase) {
-    const normalized = toV1BaseUrl(rawBase);
-    assertCleanResolvedBase(normalized);
-    baseUrl = normalized;
-  }
-  const inputs = mementosResolverInputs(env, options.credentials);
-  return {
-    baseUrl,
-    apiKeyPresent: resolveCredential("mementos", inputs.env, inputs.credentials) !== null,
-    dbPathKey: firstEnvKey(DB_PATH_ENV_KEYS, env)
-  };
-}
-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 toStoreConfigError(error) {
-  const message = error instanceof Error ? error.message : String(error);
-  return new MementosStoreConfigError(`${message} Local SQLite is opt-in only (${DB_PATH_ENV_KEYS[0]}, or ${MEMENTOS_LOCAL_OPT_IN_ENV_KEYS[0]} = 1) and is disabled by default \u2014 failing closed`);
-}
-function getApiConfig(env = process.env, options = {}) {
-  if (hasDatabaseUrl(env))
-    return null;
-  if (selectsMementosLocalStore(env))
-    return null;
-  const inputs = mementosResolverInputs(env, options.credentials);
-  let credential;
-  try {
-    credential = resolveCredential("mementos", inputs.env, inputs.credentials);
-  } catch (error) {
-    throw toStoreConfigError(error);
-  }
-  let resolution;
-  try {
-    resolution = resolveClientTransport("mementos", inputs.env, {
-      credentials: credential ? { ...inputs.credentials, apiKey: credential.apiKey } : inputs.credentials
-    });
-  } catch (error) {
-    if (error instanceof ClientTransportConfigurationError && credential === null && /is not set and no API key could be resolved/.test(error.message)) {
-      return null;
-    }
-    throw toStoreConfigError(error);
-  }
-  return { baseUrl: assertCleanResolvedBase(resolution.baseUrl), apiKey: credential.apiKey };
-}
-function isApiMode() {
-  if (hasDatabaseUrl())
-    return false;
-  return getApiConfig() !== null;
-}
-function getResolvedApiModeReport(env = process.env, options = {}) {
-  if (hasDatabaseUrl(env))
-    return null;
-  if (selectsMementosLocalStore(env))
-    return null;
-  const inputs = mementosResolverInputs(env, options.credentials);
-  let credential;
-  try {
-    credential = resolveCredential("mementos", inputs.env, inputs.credentials);
-  } catch (error) {
-    throw toStoreConfigError(error);
-  }
-  if (!credential) {
-    try {
-      resolveClientTransport("mementos", inputs.env, { credentials: inputs.credentials });
-    } catch (error) {
-      if (error instanceof ClientTransportConfigurationError && /is not set and no API key could be resolved/.test(error.message)) {
-        return null;
-      }
-      throw toStoreConfigError(error);
-    }
-    return null;
-  }
-  const resolution = resolveClientTransport("mementos", inputs.env, {
-    credentials: { ...inputs.credentials, apiKey: credential.apiKey }
-  });
-  assertCleanResolvedBase(resolution.baseUrl);
-  return {
-    baseUrl: resolution.baseUrl,
-    apiUrlSource: resolution.apiUrlSource,
-    apiKeySource: credential.source,
-    apiKeyTier: credential.tier
-  };
-}
-function assertClientStoreConfigured(env = process.env, options = {}) {
-  if (selectsMementosLocalStore(env))
-    return;
-  if (hasDatabaseUrl(env))
-    return;
-  const config = getApiConfig(env, options);
-  if (config !== null)
-    return;
-  throw new MementosStoreConfigError(unconfiguredStoreMessage());
-}
-function unconfiguredStoreMessage() {
-  return "mementos is not configured to reach any memory store, and will NOT fall back to the " + "on-box SQLite store (~/.hasna/mementos/mementos.db). " + "No credential could be resolved from the Keychain item hasna.credentials.mementos.api-key " + "(macOS only), ~/.hasna/mementos/config/credentials, or " + `${API_KEY_ENV_KEYS[0]}; the authority would be the fleet gateway ${"https://api.hasna.com/mementos"} ` + `(or ${API_URL_ENV_KEYS[0]} if set). ` + `Set ${API_URL_ENV_KEYS[0]} and ${API_KEY_ENV_KEYS[0]} (the resolver also accepts the legacy ` + `${API_URL_ENV_KEYS[1]} / ${API_KEY_ENV_KEYS[1]} aliases for one release) to use the fleet memory ` + `API, or opt into an explicit local SQLite file with ${DB_PATH_ENV_KEYS[0]} / ` + `${DB_PATH_ENV_KEYS[1]} (or ${MEMENTOS_LOCAL_OPT_IN_ENV_KEYS[0]}=1).`;
-}
-function apiRequestRaw(method, path, body) {
-  const cfg = getApiConfig();
-  if (!cfg)
-    throw new Error("api-mode: not configured (no Hasna mementos credential resolved)");
-  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;
-  const headerLines = `Authorization: Bearer ${cfg.apiKey}
-x-api-key: ${cfg.apiKey}
-`;
-  const args = [
-    "curl",
-    "-sS",
-    "--fail-with-body",
-    "-m",
-    timeout,
-    "-X",
-    method,
-    "-H",
-    "@-",
-    "-H",
-    "Content-Type: application/json",
-    "-H",
-    "Accept: application/json",
-    "-w",
-    "\\n%{http_code}"
-  ];
-  let bodyFile;
-  if (hasBody) {
-    bodyFile = join(tmpdir(), `mem-req-${process.pid}-${randomUUID()}.json`);
-    writeFileSync(bodyFile, JSON.stringify(body), { mode: 384 });
-    args.push("--data-binary", `@${bodyFile}`);
-  }
-  args.push(url);
-  const childEnv = {};
-  for (const [k, v] of Object.entries(process.env)) {
-    if (v === undefined)
-      continue;
-    if (k === "HASNA_MEMENTOS_API_KEY" || k === "MEMENTOS_API_KEY")
-      continue;
-    childEnv[k] = v;
-  }
-  let out = "";
-  let err = "";
-  try {
-    const proc = Bun.spawnSync(args, {
-      stdin: Buffer.from(headerLines),
-      stdout: "pipe",
-      stderr: "pipe",
-      env: childEnv
-    });
-    out = proc.stdout ? new TextDecoder().decode(proc.stdout) : "";
-    err = proc.stderr ? new TextDecoder().decode(proc.stderr) : "";
-  } finally {
-    if (bodyFile) {
-      try {
-        unlinkSync(bodyFile);
-      } catch {}
-    }
-  }
-  const nl = out.lastIndexOf(`
-`);
-  const codeStr = nl >= 0 ? out.slice(nl + 1).trim() : "";
-  const respBody = nl >= 0 ? out.slice(0, nl) : out;
-  const status = parseInt(codeStr, 10);
-  if (!Number.isFinite(status) || status === 0) {
-    throw new ApiRequestError(`mementos cloud request failed (${method} ${path}): ${err.trim() || "no HTTP status"}`, 0, respBody);
-  }
-  return { status, body: respBody };
-}
-function apiJson(method, path, body, options) {
-  const raw = apiRequestRaw(method, path, body);
-  if (raw.status >= 200 && raw.status < 300) {
-    let data;
-    if (raw.body.trim()) {
-      try {
-        data = JSON.parse(raw.body);
-      } catch (e) {
-        throw new ApiRequestError(`mementos cloud ${method} ${path} returned status ${raw.status} with a body that is not valid JSON (${e instanceof Error ? e.message : String(e)}) \u2014 the response is truncated or the server is unhealthy`, raw.status, raw.body.slice(0, 500));
-      }
-    } else {
-      data = undefined;
-    }
-    return { status: raw.status, data };
-  }
-  if (raw.status === 404 && options?.allow404) {
-    return { status: 404, data: undefined };
-  }
-  let msg = `mementos cloud ${method} ${path} \u2192 ${raw.status}`;
-  try {
-    const parsed = JSON.parse(raw.body);
-    if (parsed.error || parsed.message)
-      msg += `: ${parsed.error || parsed.message}`;
-  } catch {
-    if (raw.body.trim())
-      msg += `: ${raw.body.slice(0, 200)}`;
-  }
-  throw new ApiRequestError(msg, raw.status, raw.body);
-}
-function toQuery(params) {
-  const sp = new URLSearchParams;
-  for (const [k, v] of Object.entries(params)) {
-    if (v === undefined || v === null || v === "")
-      continue;
-    if (Array.isArray(v)) {
-      if (v.length === 0)
-        continue;
-      sp.set(k, v.join(","));
-    } else if (typeof v === "boolean") {
-      sp.set(k, v ? "true" : "false");
-    } else {
-      sp.set(k, String(v));
-    }
-  }
-  const s = sp.toString();
-  return s ? `?${s}` : "";
-}
-var API_URL_ENV_KEYS, API_KEY_ENV_KEYS, DATABASE_URL_ENV_KEYS, DB_PATH_ENV_KEYS, ALLOW_REMOTE_API_IN_TESTS_ENV = "MEMENTOS_ALLOW_REMOTE_API_IN_TESTS", MementosStoreConfigError, ApiRequestError, DEFAULT_TIMEOUT_S = "45";
-var init_api_mode = __esm(() => {
-  init_local_opt_in();
-  API_URL_ENV_KEYS = clientTransportEnvKeys2("mementos").apiUrlKeys;
-  API_KEY_ENV_KEYS = clientTransportEnvKeys2("mementos").apiKeyKeys;
-  DATABASE_URL_ENV_KEYS = ["HASNA_MEMENTOS_DATABASE_URL", "MEMENTOS_DATABASE_URL"];
-  DB_PATH_ENV_KEYS = MEMENTOS_DB_PATH_ENV_KEYS;
-  MementosStoreConfigError = class MementosStoreConfigError extends Error {
-    code = "MEMENTOS_STORE_CONFIG";
-    constructor(message) {
-      super(message);
-      this.name = "MementosStoreConfigError";
-    }
-  };
-  ApiRequestError = class ApiRequestError extends Error {
-    status;
-    body;
-    constructor(message, status, body) {
-      super(message);
-      this.status = status;
-      this.body = body;
-      this.name = "ApiRequestError";
-    }
-  };
-});
-
 // src/generated/storage-kit/own.ts
 function ownProp(source, key) {
   if (source === null || source === undefined)
@@ -2538,7 +2232,7 @@ var init_backend = () => {};
 // src/lib/paths.ts
 import { existsSync } from "fs";
 import { homedir } from "os";
-import { join as join2, resolve } from "path";
+import { join, resolve } from "path";
 import { homedir as pathsResolverHomedir } from "os";
 import { join as pathsResolverJoin } from "path";
 function pathsResolverAssertApp(app) {
@@ -2593,7 +2287,7 @@ function effectiveHome() {
   return process.env["HOME"] || process.env["USERPROFILE"] || homedir() || "/tmp";
 }
 function legacyDataRoot() {
-  return join2(effectiveHome(), ".hasna", "mementos");
+  return join(effectiveHome(), ".hasna", "mementos");
 }
 function resolverDataRoot() {
   return dataDir({
@@ -2605,7 +2299,7 @@ function adoptResolverDataRoot(resolved, env = process.env) {
   const dataOverride = env.HASNA_DATA_HOME;
   if (typeof dataOverride === "string" && dataOverride.trim().length > 0)
     return true;
-  return existsSync(join2(resolved, "mementos.db"));
+  return existsSync(join(resolved, "mementos.db"));
 }
 function exactDataRoot() {
   for (const key of ["HASNA_MEMENTOS_HOME", "MEMENTOS_HOME"]) {
@@ -2648,8 +2342,8 @@ var init_env = __esm(() => {
 
 // src/storage.ts
 import { Database } from "bun:sqlite";
-import { existsSync as existsSync2, mkdirSync, readFileSync, writeFileSync as writeFileSync2 } from "fs";
-import { join as join3 } from "path";
+import { existsSync as existsSync2, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { join as join2 } from "path";
 import { fileURLToPath } from "url";
 import { Worker } from "worker_threads";
 import pg from "pg";
@@ -3359,9 +3053,9 @@ var init_storage = __esm(() => {
       const ext = import.meta.url.endsWith(".ts") ? ".ts" : ".js";
       const here = fileURLToPath(new URL(".", import.meta.url));
       const candidates = [
-        join3(here, `pg-sync-worker${ext}`),
-        join3(here, "..", `pg-sync-worker${ext}`),
-        join3(here, "..", "..", `pg-sync-worker${ext}`)
+        join2(here, `pg-sync-worker${ext}`),
+        join2(here, "..", `pg-sync-worker${ext}`),
+        join2(here, "..", "..", `pg-sync-worker${ext}`)
       ];
       for (const candidate of candidates) {
         if (existsSync2(candidate))
@@ -3466,8 +3160,8 @@ var init_storage = __esm(() => {
       schedule_minutes: 0
     }
   };
-  STORAGE_CONFIG_DIR = join3(LOCAL_DATA_DIR, "storage");
-  STORAGE_CONFIG_PATH = join3(STORAGE_CONFIG_DIR, "config.json");
+  STORAGE_CONFIG_DIR = join2(LOCAL_DATA_DIR, "storage");
+  STORAGE_CONFIG_PATH = join2(STORAGE_CONFIG_DIR, "config.json");
   DATABASE_ENV_NAMES = [
     { name: MEMENTOS_STORAGE_ENV.databaseUrl, deprecated: false },
     { name: MEMENTOS_STORAGE_FALLBACK_ENV.databaseUrl, deprecated: false }
@@ -3490,6 +3184,349 @@ var init_storage = __esm(() => {
   ];
 });
 
+// src/db/api-mode.ts
+var exports_api_mode = {};
+__export(exports_api_mode, {
+  unconfiguredStoreMessage: () => unconfiguredStoreMessage,
+  toQuery: () => toQuery,
+  isApiMode: () => isApiMode,
+  getResolvedApiModeReport: () => getResolvedApiModeReport,
+  getConfiguredApiEnv: () => getConfiguredApiEnv,
+  getApiModeEnvSources: () => getApiModeEnvSources,
+  getApiConfig: () => getApiConfig,
+  assertUnambiguousStoreEnv: () => assertUnambiguousStoreEnv,
+  assertClientStoreConfigured: () => assertClientStoreConfigured,
+  apiJson: () => apiJson,
+  MementosStoreConfigError: () => MementosStoreConfigError,
+  DB_PATH_ENV_KEYS: () => DB_PATH_ENV_KEYS,
+  DATABASE_URL_ENV_KEYS: () => DATABASE_URL_ENV_KEYS,
+  ApiRequestError: () => ApiRequestError,
+  API_URL_ENV_KEYS: () => API_URL_ENV_KEYS,
+  API_KEY_ENV_KEYS: () => API_KEY_ENV_KEYS,
+  ALLOW_REMOTE_API_IN_TESTS_ENV: () => ALLOW_REMOTE_API_IN_TESTS_ENV
+});
+import { tmpdir } from "os";
+import { join as join3 } from "path";
+import { writeFileSync as writeFileSync2, unlinkSync } from "fs";
+import { randomUUID } from "crypto";
+import {
+  clientTransportEnvKeys as clientTransportEnvKeys2,
+  resolveClientTransport,
+  resolveCredential,
+  toV1BaseUrl,
+  ClientTransportConfigurationError
+} from "@hasna/contracts/client";
+function firstEnv(keys, env2 = process.env) {
+  for (const k of keys) {
+    const v = env2[k]?.trim();
+    if (v)
+      return v;
+  }
+  return;
+}
+function firstEnvKey(keys, env2 = process.env) {
+  for (const k of keys) {
+    if (env2[k]?.trim())
+      return k;
+  }
+  return null;
+}
+function hasDatabaseUrl(env2 = process.env) {
+  return Boolean(firstEnv(DATABASE_URL_ENV_KEYS, env2));
+}
+function getApiModeEnvSources(env2 = process.env) {
+  return {
+    urlKey: firstEnvKey(API_URL_ENV_KEYS, env2),
+    keyKey: firstEnvKey(API_KEY_ENV_KEYS, env2),
+    databaseUrlKey: firstEnvKey(DATABASE_URL_ENV_KEYS, env2)
+  };
+}
+function assertCleanResolvedBase(baseUrl) {
+  if (/[?#]/.test(baseUrl)) {
+    throw new Error("mementos base URL must not contain userinfo, query, or fragment data");
+  }
+  return baseUrl;
+}
+function getConfiguredApiEnv(env2 = process.env, options = {}) {
+  const rawBase = firstEnv(API_URL_ENV_KEYS, env2);
+  let baseUrl = null;
+  if (rawBase) {
+    const normalized = toV1BaseUrl(rawBase);
+    assertCleanResolvedBase(normalized);
+    baseUrl = normalized;
+  }
+  const inputs = mementosResolverInputs(env2, options.credentials);
+  return {
+    baseUrl,
+    apiKeyPresent: resolveCredential("mementos", inputs.env, inputs.credentials) !== null,
+    dbPathKey: firstEnvKey(DB_PATH_ENV_KEYS, env2)
+  };
+}
+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 toStoreConfigError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return new MementosStoreConfigError(`${message} Local SQLite is opt-in only (${DB_PATH_ENV_KEYS[0]}, or ${MEMENTOS_LOCAL_OPT_IN_ENV_KEYS[0]} = 1) and is disabled by default \u2014 failing closed`);
+}
+function getApiConfig(env2 = process.env, options = {}) {
+  if (hasDatabaseUrl(env2))
+    return null;
+  if (selectsMementosLocalStore(env2))
+    return null;
+  const inputs = mementosResolverInputs(env2, options.credentials);
+  let credential;
+  try {
+    credential = resolveCredential("mementos", inputs.env, inputs.credentials);
+  } catch (error) {
+    throw toStoreConfigError(error);
+  }
+  let resolution;
+  try {
+    resolution = resolveClientTransport("mementos", inputs.env, {
+      credentials: credential ? { ...inputs.credentials, apiKey: credential.apiKey } : inputs.credentials
+    });
+  } catch (error) {
+    if (error instanceof ClientTransportConfigurationError && credential === null && /is not set and no API key could be resolved/.test(error.message)) {
+      return null;
+    }
+    throw toStoreConfigError(error);
+  }
+  return { baseUrl: assertCleanResolvedBase(resolution.baseUrl), apiKey: credential.apiKey };
+}
+function isApiMode() {
+  if (hasDatabaseUrl())
+    return false;
+  if (isServerContext())
+    return false;
+  return getApiConfig() !== null;
+}
+function getResolvedApiModeReport(env2 = process.env, options = {}) {
+  if (hasDatabaseUrl(env2))
+    return null;
+  if (selectsMementosLocalStore(env2))
+    return null;
+  const inputs = mementosResolverInputs(env2, options.credentials);
+  let credential;
+  try {
+    credential = resolveCredential("mementos", inputs.env, inputs.credentials);
+  } catch (error) {
+    throw toStoreConfigError(error);
+  }
+  if (!credential) {
+    try {
+      resolveClientTransport("mementos", inputs.env, { credentials: inputs.credentials });
+    } catch (error) {
+      if (error instanceof ClientTransportConfigurationError && /is not set and no API key could be resolved/.test(error.message)) {
+        return null;
+      }
+      throw toStoreConfigError(error);
+    }
+    return null;
+  }
+  const resolution = resolveClientTransport("mementos", inputs.env, {
+    credentials: { ...inputs.credentials, apiKey: credential.apiKey }
+  });
+  assertCleanResolvedBase(resolution.baseUrl);
+  return {
+    baseUrl: resolution.baseUrl,
+    apiUrlSource: resolution.apiUrlSource,
+    apiKeySource: credential.source,
+    apiKeyTier: credential.tier
+  };
+}
+function assertUnambiguousStoreEnv(env2 = process.env, options = {}) {
+  if (hasExplicitLocalDbPath(env2))
+    return;
+  if (hasDatabaseUrl(env2))
+    return;
+  getApiConfig(env2, options);
+}
+function assertClientStoreConfigured(env2 = process.env, options = {}) {
+  if (selectsMementosLocalStore(env2))
+    return;
+  if (hasDatabaseUrl(env2))
+    return;
+  const config = getApiConfig(env2, options);
+  if (config !== null)
+    return;
+  throw new MementosStoreConfigError(unconfiguredStoreMessage());
+}
+function unconfiguredStoreMessage() {
+  return "mementos is not configured to reach any memory store, and will NOT fall back to the " + "on-box SQLite store (~/.hasna/mementos/mementos.db). " + "No credential could be resolved from the Keychain item hasna.credentials.mementos.api-key " + "(macOS only), ~/.hasna/mementos/config/credentials, or " + `${API_KEY_ENV_KEYS[0]}; the authority would be the fleet gateway ${"https://api.hasna.com/mementos"} ` + `(or ${API_URL_ENV_KEYS[0]} if set). ` + `Set ${API_URL_ENV_KEYS[0]} and ${API_KEY_ENV_KEYS[0]} (the resolver also accepts the legacy ` + `${API_URL_ENV_KEYS[1]} / ${API_KEY_ENV_KEYS[1]} aliases for one release) to use the fleet memory ` + `API, or opt into an explicit local SQLite file with ${DB_PATH_ENV_KEYS[0]} / ` + `${DB_PATH_ENV_KEYS[1]} (or ${MEMENTOS_LOCAL_OPT_IN_ENV_KEYS[0]}=1).`;
+}
+function apiRequestRaw(method, path, body) {
+  const cfg = getApiConfig();
+  if (!cfg)
+    throw new Error("api-mode: not configured (no Hasna mementos credential resolved)");
+  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;
+  const headerLines = `Authorization: Bearer ${cfg.apiKey}
+x-api-key: ${cfg.apiKey}
+`;
+  const args = [
+    "curl",
+    "-sS",
+    "--fail-with-body",
+    "-m",
+    timeout,
+    "-X",
+    method,
+    "-H",
+    "@-",
+    "-H",
+    "Content-Type: application/json",
+    "-H",
+    "Accept: application/json",
+    "-w",
+    "\\n%{http_code}"
+  ];
+  let bodyFile;
+  if (hasBody) {
+    bodyFile = join3(tmpdir(), `mem-req-${process.pid}-${randomUUID()}.json`);
+    try {
+      writeFileSync2(bodyFile, JSON.stringify(body), { mode: 384 });
+    } catch (error) {
+      try {
+        unlinkSync(bodyFile);
+      } catch {}
+      throw error;
+    }
+    args.push("--data-binary", `@${bodyFile}`);
+  }
+  args.push(url);
+  const childEnv = {};
+  for (const [k, v] of Object.entries(process.env)) {
+    if (v === undefined)
+      continue;
+    if (k === "HASNA_MEMENTOS_API_KEY" || k === "MEMENTOS_API_KEY")
+      continue;
+    childEnv[k] = v;
+  }
+  let out = "";
+  let err = "";
+  try {
+    const proc = Bun.spawnSync(args, {
+      stdin: Buffer.from(headerLines),
+      stdout: "pipe",
+      stderr: "pipe",
+      env: childEnv
+    });
+    out = proc.stdout ? new TextDecoder().decode(proc.stdout) : "";
+    err = proc.stderr ? new TextDecoder().decode(proc.stderr) : "";
+  } finally {
+    if (bodyFile) {
+      try {
+        unlinkSync(bodyFile);
+      } catch {}
+    }
+  }
+  const nl = out.lastIndexOf(`
+`);
+  const codeStr = nl >= 0 ? out.slice(nl + 1).trim() : "";
+  const respBody = nl >= 0 ? out.slice(0, nl) : out;
+  const status = parseInt(codeStr, 10);
+  if (!Number.isFinite(status) || status === 0) {
+    throw new ApiRequestError(`mementos cloud request failed (${method} ${path}): ${err.trim() || "no HTTP status"}`, 0, respBody);
+  }
+  return { status, body: respBody };
+}
+function apiJson(method, path, body, options) {
+  const raw = apiRequestRaw(method, path, body);
+  if (raw.status >= 200 && raw.status < 300) {
+    let data;
+    if (raw.body.trim()) {
+      try {
+        data = JSON.parse(raw.body);
+      } catch (e) {
+        throw new ApiRequestError(`mementos cloud ${method} ${path} returned status ${raw.status} with a body that is not valid JSON (${e instanceof Error ? e.message : String(e)}) \u2014 the response is truncated or the server is unhealthy`, raw.status, "");
+      }
+    } else {
+      data = undefined;
+    }
+    return { status: raw.status, data };
+  }
+  if (raw.status === 404 && options?.allow404) {
+    return { status: 404, data: undefined };
+  }
+  let msg = `mementos cloud ${method} ${path} \u2192 ${raw.status}`;
+  try {
+    const parsed = JSON.parse(raw.body);
+    if (parsed.error || parsed.message)
+      msg += `: ${parsed.error || parsed.message}`;
+  } catch {
+    if (raw.body.trim())
+      msg += `: ${raw.body.slice(0, 200)}`;
+  }
+  throw new ApiRequestError(msg, raw.status, raw.body);
+}
+function toQuery(params) {
+  const sp = new URLSearchParams;
+  for (const [k, v] of Object.entries(params)) {
+    if (v === undefined || v === null || v === "")
+      continue;
+    if (Array.isArray(v)) {
+      if (v.length === 0)
+        continue;
+      sp.set(k, v.join(","));
+    } else if (typeof v === "boolean") {
+      sp.set(k, v ? "true" : "false");
+    } else {
+      sp.set(k, String(v));
+    }
+  }
+  const s = sp.toString();
+  return s ? `?${s}` : "";
+}
+var API_URL_ENV_KEYS, API_KEY_ENV_KEYS, DATABASE_URL_ENV_KEYS, DB_PATH_ENV_KEYS, ALLOW_REMOTE_API_IN_TESTS_ENV = "MEMENTOS_ALLOW_REMOTE_API_IN_TESTS", MementosStoreConfigError, ApiRequestError, DEFAULT_TIMEOUT_S = "45";
+var init_api_mode = __esm(() => {
+  init_local_opt_in();
+  init_storage();
+  API_URL_ENV_KEYS = clientTransportEnvKeys2("mementos").apiUrlKeys;
+  API_KEY_ENV_KEYS = clientTransportEnvKeys2("mementos").apiKeyKeys;
+  DATABASE_URL_ENV_KEYS = ["HASNA_MEMENTOS_DATABASE_URL", "MEMENTOS_DATABASE_URL"];
+  DB_PATH_ENV_KEYS = MEMENTOS_DB_PATH_ENV_KEYS;
+  MementosStoreConfigError = class MementosStoreConfigError extends Error {
+    code = "MEMENTOS_STORE_CONFIG";
+    constructor(message) {
+      super(message);
+      this.name = "MementosStoreConfigError";
+    }
+  };
+  ApiRequestError = class ApiRequestError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+      super(message);
+      this.status = status;
+      this.body = body;
+      this.name = "ApiRequestError";
+    }
+  };
+});
+
 // src/project-registration/schema.ts
 function sqliteMementosProjectRegistrationSchemaSql() {
   return `
@@ -4845,6 +4882,220 @@ INSERT OR IGNORE INTO _migrations (id) VALUES (38);
     `
 ${sqliteMementosMemoryProjectLinkSchemaSql()}
 INSERT OR IGNORE INTO _migrations (id) VALUES (40);
+`,
+    `
+DROP TABLE IF EXISTS temp.mementos_m41_machine_preflight;
+CREATE TEMP TABLE mementos_m41_machine_preflight (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL CHECK(
+    length(name) BETWEEN 1 AND 128
+    AND instr(name, char(0)) = 0
+    AND instr(name, char(1)) = 0
+    AND instr(name, char(2)) = 0
+    AND instr(name, char(3)) = 0
+    AND instr(name, char(4)) = 0
+    AND instr(name, char(5)) = 0
+    AND instr(name, char(6)) = 0
+    AND instr(name, char(7)) = 0
+    AND instr(name, char(8)) = 0
+    AND instr(name, char(9)) = 0
+    AND instr(name, char(10)) = 0
+    AND instr(name, char(11)) = 0
+    AND instr(name, char(12)) = 0
+    AND instr(name, char(13)) = 0
+    AND instr(name, char(14)) = 0
+    AND instr(name, char(15)) = 0
+    AND instr(name, char(16)) = 0
+    AND instr(name, char(17)) = 0
+    AND instr(name, char(18)) = 0
+    AND instr(name, char(19)) = 0
+    AND instr(name, char(20)) = 0
+    AND instr(name, char(21)) = 0
+    AND instr(name, char(22)) = 0
+    AND instr(name, char(23)) = 0
+    AND instr(name, char(24)) = 0
+    AND instr(name, char(25)) = 0
+    AND instr(name, char(26)) = 0
+    AND instr(name, char(27)) = 0
+    AND instr(name, char(28)) = 0
+    AND instr(name, char(29)) = 0
+    AND instr(name, char(30)) = 0
+    AND instr(name, char(31)) = 0
+    AND instr(name, char(127)) = 0
+  ),
+  hostname TEXT NOT NULL UNIQUE CHECK(
+    length(hostname) BETWEEN 1 AND 253
+    AND hostname = lower(rtrim(trim(hostname), '.'))
+    AND instr(hostname, ' ') = 0
+    AND instr(hostname, char(9)) = 0
+    AND instr(hostname, char(10)) = 0
+    AND instr(hostname, char(13)) = 0
+    AND instr(hostname, '/') = 0
+    AND instr(hostname, char(92)) = 0
+  ),
+  platform TEXT NOT NULL CHECK(
+    length(platform) BETWEEN 1 AND 64
+    AND platform = lower(trim(platform))
+    AND platform NOT GLOB '*[^a-z0-9._-]*'
+  ),
+  is_primary INTEGER NOT NULL CHECK(is_primary IN (0, 1)),
+  created_at TEXT NOT NULL CHECK(julianday(created_at) IS NOT NULL),
+  last_seen_at TEXT NOT NULL CHECK(
+    julianday(last_seen_at) IS NOT NULL
+    AND julianday(last_seen_at) >= julianday(created_at)
+  )
+);
+INSERT INTO mementos_m41_machine_preflight
+  (id, name, hostname, platform, is_primary, created_at, last_seen_at)
+SELECT
+  id,
+  name,
+  lower(rtrim(trim(hostname), '.')),
+  platform,
+  is_primary,
+  created_at,
+  last_seen_at
+FROM machines;
+
+UPDATE machines
+SET hostname = (
+  SELECT preflight.hostname
+  FROM mementos_m41_machine_preflight preflight
+  WHERE preflight.id = machines.id
+);
+
+DROP TABLE mementos_m41_machine_preflight;
+DROP TRIGGER IF EXISTS machines_single_primary_insert;
+DROP TRIGGER IF EXISTS machines_single_primary_update;
+DROP INDEX IF EXISTS idx_machines_hostname;
+CREATE UNIQUE INDEX idx_machines_hostname ON machines(hostname);
+DROP INDEX IF EXISTS idx_machines_single_primary;
+CREATE UNIQUE INDEX idx_machines_single_primary
+  ON machines(is_primary) WHERE is_primary = 1;
+
+CREATE TRIGGER IF NOT EXISTS machines_hostname_canonical_insert
+BEFORE INSERT ON machines
+WHEN NEW.hostname != lower(rtrim(trim(NEW.hostname), '.'))
+  OR length(NEW.hostname) NOT BETWEEN 1 AND 253
+  OR instr(NEW.hostname, ' ') > 0
+  OR instr(NEW.hostname, char(9)) > 0
+  OR instr(NEW.hostname, char(10)) > 0
+  OR instr(NEW.hostname, char(13)) > 0
+  OR instr(NEW.hostname, '/') > 0
+  OR instr(NEW.hostname, char(92)) > 0
+BEGIN
+  SELECT RAISE(ABORT, 'machines.hostname must be canonical');
+END;
+
+CREATE TRIGGER IF NOT EXISTS machines_hostname_canonical_update
+BEFORE UPDATE OF hostname ON machines
+WHEN NEW.hostname != lower(rtrim(trim(NEW.hostname), '.'))
+  OR length(NEW.hostname) NOT BETWEEN 1 AND 253
+  OR instr(NEW.hostname, ' ') > 0
+  OR instr(NEW.hostname, char(9)) > 0
+  OR instr(NEW.hostname, char(10)) > 0
+  OR instr(NEW.hostname, char(13)) > 0
+  OR instr(NEW.hostname, '/') > 0
+  OR instr(NEW.hostname, char(92)) > 0
+BEGIN
+  SELECT RAISE(ABORT, 'machines.hostname must be canonical');
+END;
+
+CREATE TRIGGER IF NOT EXISTS machines_runtime_contract_insert
+BEFORE INSERT ON machines
+WHEN length(NEW.name) NOT BETWEEN 1 AND 128
+  OR instr(NEW.name, char(0)) > 0
+  OR instr(NEW.name, char(1)) > 0
+  OR instr(NEW.name, char(2)) > 0
+  OR instr(NEW.name, char(3)) > 0
+  OR instr(NEW.name, char(4)) > 0
+  OR instr(NEW.name, char(5)) > 0
+  OR instr(NEW.name, char(6)) > 0
+  OR instr(NEW.name, char(7)) > 0
+  OR instr(NEW.name, char(8)) > 0
+  OR instr(NEW.name, char(9)) > 0
+  OR instr(NEW.name, char(10)) > 0
+  OR instr(NEW.name, char(11)) > 0
+  OR instr(NEW.name, char(12)) > 0
+  OR instr(NEW.name, char(13)) > 0
+  OR instr(NEW.name, char(14)) > 0
+  OR instr(NEW.name, char(15)) > 0
+  OR instr(NEW.name, char(16)) > 0
+  OR instr(NEW.name, char(17)) > 0
+  OR instr(NEW.name, char(18)) > 0
+  OR instr(NEW.name, char(19)) > 0
+  OR instr(NEW.name, char(20)) > 0
+  OR instr(NEW.name, char(21)) > 0
+  OR instr(NEW.name, char(22)) > 0
+  OR instr(NEW.name, char(23)) > 0
+  OR instr(NEW.name, char(24)) > 0
+  OR instr(NEW.name, char(25)) > 0
+  OR instr(NEW.name, char(26)) > 0
+  OR instr(NEW.name, char(27)) > 0
+  OR instr(NEW.name, char(28)) > 0
+  OR instr(NEW.name, char(29)) > 0
+  OR instr(NEW.name, char(30)) > 0
+  OR instr(NEW.name, char(31)) > 0
+  OR instr(NEW.name, char(127)) > 0
+  OR length(NEW.platform) NOT BETWEEN 1 AND 64
+  OR NEW.platform != lower(trim(NEW.platform))
+  OR NEW.platform GLOB '*[^a-z0-9._-]*'
+  OR NEW.is_primary NOT IN (0, 1)
+  OR julianday(NEW.created_at) IS NULL
+  OR julianday(NEW.last_seen_at) IS NULL
+  OR julianday(NEW.last_seen_at) < julianday(NEW.created_at)
+BEGIN
+  SELECT RAISE(ABORT, 'machines row violates the persisted runtime contract');
+END;
+
+CREATE TRIGGER IF NOT EXISTS machines_runtime_contract_update
+BEFORE UPDATE OF name, platform, is_primary, created_at, last_seen_at ON machines
+WHEN length(NEW.name) NOT BETWEEN 1 AND 128
+  OR instr(NEW.name, char(0)) > 0
+  OR instr(NEW.name, char(1)) > 0
+  OR instr(NEW.name, char(2)) > 0
+  OR instr(NEW.name, char(3)) > 0
+  OR instr(NEW.name, char(4)) > 0
+  OR instr(NEW.name, char(5)) > 0
+  OR instr(NEW.name, char(6)) > 0
+  OR instr(NEW.name, char(7)) > 0
+  OR instr(NEW.name, char(8)) > 0
+  OR instr(NEW.name, char(9)) > 0
+  OR instr(NEW.name, char(10)) > 0
+  OR instr(NEW.name, char(11)) > 0
+  OR instr(NEW.name, char(12)) > 0
+  OR instr(NEW.name, char(13)) > 0
+  OR instr(NEW.name, char(14)) > 0
+  OR instr(NEW.name, char(15)) > 0
+  OR instr(NEW.name, char(16)) > 0
+  OR instr(NEW.name, char(17)) > 0
+  OR instr(NEW.name, char(18)) > 0
+  OR instr(NEW.name, char(19)) > 0
+  OR instr(NEW.name, char(20)) > 0
+  OR instr(NEW.name, char(21)) > 0
+  OR instr(NEW.name, char(22)) > 0
+  OR instr(NEW.name, char(23)) > 0
+  OR instr(NEW.name, char(24)) > 0
+  OR instr(NEW.name, char(25)) > 0
+  OR instr(NEW.name, char(26)) > 0
+  OR instr(NEW.name, char(27)) > 0
+  OR instr(NEW.name, char(28)) > 0
+  OR instr(NEW.name, char(29)) > 0
+  OR instr(NEW.name, char(30)) > 0
+  OR instr(NEW.name, char(31)) > 0
+  OR instr(NEW.name, char(127)) > 0
+  OR length(NEW.platform) NOT BETWEEN 1 AND 64
+  OR NEW.platform != lower(trim(NEW.platform))
+  OR NEW.platform GLOB '*[^a-z0-9._-]*'
+  OR NEW.is_primary NOT IN (0, 1)
+  OR julianday(NEW.created_at) IS NULL
+  OR julianday(NEW.last_seen_at) IS NULL
+  OR julianday(NEW.last_seen_at) < julianday(NEW.created_at)
+BEGIN
+  SELECT RAISE(ABORT, 'machines row violates the persisted runtime contract');
+END;
+
+INSERT OR IGNORE INTO _migrations (id) VALUES (41);
 `
   ];
 });
@@ -4860,7 +5111,8 @@ __export(exports_database, {
   getDbPath: () => getDbPath,
   getDatabase: () => getDatabase,
   escapeLikePrefix: () => escapeLikePrefix,
-  closeDatabase: () => closeDatabase
+  closeDatabase: () => closeDatabase,
+  applyMachineIdentityMigration: () => applyMachineIdentityMigration
 });
 import { existsSync as existsSync3, mkdirSync as mkdirSync2, cpSync } from "fs";
 import { dirname, join as join4, resolve as resolve2 } from "path";
@@ -4988,32 +5240,62 @@ function getDatabase(dbPath) {
   return _db;
 }
 function runMigrations(db) {
+  let currentLevel = 0;
   try {
     const result = db.query("SELECT MAX(id) as max_id FROM _migrations").get();
-    const currentLevel = result?.max_id ?? 0;
-    for (let i = currentLevel;i < MIGRATIONS.length; i++) {
-      try {
-        applyMigration(db, i);
-      } catch (e) {
-        console.warn(`[mementos] Migration ${i + 1} failed: ${e instanceof Error ? e.message : String(e)}`);
-      }
-    }
-  } catch {
-    for (let i = 0;i < MIGRATIONS.length; i++) {
-      try {
-        applyMigration(db, i);
-      } catch (e) {
-        console.warn(`[mementos] Migration ${i + 1} failed: ${e instanceof Error ? e.message : String(e)}`);
+    currentLevel = result?.max_id ?? 0;
+  } catch {}
+  for (let i = currentLevel;i < MIGRATIONS.length; i++) {
+    try {
+      applyMigration(db, i);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (i === 40) {
+        throw new Error(`Mementos migration 41 refused unsafe machine identity data: ${message}`);
       }
+      console.warn(`[mementos] Migration ${i + 1} failed: ${message}`);
     }
   }
 }
 function applyMigration(db, index) {
-  if (index === 32) {
+  if (index === 32)
     ensureMachinePrimaryColumn(db);
+  if (index === 40) {
+    applyMachineIdentityMigration(db);
+    return;
   }
   db.exec(MIGRATIONS[index]);
 }
+function applyMachineIdentityMigration(db) {
+  db.transaction(() => {
+    const rows = db.query("SELECT id, name, hostname, platform, is_primary, created_at, last_seen_at FROM machines").all();
+    const identities = new Map;
+    let primaryCount = 0;
+    for (const row of rows) {
+      const canonical = row.hostname.trim().replace(/\.+$/, "").toLowerCase();
+      const createdAt = new Date(row.created_at).getTime();
+      const lastSeenAt = new Date(row.last_seen_at).getTime();
+      const primaryValueValid = row.is_primary === 0 || row.is_primary === 1 || row.is_primary === false || row.is_primary === true;
+      if (!row.id || !row.name || row.name.length > 128 || /[\u0000-\u001f\u007f]/.test(row.name) || !canonical || canonical.length > 253 || /[\u0000-\u001f\u007f/\\\s]/.test(canonical) || !row.platform || row.platform.length > 64 || row.platform !== row.platform.trim().toLowerCase() || !/^[a-z0-9._-]+$/.test(row.platform) || !primaryValueValid || !Number.isFinite(createdAt) || !Number.isFinite(lastSeenAt) || lastSeenAt < createdAt) {
+        throw new Error(`invalid legacy machine row ${row.id || "(missing id)"}`);
+      }
+      const owner = identities.get(canonical);
+      if (owner && owner !== row.id) {
+        throw new Error(`ambiguous normalized hostname '${canonical}' belongs to both ${owner} and ${row.id}`);
+      }
+      identities.set(canonical, row.id);
+      if (Boolean(row.is_primary))
+        primaryCount += 1;
+    }
+    if (primaryCount > 1) {
+      throw new Error(`legacy machine registry contains ${primaryCount} primary rows`);
+    }
+    db.exec(MIGRATIONS[40]);
+    const receipt = db.query("SELECT id FROM _migrations WHERE id = 41").get();
+    if (receipt?.id !== 41)
+      throw new Error("machine identity migration did not record completion");
+  });
+}
 function ensureMachinePrimaryColumn(db) {
   const columns = db.query("PRAGMA table_info(machines)").all();
   if (columns.length === 0 || columns.some((column) => column.name === "is_primary")) {
@@ -5087,6 +5369,70 @@ var init_database = __esm(() => {
   ]);
 });
 
+// src/db/api-response-contract.ts
+function expectObject(value, operation) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new MementosApiProtocolError(operation, "expected a JSON object");
+  }
+  return value;
+}
+function expectArray(value, operation, field) {
+  if (!Array.isArray(value)) {
+    throw new MementosApiProtocolError(operation, field ? `expected '${field}' to be an array` : "expected a JSON array");
+  }
+  return value;
+}
+function expectString(object, field, operation, options = {}) {
+  const value = object[field];
+  if (typeof value !== "string" || !options.allowEmpty && value.length === 0) {
+    throw new MementosApiProtocolError(operation, `expected '${field}' to be ${options.allowEmpty ? "a string" : "a non-empty string"}`);
+  }
+  return value;
+}
+function expectNullableString(object, field, operation) {
+  const value = object[field];
+  if (value === null)
+    return null;
+  if (typeof value !== "string") {
+    throw new MementosApiProtocolError(operation, `expected '${field}' to be a string or null`);
+  }
+  return value.length === 0 ? null : value;
+}
+function expectBoolean(object, field, operation) {
+  const value = object[field];
+  if (typeof value !== "boolean") {
+    throw new MementosApiProtocolError(operation, `expected '${field}' to be a boolean`);
+  }
+  return value;
+}
+function expectNonNegativeInteger(object, field, operation) {
+  const value = object[field];
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new MementosApiProtocolError(operation, `expected '${field}' to be a non-negative safe integer`);
+  }
+  return value;
+}
+function expectRecord(object, field, operation) {
+  try {
+    return expectObject(object[field], operation);
+  } catch (error) {
+    if (error instanceof MementosApiProtocolError) {
+      throw new MementosApiProtocolError(operation, `expected '${field}' to be a JSON object`);
+    }
+    throw error;
+  }
+}
+var MementosApiProtocolError;
+var init_api_response_contract = __esm(() => {
+  MementosApiProtocolError = class MementosApiProtocolError extends Error {
+    code = "MEMENTOS_API_PROTOCOL";
+    constructor(operation, detail) {
+      super(`mementos cloud ${operation} returned a malformed 2xx response: ${detail}`);
+      this.name = "MementosApiProtocolError";
+    }
+  };
+});
+
 // src/lib/redact.ts
 function redactSecrets(text) {
   let result = text;
@@ -6076,7 +6422,7 @@ function buildMemoryListConditions(filter) {
       conditions.push("status = 'active'");
     }
     if (filter.project_id) {
-      conditions.push("project_id = ?");
+      conditions.push(filter.include_unassigned_project === true ? "(project_id = ? OR project_id IS NULL)" : "project_id = ?");
       params.push(filter.project_id);
     }
     if (filter.agent_id) {
@@ -6156,6 +6502,7 @@ function listMemoriesPage(filter, db) {
       pinned: f.pinned,
       agent_id: f.agent_id,
       project_id: f.project_id,
+      include_unassigned_project: f.project_id && f.include_unassigned_project === true ? true : undefined,
       session_id: f.session_id,
       machine_id: f.machine_id,
       visible_to_machine_id: f.visible_to_machine_id,
@@ -6180,7 +6527,7 @@ function listMemoriesPage(filter, db) {
   if (conditions.length > 0) {
     sql += ` WHERE ${conditions.join(" AND ")}`;
   }
-  sql += " ORDER BY importance DESC, created_at DESC";
+  sql += " ORDER BY importance DESC, created_at DESC, id DESC";
   if (f.limit) {
     sql += " LIMIT ?";
     params.push(f.limit);
@@ -6324,7 +6671,7 @@ function listMemoryHistoryPage(opts = {}, db) {
   }
   const d = db || getDatabase();
   const params = [limit];
-  let sql = "SELECT * FROM memories WHERE status = 'active' AND accessed_at IS NOT NULL ORDER BY accessed_at DESC LIMIT ?";
+  let sql = "SELECT * FROM memories WHERE status = 'active' AND accessed_at IS NOT NULL ORDER BY accessed_at DESC, id DESC LIMIT ?";
   if (offset) {
     sql += " OFFSET ?";
     params.push(offset);
@@ -7093,7 +7440,7 @@ __export(exports_projects, {
   ProjectGuardedUpdateError: () => ProjectGuardedUpdateError,
   ProjectCollisionError: () => ProjectCollisionError
 });
-import { createHash } from "crypto";
+import { createHash as createHash2 } from "crypto";
 function parseProjectRow(row) {
   return {
     id: row["id"],
@@ -7132,7 +7479,7 @@ function canonicalProjectUpdateJson(value) {
   return JSON.stringify(canonicalizeProjectUpdateValue(value));
 }
 function digestProjectUpdateValue(value) {
-  return createHash("sha256").update(canonicalProjectUpdateJson(value)).digest("hex");
+  return createHash2("sha256").update(canonicalProjectUpdateJson(value)).digest("hex");
 }
 function timestampString(value) {
   return value instanceof Date ? value.toISOString() : String(value);
@@ -9293,6 +9640,245 @@ var init_search = __esm(() => {
   ]);
 });
 
+// src/lib/config.ts
+import { existsSync as existsSync6, mkdirSync as mkdirSync3, readFileSync as readFileSync6, readdirSync, writeFileSync as writeFileSync3, unlinkSync as unlinkSync2, cpSync as cpSync2 } from "fs";
+import { homedir as homedir4 } from "os";
+import { basename, dirname as dirname4, join as join9, resolve as resolve14 } from "path";
+function isInMemoryDb2(path) {
+  return path === ":memory:" || path.startsWith("file::memory:");
+}
+function homeDir() {
+  return process.env["HOME"] || process.env["USERPROFILE"] || homedir4();
+}
+function deepMerge(target, source) {
+  const result = { ...target };
+  for (const key of Object.keys(source)) {
+    const sourceVal = source[key];
+    const targetVal = result[key];
+    if (sourceVal !== null && typeof sourceVal === "object" && !Array.isArray(sourceVal) && targetVal !== null && typeof targetVal === "object" && !Array.isArray(targetVal)) {
+      result[key] = deepMerge(targetVal, sourceVal);
+    } else {
+      result[key] = sourceVal;
+    }
+  }
+  return result;
+}
+function isValidScope(value) {
+  return VALID_SCOPES2.includes(value);
+}
+function isValidCategory(value) {
+  return VALID_CATEGORIES2.includes(value);
+}
+function loadConfig() {
+  const configPath = join9(getDataRoot(), "config.json");
+  let fileConfig = {};
+  if (existsSync6(configPath)) {
+    try {
+      const raw = readFileSync6(configPath, "utf-8");
+      fileConfig = JSON.parse(raw);
+    } catch {}
+  }
+  const merged = deepMerge(DEFAULT_CONFIG, fileConfig);
+  const envScope = env.defaultScope();
+  if (envScope && isValidScope(envScope)) {
+    merged.default_scope = envScope;
+  }
+  const envCategory = env.defaultCategory();
+  if (envCategory && isValidCategory(envCategory)) {
+    merged.default_category = envCategory;
+  }
+  const envImportance = env.defaultImportance();
+  if (envImportance) {
+    const parsed = parseInt(envImportance, 10);
+    if (!Number.isNaN(parsed) && parsed >= 1 && parsed <= 10) {
+      merged.default_importance = parsed;
+    }
+  }
+  return merged;
+}
+function findFileWalkingUp(filename) {
+  let dir = process.cwd();
+  const legacyHomeMementosDb = resolve14(homeDir(), ".mementos", "mementos.db");
+  while (true) {
+    const candidate = join9(dir, filename);
+    if (existsSync6(candidate) && resolve14(candidate) !== legacyHomeMementosDb) {
+      return candidate;
+    }
+    const parent = dirname4(dir);
+    if (parent === dir) {
+      return null;
+    }
+    dir = parent;
+  }
+}
+function findGitRoot2() {
+  let dir = process.cwd();
+  while (true) {
+    if (existsSync6(join9(dir, ".git"))) {
+      return dir;
+    }
+    const parent = dirname4(dir);
+    if (parent === dir) {
+      return null;
+    }
+    dir = parent;
+  }
+}
+function profilesDir() {
+  return join9(getDataRoot(), "profiles");
+}
+function globalConfigPath() {
+  return join9(getDataRoot(), "config.json");
+}
+function readGlobalConfig() {
+  const p = globalConfigPath();
+  if (!existsSync6(p))
+    return {};
+  try {
+    return JSON.parse(readFileSync6(p, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+function readGlobalConfigForWrite() {
+  const p = globalConfigPath();
+  if (!existsSync6(p))
+    return {};
+  try {
+    const data = JSON.parse(readFileSync6(p, "utf-8"));
+    if (data === null || typeof data !== "object" || Array.isArray(data)) {
+      throw new Error("expected a JSON object");
+    }
+    return data;
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`Cannot update global config at ${p}: ${detail}`);
+  }
+}
+function writeGlobalConfig(data) {
+  const p = globalConfigPath();
+  ensureDir2(dirname4(p));
+  writeFileSync3(p, JSON.stringify(data, null, 2), "utf-8");
+}
+function getActiveProfile() {
+  const envProfile = process.env["MEMENTOS_PROFILE"];
+  if (envProfile)
+    return envProfile.trim();
+  const cfg = readGlobalConfig();
+  return cfg["active_profile"] || null;
+}
+function setActiveProfile(name) {
+  const cfg = readGlobalConfigForWrite();
+  if (name === null) {
+    delete cfg["active_profile"];
+  } else {
+    cfg["active_profile"] = name;
+  }
+  writeGlobalConfig(cfg);
+}
+function listProfiles() {
+  const dir = profilesDir();
+  if (!existsSync6(dir))
+    return [];
+  return readdirSync(dir).filter((f) => f.endsWith(".db")).map((f) => basename(f, ".db")).sort();
+}
+function deleteProfile(name) {
+  const dbPath = join9(profilesDir(), `${name}.db`);
+  if (!existsSync6(dbPath))
+    return false;
+  unlinkSync2(dbPath);
+  if (getActiveProfile() === name)
+    setActiveProfile(null);
+  return true;
+}
+function getDbPath2() {
+  const _home = homeDir();
+  const _newDir = getDataRoot();
+  const _oldDir = join9(_home, ".mementos");
+  if (selectsMementosLocalStore() && !existsSync6(_newDir) && existsSync6(_oldDir)) {
+    mkdirSync3(join9(_home, ".hasna"), { recursive: true });
+    cpSync2(_oldDir, _newDir, { recursive: true });
+  }
+  const envDbPath = process.env["HASNA_MEMENTOS_DB_PATH"] ?? process.env["MEMENTOS_DB_PATH"];
+  if (envDbPath) {
+    if (isInMemoryDb2(envDbPath)) {
+      return envDbPath;
+    }
+    const resolved = resolve14(envDbPath);
+    ensureDir2(dirname4(resolved));
+    return resolved;
+  }
+  const profile = getActiveProfile();
+  if (profile) {
+    const profilePath = join9(profilesDir(), `${profile}.db`);
+    ensureDir2(dirname4(profilePath));
+    return profilePath;
+  }
+  const dbScope = process.env["MEMENTOS_DB_SCOPE"];
+  if (dbScope === "project") {
+    const gitRoot = findGitRoot2();
+    if (gitRoot) {
+      const dbPath = join9(gitRoot, ".mementos", "mementos.db");
+      ensureDir2(dirname4(dbPath));
+      return dbPath;
+    }
+  }
+  const found = findFileWalkingUp(join9(".mementos", "mementos.db"));
+  if (found) {
+    return found;
+  }
+  const fallback = join9(getDataRoot(), "mementos.db");
+  ensureDir2(dirname4(fallback));
+  return fallback;
+}
+function ensureDir2(dir) {
+  if (!existsSync6(dir)) {
+    mkdirSync3(dir, { recursive: true });
+  }
+}
+var DEFAULT_CONFIG, VALID_SCOPES2, VALID_CATEGORIES2;
+var init_config = __esm(() => {
+  init_paths();
+  init_env();
+  init_local_opt_in();
+  DEFAULT_CONFIG = {
+    default_scope: "private",
+    default_category: "knowledge",
+    default_importance: 5,
+    max_entries: 1000,
+    max_entries_per_scope: {
+      global: 500,
+      shared: 300,
+      private: 200,
+      working: 100
+    },
+    injection: {
+      max_tokens: 500,
+      min_importance: 5,
+      categories: ["preference", "fact"],
+      refresh_interval: 5
+    },
+    extraction: {
+      enabled: true,
+      min_confidence: 0.5
+    },
+    sync_agents: ["claude", "codex", "gemini"],
+    auto_cleanup: {
+      enabled: true,
+      expired_check_interval: 3600,
+      unused_archive_days: 7,
+      stale_deprioritize_days: 14
+    }
+  };
+  VALID_SCOPES2 = ["global", "shared", "private", "working"];
+  VALID_CATEGORIES2 = [
+    "preference",
+    "fact",
+    "knowledge",
+    "history"
+  ];
+});
+
 // src/db/relations.ts
 function parseRelationRow(row) {
   return {
@@ -10958,17 +11544,80 @@ var exports_profile_synthesizer = {};
 __export(exports_profile_synthesizer, {
   synthesizeProfile: () => synthesizeProfile,
   markProfileStale: () => markProfileStale,
-  getProfileKey: () => getProfileKey
+  getProfileKey: () => getProfileKey,
+  ProfileSynthesisError: () => ProfileSynthesisError,
+  ProfileScopeError: () => ProfileScopeError,
+  PROFILE_SYNTHESIS_CONTRACT: () => PROFILE_SYNTHESIS_CONTRACT
 });
+function resolveProfileTarget(options) {
+  const scope = options.scope ?? (options.project_id ? "project" : options.agent_id ? "agent" : "global");
+  if (scope === "project") {
+    if (!options.project_id)
+      throw new ProfileScopeError("project scope requires project_id");
+    return { scope, id: options.project_id, memory_scope: "shared", project_id: options.project_id };
+  }
+  if (scope === "agent") {
+    if (!options.agent_id)
+      throw new ProfileScopeError("agent scope requires agent_id");
+    return { scope, id: options.agent_id, memory_scope: "private", agent_id: options.agent_id };
+  }
+  return { scope: "global", id: "global", memory_scope: "global" };
+}
 function getProfileKey(scope, id) {
   return `_profile_${scope}_${id}`;
 }
+function listProfileMemories(category, target) {
+  if (target.scope !== "global") {
+    return listMemories({
+      category,
+      scope: target.memory_scope,
+      project_id: target.project_id,
+      agent_id: target.agent_id,
+      machine_id: null,
+      status: "active",
+      limit: 30
+    });
+  }
+  return [
+    ...listMemories({ category, scope: "global", machine_id: null, status: "active", limit: 30 }),
+    ...listMemories({ category, scope: "shared", machine_id: null, status: "active", limit: 1000 })
+  ].filter((memory) => memory.agent_id === null && memory.project_id === null).slice(0, 30);
+}
 async function synthesizeProfile(options) {
-  const scope = options.scope || (options.project_id ? "project" : options.agent_id ? "agent" : "global");
-  const id = options.project_id || options.agent_id || "global";
-  const profileKey = getProfileKey(scope, id);
+  if (!isServerContext() && isApiMode()) {
+    const operation = "POST /profile/synthesize";
+    const { data } = apiJson("POST", "/profile/synthesize", {
+      project_id: options.project_id,
+      agent_id: options.agent_id,
+      scope: options.scope,
+      force_refresh: options.force_refresh === true
+    });
+    const response = expectObject(data, operation);
+    if (response["contract"] !== PROFILE_SYNTHESIS_CONTRACT) {
+      throw new MementosApiProtocolError(operation, `expected contract '${PROFILE_SYNTHESIS_CONTRACT}'`);
+    }
+    if (!("profile" in response)) {
+      throw new MementosApiProtocolError(operation, "missing 'profile'");
+    }
+    if (response["profile"] === null) {
+      if (response["reason"] !== "no_memories") {
+        throw new MementosApiProtocolError(operation, "null profile requires reason 'no_memories'");
+      }
+      return null;
+    }
+    if (typeof response["profile"] !== "string" || response["profile"].length === 0) {
+      throw new MementosApiProtocolError(operation, "expected 'profile' to be a non-empty string or null");
+    }
+    return {
+      profile: response["profile"],
+      memory_count: expectNonNegativeInteger(response, "memory_count", operation),
+      from_cache: expectBoolean(response, "from_cache", operation)
+    };
+  }
+  const target = resolveProfileTarget(options);
+  const profileKey = getProfileKey(target.scope, target.id);
   if (!options.force_refresh) {
-    const cached = getMemoryByKey(profileKey, "shared", undefined, options.project_id);
+    const cached = getMemoryByKey(profileKey, "shared", target.agent_id, target.project_id);
     if (cached) {
       const age = Date.now() - new Date(cached.updated_at).getTime();
       const maxAge = 24 * 60 * 60 * 1000;
@@ -10978,20 +11627,8 @@ async function synthesizeProfile(options) {
       }
     }
   }
-  const prefMemories = listMemories({
-    category: "preference",
-    project_id: options.project_id,
-    machine_id: null,
-    status: "active",
-    limit: 30
-  });
-  const factMemories = listMemories({
-    category: "fact",
-    project_id: options.project_id,
-    machine_id: null,
-    status: "active",
-    limit: 30
-  });
+  const prefMemories = listProfileMemories("preference", target);
+  const factMemories = listProfileMemories("fact", target);
   const allMemories = [...prefMemories, ...factMemories];
   if (allMemories.length === 0)
     return null;
@@ -11001,7 +11638,7 @@ async function synthesizeProfile(options) {
 `);
     const fallbackProfile = `## Profile
 ${lines}`;
-    saveProfile(profileKey, fallbackProfile, allMemories.length, options);
+    saveProfile(profileKey, fallbackProfile, allMemories.length, target);
     return { profile: fallbackProfile, memory_count: allMemories.length, from_cache: false };
   }
   try {
@@ -11023,41 +11660,63 @@ ${lines}`;
 ${memoryList}` }]
       })
     });
-    if (!response.ok)
+    if (!response.ok) {
+      if (options.fail_on_provider_error)
+        throw new ProfileSynthesisError;
       return null;
+    }
     const data = await response.json();
     const profile = data.content?.[0]?.text?.trim();
-    if (!profile)
+    if (!profile) {
+      if (options.fail_on_provider_error)
+        throw new ProfileSynthesisError;
       return null;
-    saveProfile(profileKey, profile, allMemories.length, options);
+    }
+    saveProfile(profileKey, profile, allMemories.length, target);
     return { profile, memory_count: allMemories.length, from_cache: false };
-  } catch {
+  } catch (error) {
+    if (options.fail_on_provider_error) {
+      if (error instanceof ProfileSynthesisError)
+        throw error;
+      throw new ProfileSynthesisError;
+    }
     return null;
   }
 }
-function saveProfile(key, value, memoryCount, options) {
+function saveProfile(key, value, memoryCount, target) {
   try {
     createMemory({
       key,
       value,
-      category: "fact",
+      category: "resource",
       scope: "shared",
       importance: 10,
       source: "auto",
       tags: ["profile", "synthesized"],
       when_to_use: "When needing to understand this agent's or project's preferences, style, and conventions",
       metadata: { memory_count: memoryCount, synthesized_at: new Date().toISOString(), stale: false },
-      agent_id: options.agent_id,
-      project_id: options.project_id
+      agent_id: target.agent_id,
+      project_id: target.project_id
     });
   } catch {}
 }
-function markProfileStale(projectId, _agentId) {
+function markProfileStale(projectId, agentId) {
+  const targets = [{ scope: "global", id: "global", memory_scope: "global" }];
+  if (projectId)
+    targets.push({ scope: "project", id: projectId, memory_scope: "shared", project_id: projectId });
+  if (agentId)
+    targets.push({ scope: "agent", id: agentId, memory_scope: "private", agent_id: agentId });
   try {
-    const { getDatabase: getDatabase2 } = (init_database(), __toCommonJS(exports_database));
-    const db = getDatabase2();
-    db.run(`UPDATE memories SET metadata = json_set(COALESCE(metadata, '{}'), '$.stale', json('true'))
-       WHERE key LIKE '_profile_%' AND COALESCE(project_id, '') = ?`, [projectId || ""]);
+    const db = !isServerContext() && isApiMode() ? undefined : (init_database(), __toCommonJS(exports_database)).getDatabase();
+    for (const target of targets) {
+      const cached = getMemoryByKey(getProfileKey(target.scope, target.id), "shared", target.agent_id, target.project_id, undefined, db);
+      if (!cached)
+        continue;
+      updateMemory(cached.id, {
+        metadata: { ...cached.metadata ?? {}, stale: true },
+        version: cached.version
+      }, db);
+    }
   } catch {}
 }
 var PROFILE_PROMPT = `You synthesize a coherent agent/project profile from individual preference and fact memories.
@@ -11070,9 +11729,26 @@ Output a concise profile (200-300 words max) organized by:
 - **Key Facts**: Architecture decisions, constraints, team conventions
 
 Only include sections that have relevant data. Be specific and actionable.
-Output in markdown format.`;
+Output in markdown format.`, PROFILE_SYNTHESIS_CONTRACT = "mementos.profile.synthesize.v2", ProfileScopeError, ProfileSynthesisError;
 var init_profile_synthesizer = __esm(() => {
   init_memories();
+  init_api_mode();
+  init_api_response_contract();
+  init_storage();
+  ProfileScopeError = class ProfileScopeError extends Error {
+    code = "MEMENTOS_PROFILE_SCOPE";
+    constructor(message) {
+      super(message);
+      this.name = "ProfileScopeError";
+    }
+  };
+  ProfileSynthesisError = class ProfileSynthesisError extends Error {
+    code = "MEMENTOS_PROFILE_SYNTHESIS";
+    constructor() {
+      super("Profile synthesis provider failed");
+      this.name = "ProfileSynthesisError";
+    }
+  };
 });
 
 // src/lib/contradiction.ts
@@ -11356,6 +12032,22 @@ var init_built_in_hooks = __esm(() => {
       } catch {}
     }
   });
+  hookRegistry.register({
+    type: "PostMemoryUpdate",
+    blocking: false,
+    builtin: true,
+    priority: 65,
+    description: "Mark synthesized profile as stale when a preference or fact memory is updated",
+    handler: async (ctx) => {
+      const category = ctx.memory?.category;
+      if (category !== "preference" && category !== "fact")
+        return;
+      try {
+        const { markProfileStale: markProfileStale2 } = await Promise.resolve().then(() => (init_profile_synthesizer(), exports_profile_synthesizer));
+        markProfileStale2(ctx.projectId, ctx.agentId);
+      } catch {}
+    }
+  });
   hookRegistry.register({
     type: "PostMemorySave",
     blocking: false,
@@ -12213,10 +12905,20 @@ __export(exports_synthesis2, {
   getSynthesisStatus: () => getSynthesisStatus
 });
 async function runSynthesis(options = {}) {
-  const d = options.db || getDatabase();
   const projectId = options.projectId ?? null;
   const agentId = options.agentId ?? null;
   const dryRun = options.dryRun ?? false;
+  if (!options.db && isApiMode()) {
+    const { data } = apiJson("POST", "/synthesis/run", {
+      project_id: projectId,
+      agent_id: agentId,
+      dry_run: dryRun,
+      max_proposals: options.maxProposals,
+      provider: options.provider
+    });
+    return data;
+  }
+  const d = options.db || getDatabase();
   const run = createSynthesisRun({
     triggered_by: "manual",
     project_id: projectId,
@@ -12305,6 +13007,10 @@ async function runSynthesis(options = {}) {
   }
 }
 async function rollbackSynthesis(runId, db) {
+  if (!db && isApiMode()) {
+    const { data } = apiJson("POST", `/synthesis/rollback/${encodeURIComponent(runId)}`);
+    return data;
+  }
   const d = db || getDatabase();
   const result = await rollbackRun(runId, d);
   if (result.errors.length === 0) {
@@ -12353,8 +13059,37 @@ __export(exports_session_jobs, {
   getSessionJob: () => getSessionJob,
   getNextPendingJob: () => getNextPendingJob,
   createSessionJob: () => createSessionJob,
-  claimSessionJob: () => claimSessionJob
+  claimSessionJob: () => claimSessionJob,
+  SESSION_JOBS_PAGE_CONTRACT: () => SESSION_JOBS_PAGE_CONTRACT,
+  SESSION_INGEST_CONTRACT: () => SESSION_INGEST_CONTRACT
 });
+function parseHostedSessionJob(value, operation) {
+  const row = expectObject(value, operation);
+  const source = expectString(row, "source", operation);
+  const status = expectString(row, "status", operation);
+  if (!SESSION_JOB_SOURCES.has(source)) {
+    throw new MementosApiProtocolError(operation, "unsupported 'source'");
+  }
+  if (!SESSION_JOB_STATUSES.has(status)) {
+    throw new MementosApiProtocolError(operation, "unsupported 'status'");
+  }
+  return {
+    id: expectString(row, "id", operation),
+    session_id: expectString(row, "session_id", operation),
+    agent_id: expectNullableString(row, "agent_id", operation),
+    project_id: expectNullableString(row, "project_id", operation),
+    source,
+    status,
+    transcript: expectString(row, "transcript", operation, { allowEmpty: true }),
+    chunk_count: expectNonNegativeInteger(row, "chunk_count", operation),
+    memories_extracted: expectNonNegativeInteger(row, "memories_extracted", operation),
+    error: expectNullableString(row, "error", operation),
+    metadata: expectRecord(row, "metadata", operation),
+    created_at: expectString(row, "created_at", operation),
+    started_at: expectNullableString(row, "started_at", operation),
+    completed_at: expectNullableString(row, "completed_at", operation)
+  };
+}
 function parseJobRow(row) {
   return {
     id: row["id"],
@@ -12374,6 +13109,28 @@ function parseJobRow(row) {
   };
 }
 function createSessionJob(input, db) {
+  if (!db && isApiMode()) {
+    const operation = "POST /sessions/ingest";
+    const { data } = apiJson("POST", "/sessions/ingest", {
+      session_id: input.session_id,
+      transcript: input.transcript,
+      source: input.source ?? "manual",
+      agent_id: input.agent_id,
+      project_id: input.project_id,
+      metadata: input.metadata ?? {}
+    });
+    const response = expectObject(data, operation);
+    if (response["contract"] !== SESSION_INGEST_CONTRACT) {
+      throw new MementosApiProtocolError(operation, `expected contract '${SESSION_INGEST_CONTRACT}'`);
+    }
+    const jobId = expectString(response, "job_id", operation);
+    const jobObject = expectObject(response["job"], operation);
+    const job = parseHostedSessionJob({ ...jobObject, transcript: input.transcript }, `${operation} job`);
+    if (job.id !== jobId || job.session_id !== input.session_id) {
+      throw new MementosApiProtocolError(operation, "job receipt identity does not match the request");
+    }
+    return job;
+  }
   const d = db || getDatabase();
   const id = uuid();
   const timestamp2 = now();
@@ -12395,10 +13152,11 @@ function createSessionJob(input, db) {
 }
 function getSessionJob(id, db) {
   if (!db && isApiMode()) {
+    const operation = `GET /sessions/jobs/${encodeURIComponent(id)}`;
     const { status, data } = apiJson("GET", `/sessions/jobs/${encodeURIComponent(id)}`, undefined, { allow404: true });
-    if (status === 404 || !data)
+    if (status === 404)
       return null;
-    return data;
+    return parseHostedSessionJob(data, operation);
   }
   const d = db || getDatabase();
   const row = d.query("SELECT * FROM session_memory_jobs WHERE id = ?").get(id);
@@ -12412,10 +13170,58 @@ function listSessionJobs(filter, db) {
       agent_id: filter?.agent_id,
       project_id: filter?.project_id,
       status: filter?.status,
-      limit: filter?.limit
+      session_id: filter?.session_id,
+      limit: filter?.limit,
+      offset: filter?.offset
     });
+    const operation = "GET /sessions/jobs";
     const { data } = apiJson("GET", `/sessions/jobs${q}`);
-    return data?.jobs ?? [];
+    const response = expectObject(data, operation);
+    if (response["contract"] !== SESSION_JOBS_PAGE_CONTRACT) {
+      throw new MementosApiProtocolError(operation, `expected contract '${SESSION_JOBS_PAGE_CONTRACT}'`);
+    }
+    const jobs = expectArray(response["jobs"], operation, "jobs").map((job, index) => parseHostedSessionJob(job, `${operation} item ${index}`));
+    const count = expectNonNegativeInteger(response, "count", operation);
+    const responseLimit = expectNonNegativeInteger(response, "limit", operation);
+    const responseOffset = expectNonNegativeInteger(response, "offset", operation);
+    const hasMore = expectBoolean(response, "has_more", operation);
+    const nextOffset = response["next_offset"];
+    if (responseLimit < 1) {
+      throw new MementosApiProtocolError(operation, "expected 'limit' to be positive");
+    }
+    if (count !== jobs.length || count > responseLimit) {
+      throw new MementosApiProtocolError(operation, "page count is inconsistent with jobs/limit");
+    }
+    if (nextOffset !== null && (!Number.isSafeInteger(nextOffset) || nextOffset < 0)) {
+      throw new MementosApiProtocolError(operation, "expected 'next_offset' to be a non-negative safe integer or null");
+    }
+    if (hasMore && nextOffset !== responseOffset + jobs.length) {
+      throw new MementosApiProtocolError(operation, "'has_more' requires the exact next offset");
+    }
+    if (!hasMore && nextOffset !== null) {
+      throw new MementosApiProtocolError(operation, "terminal page must set 'next_offset' to null");
+    }
+    if (filter?.limit !== undefined && responseLimit !== filter.limit) {
+      throw new MementosApiProtocolError(operation, "server did not preserve requested 'limit'");
+    }
+    if (filter?.offset !== undefined && responseOffset !== filter.offset) {
+      throw new MementosApiProtocolError(operation, "server did not preserve requested 'offset'");
+    }
+    for (const job of jobs) {
+      if (filter?.agent_id !== undefined && job.agent_id !== filter.agent_id) {
+        throw new MementosApiProtocolError(operation, "server did not preserve requested 'agent_id'");
+      }
+      if (filter?.project_id !== undefined && job.project_id !== filter.project_id) {
+        throw new MementosApiProtocolError(operation, "server did not preserve requested 'project_id'");
+      }
+      if (filter?.session_id !== undefined && job.session_id !== filter.session_id) {
+        throw new MementosApiProtocolError(operation, "server did not preserve requested 'session_id'");
+      }
+      if (filter?.status !== undefined && job.status !== filter.status) {
+        throw new MementosApiProtocolError(operation, "server did not preserve requested 'status'");
+      }
+    }
+    return jobs;
   }
   const d = db || getDatabase();
   const conditions = [];
@@ -12495,9 +13301,13 @@ function recoverStaleProcessingJobs(maxAgeMs, db) {
   const result = d.run("UPDATE session_memory_jobs SET status = 'pending', started_at = NULL WHERE status = 'processing' AND started_at < ?", [cutoff]);
   return result.changes;
 }
+var SESSION_JOBS_PAGE_CONTRACT = "mementos.sessions.jobs.v2", SESSION_INGEST_CONTRACT = "mementos.sessions.ingest.v2", SESSION_JOB_SOURCES, SESSION_JOB_STATUSES;
 var init_session_jobs = __esm(() => {
   init_database();
   init_api_mode();
+  init_api_response_contract();
+  SESSION_JOB_SOURCES = new Set(["claude-code", "codex", "manual", "open-sessions"]);
+  SESSION_JOB_STATUSES = new Set(["pending", "processing", "completed", "failed"]);
 });
 
 // src/db/tool-events.ts
@@ -13120,12 +13930,25 @@ __export(exports_session_queue, {
   enqueueSessionJob: () => enqueueSessionJob
 });
 function enqueueSessionJob(jobId) {
+  if (!isServerContext() && isApiMode())
+    return;
   _pendingQueue.add(jobId);
   if (!_isProcessing) {
     _processNext();
   }
 }
 function getSessionQueueStats() {
+  if (!isServerContext() && isApiMode()) {
+    const operation = "GET /sessions/queue/stats";
+    const { data } = apiJson("GET", "/sessions/queue/stats");
+    const response = expectObject(data, operation);
+    return {
+      pending: expectNonNegativeInteger(response, "pending", operation),
+      processing: expectNonNegativeInteger(response, "processing", operation),
+      completed: expectNonNegativeInteger(response, "completed", operation),
+      failed: expectNonNegativeInteger(response, "failed", operation)
+    };
+  }
   try {
     const db = getDatabase();
     const rows = db.query("SELECT status, COUNT(*) as count FROM session_memory_jobs GROUP BY status").all();
@@ -13146,7 +13969,9 @@ function getSessionQueueStats() {
         stats.failed = row.count;
     }
     return stats;
-  } catch {
+  } catch (error) {
+    if (isServerContext())
+      throw error;
     return {
       pending: _pendingQueue.size,
       processing: _isProcessing ? 1 : 0,
@@ -13158,6 +13983,8 @@ function getSessionQueueStats() {
 function startSessionQueueWorker() {
   if (_workerStarted)
     return;
+  if (!isServerContext() && isApiMode())
+    return;
   _workerStarted = true;
   setInterval(() => {
     try {
@@ -13199,6 +14026,9 @@ var init_session_queue = __esm(() => {
   init_database();
   init_session_jobs();
   init_session_processor();
+  init_api_mode();
+  init_api_response_contract();
+  init_storage();
   _pendingQueue = new Set;
 });
 
@@ -13207,6 +14037,8 @@ var exports_session_registry = {};
 __export(exports_session_registry, {
   updateSessionAgent: () => updateSessionAgent,
   unregisterSession: () => unregisterSession,
+  sessionRegistryUsesLocalStore: () => sessionRegistryUsesLocalStore,
+  sessionRegistryPath: () => sessionRegistryPath,
   registerSession: () => registerSession,
   listSessions: () => listSessions,
   heartbeatSession: () => heartbeatSession,
@@ -13214,17 +14046,36 @@ __export(exports_session_registry, {
   getSessionByAgent: () => getSessionByAgent,
   getSession: () => getSession,
   closeRegistry: () => closeRegistry,
-  cleanStaleSessions: () => cleanStaleSessions
+  cleanStaleSessions: () => cleanStaleSessions,
+  __resetProcessLocalRegistry: () => __resetProcessLocalRegistry,
+  SESSION_REGISTRY_FILE: () => SESSION_REGISTRY_FILE
 });
 import { existsSync as existsSync10, mkdirSync as mkdirSync5 } from "fs";
 import { dirname as dirname6, join as join14 } from "path";
+function sessionRegistryUsesLocalStore(env2 = process.env) {
+  return isServerContext() || selectsMementosLocalStore(env2);
+}
+function sessionRegistryPath() {
+  const store = getDbPath2();
+  if (store === ":memory:")
+    return ":memory:";
+  return join14(dirname6(store), SESSION_REGISTRY_FILE);
+}
 function getDb() {
-  if (_db2)
+  const path = sessionRegistryPath();
+  if (_db2 && _dbPath2 === path)
     return _db2;
-  const dir = dirname6(DB_PATH);
-  if (!existsSync10(dir))
-    mkdirSync5(dir, { recursive: true });
-  _db2 = new SqliteAdapter(DB_PATH);
+  if (_db2) {
+    _db2.close();
+    _db2 = null;
+  }
+  if (path !== ":memory:") {
+    const dir = dirname6(path);
+    if (!existsSync10(dir))
+      mkdirSync5(dir, { recursive: true });
+  }
+  _db2 = new SqliteAdapter(path);
+  _dbPath2 = path;
   _db2.run("PRAGMA journal_mode = WAL");
   _db2.run("PRAGMA busy_timeout = 3000");
   _db2.exec(`
@@ -13281,12 +14132,45 @@ function isProcessAlive(pid) {
     return false;
   }
 }
+function matchesFilter(s, filter) {
+  if (!filter)
+    return true;
+  if (filter.project_name && s.project_name !== filter.project_name)
+    return false;
+  if (filter.git_root && s.git_root !== filter.git_root)
+    return false;
+  if (filter.mcp_server && s.mcp_server !== filter.mcp_server)
+    return false;
+  if (filter.agent_name && s.agent_name !== filter.agent_name)
+    return false;
+  if (filter.exclude_pid && s.pid === filter.exclude_pid)
+    return false;
+  return true;
+}
 function registerSession(opts) {
-  const db = getDb();
   const pid = process.pid;
   const cwd = opts.cwd || process.cwd();
-  const id = generateId();
   const timestamp2 = now3();
+  if (!sessionRegistryUsesLocalStore()) {
+    const existing2 = [..._memory.values()].find((s) => s.pid === pid && s.mcp_server === opts.mcp_server);
+    const record = {
+      id: existing2?.id ?? generateId(),
+      pid,
+      cwd,
+      git_root: opts.git_root || null,
+      agent_name: opts.agent_name || null,
+      project_name: opts.project_name || null,
+      tty: opts.tty || null,
+      mcp_server: opts.mcp_server,
+      metadata: { ...opts.metadata || {} },
+      registered_at: existing2?.registered_at ?? timestamp2,
+      last_seen_at: timestamp2
+    };
+    _memory.set(record.id, record);
+    return { ...record, metadata: { ...record.metadata } };
+  }
+  const db = getDb();
+  const id = generateId();
   const existing = db.query("SELECT id FROM sessions WHERE pid = ? AND mcp_server = ?").get(pid, opts.mcp_server);
   if (existing) {
     db.run(`UPDATE sessions SET agent_name = ?, project_name = ?, cwd = ?,
@@ -13319,19 +14203,41 @@ function registerSession(opts) {
   return getSession(id);
 }
 function heartbeatSession(id) {
+  if (!sessionRegistryUsesLocalStore()) {
+    const s = _memory.get(id);
+    if (s)
+      s.last_seen_at = now3();
+    return;
+  }
   const db = getDb();
   db.run("UPDATE sessions SET last_seen_at = ? WHERE id = ?", [now3(), id]);
 }
 function unregisterSession(id) {
+  if (!sessionRegistryUsesLocalStore()) {
+    _memory.delete(id);
+    return;
+  }
   const db = getDb();
   db.run("DELETE FROM sessions WHERE id = ?", [id]);
 }
 function getSession(id) {
+  if (!sessionRegistryUsesLocalStore()) {
+    const s = _memory.get(id);
+    return s ? { ...s, metadata: { ...s.metadata } } : null;
+  }
   const db = getDb();
   const row = db.query("SELECT * FROM sessions WHERE id = ?").get(id);
   return row ? parseRow2(row) : null;
 }
 function listSessions(filter) {
+  if (!sessionRegistryUsesLocalStore()) {
+    return [..._memory.values()].filter((s) => matchesFilter(s, filter)).filter((s) => {
+      if (isProcessAlive(s.pid))
+        return true;
+      _memory.delete(s.id);
+      return false;
+    }).sort((a, b) => a.last_seen_at < b.last_seen_at ? 1 : a.last_seen_at > b.last_seen_at ? -1 : 0).map((s) => ({ ...s, metadata: { ...s.metadata } }));
+  }
   const db = getDb();
   const conditions = [];
   const params = [];
@@ -13372,6 +14278,16 @@ function getSessionsByProject(projectName) {
   return listSessions({ project_name: projectName });
 }
 function cleanStaleSessions() {
+  if (!sessionRegistryUsesLocalStore()) {
+    let cleaned2 = 0;
+    for (const s of [..._memory.values()]) {
+      if (!isProcessAlive(s.pid)) {
+        _memory.delete(s.id);
+        cleaned2++;
+      }
+    }
+    return cleaned2;
+  }
   const db = getDb();
   const rows = db.query("SELECT id, pid FROM sessions").all();
   let cleaned = 0;
@@ -13384,20 +14300,35 @@ function cleanStaleSessions() {
   return cleaned;
 }
 function updateSessionAgent(mcpServer, agentName) {
-  const db = getDb();
   const pid = process.pid;
+  if (!sessionRegistryUsesLocalStore()) {
+    for (const s of _memory.values()) {
+      if (s.pid === pid && s.mcp_server === mcpServer) {
+        s.agent_name = agentName;
+        s.last_seen_at = now3();
+      }
+    }
+    return;
+  }
+  const db = getDb();
   db.run("UPDATE sessions SET agent_name = ?, last_seen_at = ? WHERE pid = ? AND mcp_server = ?", [agentName, now3(), pid, mcpServer]);
 }
 function closeRegistry() {
   if (_db2) {
     _db2.close();
     _db2 = null;
+    _dbPath2 = null;
   }
 }
-var DB_PATH, _db2 = null;
+function __resetProcessLocalRegistry() {
+  _memory.clear();
+}
+var SESSION_REGISTRY_FILE = "sessions-registry.db", _db2 = null, _dbPath2 = null, _memory;
 var init_session_registry = __esm(() => {
   init_storage();
-  DB_PATH = join14(process.env["HOME"] || process.env["USERPROFILE"] || "~", ".open-sessions-registry.db");
+  init_config();
+  init_local_opt_in();
+  _memory = new Map;
 });
 
 // src/db/pg-migrations.ts
@@ -14177,6 +15108,79 @@ var init_pg_migrations = __esm(() => {
     `
   ${postgresMementosMemoryProjectLinkSchemaSql()}
   INSERT INTO _migrations (id) VALUES (40) ON CONFLICT DO NOTHING;
+  `,
+    `
+  DROP TABLE IF EXISTS pg_temp.mementos_m41_machine_preflight;
+  CREATE TEMP TABLE mementos_m41_machine_preflight (
+    id TEXT PRIMARY KEY,
+    name TEXT NOT NULL CHECK(
+      length(name) BETWEEN 1 AND 128
+      AND name !~ '[[:cntrl:]]'
+    ),
+    hostname TEXT NOT NULL UNIQUE CHECK(
+      length(hostname) BETWEEN 1 AND 253
+      AND hostname = lower(regexp_replace(btrim(hostname), '\\.+$', ''))
+      AND hostname !~ '[[:space:]/\\\\]'
+    ),
+    platform TEXT NOT NULL CHECK(
+      length(platform) BETWEEN 1 AND 64
+      AND platform = lower(btrim(platform))
+      AND platform ~ '^[a-z0-9._-]+$'
+    ),
+    is_primary BOOLEAN NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL,
+    last_seen_at TIMESTAMPTZ NOT NULL CHECK(last_seen_at >= created_at)
+  ) ON COMMIT DROP;
+
+  INSERT INTO mementos_m41_machine_preflight
+    (id, name, hostname, platform, is_primary, created_at, last_seen_at)
+  SELECT
+    id,
+    name,
+    lower(regexp_replace(btrim(hostname), '\\.+$', '')),
+    platform,
+    is_primary,
+    created_at,
+    last_seen_at
+  FROM machines;
+
+  UPDATE machines machine
+  SET hostname = preflight.hostname
+  FROM mementos_m41_machine_preflight preflight
+  WHERE preflight.id = machine.id;
+
+  DROP TRIGGER IF EXISTS machines_single_primary_insert ON machines;
+  DROP TRIGGER IF EXISTS machines_single_primary_update ON machines;
+  DROP INDEX IF EXISTS idx_machines_hostname;
+  CREATE UNIQUE INDEX idx_machines_hostname ON machines(hostname);
+  DROP INDEX IF EXISTS idx_machines_single_primary;
+  CREATE UNIQUE INDEX idx_machines_single_primary
+    ON machines ((1)) WHERE is_primary = TRUE;
+
+  ALTER TABLE machines DROP CONSTRAINT IF EXISTS machines_hostname_canonical;
+  ALTER TABLE machines ADD CONSTRAINT machines_hostname_canonical CHECK(
+    length(hostname) BETWEEN 1 AND 253
+    AND hostname = lower(regexp_replace(btrim(hostname), '\\.+$', ''))
+    AND hostname !~ '[[:space:]/\\\\]'
+  );
+
+  ALTER TABLE machines DROP CONSTRAINT IF EXISTS machines_name_runtime;
+  ALTER TABLE machines ADD CONSTRAINT machines_name_runtime CHECK(
+    length(name) BETWEEN 1 AND 128
+    AND name !~ '[[:cntrl:]]'
+  );
+  ALTER TABLE machines DROP CONSTRAINT IF EXISTS machines_platform_runtime;
+  ALTER TABLE machines ADD CONSTRAINT machines_platform_runtime CHECK(
+    length(platform) BETWEEN 1 AND 64
+    AND platform = lower(btrim(platform))
+    AND platform ~ '^[a-z0-9._-]+$'
+  );
+  ALTER TABLE machines DROP CONSTRAINT IF EXISTS machines_liveness_runtime;
+  ALTER TABLE machines ADD CONSTRAINT machines_liveness_runtime CHECK(
+    last_seen_at >= created_at
+  );
+
+  INSERT INTO _migrations (id) VALUES (41) ON CONFLICT DO NOTHING;
   `
   ];
 });
@@ -14232,24 +15236,32 @@ async function applyPgMigrations(connectionString) {
     totalMigrations: PG_MIGRATIONS.length
   };
   try {
-    await pg2.run(`CREATE TABLE IF NOT EXISTS _pg_migrations (
-        id SERIAL PRIMARY KEY,
-        version INT UNIQUE NOT NULL,
-        applied_at TIMESTAMPTZ DEFAULT NOW()
-      )`);
-    const applied = await pg2.all("SELECT version FROM _pg_migrations ORDER BY version");
-    const appliedSet = new Set(applied.map((r) => r.version));
+    const migrationLockKey = 21760041;
+    await pg2.transaction(async (client) => {
+      await client.query("SELECT pg_advisory_xact_lock($1)", [migrationLockKey]);
+      await client.query(`CREATE TABLE IF NOT EXISTS _pg_migrations (
+          id SERIAL PRIMARY KEY,
+          version INT UNIQUE NOT NULL,
+          applied_at TIMESTAMPTZ DEFAULT NOW()
+        )`);
+    });
     for (let i = 0;i < PG_MIGRATIONS.length; i++) {
-      if (appliedSet.has(i)) {
-        result.alreadyApplied.push(i);
-        continue;
-      }
       try {
-        await pg2.exec(PG_MIGRATIONS[i]);
-        await pg2.run("INSERT INTO _pg_migrations (version) VALUES ($1) ON CONFLICT DO NOTHING", i);
-        result.applied.push(i);
-      } catch (err) {
-        result.errors.push(`Migration ${i}: ${err?.message ?? String(err)}`);
+        const outcome = await pg2.transaction(async (client) => {
+          await client.query("SELECT pg_advisory_xact_lock($1)", [migrationLockKey]);
+          const already = await client.query("SELECT 1 FROM _pg_migrations WHERE version = $1", [i]);
+          if (already.rowCount)
+            return "already";
+          await client.query(PG_MIGRATIONS[i]);
+          await client.query("INSERT INTO _pg_migrations (version) VALUES ($1)", [i]);
+          return "applied";
+        });
+        if (outcome === "already")
+          result.alreadyApplied.push(i);
+        else
+          result.applied.push(i);
+      } catch (error) {
+        result.errors.push(`Migration ${i}: ${error instanceof Error ? error.message : String(error)}`);
         break;
       }
     }
@@ -46679,7 +47691,7 @@ var require_token_io = __commonJS((exports, module) => {
   module.exports = __toCommonJS2(token_io_exports);
   var import_path2 = __toESM2(__require("path"));
   var import_fs2 = __toESM2(__require("fs"));
-  var import_os3 = __toESM2(__require("os"));
+  var import_os2 = __toESM2(__require("os"));
   var import_token_error = require_token_error();
   function findRootDir() {
     try {
@@ -46700,11 +47712,11 @@ var require_token_io = __commonJS((exports, module) => {
     if (process.env.XDG_DATA_HOME) {
       return process.env.XDG_DATA_HOME;
     }
-    switch (import_os3.default.platform()) {
+    switch (import_os2.default.platform()) {
       case "darwin":
-        return import_path2.default.join(import_os3.default.homedir(), "Library/Application Support");
+        return import_path2.default.join(import_os2.default.homedir(), "Library/Application Support");
       case "linux":
-        return import_path2.default.join(import_os3.default.homedir(), ".local/share");
+        return import_path2.default.join(import_os2.default.homedir(), ".local/share");
       case "win32":
         if (process.env.LOCALAPPDATA) {
           return process.env.LOCALAPPDATA;
@@ -46814,10 +47826,10 @@ var require_oauth = __commonJS((exports, module) => {
     refreshTokenRequest: () => refreshTokenRequest
   });
   module.exports = __toCommonJS2(oauth_exports);
-  var import_os3 = __require("os");
+  var import_os2 = __require("os");
   var VERCEL_ISSUER = "https://vercel.com";
   var VERCEL_CLI_CLIENT_ID = "cl_HYyOPBNtFMfHhaUn9L4QPfTZz6TP47bp";
-  var userAgent = `@vercel/oidc node-${process.version} ${(0, import_os3.platform)()} (${(0, import_os3.arch)()}) ${(0, import_os3.hostname)()}`;
+  var userAgent = `@vercel/oidc node-${process.version} ${(0, import_os2.platform)()} (${(0, import_os2.arch)()}) ${(0, import_os2.hostname)()}`;
   var _tokenEndpoint = null;
   async function getTokenEndpoint() {
     if (_tokenEndpoint) {
@@ -64449,65 +65461,283 @@ import { fileURLToPath as fileURLToPath5 } from "url";
 
 // src/db/machines.ts
 init_database();
+init_api_mode();
+init_api_response_contract();
+import { createHash } from "crypto";
 import { hostname, platform } from "os";
-function parseMachine(row) {
+var MACHINE_REGISTRATION_CONTRACT = "mementos.machine-registration.v1";
+var MACHINE_LIST_CONTRACT = "mementos.machines.v1";
+class MachineRegistryError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "MachineRegistryError";
+  }
+}
+var ISO_UTC_TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+function canonicalTimestamp(value, operation, field) {
+  const stringValue = value instanceof Date ? value.toISOString() : value;
+  if (typeof stringValue !== "string" || !ISO_UTC_TIMESTAMP.test(stringValue)) {
+    throw new MementosApiProtocolError(operation, `expected '${field}' to be a canonical UTC ISO-8601 timestamp`);
+  }
+  const parsed = new Date(stringValue);
+  if (!Number.isFinite(parsed.getTime()) || parsed.toISOString() !== stringValue) {
+    throw new MementosApiProtocolError(operation, `expected '${field}' to be a real calendar timestamp`);
+  }
+  return stringValue;
+}
+function machineFromDb(row, operation = "machine database row") {
   if (!row)
     return null;
+  if (typeof row.id !== "string" || !row.id || typeof row.name !== "string" || !row.name || row.name.length > 128 || /[\u0000-\u001f\u007f]/.test(row.name) || typeof row.hostname !== "string" || !row.hostname || typeof row.platform !== "string" || !row.platform) {
+    throw new Error(`${operation} is missing or violates required machine identity fields`);
+  }
+  const canonicalHostname = normalizeMachineHostname(row.hostname);
+  const canonicalPlatform = normalizeMachinePlatform(row.platform);
+  if (canonicalHostname !== row.hostname || canonicalPlatform !== row.platform) {
+    throw new Error(`${operation} contains noncanonical hostname or platform data`);
+  }
+  if (!["boolean", "number"].includes(typeof row.is_primary)) {
+    throw new Error(`${operation} has an invalid is_primary value`);
+  }
+  const createdValue = row.created_at instanceof Date ? row.created_at : new Date(String(row.created_at ?? ""));
+  const lastSeenValue = row.last_seen_at instanceof Date ? row.last_seen_at : new Date(String(row.last_seen_at ?? ""));
+  if (!Number.isFinite(createdValue.getTime()) || !Number.isFinite(lastSeenValue.getTime())) {
+    throw new Error(`${operation} has an invalid timestamp`);
+  }
+  const createdAt = createdValue.toISOString();
+  const lastSeenAt = lastSeenValue.toISOString();
+  if (lastSeenAt < createdAt)
+    throw new Error(`${operation} has last_seen_at before created_at`);
   return {
-    ...row,
-    is_primary: Boolean(row.is_primary)
-  };
+    id: row.id,
+    name: row.name,
+    hostname: canonicalHostname,
+    platform: canonicalPlatform,
+    is_primary: Boolean(row.is_primary),
+    created_at: createdAt,
+    last_seen_at: lastSeenAt
+  };
+}
+function decodeMachine(value, operation) {
+  const object = expectObject(value, operation);
+  const name = expectString(object, "name", operation);
+  if (name.length > 128 || /[\u0000-\u001f\u007f]/.test(name)) {
+    throw new MementosApiProtocolError(operation, "machine.name is outside the public contract");
+  }
+  const rawHost = expectString(object, "hostname", operation);
+  const rawPlatform = expectString(object, "platform", operation);
+  let machineHostname;
+  let machinePlatform;
+  try {
+    machineHostname = normalizeMachineHostname(rawHost);
+    machinePlatform = normalizeMachinePlatform(rawPlatform);
+  } catch {
+    throw new MementosApiProtocolError(operation, "machine hostname or platform is not canonical");
+  }
+  if (machineHostname !== rawHost || machinePlatform !== rawPlatform) {
+    throw new MementosApiProtocolError(operation, "machine hostname or platform is not canonical");
+  }
+  const createdAt = canonicalTimestamp(object["created_at"], operation, "created_at");
+  const lastSeenAt = canonicalTimestamp(object["last_seen_at"], operation, "last_seen_at");
+  if (lastSeenAt < createdAt) {
+    throw new MementosApiProtocolError(operation, "last_seen_at precedes created_at");
+  }
+  return {
+    id: expectString(object, "id", operation),
+    name,
+    hostname: machineHostname,
+    platform: machinePlatform,
+    is_primary: expectBoolean(object, "is_primary", operation),
+    created_at: createdAt,
+    last_seen_at: lastSeenAt
+  };
+}
+function expectContract(object, contract, operation) {
+  if (object["contract"] !== contract) {
+    throw new MementosApiProtocolError(operation, `expected contract '${contract}'`);
+  }
+}
+function decodeRegistration(value, expected) {
+  const operation = "POST /v1/machines";
+  const object = expectObject(value, operation);
+  expectContract(object, MACHINE_REGISTRATION_CONTRACT, operation);
+  const machine = decodeMachine(object["machine"], operation);
+  const created = expectBoolean(object, "created", operation);
+  const identity = expectObject(object["identity"], operation);
+  if (identity["idempotency_key"] !== "normalized_hostname") {
+    throw new MementosApiProtocolError(operation, "expected normalized-hostname identity semantics");
+  }
+  if (expectString(identity, "stable_id", operation) !== machine.id) {
+    throw new MementosApiProtocolError(operation, "identity stable_id does not match machine.id");
+  }
+  const expectedHostname = normalizeMachineHostname(expected.hostname);
+  const expectedPlatform = normalizeMachinePlatform(expected.platform);
+  if (machine.hostname !== expectedHostname || machine.platform !== expectedPlatform) {
+    throw new MementosApiProtocolError(operation, "registration receipt does not match the requested hostname/platform");
+  }
+  if (created && machine.name !== normalizeMachineName(expected.name, expectedHostname)) {
+    throw new MementosApiProtocolError(operation, "created registration receipt does not match the requested name");
+  }
+  return { machine, created };
+}
+function decodeMachineList(value) {
+  const operation = "GET /v1/machines";
+  const object = expectObject(value, operation);
+  expectContract(object, MACHINE_LIST_CONTRACT, operation);
+  const values = expectArray(object["machines"], operation, "machines");
+  const count = expectNonNegativeInteger(object, "count", operation);
+  if (count !== values.length) {
+    throw new MementosApiProtocolError(operation, "count does not match machines.length");
+  }
+  if (object["complete"] !== true) {
+    throw new MementosApiProtocolError(operation, "expected complete=true");
+  }
+  const machines = values.map((entry, index) => decodeMachine(entry, `${operation} machines[${index}]`));
+  const ids = new Set;
+  const hosts = new Set;
+  const names = new Set;
+  let primaryCount = 0;
+  for (const machine of machines) {
+    if (ids.has(machine.id))
+      throw new MementosApiProtocolError(operation, `duplicate machine id '${machine.id}'`);
+    if (hosts.has(machine.hostname))
+      throw new MementosApiProtocolError(operation, `duplicate machine hostname '${machine.hostname}'`);
+    if (names.has(machine.name))
+      throw new MementosApiProtocolError(operation, `duplicate machine name '${machine.name}'`);
+    ids.add(machine.id);
+    hosts.add(machine.hostname);
+    names.add(machine.name);
+    if (machine.is_primary)
+      primaryCount += 1;
+  }
+  if (primaryCount > 1)
+    throw new MementosApiProtocolError(operation, "more than one machine is primary");
+  return machines;
+}
+function normalizeMachineHostname(host) {
+  const normalized = host.trim().replace(/\.+$/, "").toLowerCase();
+  if (!normalized || normalized.length > 253 || /[\u0000-\u001f\u007f/\\\s]/.test(normalized)) {
+    throw new MachineRegistryError("MACHINE_INVALID_INPUT", "Machine hostname must be a non-empty hostname of at most 253 characters");
+  }
+  return normalized;
+}
+function normalizeMachinePlatform(value) {
+  const normalized = value.trim().toLowerCase();
+  if (!normalized || normalized.length > 64 || !/^[a-z0-9._-]+$/.test(normalized)) {
+    throw new MachineRegistryError("MACHINE_INVALID_INPUT", "Machine platform must contain 1-64 lowercase letters, digits, dots, underscores, or hyphens");
+  }
+  return normalized;
 }
-function normalizeHostname(host) {
-  return host.replace(/\.(local|lan|home|internal)$/i, "");
+function normalizeMachineName(value, fallback) {
+  const normalized = value?.trim() || fallback;
+  if (!normalized || normalized.length > 128 || /[\u0000-\u001f\u007f]/.test(normalized)) {
+    throw new MachineRegistryError("MACHINE_INVALID_INPUT", "Machine name must contain 1-128 printable characters");
+  }
+  return normalized;
 }
-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));
+function registerMachineRecord(input, db) {
+  const d = db ?? getDatabase();
+  const host = normalizeMachineHostname(input.hostname);
+  const machineName = normalizeMachineName(input.name, host);
+  const machinePlatform = normalizeMachinePlatform(input.platform);
+  const proposedId = uuid();
+  const seenAt = now();
+  try {
+    const row = d.query(`INSERT INTO machines (id, name, hostname, platform, created_at, last_seen_at)
+       VALUES (?, ?, ?, ?, ?, ?)
+       ON CONFLICT(hostname) DO UPDATE SET
+         platform = excluded.platform,
+         last_seen_at = CASE
+           WHEN machines.last_seen_at > excluded.last_seen_at THEN machines.last_seen_at
+           ELSE excluded.last_seen_at
+         END
+       RETURNING *, id = ? AS registration_created`).get(proposedId, machineName, host, machinePlatform, seenAt, seenAt, proposedId);
+    const machine = machineFromDb(row, "machine registration upsert");
+    if (!machine || typeof row?.registration_created !== "boolean" && typeof row?.registration_created !== "number") {
+      throw new MachineRegistryError("MACHINE_REGISTRATION_CONFLICT", "Machine registration returned no stable identity receipt");
+    }
+    return { machine, created: Boolean(row.registration_created) };
+  } catch (error) {
+    if (error instanceof MachineRegistryError)
+      throw error;
+    const details = error && typeof error === "object" ? error : {};
+    const diagnostic = `${String(details.constraint ?? "")} ${String(details.message ?? "")}`;
+    if (/machines(?:_|\.)name|machines_name_key/i.test(diagnostic)) {
+      throw new MachineRegistryError("MACHINE_NAME_CONFLICT", `Machine name already taken: ${machineName}`);
+    }
+    throw error;
+  }
+}
+function registerMachine(name, db) {
+  const host = normalizeMachineHostname(hostname());
+  const plat = normalizeMachinePlatform(platform());
+  if (!db && isApiMode()) {
+    const input = { name: name?.trim() || undefined, hostname: host, platform: plat };
+    const { data } = apiJson("POST", "/machines", input);
+    return decodeRegistration(data, input).machine;
   }
-  let finalName = machineName;
-  let suffix = 2;
-  while (db.query("SELECT id FROM machines WHERE name = ?").get(finalName)) {
-    finalName = `${machineName}-${suffix++}`;
+  return registerMachineRecord({ name, hostname: host, platform: plat }, db).machine;
+}
+function listMachines(db) {
+  if (!db && isApiMode()) {
+    const { data } = apiJson("GET", "/machines");
+    return decodeMachineList(data);
   }
-  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));
+  const d = db ?? getDatabase();
+  const rows = d.query("SELECT * FROM machines ORDER BY is_primary DESC, last_seen_at DESC, created_at ASC, id ASC").all();
+  return rows.map((row) => machineFromDb(row));
 }
-function getPrimaryMachine(db = getDatabase()) {
-  return parseMachine(db.query("SELECT * FROM machines WHERE is_primary = 1 LIMIT 1").get());
+function getPrimaryMachine(db) {
+  if (!db && isApiMode())
+    return listMachines().find((machine) => machine.is_primary) ?? null;
+  const d = db ?? getDatabase();
+  return machineFromDb(d.query("SELECT * FROM machines WHERE is_primary = 1 LIMIT 1").get());
 }
-function getPrimaryMachineCandidate(db = getDatabase()) {
-  if (getPrimaryMachine(db))
+function getPrimaryMachineCandidate(db) {
+  if (!db && isApiMode()) {
+    const machines = listMachines();
+    if (machines.some((machine) => machine.is_primary))
+      return null;
+    return [...machines].sort((a, b) => a.created_at.localeCompare(b.created_at) || a.id.localeCompare(b.id))[0] ?? null;
+  }
+  const d = db ?? getDatabase();
+  if (getPrimaryMachine(d))
     return null;
-  return parseMachine(db.query("SELECT * FROM machines ORDER BY created_at ASC, id ASC LIMIT 1").get());
+  return machineFromDb(d.query("SELECT * FROM machines ORDER BY created_at ASC, id ASC LIMIT 1").get());
 }
-function getPrimaryMachineStartupWarning(db = getDatabase()) {
+function getPrimaryMachineStartupWarning(db) {
   if (getPrimaryMachine(db))
     return null;
   const candidate = getPrimaryMachineCandidate(db);
-  if (!candidate) {
+  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;
+var hostedMachineCache = null;
+function getCurrentMachineId(db) {
+  if (!db && isApiMode()) {
+    const host = normalizeMachineHostname(hostname());
+    const plat = normalizeMachinePlatform(platform());
+    const configBefore = getApiConfig();
+    if (!configBefore)
+      throw new Error("mementos hosted machine identity requires a resolved API authority");
+    const credentialFingerprint = createHash("sha256").update(configBefore.apiKey).digest("hex");
+    const key = `${configBefore.baseUrl}\x00${credentialFingerprint}\x00${host}\x00${plat}`;
+    if (hostedMachineCache?.key === key)
+      return hostedMachineCache.id;
+    const id = registerMachine().id;
+    const configAfter = getApiConfig();
+    const fingerprintAfter = configAfter ? createHash("sha256").update(configAfter.apiKey).digest("hex") : null;
+    if (!configAfter || configAfter.baseUrl !== configBefore.baseUrl || fingerprintAfter !== credentialFingerprint) {
+      throw new Error("MEMENTOS_AUTHORITY_CHANGED: the machine registry authority or credential changed while resolving the stable machine identity");
+    }
+    hostedMachineCache = { key, id };
+    return id;
   }
-  return registerMachine(undefined, db).id;
+  const d = db ?? getDatabase();
+  return registerMachine(undefined, d).id;
 }
 
 // src/cli/startup-side-effects.ts
@@ -65256,7 +66486,7 @@ init_memories();
 init_package_version();
 init_schema();
 init_identity();
-import { createHash as createHash2 } from "crypto";
+import { createHash as createHash3 } from "crypto";
 
 class MemoryProjectLinkError extends Error {
   code;
@@ -65296,7 +66526,7 @@ function canonicalJson(value) {
   return JSON.stringify(canonicalize(value));
 }
 function digest(value) {
-  return createHash2("sha256").update(canonicalJson(value)).digest("hex");
+  return createHash3("sha256").update(canonicalJson(value)).digest("hex");
 }
 function timestampString2(value) {
   return value instanceof Date ? value.toISOString() : String(value);
@@ -65881,7 +67111,7 @@ function getMemoryProjectLinkReceipt(memoryId, receiptId, identity = linkAuthori
 }
 
 // src/project-registration/authority.ts
-import { createHash as createHash3 } from "crypto";
+import { createHash as createHash4 } from "crypto";
 init_projects();
 init_types2();
 init_identity();
@@ -65903,7 +67133,7 @@ function canonicalize2(value) {
   return out;
 }
 function digestMementosProjectRegistrationValue(value) {
-  return createHash3("sha256").update(canonicalMementosProjectRegistrationJson(value)).digest("hex");
+  return createHash4("sha256").update(canonicalMementosProjectRegistrationJson(value)).digest("hex");
 }
 // src/project-registration/http.ts
 init_types2();
@@ -67303,16 +68533,164 @@ init_redact();
 init_helpers();
 import chalk12 from "chalk";
 import { resolve as resolve8 } from "path";
+var STRUCTURED_PAGE_MAX_ROWS = 1000;
+var STRUCTURED_ALL_MAX_ROWS = 5000;
+var STRUCTURED_DEFAULT_MAX_BYTES = 32 * 1024;
+var STRUCTURED_FULL_MAX_BYTES = 64 * 1024;
+var STRUCTURED_ALL_MAX_BYTES = 1024 * 1024;
+var STRUCTURED_MIN_MAX_BYTES = 1024;
+function structuredMaxBytes(value, opts) {
+  const fallback = opts.all ? STRUCTURED_ALL_MAX_BYTES : opts.detail === "full" ? STRUCTURED_FULL_MAX_BYTES : STRUCTURED_DEFAULT_MAX_BYTES;
+  if (value === undefined)
+    return fallback;
+  const parsed = typeof value === "number" ? value : Number(value);
+  if (!Number.isInteger(parsed) || parsed < STRUCTURED_MIN_MAX_BYTES || parsed > STRUCTURED_ALL_MAX_BYTES) {
+    throw new Error(`--max-bytes must be an integer from ${STRUCTURED_MIN_MAX_BYTES} to ${STRUCTURED_ALL_MAX_BYTES}`);
+  }
+  return parsed;
+}
+function compactMemoryForStructuredOutput(memory, opts = {}) {
+  const value = truncateText(memory.value, 160);
+  const summary = memory.summary ? truncateText(memory.summary, 160) : null;
+  return {
+    id: memory.id,
+    key: memory.key,
+    value,
+    ...summary ? { summary } : {},
+    scope: memory.scope,
+    category: memory.category,
+    importance: memory.importance,
+    status: memory.status,
+    pinned: memory.pinned,
+    ...Array.isArray(memory.tags) && memory.tags.length ? { tags: memory.tags.slice(0, 10) } : {},
+    ...memory.agent_id ? { agent_id: memory.agent_id } : {},
+    ...memory.project_id ? { project_id: memory.project_id } : {},
+    ...memory.session_id ? { session_id: memory.session_id } : {},
+    ...opts.history && memory.accessed_at ? { accessed_at: memory.accessed_at } : {},
+    updated_at: memory.updated_at
+  };
+}
+function withResponseBytes(envelope) {
+  for (let attempt = 0;attempt < 8; attempt += 1) {
+    const bytes = Buffer.byteLength(`${JSON.stringify(envelope)}
+`);
+    if (bytes === envelope._meta.response_bytes)
+      return envelope;
+    envelope._meta.response_bytes = bytes;
+  }
+  return envelope;
+}
+function makeStructuredEnvelope(args) {
+  const hasMore = args.byteTruncated || args.sourceHasMore;
+  const complete = args.offset === 0 && !hasMore;
+  const nextCursor = hasMore ? args.offset + args.memories.length : null;
+  const truncationReason = args.byteTruncated ? "max_bytes" : args.sourceHasMore ? "limit" : args.offset > 0 ? "cursor" : null;
+  return withResponseBytes({
+    memories: args.memories,
+    _meta: {
+      receipt: args.receipt,
+      count: args.memories.length,
+      limit: args.all ? null : args.limit,
+      offset: args.offset,
+      next_cursor: nextCursor,
+      has_more: hasMore,
+      complete,
+      all: args.all,
+      detail: args.detail,
+      max_rows: args.all ? STRUCTURED_ALL_MAX_ROWS : STRUCTURED_PAGE_MAX_ROWS,
+      max_bytes: args.maxBytes,
+      response_bytes: 0,
+      truncated: !complete,
+      truncation_reason: truncationReason,
+      omitted_from_page: args.omittedFromPage,
+      next_arguments: nextCursor === null ? null : {
+        cursor: nextCursor,
+        limit: args.limit,
+        agent_json: true,
+        ...args.detail === "full" ? { full: true } : {},
+        max_bytes: args.maxBytes
+      },
+      continuation_scope: "unchanged_snapshot"
+    }
+  });
+}
+function structuredMemoryOutput(args) {
+  const projected = args.detail === "full" ? args.memories : args.memories.map((memory) => compactMemoryForStructuredOutput(memory, { history: args.history }));
+  const completeEnvelope = makeStructuredEnvelope({
+    memories: projected,
+    receipt: args.receipt,
+    offset: args.offset,
+    limit: args.limit,
+    sourceHasMore: args.sourceHasMore,
+    all: args.all,
+    detail: args.detail,
+    maxBytes: args.maxBytes,
+    byteTruncated: false,
+    omittedFromPage: 0
+  });
+  const completeText = `${JSON.stringify(completeEnvelope)}
+`;
+  if (Buffer.byteLength(completeText) <= args.maxBytes)
+    return completeText;
+  if (args.all) {
+    throw new Error(`Exhaustive structured output exceeds the hard safety limit of ${args.maxBytes} bytes; use paginated JSON output instead`);
+  }
+  for (let count = projected.length - 1;count >= 0; count -= 1) {
+    const envelope = makeStructuredEnvelope({
+      memories: projected.slice(0, count),
+      receipt: args.receipt,
+      offset: args.offset,
+      limit: args.limit,
+      sourceHasMore: true,
+      all: false,
+      detail: args.detail,
+      maxBytes: args.maxBytes,
+      byteTruncated: true,
+      omittedFromPage: projected.length - count
+    });
+    const text = `${JSON.stringify(envelope)}
+`;
+    if (Buffer.byteLength(text) > args.maxBytes)
+      continue;
+    if (count === 0 && projected.length > 0) {
+      throw new Error(`One structured memory row exceeds --max-bytes=${args.maxBytes}; use compact detail, a larger --max-bytes value, or mementos show <id>`);
+    }
+    return text;
+  }
+  throw new Error(`Structured output metadata exceeds --max-bytes=${args.maxBytes}`);
+}
+function assertReceiptFlags(opts, receiptMode, requestedFormat) {
+  if (!receiptMode && (opts.all || opts.full || opts.maxBytes !== undefined)) {
+    throw new Error("--all, --full, and --max-bytes require --agent-json receipt mode");
+  }
+  if (receiptMode && requestedFormat !== undefined && requestedFormat !== "json") {
+    throw new Error("--agent-json cannot be combined with a non-JSON --format");
+  }
+  if (opts.all && opts.limit !== undefined) {
+    throw new Error("--all cannot be combined with --limit");
+  }
+}
 function registerListCommand(program2) {
   const handleError = makeHandleError(program2);
-  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) => {
+  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 (agent JSON page max: ${STRUCTURED_PAGE_MAX_ROWS})`, 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").option("--agent-json", "Output a bounded, receipt-bearing JSON page").option("--all", `Exhaust agent JSON results from offset zero (hard max: ${STRUCTURED_ALL_MAX_ROWS} rows)`).option("--full", "Emit full memory objects in agent JSON instead of compact projections").option("--max-bytes <n>", `Agent JSON response byte ceiling (hard max: ${STRUCTURED_ALL_MAX_BYTES})`, parseInt).action((opts) => {
     try {
       const globalOpts = program2.opts();
+      const requestedFormat = opts.format ?? globalOpts.format;
       const fmt = getOutputFormat(program2, opts.format);
+      const receiptMode = Boolean(opts.agentJson);
       const isStructured = fmt === "json" || fmt === "csv" || fmt === "yaml";
+      assertReceiptFlags(opts, receiptMode, requestedFormat);
       const requestedLimit = opts.limit;
-      const limit = requestedLimit === undefined ? isStructured ? undefined : DEFAULT_COMPACT_LIMIT : positiveIntOrDefault(requestedLimit, isStructured ? 50 : DEFAULT_COMPACT_LIMIT);
+      const all = Boolean(opts.all);
+      const detail = opts.full ? "full" : "compact";
+      const limit = requestedLimit === undefined ? receiptMode ? DEFAULT_COMPACT_LIMIT : isStructured ? undefined : DEFAULT_COMPACT_LIMIT : positiveIntOrDefault(requestedLimit, receiptMode ? DEFAULT_COMPACT_LIMIT : isStructured ? 50 : DEFAULT_COMPACT_LIMIT);
+      if (receiptMode && limit !== undefined && limit > STRUCTURED_PAGE_MAX_ROWS) {
+        throw new Error(`--limit cannot exceed the agent JSON page ceiling of ${STRUCTURED_PAGE_MAX_ROWS}; use --all for a bounded exhaustive read`);
+      }
       const offset = cursorOrOffset(opts.cursor, opts.offset) ?? 0;
+      if (all && offset !== 0) {
+        throw new Error("--all requires --cursor/--offset 0");
+      }
       const agentId = resolveAgentFilter(opts.agent || globalOpts.agent);
       const projectPath = opts.project || globalOpts.project;
       let projectId;
@@ -67334,6 +68712,7 @@ function registerListCommand(program2) {
         status: opts.status,
         session_id: opts.session || globalOpts.session
       };
+      const target = all ? STRUCTURED_ALL_MAX_ROWS : limit;
       const { rows: collected, hasMore } = collectPagedRows((cursor, pageLimit) => {
         const page = listMemoriesPage({
           ...filter,
@@ -67345,9 +68724,25 @@ function registerListCommand(program2) {
           has_more: page.has_more,
           next_cursor: page.next_cursor
         };
-      }, limit, offset);
-      const memories = hasMore && limit !== undefined ? collected.slice(0, limit) : collected;
+      }, target, offset);
+      if (all && hasMore) {
+        throw new Error(`Exhaustive structured output exceeds the hard safety limit of ${STRUCTURED_ALL_MAX_ROWS} rows; use paginated JSON output instead`);
+      }
+      const memories = target === undefined ? collected : collected.slice(0, target);
       const sanitized = memories.map(redactMemoryForOutput);
+      if (receiptMode) {
+        process.stdout.write(structuredMemoryOutput({
+          memories: sanitized,
+          receipt: "mementos.list.page.v1",
+          offset,
+          limit: limit ?? DEFAULT_COMPACT_LIMIT,
+          sourceHasMore: hasMore,
+          all,
+          detail,
+          maxBytes: structuredMaxBytes(opts.maxBytes, { all, detail })
+        }));
+        return;
+      }
       if (fmt === "json") {
         outputJson(sanitized);
         return;
@@ -67381,7 +68776,7 @@ function registerListCommand(program2) {
         offset,
         hasMore,
         command: "mementos list",
-        detailHint: "use mementos show <id> for full details or --json for full objects"
+        detailHint: "use mementos show <id> for full details, --json for the compatible full array, or --agent-json for a bounded receipt"
       });
     } catch (e) {
       handleError(e);
@@ -67808,13 +69203,33 @@ init_helpers();
 import chalk16 from "chalk";
 function registerHistoryCommand(program2) {
   const handleError = makeHandleError(program2);
-  program2.command("history").description("List memories sorted by most recently accessed").option("--limit <n>", "Max results (compact default: 10)", parseInt).option("--offset <n>", "Offset for pagination", parseInt).option("--cursor <n>", "Cursor offset for the next page", parseInt).option("--verbose", "Show wider memory snippets").action((opts) => {
+  program2.command("history").description("List memories sorted by most recently accessed").option("--limit <n>", `Max results (agent JSON page max: ${STRUCTURED_PAGE_MAX_ROWS})`, parseInt).option("--offset <n>", "Offset for pagination", parseInt).option("--cursor <n>", "Cursor offset for the next page", parseInt).option("--verbose", "Show wider memory snippets").option("--agent-json", "Output a bounded, receipt-bearing JSON page").option("--all", `Exhaust agent JSON results from offset zero (hard max: ${STRUCTURED_ALL_MAX_ROWS} rows)`).option("--full", "Emit full memory objects in agent JSON instead of compact projections").option("--max-bytes <n>", `Agent JSON response byte ceiling (hard max: ${STRUCTURED_ALL_MAX_BYTES})`, parseInt).action((opts) => {
     try {
       const globalOpts = program2.opts();
-      const isJson = Boolean(globalOpts.json);
+      const format = getOutputFormat(program2);
+      const receiptMode = Boolean(opts.agentJson);
+      const isJson = format === "json";
+      if (!receiptMode && (opts.all || opts.full || opts.maxBytes !== undefined)) {
+        throw new Error("--all, --full, and --max-bytes require --agent-json receipt mode");
+      }
+      if (receiptMode && globalOpts.format !== undefined && globalOpts.format !== "json") {
+        throw new Error("--agent-json cannot be combined with a non-JSON --format");
+      }
+      if (opts.all && opts.limit !== undefined) {
+        throw new Error("--all cannot be combined with --limit");
+      }
       const requestedLimit = opts.limit;
-      const limit = requestedLimit === undefined ? isJson ? undefined : DEFAULT_SEARCH_LIMIT : positiveIntOrDefault(requestedLimit, isJson ? 20 : DEFAULT_SEARCH_LIMIT);
+      const all = Boolean(opts.all);
+      const detail = opts.full ? "full" : "compact";
+      const limit = requestedLimit === undefined ? receiptMode ? DEFAULT_SEARCH_LIMIT : isJson ? undefined : DEFAULT_SEARCH_LIMIT : positiveIntOrDefault(requestedLimit, receiptMode ? DEFAULT_SEARCH_LIMIT : isJson ? 20 : DEFAULT_SEARCH_LIMIT);
+      if (receiptMode && limit !== undefined && limit > STRUCTURED_PAGE_MAX_ROWS) {
+        throw new Error(`--limit cannot exceed the agent JSON page ceiling of ${STRUCTURED_PAGE_MAX_ROWS}; use --all for a bounded exhaustive read`);
+      }
       const offset = cursorOrOffset(opts.cursor, opts.offset) ?? 0;
+      if (all && offset !== 0) {
+        throw new Error("--all requires --cursor/--offset 0");
+      }
+      const target = all ? STRUCTURED_ALL_MAX_ROWS : limit;
       const { rows: collected, hasMore } = collectPagedRows((cursor, pageLimit) => {
         const page = listMemoryHistoryPage({ limit: pageLimit, offset: cursor });
         return {
@@ -67822,10 +69237,27 @@ function registerHistoryCommand(program2) {
           has_more: page.has_more,
           next_cursor: page.next_cursor
         };
-      }, limit, offset);
-      const memories = hasMore && limit !== undefined ? collected.slice(0, limit) : collected;
+      }, target, offset);
+      if (all && hasMore) {
+        throw new Error(`Exhaustive structured output exceeds the hard safety limit of ${STRUCTURED_ALL_MAX_ROWS} rows; use paginated JSON output instead`);
+      }
+      const memories = target === undefined ? collected : collected.slice(0, target);
       const sanitized = memories.map(redactMemoryForOutput);
-      if (globalOpts.json) {
+      if (receiptMode) {
+        process.stdout.write(structuredMemoryOutput({
+          memories: sanitized,
+          receipt: "mementos.history.page.v1",
+          offset,
+          limit: limit ?? DEFAULT_SEARCH_LIMIT,
+          sourceHasMore: hasMore,
+          all,
+          detail,
+          maxBytes: structuredMaxBytes(opts.maxBytes, { all, detail }),
+          history: true
+        }));
+        return;
+      }
+      if (isJson) {
         outputJson(sanitized);
         return;
       }
@@ -67848,7 +69280,7 @@ function registerHistoryCommand(program2) {
         offset,
         hasMore,
         command: "mementos history",
-        detailHint: "use mementos show <id> for full details or --json for full objects"
+        detailHint: "use mementos show <id> for full details, --json for the compatible full array, or --agent-json for a bounded receipt"
       });
     } catch (e) {
       handleError(e);
@@ -67863,13 +69295,16 @@ import chalk17 from "chalk";
 import { resolve as resolve11 } from "path";
 
 // src/lib/machine-visibility.ts
+init_api_mode();
 function resolveVisibleMachineId(machineId, db) {
   if (machineId !== undefined) {
     return machineId;
   }
   try {
     return getCurrentMachineId(db);
-  } catch {
+  } catch (error) {
+    if (!db && isApiMode())
+      throw error;
     return null;
   }
 }
@@ -67900,13 +69335,16 @@ function registerContextCommand(program2) {
       const categoriesRaw = opts.categories;
       const categories = categoriesRaw ? categoriesRaw.split(",").map((c) => c.trim()) : undefined;
       const agentId = resolveAgentFilter(opts.agent || globalOpts.agent);
-      const projectPath = opts.project || globalOpts.project;
+      const projectPath = opts.project ?? globalOpts.project;
       const visibleMachineId = resolveVisibleMachineId(opts.machine);
       let projectId;
-      if (projectPath) {
+      if (projectPath !== undefined) {
+        if (!projectPath.trim())
+          throw new Error("Project not found: empty project path");
         const project = getProject(resolve11(projectPath));
-        if (project)
-          projectId = project.id;
+        if (!project)
+          throw new Error(`Project not found: ${projectPath}`);
+        projectId = project.id;
       }
       let memories;
       if (query) {
@@ -67954,6 +69392,7 @@ function registerContextCommand(program2) {
               ...baseFilter,
               scope: "private",
               agent_id: agentId,
+              project_id: projectId,
               ...visibleToMachineFilter(visibleMachineId)
             }));
           }
@@ -68090,247 +69529,13 @@ function registerImportCommand(program2) {
 }
 
 // src/cli/commands/io-clean.ts
+init_config();
 import chalk19 from "chalk";
 
-// src/lib/config.ts
-init_paths();
-init_env();
-init_local_opt_in();
-import { existsSync as existsSync6, mkdirSync as mkdirSync3, readFileSync as readFileSync6, readdirSync, writeFileSync as writeFileSync3, unlinkSync as unlinkSync2, cpSync as cpSync2 } from "fs";
-import { homedir as homedir4 } from "os";
-import { basename, dirname as dirname4, join as join9, resolve as resolve14 } from "path";
-function isInMemoryDb2(path) {
-  return path === ":memory:" || path.startsWith("file::memory:");
-}
-function homeDir() {
-  return process.env["HOME"] || process.env["USERPROFILE"] || homedir4();
-}
-var DEFAULT_CONFIG = {
-  default_scope: "private",
-  default_category: "knowledge",
-  default_importance: 5,
-  max_entries: 1000,
-  max_entries_per_scope: {
-    global: 500,
-    shared: 300,
-    private: 200,
-    working: 100
-  },
-  injection: {
-    max_tokens: 500,
-    min_importance: 5,
-    categories: ["preference", "fact"],
-    refresh_interval: 5
-  },
-  extraction: {
-    enabled: true,
-    min_confidence: 0.5
-  },
-  sync_agents: ["claude", "codex", "gemini"],
-  auto_cleanup: {
-    enabled: true,
-    expired_check_interval: 3600,
-    unused_archive_days: 7,
-    stale_deprioritize_days: 14
-  }
-};
-function deepMerge(target, source) {
-  const result = { ...target };
-  for (const key of Object.keys(source)) {
-    const sourceVal = source[key];
-    const targetVal = result[key];
-    if (sourceVal !== null && typeof sourceVal === "object" && !Array.isArray(sourceVal) && targetVal !== null && typeof targetVal === "object" && !Array.isArray(targetVal)) {
-      result[key] = deepMerge(targetVal, sourceVal);
-    } else {
-      result[key] = sourceVal;
-    }
-  }
-  return result;
-}
-var VALID_SCOPES2 = ["global", "shared", "private", "working"];
-var VALID_CATEGORIES2 = [
-  "preference",
-  "fact",
-  "knowledge",
-  "history"
-];
-function isValidScope(value) {
-  return VALID_SCOPES2.includes(value);
-}
-function isValidCategory(value) {
-  return VALID_CATEGORIES2.includes(value);
-}
-function loadConfig() {
-  const configPath = join9(getDataRoot(), "config.json");
-  let fileConfig = {};
-  if (existsSync6(configPath)) {
-    try {
-      const raw = readFileSync6(configPath, "utf-8");
-      fileConfig = JSON.parse(raw);
-    } catch {}
-  }
-  const merged = deepMerge(DEFAULT_CONFIG, fileConfig);
-  const envScope = env.defaultScope();
-  if (envScope && isValidScope(envScope)) {
-    merged.default_scope = envScope;
-  }
-  const envCategory = env.defaultCategory();
-  if (envCategory && isValidCategory(envCategory)) {
-    merged.default_category = envCategory;
-  }
-  const envImportance = env.defaultImportance();
-  if (envImportance) {
-    const parsed = parseInt(envImportance, 10);
-    if (!Number.isNaN(parsed) && parsed >= 1 && parsed <= 10) {
-      merged.default_importance = parsed;
-    }
-  }
-  return merged;
-}
-function findFileWalkingUp(filename) {
-  let dir = process.cwd();
-  const legacyHomeMementosDb = resolve14(homeDir(), ".mementos", "mementos.db");
-  while (true) {
-    const candidate = join9(dir, filename);
-    if (existsSync6(candidate) && resolve14(candidate) !== legacyHomeMementosDb) {
-      return candidate;
-    }
-    const parent = dirname4(dir);
-    if (parent === dir) {
-      return null;
-    }
-    dir = parent;
-  }
-}
-function findGitRoot2() {
-  let dir = process.cwd();
-  while (true) {
-    if (existsSync6(join9(dir, ".git"))) {
-      return dir;
-    }
-    const parent = dirname4(dir);
-    if (parent === dir) {
-      return null;
-    }
-    dir = parent;
-  }
-}
-function profilesDir() {
-  return join9(getDataRoot(), "profiles");
-}
-function globalConfigPath() {
-  return join9(getDataRoot(), "config.json");
-}
-function readGlobalConfig() {
-  const p = globalConfigPath();
-  if (!existsSync6(p))
-    return {};
-  try {
-    return JSON.parse(readFileSync6(p, "utf-8"));
-  } catch {
-    return {};
-  }
-}
-function readGlobalConfigForWrite() {
-  const p = globalConfigPath();
-  if (!existsSync6(p))
-    return {};
-  try {
-    const data = JSON.parse(readFileSync6(p, "utf-8"));
-    if (data === null || typeof data !== "object" || Array.isArray(data)) {
-      throw new Error("expected a JSON object");
-    }
-    return data;
-  } catch (error) {
-    const detail = error instanceof Error ? error.message : String(error);
-    throw new Error(`Cannot update global config at ${p}: ${detail}`);
-  }
-}
-function writeGlobalConfig(data) {
-  const p = globalConfigPath();
-  ensureDir2(dirname4(p));
-  writeFileSync3(p, JSON.stringify(data, null, 2), "utf-8");
-}
-function getActiveProfile() {
-  const envProfile = process.env["MEMENTOS_PROFILE"];
-  if (envProfile)
-    return envProfile.trim();
-  const cfg = readGlobalConfig();
-  return cfg["active_profile"] || null;
-}
-function setActiveProfile(name) {
-  const cfg = readGlobalConfigForWrite();
-  if (name === null) {
-    delete cfg["active_profile"];
-  } else {
-    cfg["active_profile"] = name;
-  }
-  writeGlobalConfig(cfg);
-}
-function listProfiles() {
-  const dir = profilesDir();
-  if (!existsSync6(dir))
-    return [];
-  return readdirSync(dir).filter((f) => f.endsWith(".db")).map((f) => basename(f, ".db")).sort();
-}
-function deleteProfile(name) {
-  const dbPath = join9(profilesDir(), `${name}.db`);
-  if (!existsSync6(dbPath))
-    return false;
-  unlinkSync2(dbPath);
-  if (getActiveProfile() === name)
-    setActiveProfile(null);
-  return true;
-}
-function getDbPath2() {
-  const _home = homeDir();
-  const _newDir = getDataRoot();
-  const _oldDir = join9(_home, ".mementos");
-  if (selectsMementosLocalStore() && !existsSync6(_newDir) && existsSync6(_oldDir)) {
-    mkdirSync3(join9(_home, ".hasna"), { recursive: true });
-    cpSync2(_oldDir, _newDir, { recursive: true });
-  }
-  const envDbPath = process.env["HASNA_MEMENTOS_DB_PATH"] ?? process.env["MEMENTOS_DB_PATH"];
-  if (envDbPath) {
-    if (isInMemoryDb2(envDbPath)) {
-      return envDbPath;
-    }
-    const resolved = resolve14(envDbPath);
-    ensureDir2(dirname4(resolved));
-    return resolved;
-  }
-  const profile = getActiveProfile();
-  if (profile) {
-    const profilePath = join9(profilesDir(), `${profile}.db`);
-    ensureDir2(dirname4(profilePath));
-    return profilePath;
-  }
-  const dbScope = process.env["MEMENTOS_DB_SCOPE"];
-  if (dbScope === "project") {
-    const gitRoot = findGitRoot2();
-    if (gitRoot) {
-      const dbPath = join9(gitRoot, ".mementos", "mementos.db");
-      ensureDir2(dirname4(dbPath));
-      return dbPath;
-    }
-  }
-  const found = findFileWalkingUp(join9(".mementos", "mementos.db"));
-  if (found) {
-    return found;
-  }
-  const fallback = join9(getDataRoot(), "mementos.db");
-  ensureDir2(dirname4(fallback));
-  return fallback;
-}
-function ensureDir2(dir) {
-  if (!existsSync6(dir)) {
-    mkdirSync3(dir, { recursive: true });
-  }
-}
-
 // src/lib/retention.ts
 init_database();
 init_memories();
+init_config();
 function enforceQuotas(config, db) {
   const d = db || getDatabase();
   let totalEvicted = 0;
@@ -68438,11 +69643,108 @@ function registerCleanCommand(program2) {
 
 // src/cli/commands/io-backup.ts
 init_database();
+init_api_mode();
+init_memories();
 init_paths();
 init_helpers();
 import chalk20 from "chalk";
 import { join as join10, resolve as resolve15, dirname as dirname5 } from "path";
-import { existsSync as existsSync7, statSync, copyFileSync, mkdirSync as mkdirSync4, readdirSync as readdirSync2 } from "fs";
+import { existsSync as existsSync7, statSync, copyFileSync, mkdirSync as mkdirSync4, readdirSync as readdirSync2, unlinkSync as unlinkSync3 } from "fs";
+function writeMemoriesBackupFile(dest, rows) {
+  const { Database: Database3 } = __require("bun:sqlite");
+  if (existsSync7(dest)) {
+    unlinkSync3(dest);
+  }
+  const backupDb = new Database3(dest);
+  try {
+    backupDb.run(`
+      CREATE TABLE IF NOT EXISTS _backup_carrier (
+        format INTEGER NOT NULL
+      )
+    `);
+    backupDb.run(`INSERT INTO _backup_carrier (format) VALUES (1)`);
+    backupDb.run(`
+      CREATE TABLE IF NOT EXISTS memories (
+        id TEXT PRIMARY KEY,
+        key TEXT NOT NULL,
+        value TEXT NOT NULL,
+        category TEXT,
+        scope TEXT,
+        summary TEXT,
+        tags TEXT,
+        importance INTEGER,
+        source TEXT,
+        status TEXT,
+        pinned INTEGER,
+        agent_id TEXT,
+        project_id TEXT,
+        session_id TEXT,
+        machine_id TEXT,
+        namespace TEXT,
+        created_by_agent TEXT,
+        when_to_use TEXT,
+        sequence_group TEXT,
+        sequence_order INTEGER,
+        metadata TEXT,
+        access_count INTEGER,
+        version INTEGER,
+        expires_at TEXT,
+        valid_from TEXT,
+        valid_until TEXT,
+        ingested_at TEXT,
+        created_at TEXT,
+        updated_at TEXT,
+        accessed_at TEXT
+      )
+    `);
+    const insert = backupDb.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, accessed_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+    const bind = (v) => {
+      if (v === undefined || v === null)
+        return null;
+      return typeof v === "string" || typeof v === "number" ? v : JSON.stringify(v);
+    };
+    const boolBind = (v) => v === undefined || v === null ? null : v ? 1 : 0;
+    for (const row of rows) {
+      const params = [
+        bind(row["id"]),
+        bind(row["key"]),
+        bind(row["value"]),
+        bind(row["category"]),
+        bind(row["scope"]),
+        bind(row["summary"]),
+        Array.isArray(row["tags"]) ? JSON.stringify(row["tags"]) : bind(row["tags"]),
+        bind(row["importance"]),
+        bind(row["source"]),
+        bind(row["status"]),
+        boolBind(row["pinned"]),
+        bind(row["agent_id"]),
+        bind(row["project_id"]),
+        bind(row["session_id"]),
+        bind(row["machine_id"]),
+        bind(row["namespace"]),
+        bind(row["created_by_agent"]),
+        bind(row["when_to_use"]),
+        bind(row["sequence_group"]),
+        bind(row["sequence_order"]),
+        bind(row["metadata"]),
+        bind(row["access_count"]),
+        bind(row["version"]),
+        bind(row["expires_at"]),
+        bind(row["valid_from"]),
+        bind(row["valid_until"]),
+        bind(row["ingested_at"]),
+        bind(row["created_at"]),
+        bind(row["updated_at"]),
+        bind(row["accessed_at"])
+      ];
+      insert.run(...params);
+    }
+    return rows.length;
+  } finally {
+    backupDb.close();
+  }
+}
 function registerBackupCommand(program2) {
   const handleError = makeHandleError(program2);
   program2.command("backup [path]").description("Backup the SQLite database to a file").option("--list", "List available backups in the mementos backups dir").action((targetPath, opts) => {
@@ -68491,11 +69793,6 @@ function registerBackupCommand(program2) {
         }
         return;
       }
-      const dbPath = getDbPath();
-      if (!existsSync7(dbPath)) {
-        console.error(chalk20.red(`Database not found at ${dbPath}`));
-        process.exit(1);
-      }
       let dest;
       if (targetPath) {
         dest = resolve15(targetPath);
@@ -68511,6 +69808,26 @@ function registerBackupCommand(program2) {
       if (!existsSync7(destDir)) {
         mkdirSync4(destDir, { recursive: true });
       }
+      if (isApiMode()) {
+        const { rows } = listMemoriesBounded({}, undefined);
+        const count = writeMemoriesBackupFile(dest, rows);
+        const st2 = statSync(dest);
+        const sizeMB2 = (st2.size / (1024 * 1024)).toFixed(1);
+        const sizeStr2 = st2.size >= 1024 * 1024 ? `${sizeMB2} MB` : `${(st2.size / 1024).toFixed(1)} KB`;
+        if (globalOpts.json) {
+          outputJson({ backed_up_to: dest, size: st2.size, source: "cloud-api", memories: count });
+          return;
+        }
+        console.log(`Backed up to: ${chalk20.green(dest)} (size: ${sizeStr2})`);
+        console.log(`  Source:   hosted store (cloud-api)`);
+        console.log(`  Memories: ${chalk20.cyan(String(count))}`);
+        return;
+      }
+      const dbPath = getDbPath();
+      if (!existsSync7(dbPath)) {
+        console.error(chalk20.red(`Database not found at ${dbPath}`));
+        process.exit(1);
+      }
       copyFileSync(dbPath, dest);
       const st = statSync(dest);
       const sizeMB = (st.size / (1024 * 1024)).toFixed(1);
@@ -68545,6 +69862,28 @@ function readMemoriesFromBackup(source) {
     backupDb.close();
   }
 }
+function inspectLocalRestoreSource(source) {
+  const { Database: Database3 } = __require("bun:sqlite");
+  let backupDb;
+  try {
+    backupDb = new Database3(source, { readonly: true });
+  } catch (error) {
+    throw new Error(`Backup file is not a readable SQLite database: ${source} ` + `(${error instanceof Error ? error.message : String(error)})`);
+  }
+  try {
+    const tables = backupDb.query("SELECT name FROM sqlite_master WHERE type = 'table'").all().map((t) => t.name);
+    if (tables.includes("_backup_carrier")) {
+      throw new Error(`${source} is a memories-only cloud backup (created by \`mementos backup\` in hosted mode), ` + `not a full local database backup. Restoring it over the on-box database would drop every ` + `non-memories table and its migration history, and the next migration run would collide with ` + `the half-shaped schema. Restore it into the hosted store instead (run \`mementos restore\` with ` + `a hosted credential), or re-import its memories with \`mementos import\`.`);
+    }
+    if (!tables.includes("memories")) {
+      throw new Error(`Backup file has no mementos \`memories\` table: ${source} \u2014 it is not a mementos backup.`);
+    }
+    const row = backupDb.query("SELECT COUNT(*) as count FROM memories").get();
+    return { memories: row?.count ?? 0 };
+  } finally {
+    backupDb.close();
+  }
+}
 function registerRestoreCommand(program2) {
   const handleError = makeHandleError(program2);
   program2.command("restore [file]").description("Restore the database from a backup file").option("--latest", "Restore the most recent backup from the mementos backups dir").option("--force", "Skip confirmation and perform the restore").action((filePath, opts) => {
@@ -68655,14 +69994,7 @@ function registerRestoreCommand(program2) {
           currentCount = row?.count ?? 0;
         } catch {}
       }
-      let backupCount = 0;
-      try {
-        const { Database: Database3 } = __require("bun:sqlite");
-        const backupDb = new Database3(source, { readonly: true });
-        const row = backupDb.query("SELECT COUNT(*) as count FROM memories").get();
-        backupCount = row?.count ?? 0;
-        backupDb.close();
-      } catch {}
+      const backupCount = inspectLocalRestoreSource(source).memories;
       if (!opts.force) {
         if (globalOpts.json) {
           outputJson({
@@ -69103,14 +70435,17 @@ function registerProjectCommands(program2) {
       const categoriesRaw = opts.categories || "preference,fact,knowledge";
       const categories = categoriesRaw.split(",").map((c) => c.trim());
       const agentId = opts.agent || globalOpts.agent;
-      const projectPath = opts.project || globalOpts.project;
+      const projectPath = opts.project ?? globalOpts.project;
       const sessionId = opts.session || globalOpts.session;
       const visibleMachineId = resolveVisibleMachineId(opts.machine);
       let projectId;
-      if (projectPath) {
+      if (projectPath !== undefined) {
+        if (!projectPath.trim())
+          throw new Error("Project not found: empty project path");
         const project = getProject(resolve17(projectPath));
-        if (project)
-          projectId = project.id;
+        if (!project)
+          throw new Error(`Project not found: ${projectPath}`);
+        projectId = project.id;
       }
       const allMemories = [];
       const globalMems = listMemories({
@@ -69142,6 +70477,7 @@ function registerProjectCommands(program2) {
           min_importance: minImportance,
           status: "active",
           agent_id: agentId,
+          project_id: projectId,
           session_id: sessionId,
           ...visibleToMachineFilter(visibleMachineId),
           limit: 50
@@ -69901,6 +71237,8 @@ init_database();
 init_memories();
 init_agents();
 init_projects();
+init_config();
+init_api_mode();
 import chalk27 from "chalk";
 import { join as join12 } from "path";
 import { homedir as homedir5 } from "os";
@@ -69911,7 +71249,6 @@ import {
   statSync as statSync3,
   constants as fsConstants
 } from "fs";
-init_api_mode();
 init_helpers();
 async function runCommandWithTimeout(args, timeoutMs) {
   const proc = Bun.spawn(args, { stdout: "pipe", stderr: "pipe" });
@@ -70340,8 +71677,9 @@ function registerStatusCommand(program2) {
 }
 
 // src/cli/commands/system-config.ts
-import chalk28 from "chalk";
+init_config();
 init_helpers();
+import chalk28 from "chalk";
 function registerConfigCommand(program2) {
   program2.command("config [subcommand] [args...]").description("View or modify configuration. Subcommands: get <key>, set <key> <value>, reset [key], path").action((subcommand, args) => {
     try {
@@ -70427,9 +71765,9 @@ function registerConfigCommand(program2) {
           }
         } else {
           const configPath = getConfigPath2();
-          const { unlinkSync: unlinkSync3, existsSync: _existsSync } = __require("fs");
+          const { unlinkSync: unlinkSync4, existsSync: _existsSync } = __require("fs");
           if (_existsSync(configPath)) {
-            unlinkSync3(configPath);
+            unlinkSync4(configPath);
           }
           if (useJson) {
             outputJson({ reset: true, all: true });
@@ -70449,10 +71787,11 @@ function registerConfigCommand(program2) {
 }
 
 // src/cli/commands/system-profile.ts
-import chalk29 from "chalk";
-import { join as join13 } from "path";
+init_config();
 init_paths();
 init_helpers();
+import chalk29 from "chalk";
+import { join as join13 } from "path";
 function registerProfileCommand(program2) {
   const profileCmd = program2.command("profile").description("Manage named profile files and active-profile metadata");
   profileCmd.command("list").description("List all available profiles").action(() => {
@@ -70860,10 +72199,12 @@ function registerSessionCommand(program2) {
   const sessionCmd = program2.command("session").description("Session auto-memory \u2014 ingest session transcripts for memory extraction");
   sessionCmd.command("ingest <transcriptFile>").description("Ingest a session transcript file for memory extraction").option("--session-id <id>", "Session ID (default: auto-generated)").option("--agent <id>", "Agent ID").option("--project <id>", "Project ID").option("--source <source>", "Source (claude-code, codex, manual, open-sessions)", "manual").action(async (transcriptFile, opts) => {
     const { readFileSync: _rfs } = await import("fs");
-    const { createSessionJob: createSessionJob2 } = await Promise.resolve().then(() => (init_session_jobs(), exports_session_jobs));
-    const { enqueueSessionJob: enqueueSessionJob2 } = await Promise.resolve().then(() => (init_session_queue(), exports_session_queue));
     const transcript = _rfs(transcriptFile, "utf-8");
     const sessionId = opts.sessionId ?? `cli-${Date.now()}`;
+    const { isApiMode: isApiMode2 } = await Promise.resolve().then(() => (init_api_mode(), exports_api_mode));
+    const hosted = isApiMode2();
+    const { createSessionJob: createSessionJob2 } = await Promise.resolve().then(() => (init_session_jobs(), exports_session_jobs));
+    const { enqueueSessionJob: enqueueSessionJob2 } = await Promise.resolve().then(() => (init_session_queue(), exports_session_queue));
     const job = createSessionJob2({
       session_id: sessionId,
       transcript,
@@ -70872,7 +72213,7 @@ function registerSessionCommand(program2) {
       project_id: opts.project
     });
     enqueueSessionJob2(job.id);
-    console.log(chalk33.green(`\u2713 Session queued: ${chalk33.cyan(job.id)}`));
+    console.log(chalk33.green(`\u2713 Session queued${hosted ? " (hosted store)" : ""}: ${chalk33.cyan(job.id)}`));
     console.log(`  Session: ${sessionId}`);
     console.log(`  Length:  ${transcript.length} chars`);
   });
@@ -70891,14 +72232,16 @@ function registerSessionCommand(program2) {
     if (job.error)
       console.log(chalk33.red(`  Error: ${job.error}`));
   });
-  sessionCmd.command("list").description("List session extraction jobs").option("--agent <id>", "Filter by agent").option("--project <id>", "Filter by project").option("--status <status>", "Filter by status").option("--limit <n>", "Max results", "20").action(async (opts) => {
+  sessionCmd.command("list").description("List session extraction jobs").option("--agent <id>", "Filter by agent").option("--project <id>", "Filter by project").option("--status <status>", "Filter by status").option("--session-id <id>", "Filter by session ID").option("--limit <n>", "Max results", "20").option("--offset <n>", "Result offset", "0").action(async (opts) => {
     const globalOpts = program2.opts();
     const { listSessionJobs: listSessionJobs2 } = await Promise.resolve().then(() => (init_session_jobs(), exports_session_jobs));
     const jobs = listSessionJobs2({
       agent_id: opts.agent,
       project_id: opts.project,
       status: opts.status,
-      limit: parseInt(opts.limit)
+      session_id: opts.sessionId,
+      limit: parseInt(opts.limit, 10),
+      offset: parseInt(opts.offset, 10)
     });
     if (globalOpts.json) {
       outputJson(jobs);
@@ -71044,7 +72387,7 @@ import chalk35 from "chalk";
 import { resolve as resolve19 } from "path";
 function registerSynthesizedProfileCommand(program2) {
   const handleError = makeHandleError(program2);
-  program2.command("synthesized-profile").description("Show or refresh the synthesized agent/project profile").option("--project-id <id>", "Project ID").option("--refresh", "Force refresh the profile (re-synthesize from memories)").action(async (opts) => {
+  program2.command("synthesized-profile").description("Show or refresh the synthesized agent/project profile").option("--project-id <id>", "Project ID").option("--scope <scope>", "Profile scope: agent, project, or global").option("--refresh", "Force refresh the profile (re-synthesize from memories)").action(async (opts) => {
     try {
       const globalOpts = program2.opts();
       const { synthesizeProfile: synthesizeProfile2 } = await Promise.resolve().then(() => (init_profile_synthesizer(), exports_profile_synthesizer));
@@ -71058,6 +72401,7 @@ function registerSynthesizedProfileCommand(program2) {
       const result = await synthesizeProfile2({
         project_id: projectId,
         agent_id: globalOpts.agent,
+        scope: opts.scope,
         force_refresh: !!opts.refresh
       });
       if (!result) {
@@ -71575,6 +72919,15 @@ import chalk40 from "chalk";
 // src/lib/storage-sync.ts
 init_storage();
 init_database();
+init_config();
+init_local_opt_in();
+var STORAGE_SYNC_LOCAL_ONLY_MESSAGE = "REMOTE_COMMAND_UNSUPPORTED: mementos storage push/pull/sync/status operate on the on-box SQLite store, " + "which is opt-in only (" + `${MEMENTOS_LOCAL_OPT_IN_ENV_KEYS[0]}=1 or an explicit ${MEMENTOS_DB_PATH_ENV_KEYS[0]}` + ") and disabled by default. On the hosted route there is no local store to sync \u2014 refusing rather than " + "creating one. Run these verbs where the on-box store deliberately lives (the local opt-in) or in mementos-serve.";
+function openLocalSyncAdapter() {
+  if (!isServerContext() && !selectsMementosLocalStore(process.env)) {
+    throw new Error(STORAGE_SYNC_LOCAL_ONLY_MESSAGE);
+  }
+  return new SqliteAdapter(getDbPath2());
+}
 var MEMORY_TABLE = "memories";
 var MEMORY_SYNC_META_TABLE = "_mementos_storage_sync_meta";
 var SOURCE_MACHINE_METADATA_KEY = "last_synced_source_machine";
@@ -71953,7 +73306,7 @@ function resolveTables(local, tables) {
 function withManagedAdapters(options, fn) {
   const localOwned = !options.local;
   const remoteOwned = !options.remote;
-  const local = options.local ?? new SqliteAdapter(getDbPath2());
+  const local = options.local ?? openLocalSyncAdapter();
   const remote = options.remote ?? new PgAdapter(getStorageConnectionString("mementos"));
   try {
     const currentMachineId = resolveCurrentMachineId(local, options.current_machine_id);
@@ -72009,7 +73362,7 @@ function pullStorageChanges(options = {}) {
 function getStorageSyncStatus(options = {}) {
   const backend = getStorageBackend();
   const localOwned = !options.local;
-  const local = options.local ?? new SqliteAdapter(getDbPath2());
+  const local = options.local ?? openLocalSyncAdapter();
   try {
     const currentMachineId = resolveCurrentMachineId(local, options.current_machine_id);
     return {