@hasna/mementos 0.14.72 → 0.14.74

package/dist/cli/commands/memory-cmd-crud.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memory-cmd-crud.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/memory-cmd-crud.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA+BzC,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAka3D"}
+{"version":3,"file":"memory-cmd-crud.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/memory-cmd-crud.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA+BzC,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAwf3D"}

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

@@ -1 +1 @@
-{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/storage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAsUzC,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAK9D"}
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/storage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA8UzC,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAK9D"}

package/dist/cli/exit-codes.d.ts

@@ -0,0 +1,13 @@
+export declare const EXIT_USAGE = 64;
+/**
+ * Map a CommanderError onto this CLI's exit-status contract.
+ *
+ * Pure and total: given the `code`/`exitCode` pair Commander produces, returns
+ * the status the process should exit with. Success paths (`--help`, `--version`,
+ * which arrive with exitCode 0) are passed through untouched.
+ */
+export declare function resolveExitCode(err: {
+    code?: string;
+    exitCode?: number;
+}): number;
+//# sourceMappingURL=exit-codes.d.ts.map

package/dist/cli/exit-codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exit-codes.d.ts","sourceRoot":"","sources":["../../src/cli/exit-codes.ts"],"names":[],"mappings":"AAsCA,eAAO,MAAM,UAAU,KAAK,CAAC;AA2B7B;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,MAAM,CAOT"}

package/dist/cli/helpers.d.ts

@@ -6,7 +6,7 @@ export declare function importanceColor(importance: number): (s: string) => stri
 export declare function colorScope(scope: MemoryScope): string;
 export declare function colorCategory(category: MemoryCategory): string;
 export declare function colorImportance(importance: number): string;
-export declare function colorEntityType(type: string): string;
+export declare function colorEntityType(type: string, suffix?: string): string;
 export declare function resolveEntityArg(nameOrId: string, type?: EntityType): Entity;
 export declare function outputJson(data: unknown): void;
 export declare const DEFAULT_COMPACT_LIMIT = 20;

package/dist/cli/helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/cli/helpers.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/cli/helpers.ts"],"names":[],"mappings":"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"}

package/dist/cli/index.js

@@ -3010,6 +3010,14 @@ function getApiModeEnvSources() {
     databaseUrlKey: firstEnvKey(DATABASE_URL_ENV_KEYS)
   };
 }
+function getConfiguredApiEnv() {
+  const rawBase = firstEnv(API_URL_ENV_KEYS);
+  return {
+    baseUrl: rawBase ? normalizeBase(rawBase) : null,
+    apiKeyPresent: Boolean(firstEnvKey(API_KEY_ENV_KEYS)),
+    dbPathKey: firstEnvKey(DB_PATH_ENV_KEYS)
+  };
+}
 function isLoopbackHost(rawHost) {
   const host = rawHost.replace(/^\[/, "").replace(/\]$/, "").toLowerCase();
   return host === "localhost" || host === "::1" || /^127\./.test(host);
@@ -3055,6 +3063,8 @@ function assertUnambiguousStoreEnv() {
 }
 function getApiConfig() {
   assertUnambiguousStoreEnv();
+  if (firstEnvKey(DB_PATH_ENV_KEYS))
+    return null;
   const rawBase = firstEnv(API_URL_ENV_KEYS);
   const apiKey = firstEnv(API_KEY_ENV_KEYS);
   if (!rawBase || !apiKey)
@@ -4179,9 +4189,10 @@ function migrateGlobalDir() {
   }
 }
 function getDbPath() {
-  const envPath = process.env["HASNA_MEMENTOS_DB_PATH"] ?? process.env["MEMENTOS_DB_PATH"];
-  if (envPath) {
-    return envPath;
+  for (const key of DB_PATH_ENV_KEYS) {
+    const envPath = process.env[key]?.trim();
+    if (envPath)
+      return envPath;
   }
   const cwd = process.cwd();
   const nearest = findNearestMementosDb(cwd);
@@ -4225,6 +4236,12 @@ function getDatabase(dbPath) {
     if (getStorageMode() === "cloud") {
       return getCloudDatabase();
     }
+    if (process.env["NODE_ENV"] === "test") {
+      const hasExplicitDbPath = DB_PATH_ENV_KEYS.some((key) => process.env[key]?.trim());
+      if (!hasExplicitDbPath) {
+        throw new Error("REFUSING-UNPINNED-TEST-OPEN: a test process tried to open the default local " + `SQLite store (${getDbPath()}) with no explicit dbPath argument and no ` + `${DB_PATH_ENV_KEYS.join("/")} set. Pass an explicit dbPath (e.g. ":memory:" ` + "or a scratch file), or set one of those env keys to a scratch path, before " + "calling getDatabase(). This guard exists because an unpinned test process " + "would otherwise silently read and write the real, shared, on-disk memory " + "store (todos 57b8b8c5).");
+      }
+    }
   }
   const path = dbPath || getDbPath();
   if (_db) {
@@ -6036,9 +6053,9 @@ function colorCategory(category) {
 function colorImportance(importance) {
   return importanceColor(importance)(String(importance));
 }
-function colorEntityType(type) {
+function colorEntityType(type, suffix = "") {
   const colorFn = entityTypeColor[type] || chalk.white;
-  return colorFn(type);
+  return colorFn(`${type}${suffix}`);
 }
 function resolveEntityArg(nameOrId, type) {
   const byName = getEntityByName(nameOrId, type);
@@ -59025,6 +59042,26 @@ function applyGlobalOptions(program2) {
   return program2;
 }
 
+// src/cli/exit-codes.ts
+var EXIT_USAGE = 64;
+var USAGE_ERROR_CODES = new Set([
+  "commander.unknownCommand",
+  "commander.unknownOption",
+  "commander.missingArgument",
+  "commander.optionMissingArgument",
+  "commander.missingMandatoryOptionValue",
+  "commander.excessArguments",
+  "commander.conflictingOption",
+  "commander.invalidArgument",
+  "commander.help"
+]);
+function resolveExitCode(err) {
+  const exitCode = typeof err.exitCode === "number" ? err.exitCode : 1;
+  if (exitCode === 0)
+    return 0;
+  return USAGE_ERROR_CODES.has(err.code ?? "") ? EXIT_USAGE : exitCode;
+}
+
 // node_modules/@hasna/events/dist/commander.js
 import { chmod, mkdir, readFile, rename, writeFile } from "fs/promises";
 import { existsSync as existsSync3 } from "fs";
@@ -59827,7 +59864,13 @@ function registerCrudCommands(program2) {
       let resolvedAgentId;
       if (globalOpts.agent) {
         const ag = getAgent(globalOpts.agent);
-        resolvedAgentId = ag?.id;
+        if (!ag) {
+          throw new Error(`Unknown agent "${globalOpts.agent}": no registered agent matches that name or id.
+` + `Refusing to save. Dropping the flag would write this memory to the unowned ` + `(no-agent) row for key "${key}", overwriting whatever is there under an owner ` + `you did not name.
+` + `Register the agent first:  mementos register-agent ${globalOpts.agent}
+` + `Or omit --agent to write to the unowned row deliberately.`);
+        }
+        resolvedAgentId = ag.id;
       }
       const input = {
         key,
@@ -59843,9 +59886,18 @@ function registerCrudCommands(program2) {
         session_id: globalOpts.session
       };
       if (globalOpts.project) {
-        const project = getProject(resolve3(globalOpts.project));
-        if (project)
-          input.project_id = project.id;
+        const projectPath = resolve3(globalOpts.project);
+        const project = getProject(projectPath);
+        if (!project) {
+          throw new Error(`Unknown project "${projectPath}": no registered project matches that path.
+` + `Refusing to save. Dropping the flag would write this memory to the no-project ` + `row for key "${key}", overwriting whatever is there in a scope you did not name.
+` + `Register it first:  mementos projects --add --path ${projectPath} --name <name>
+` + `Or omit --project to write outside any project deliberately.`);
+        }
+        input.project_id = project.id;
+      }
+      if (typeof input.session_id === "string" && MEMORY_SCOPES.includes(input.session_id)) {
+        console.error(chalk2.yellow(`Warning: --session "${input.session_id}" looks like a scope, not a session id. ` + `Note that -s is the global --session, not --scope; this save is writing ` + `session_id="${input.session_id}" and leaving scope at "${input.scope ?? "private"}". ` + `If you meant the scope, pass --scope ${input.session_id} (long form only).`));
       }
       const bucket = (m) => [m.scope ?? "private", m.agent_id ?? "", m.project_id ?? "", m.session_id ?? ""].join("\x1F");
       const targetBucket = bucket({
@@ -59864,9 +59916,9 @@ function registerCrudCommands(program2) {
         if (!match && sameKey.length > 0) {
           const rows = sameKey.map((m) => `  ${m.id.slice(0, 8)}  scope=${m.scope}  project=${m.project_id ?? "none"}  session=${m.session_id ?? "none"}  agent=${m.agent_id ?? "none"}`).join(`
 `);
-          throw new Error(`Refusing to fork key "${key}": ${sameKey.length} active memor${sameKey.length === 1 ? "y" : "ies"} ` + `already ${sameKey.length === 1 ? "uses" : "use"} it, ` + `but none matches the scope/project/session this save targets ` + `(scope=${input.scope ?? "private"}, project=${input.project_id ?? "none"}, session=${input.session_id ?? "none"}).
+          throw new Error(`Refusing to fork key "${key}": ${sameKey.length} active memor${sameKey.length === 1 ? "y" : "ies"} ` + `already ${sameKey.length === 1 ? "uses" : "use"} it, ` + `but none matches the scope/project/session/agent this save targets ` + `(scope=${input.scope ?? "private"}, project=${input.project_id ?? "none"}, session=${input.session_id ?? "none"}, agent=${input.agent_id ?? "none"}).
 ` + `${rows}
-` + `Saving would create a second active row under the same key. Either target the existing row ` + `(match its scope/project/session flags, or use \`mementos update <id>\`), or pass \`--dedupe create\` ` + `to fork deliberately.`);
+` + `Saving would create a second active row under the same key. Either target the existing row ` + `(match its scope/project/session/agent flags, or use \`mementos update <id>\`), or pass \`--dedupe create\` ` + `to fork deliberately.`);
         }
       }
       const memory = forkRequested ? createMemory(input, dedupe) : createMemory(input);
@@ -60437,7 +60489,7 @@ function registerChainCommand(program2) {
         const m = memories[i];
         const order = m.sequence_order !== null && m.sequence_order !== undefined ? m.sequence_order : i + 1;
         const value = m.value.length > 120 ? m.value.slice(0, 120) + "..." : m.value;
-        console.log(`  ${chalk8.cyan(String(order) + ".")} ${chalk8.bold(m.key)}: ${value}`);
+        console.log(`  ${chalk8.cyan(String(order) + ".")} ${chalk8.bold(`${m.key}:`)} ${value}`);
       }
     } catch (e) {
       handleError(e);
@@ -62977,12 +63029,12 @@ function registerGraphCommands(program2) {
       console.log();
       console.log(chalk26.bold(`Entities: ${stats.entities.total}`));
       for (const r of entityRows) {
-        console.log(`  ${colorEntityType(r.type)}: ${r.count}`);
+        console.log(`  ${colorEntityType(r.type, ":")} ${r.count}`);
       }
       console.log();
       console.log(chalk26.bold(`Relations: ${stats.relations.total}`));
       for (const r of relationRows) {
-        console.log(`  ${chalk26.cyan(r.relation_type)}: ${r.count}`);
+        console.log(`  ${chalk26.cyan(`${r.relation_type}:`)} ${r.count}`);
       }
       console.log();
       console.log(chalk26.bold(`Memory links: ${stats.memory_links}`));
@@ -64023,7 +64075,7 @@ function registerToolsCommand(program2) {
         console.log(chalk34.bold(`
   Common errors:`));
         for (const err of stats.common_errors) {
-          console.log(`    ${chalk34.red(err.error_type)}: ${err.count} times`);
+          console.log(`    ${chalk34.red(`${err.error_type}:`)} ${err.count} times`);
         }
       }
       if (lessons.length === 0) {
@@ -65030,10 +65082,13 @@ function resolveStoreBackend() {
   const apiConfig = getApiConfig();
   const storageMode = getStorageMode();
   const sources = getApiModeEnvSources();
+  const configured = getConfiguredApiEnv();
   const backend = apiMode ? "cloud-api" : storageMode === "cloud" ? "cloud-postgres" : "local-sqlite";
   let selectedBy = "default";
   if (apiMode) {
     selectedBy = `${sources.urlKey} + ${sources.keyKey} (presence)`;
+  } else if (backend === "local-sqlite" && configured.dbPathKey) {
+    selectedBy = configured.apiKeyPresent && configured.baseUrl ? `${configured.dbPathKey} (explicit local path, outranks the API selectors)` : `${configured.dbPathKey} (explicit local path)`;
   } else if (backend === "cloud-postgres") {
     const modeKey = [MEMENTOS_STORAGE_ENV.mode, MEMENTOS_STORAGE_FALLBACK_ENV.mode].find((key) => process.env[key]?.trim());
     selectedBy = modeKey ?? sources.databaseUrlKey ?? "storage config file";
@@ -65044,8 +65099,8 @@ function resolveStoreBackend() {
     api_mode: apiMode,
     storage_mode: storageMode,
     db_path: getDbPath(),
-    api_endpoint: apiConfig?.baseUrl ?? null,
-    api_key_present: Boolean(apiConfig?.apiKey),
+    api_endpoint: apiConfig?.baseUrl ?? configured.baseUrl,
+    api_key_present: Boolean(apiConfig?.apiKey) || configured.apiKeyPresent,
     selected_by: selectedBy
   };
 }
@@ -65099,6 +65154,9 @@ function installStorageSubcommands(storage, program2) {
     console.log(`Storage mode: ${report.storage_mode}`);
     if (report.backend === "local-sqlite") {
       console.log(`Database: ${report.db_path}`);
+      if (report.api_key_present && report.api_endpoint) {
+        console.log(`API endpoint (configured, OUTRANKED): ${report.api_endpoint}`);
+      }
     } else {
       console.log(`API endpoint: ${report.api_endpoint ?? "(none)"}`);
       console.log(`API key: ${report.api_key_present ? "configured" : "not configured"}`);
@@ -66947,6 +67005,14 @@ function getPackageVersion2() {
 var program2 = new Command;
 program2.name("mementos").description("Universal memory system for AI agents").version(getPackageVersion2());
 applyGlobalOptions(program2);
+function applyExitCodeContract(command) {
+  command.exitOverride((err) => {
+    process.exit(resolveExitCode(err));
+  });
+  for (const subcommand of command.commands) {
+    applyExitCodeContract(subcommand);
+  }
+}
 var startupWarningShown = false;
 program2.hook("preAction", (_thisCommand, actionCommand) => {
   if (skipsStartupDbAccess(actionCommand))
@@ -66962,4 +67028,5 @@ program2.hook("preAction", (_thisCommand, actionCommand) => {
   } catch {}
 });
 registerAllCommands(program2);
+applyExitCodeContract(program2);
 program2.parse(process.argv);

package/dist/db/api-mode.d.ts

@@ -15,6 +15,23 @@ export declare function getApiModeEnvSources(): {
     keyKey: string | null;
     databaseUrlKey: string | null;
 };
+/**
+ * What the environment CONFIGURES, regardless of which store finally wins.
+ *
+ * Distinct from {@link getApiConfig}, which answers "may I build a cloud
+ * request?" and returns null once an explicit DB_PATH outranks the credentials
+ * (precedence 1). An operator report needs both halves separately: conflating
+ * them prints "no API key configured" at someone whose key is configured and
+ * merely outranked, which points them at a credential problem they do not have.
+ *
+ * Never returns a credential value — the endpoint is not secret, the key is
+ * reported only as a boolean.
+ */
+export declare function getConfiguredApiEnv(): {
+    baseUrl: string | null;
+    apiKeyPresent: boolean;
+    dbPathKey: string | null;
+};
 /**
  * Escape hatch for a test that genuinely must reach a non-loopback endpoint.
  * Opt-in by design: the default has to be safe, because the failure it prevents
@@ -38,13 +55,26 @@ export declare class MementosStoreConfigError extends Error {
  * dataset with no error and no flag. From the caller's side that is
  * indistinguishable from a store that is working.
  *
+ * THIS FUNCTION ONLY ASSERTS. It returns `void`, so it cannot select anything —
+ * the precedence table below describes the RESOLVER, which is `getApiConfig()`
+ * immediately after it, and each early `return` here only suppresses the
+ * ambiguity error for a case that is already unambiguous. Steps 1 and 2 are
+ * therefore implemented in `getApiConfig()` and `isApiMode()` respectively, and
+ * the table is documented here because this is where the error text lives.
+ *
+ * Keeping the table honest about that is not cosmetic. Until 2026-08-03 step 1
+ * was implemented NOWHERE: the `return` below reads as a selection, and an
+ * operator who read it concluded that a scratch DB_PATH made them safe while a
+ * fully-configured environment still routed every read and write to the shared
+ * production store.
+ *
  * Precedence, highest first:
  *  1. An explicit SQLite path (`HASNA_MEMENTOS_DB_PATH` / `MEMENTOS_DB_PATH`) is
  *     the narrowest, most specific signal and selects LOCAL, so local dev,
  *     tooling and import/export keep working when a stray credential is exported
- *     globally.
- *  2. A client DSN present disables API mode. Unchanged here, and tracked
- *     separately — a DSN on a client is forbidden and handled in database.ts.
+ *     globally. ENFORCED in `getApiConfig()`, which returns null for it.
+ *  2. A client DSN present disables API mode. ENFORCED in `isApiMode()`. A DSN
+ *     on a client is forbidden and is tracked separately in database.ts.
  *  3. Both API URL and API key present -> API mode.
  *  4. Exactly ONE of them present -> ERROR naming the missing variable.
  *  5. Neither present -> LOCAL. The documented single-operator default.

package/dist/db/api-mode.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-mode.d.ts","sourceRoot":"","sources":["../../src/db/api-mode.ts"],"names":[],"mappings":"AA0CA,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AASD,eAAO,MAAM,gBAAgB,yDAA0D,CAAC;AACxF,eAAO,MAAM,gBAAgB,yDAA0D,CAAC;AACxF,eAAO,MAAM,qBAAqB,mEAAoE,CAAC;AAsBvG;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI;IAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAMtH;AAED;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,uCAAuC,CAAC;AAyDlF,6EAA6E;AAC7E,kEAAkE;AAClE,eAAO,MAAM,gBAAgB,yDAA0D,CAAC;AAExF,2EAA2E;AAC3E,qBAAa,wBAAyB,SAAQ,KAAK;IACjD,QAAQ,CAAC,IAAI,2BAA2B;gBAC5B,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,yBAAyB,IAAI,IAAI,CAuBhD;AAED,wBAAgB,YAAY,IAAI,SAAS,GAAG,IAAI,CAM/C;AAED;;;;GAIG;AACH,wBAAgB,SAAS,IAAI,OAAO,CAGnC;AAED,qBAAa,eAAgB,SAAQ,KAAK;aAGtB,MAAM,EAAE,MAAM;aACd,IAAI,EAAE,MAAM;gBAF5B,OAAO,EAAE,MAAM,EACC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM;CAK/B;AA0GD,MAAM,WAAW,cAAc;IAC7B;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,CAAC,GAAG,OAAO,EACjC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,cAAc,GACvB;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,CAAC,CAAA;CAAE,CAiB7B;AAED,8EAA8E;AAC9E,wBAAgB,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAe/D"}
+{"version":3,"file":"api-mode.d.ts","sourceRoot":"","sources":["../../src/db/api-mode.ts"],"names":[],"mappings":"AA0CA,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AASD,eAAO,MAAM,gBAAgB,yDAA0D,CAAC;AACxF,eAAO,MAAM,gBAAgB,yDAA0D,CAAC;AACxF,eAAO,MAAM,qBAAqB,mEAAoE,CAAC;AAsBvG;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI;IAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAMtH;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,IAAI;IACrC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,aAAa,EAAE,OAAO,CAAC;IACvB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B,CAOA;AAED;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,uCAAuC,CAAC;AAyDlF,6EAA6E;AAC7E,kEAAkE;AAClE,eAAO,MAAM,gBAAgB,yDAA0D,CAAC;AAExF,2EAA2E;AAC3E,qBAAa,wBAAyB,SAAQ,KAAK;IACjD,QAAQ,CAAC,IAAI,2BAA2B;gBAC5B,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,yBAAyB,IAAI,IAAI,CA0BhD;AAED,wBAAgB,YAAY,IAAI,SAAS,GAAG,IAAI,CAyB/C;AAED;;;;GAIG;AACH,wBAAgB,SAAS,IAAI,OAAO,CAGnC;AAED,qBAAa,eAAgB,SAAQ,KAAK;aAGtB,MAAM,EAAE,MAAM;aACd,IAAI,EAAE,MAAM;gBAF5B,OAAO,EAAE,MAAM,EACC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM;CAK/B;AA0GD,MAAM,WAAW,cAAc;IAC7B;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,CAAC,GAAG,OAAO,EACjC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,cAAc,GACvB;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,CAAC,CAAA;CAAE,CAiB7B;AAED,8EAA8E;AAC9E,wBAAgB,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAe/D"}

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

@@ -1 +1 @@
-{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../src/db/database.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,IAAI,QAAQ,EAK1B,MAAM,eAAe,CAAC;AAkDvB,wBAAgB,SAAS,IAAI,MAAM,CAoBlC;AAoDD,wBAAgB,WAAW,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,QAAQ,CA4DrD;AAgDD,wBAAgB,aAAa,IAAI,IAAI,CASpC;AAED,wBAAgB,aAAa,IAAI,IAAI,CAGpC;AAED,wBAAgB,GAAG,IAAI,MAAM,CAE5B;AAED,wBAAgB,IAAI,IAAI,MAAM,CAE7B;AAED,wBAAgB,SAAS,IAAI,MAAM,CAElC;AASD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,QAAQ,EACZ,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,IAAI,CAuBf"}
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../src/db/database.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,IAAI,QAAQ,EAK1B,MAAM,eAAe,CAAC;AAkDvB,wBAAgB,SAAS,IAAI,MAAM,CAwBlC;AAoDD,wBAAgB,WAAW,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,QAAQ,CAoGrD;AAgDD,wBAAgB,aAAa,IAAI,IAAI,CASpC;AAED,wBAAgB,aAAa,IAAI,IAAI,CAGpC;AAED,wBAAgB,GAAG,IAAI,MAAM,CAE5B;AAED,wBAAgB,IAAI,IAAI,MAAM,CAE7B;AAED,wBAAgB,SAAS,IAAI,MAAM,CAElC;AASD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,QAAQ,EACZ,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,IAAI,CAuBf"}

package/dist/db/store-backend.d.ts

@@ -16,9 +16,18 @@ export interface StoreBackendReport {
     storage_mode: string;
     /** The SQLite path that WOULD be used. Meaningful only for `local-sqlite`. */
     db_path: string;
-    /** Cloud endpoint origin + prefix. Not a secret; the key is never included. */
+    /**
+     * Cloud endpoint origin + prefix as CONFIGURED, not necessarily as used: it
+     * is still reported when an explicit DB_PATH has outranked it, because the
+     * operator needs to see what was set as well as what won. Read `backend` /
+     * `api_mode` for what is actually in force, and `selected_by` for why.
+     * Not a secret; the key is never included.
+     */
     api_endpoint: string | null;
-    /** Whether an API key is configured. The value is never read or reported. */
+    /**
+     * Whether an API key is CONFIGURED in the environment — again independent of
+     * whether it won. The value is never read or reported.
+     */
     api_key_present: boolean;
     /** Env key NAMES that produced this backend, or `"default"`. Names only. */
     selected_by: string;

package/dist/db/store-backend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store-backend.d.ts","sourceRoot":"","sources":["../../src/db/store-backend.ts"],"names":[],"mappings":"AA4BA;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,cAAc,GAAG,WAAW,GAAG,gBAAgB,CAAC;AAE3E,MAAM,WAAW,kBAAkB;IACjC,6DAA6D;IAC7D,MAAM,EAAE,2BAA2B,CAAC;IACpC,OAAO,EAAE,YAAY,CAAC;IACtB,iFAAiF;IACjF,QAAQ,EAAE,OAAO,CAAC;IAClB,6EAA6E;IAC7E,YAAY,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,6EAA6E;IAC7E,eAAe,EAAE,OAAO,CAAC;IACzB,4EAA4E;IAC5E,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,IAAI,kBAAkB,CAkCxD"}
+{"version":3,"file":"store-backend.d.ts","sourceRoot":"","sources":["../../src/db/store-backend.ts"],"names":[],"mappings":"AA4BA;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,cAAc,GAAG,WAAW,GAAG,gBAAgB,CAAC;AAE3E,MAAM,WAAW,kBAAkB;IACjC,6DAA6D;IAC7D,MAAM,EAAE,2BAA2B,CAAC;IACpC,OAAO,EAAE,YAAY,CAAC;IACtB,iFAAiF;IACjF,QAAQ,EAAE,OAAO,CAAC;IAClB,6EAA6E;IAC7E,YAAY,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B;;;OAGG;IACH,eAAe,EAAE,OAAO,CAAC;IACzB,4EAA4E;IAC5E,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,IAAI,kBAAkB,CAoDxD"}

package/dist/index.js

@@ -1031,6 +1031,8 @@ function assertUnambiguousStoreEnv() {
 }
 function getApiConfig() {
   assertUnambiguousStoreEnv();
+  if (firstEnvKey(DB_PATH_ENV_KEYS))
+    return null;
   const rawBase = firstEnv(API_URL_ENV_KEYS);
   const apiKey = firstEnv(API_KEY_ENV_KEYS);
   if (!rawBase || !apiKey)
@@ -2155,9 +2157,10 @@ function migrateGlobalDir() {
   }
 }
 function getDbPath() {
-  const envPath = process.env["HASNA_MEMENTOS_DB_PATH"] ?? process.env["MEMENTOS_DB_PATH"];
-  if (envPath) {
-    return envPath;
+  for (const key of DB_PATH_ENV_KEYS) {
+    const envPath = process.env[key]?.trim();
+    if (envPath)
+      return envPath;
   }
   const cwd = process.cwd();
   const nearest = findNearestMementosDb(cwd);
@@ -2201,6 +2204,12 @@ function getDatabase(dbPath) {
     if (getStorageMode() === "cloud") {
       return getCloudDatabase();
     }
+    if (process.env["NODE_ENV"] === "test") {
+      const hasExplicitDbPath = DB_PATH_ENV_KEYS.some((key) => process.env[key]?.trim());
+      if (!hasExplicitDbPath) {
+        throw new Error("REFUSING-UNPINNED-TEST-OPEN: a test process tried to open the default local " + `SQLite store (${getDbPath()}) with no explicit dbPath argument and no ` + `${DB_PATH_ENV_KEYS.join("/")} set. Pass an explicit dbPath (e.g. ":memory:" ` + "or a scratch file), or set one of those env keys to a scratch path, before " + "calling getDatabase(). This guard exists because an unpinned test process " + "would otherwise silently read and write the real, shared, on-disk memory " + "store (todos 57b8b8c5).");
+      }
+    }
   }
   const path = dbPath || getDbPath();
   if (_db) {

package/dist/mcp/index.js

@@ -1094,6 +1094,8 @@ function assertUnambiguousStoreEnv() {
 }
 function getApiConfig() {
   assertUnambiguousStoreEnv();
+  if (firstEnvKey(DB_PATH_ENV_KEYS))
+    return null;
   const rawBase = firstEnv(API_URL_ENV_KEYS);
   const apiKey = firstEnv(API_KEY_ENV_KEYS);
   if (!rawBase || !apiKey)
@@ -2218,9 +2220,10 @@ function migrateGlobalDir() {
   }
 }
 function getDbPath() {
-  const envPath = process.env["HASNA_MEMENTOS_DB_PATH"] ?? process.env["MEMENTOS_DB_PATH"];
-  if (envPath) {
-    return envPath;
+  for (const key of DB_PATH_ENV_KEYS) {
+    const envPath = process.env[key]?.trim();
+    if (envPath)
+      return envPath;
   }
   const cwd = process.cwd();
   const nearest = findNearestMementosDb(cwd);
@@ -2264,6 +2267,12 @@ function getDatabase(dbPath) {
     if (getStorageMode() === "cloud") {
       return getCloudDatabase();
     }
+    if (process.env["NODE_ENV"] === "test") {
+      const hasExplicitDbPath = DB_PATH_ENV_KEYS.some((key) => process.env[key]?.trim());
+      if (!hasExplicitDbPath) {
+        throw new Error("REFUSING-UNPINNED-TEST-OPEN: a test process tried to open the default local " + `SQLite store (${getDbPath()}) with no explicit dbPath argument and no ` + `${DB_PATH_ENV_KEYS.join("/")} set. Pass an explicit dbPath (e.g. ":memory:" ` + "or a scratch file), or set one of those env keys to a scratch path, before " + "calling getDatabase(). This guard exists because an unpinned test process " + "would otherwise silently read and write the real, shared, on-disk memory " + "store (todos 57b8b8c5).");
+      }
+    }
   }
   const path = dbPath || getDbPath();
   if (_db) {

package/dist/server/index.js

@@ -655,6 +655,8 @@ function assertUnambiguousStoreEnv() {
 }
 function getApiConfig() {
   assertUnambiguousStoreEnv();
+  if (firstEnvKey(DB_PATH_ENV_KEYS))
+    return null;
   const rawBase = firstEnv(API_URL_ENV_KEYS);
   const apiKey = firstEnv(API_KEY_ENV_KEYS);
   if (!rawBase || !apiKey)
@@ -1779,9 +1781,10 @@ function migrateGlobalDir() {
   }
 }
 function getDbPath2() {
-  const envPath = process.env["HASNA_MEMENTOS_DB_PATH"] ?? process.env["MEMENTOS_DB_PATH"];
-  if (envPath) {
-    return envPath;
+  for (const key of DB_PATH_ENV_KEYS) {
+    const envPath = process.env[key]?.trim();
+    if (envPath)
+      return envPath;
   }
   const cwd = process.cwd();
   const nearest = findNearestMementosDb(cwd);
@@ -1825,6 +1828,12 @@ function getDatabase(dbPath) {
     if (getStorageMode() === "cloud") {
       return getCloudDatabase();
     }
+    if (process.env["NODE_ENV"] === "test") {
+      const hasExplicitDbPath = DB_PATH_ENV_KEYS.some((key) => process.env[key]?.trim());
+      if (!hasExplicitDbPath) {
+        throw new Error("REFUSING-UNPINNED-TEST-OPEN: a test process tried to open the default local " + `SQLite store (${getDbPath2()}) with no explicit dbPath argument and no ` + `${DB_PATH_ENV_KEYS.join("/")} set. Pass an explicit dbPath (e.g. ":memory:" ` + "or a scratch file), or set one of those env keys to a scratch path, before " + "calling getDatabase(). This guard exists because an unpinned test process " + "would otherwise silently read and write the real, shared, on-disk memory " + "store (todos 57b8b8c5).");
+      }
+    }
   }
   const path = dbPath || getDbPath2();
   if (_db) {

package/dist/test-support/store-isolation.d.ts

@@ -31,8 +31,6 @@ export interface IsolatedStoreEnvOptions {
  */
 export declare function isolatedStoreEnv(dbPath: string, options?: IsolatedStoreEnvOptions): Record<string, string>;
 export interface StubApiEnvOptions {
-    /** Pin the (non-authoritative) local SQLite path too, for belt and braces. */
-    dbPath?: string;
     /** Stub bearer token. Never a real credential — the stub does not check it. */
     apiKey?: string;
 }
@@ -48,6 +46,28 @@ export interface StubApiEnvOptions {
  * @param baseUrl the stub's origin, e.g. `http://127.0.0.1:<port>/<mode>`
  */
 export declare function stubApiEnv(baseUrl: string, options?: StubApiEnvOptions): Record<string, string>;
+/**
+ * Build a child env that DOES resolve to the cloud API — the negative case the
+ * isolation guards are proved against.
+ *
+ * This exists because of the 2026-08-03 precedence-1 fix. Before it, a cloud
+ * case could be built by taking any env and adding an API url+key, and several
+ * tests did exactly that on top of {@link isolatedStoreEnv}. An explicit
+ * `MEMENTOS_DB_PATH` now DEFEATS the API selectors (see getApiConfig in
+ * src/db/api-mode.ts), so that recipe silently produces a LOCAL backend — which
+ * would leave the isolation guards' positive controls unable to observe the bad
+ * state they exist to detect, and `assertLocalStoreBackend`'s own self-test
+ * unable to fail. Both would still be green.
+ *
+ * So the DB_PATH keys are removed here explicitly, and that removal is the
+ * load-bearing line rather than an afterthought: it is the only way to reach the
+ * cloud backend now. They are NOT in STORE_SELECTOR_ENV_KEYS because that set
+ * means "moves the store OFF local SQLite", and DB_PATH does the opposite.
+ *
+ * @param baseUrl  point this at a closed loopback port, never a real endpoint
+ * @param apiKey   never a real credential
+ */
+export declare function cloudSelectingEnv(baseUrl: string, apiKey?: string): Record<string, string>;
 /** LLM provider keys most harnesses blank so no test can make a billed call. */
 export declare const LLM_PROVIDER_ENV_KEYS: readonly ["ANTHROPIC_API_KEY", "OPENAI_API_KEY", "CEREBRAS_API_KEY", "XAI_API_KEY"];
 /** `{ ANTHROPIC_API_KEY: "", ... }` — pass as `extra` to blank LLM providers. */

package/dist/test-support/store-isolation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store-isolation.d.ts","sourceRoot":"","sources":["../../src/test-support/store-isolation.ts"],"names":[],"mappings":"AAmDA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAGjE;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,EAAE,SAAS,MAAM,EAWpD,CAAC;AAEF,qEAAqE;AACrE,eAAO,MAAM,gBAAgB,yDAA0D,CAAC;AAExF,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,uBAA4B,GACpC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAKxB;AASD,MAAM,WAAW,iBAAiB;IAChC,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAQnG;AAED,gFAAgF;AAChF,eAAO,MAAM,qBAAqB,qFAKxB,CAAC;AAEX,iFAAiF;AACjF,wBAAgB,mBAAmB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAE5D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC3B,cAAc,CAAC,EAAE,MAAM,GACtB,OAAO,CAAC,kBAAkB,CAAC,CAsD7B;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,SAA0B,GAAG,IAAI,CAQ9F"}
+{"version":3,"file":"store-isolation.d.ts","sourceRoot":"","sources":["../../src/test-support/store-isolation.ts"],"names":[],"mappings":"AAmDA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAGjE;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,EAAE,SAAS,MAAM,EAWpD,CAAC;AAEF,qEAAqE;AACrE,eAAO,MAAM,gBAAgB,yDAA0D,CAAC;AAExF,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,uBAA4B,GACpC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAKxB;AASD,MAAM,WAAW,iBAAiB;IAChC,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,CAAC;CAUjB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAQnG;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,MAAM,SAAmB,GACxB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMxB;AAED,gFAAgF;AAChF,eAAO,MAAM,qBAAqB,qFAKxB,CAAC;AAEX,iFAAiF;AACjF,wBAAgB,mBAAmB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAE5D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC3B,cAAc,CAAC,EAAE,MAAM,GACtB,OAAO,CAAC,kBAAkB,CAAC,CAsD7B;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,SAA0B,GAAG,IAAI,CAQ9F"}

package/dist/test-support/strip-ansi.d.ts

@@ -0,0 +1,3 @@
+/** Remove ANSI/VT100 SGR escape sequences from CLI output before asserting on content. */
+export declare function stripAnsi(input: string): string;
+//# sourceMappingURL=strip-ansi.d.ts.map

package/dist/test-support/strip-ansi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strip-ansi.d.ts","sourceRoot":"","sources":["../../src/test-support/strip-ansi.ts"],"names":[],"mappings":"AAyBA,0FAA0F;AAC1F,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/C"}

package/package.json

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