enigma-memory 0.1.6 → 0.1.8

package/README.md

@@ -21,6 +21,29 @@ Use Enigma as a one-time AI Memory Passport setup: install the package, create t
 ```sh
 npm install -g enigma-memory
 enigma setup --overwrite
+```
+
+`enigma setup --overwrite` is the safe default. It writes local Enigma artifacts under the workspace `.enigma` path and emits deterministic, public-safe JSON without printing raw memory plaintext. It does not write Claude, Cursor, Kimi, or other third-party app configs.
+
+To let setup detect installed or already-configured clients and show the connector plan without mutating client configs:
+
+```sh
+enigma setup --client auto --overwrite
+```
+
+`--client auto` selects clients found by connector detection and falls back to the default setup client list when none are present. The setup output lists which clients were selected, which were skipped, and why.
+
+When you are ready to explicitly write connector entries for installed/config-present clients only:
+
+```sh
+enigma setup --connect-installed --overwrite
+```
+
+`--connect-installed` implies auto client selection and is an explicit client-config write flag. It skips missing client configs instead of creating every default client config. Only explicit write flags mutate client configs. Existing explicit connector writes remain available through `enigma connect <client>` without `--dry-run`, and existing `enigma setup --write-connectors` behavior for explicit/default setup clients is unchanged; keep `--dry-run` while reviewing a single planned MCP entry.
+
+After setup, use the same local vault from the CLI or connected clients:
+
+```sh
 enigma remember --text-file ./memory.txt
 enigma search --query "..."
 enigma context --query "..." --optimize
@@ -28,9 +51,7 @@ enigma verify --export ./.enigma/export.json
 enigma connect claude-desktop --dry-run
 ```
 
-`enigma setup --overwrite` writes local Enigma artifacts under the workspace `.enigma` path and emits deterministic, public-safe JSON. It does not write Claude, Cursor, Kimi, or other third-party app configs. Client config writes happen only when you explicitly run `enigma connect <client>` without `--dry-run`; keep `--dry-run` while reviewing the planned MCP entry.
-
-The local Enigma vault remains canonical. Provider-native memory should be treated as a convenience cache only. Enigma receipts prove Enigma-controlled vault state, receipts, checkpoints, and declared boundary operations; they do not prove provider deletion, provider model forgetting, provider-native memory removal, hosted availability, ROI/savings, or compliance certification.
+The local Enigma vault remains canonical. Provider-native memory is non-canonical and should be treated as a convenience cache only. Enigma receipts prove Enigma-controlled vault state, receipts, checkpoints, and declared boundary operations; they do not prove provider deletion, provider model forgetting, provider-native memory removal, hosted availability, ROI/savings, or compliance certification.
 
 One-off execution without a global install:
 
@@ -152,7 +173,9 @@ enigma connect kimi-code --dry-run
 enigma connect generic-mcp --dry-run
 ```
 
-Remove `--dry-run` only after you are ready for Enigma to merge the `mcpServers.enigma` entry into that client config. The setup command itself never writes third-party app configs.
+For the one-time setup flow, `enigma setup --client auto --overwrite` reports the installed/config-present clients that connector detection selected and the clients it skipped with reasons. It remains read-only for client configs. `enigma setup --connect-installed --overwrite` is the explicit setup-time write path for installed/config-present clients only; missing configs are skipped rather than created.
+
+Remove `--dry-run` from `enigma connect <client>` only after you are ready for Enigma to merge the `mcpServers.enigma` entry into that specific client config. The safe default setup command never writes third-party app configs.
 
 Manual MCP entry for Claude Desktop, Cursor, Kimi Code, or any generic MCP client:
 

package/apps/cli/bin/enigma.mjs

@@ -759,17 +759,80 @@ async function initCommand(flags, io) {
 
 function setupClientIds(flags) {
   const raw = getFlag(flags, ['client']);
-  if (raw === undefined) return [...DEFAULT_SETUP_CLIENTS];
+  if (raw === undefined) return { mode: 'default', auto: false, clients: [...DEFAULT_SETUP_CLIENTS], explicit_clients: [] };
   const values = Array.isArray(raw) ? raw : [raw];
   const clients = [];
+  let auto = false;
   for (const value of values) {
     if (value === true || value === '') throw new Error('Missing required --client.');
     for (const client of String(value).split(',').map((item) => item.trim()).filter(Boolean)) {
+      if (client === 'auto') {
+        auto = true;
+        continue;
+      }
       getClientProfile(client);
       if (!clients.includes(client)) clients.push(client);
     }
   }
-  return clients.length > 0 ? clients : [...DEFAULT_SETUP_CLIENTS];
+  if (auto) return { mode: 'auto', auto: true, clients, explicit_clients: clients };
+  return { mode: clients.length > 0 ? 'explicit' : 'default', auto: false, clients: clients.length > 0 ? clients : [...DEFAULT_SETUP_CLIENTS], explicit_clients: clients };
+}
+
+function setupDetectedClientReason(client) {
+  if (client.installed === true && client.recommended_action === 'already_configured') return 'already_configured';
+  if (client.installed === true) return 'installed_needs_repair';
+  return 'client_config_present';
+}
+
+function setupSkippedClientReason(client) {
+  if (client.parse_error === true) return 'config_json_invalid';
+  if (client.config_path_exists === false || client.exists === false) return 'client_config_missing';
+  if (client.ok === false) return 'config_unreadable';
+  return 'not_selected';
+}
+
+function publicSetupClientSelectionEntry(client, reason) {
+  return {
+    client_id: client.client_id,
+    display_name: client.display_name,
+    reason,
+    action: client.recommended_action ?? client.action ?? null,
+    installed: client.installed === true,
+    config_path_exists: client.config_path_exists === true || client.exists === true,
+  };
+}
+
+async function setupAutoClientSelection(flags, artifacts, fallbackClients, mode) {
+  const doctor = await doctorConnectors({
+    ...connectorOptions(flags),
+    bundlePath: artifacts.bundlePath,
+    redactPaths: true,
+  });
+  const detected = doctor.clients.filter((client) => (client.config_path_exists === true || client.exists === true) && client.parse_error !== true);
+  const fallbackUsed = detected.length === 0;
+  const selectedClients = fallbackUsed ? [...fallbackClients] : detected.map((client) => client.client_id);
+  const selectedSet = new Set(selectedClients);
+  const detectedSet = new Set(detected.map((client) => client.client_id));
+  const selected = fallbackUsed
+    ? selectedClients.map((clientId) => {
+      const client = doctor.clients.find((entry) => entry.client_id === clientId) ?? { client_id: clientId, display_name: getClientProfile(clientId).display_name };
+      return publicSetupClientSelectionEntry(client, 'default_fallback_no_client_configs_detected');
+    })
+    : detected.map((client) => publicSetupClientSelectionEntry(client, setupDetectedClientReason(client)));
+  const skipped = doctor.clients
+    .filter((client) => !selectedSet.has(client.client_id))
+    .map((client) => publicSetupClientSelectionEntry(client, fallbackUsed && !detectedSet.has(client.client_id) ? 'not_in_default_fallback' : setupSkippedClientReason(client)));
+  const connectableClientIds = new Set(detected.map((client) => client.client_id));
+  return {
+    mode,
+    auto: true,
+    fallback_used: fallbackUsed,
+    clients: selectedClients,
+    selected,
+    skipped,
+    connectable_client_ids: connectableClientIds,
+    detection: doctor,
+  };
 }
 
 function setupMemorySource(flags) {
@@ -915,7 +978,7 @@ function publicConnectPlan(plan, wizard, profile, snippet) {
   };
 }
 
-async function setupConnectorPlans(flags, artifacts, clients, writeConnectors, displays) {
+async function setupConnectorPlans(flags, artifacts, clients, writeConnectors, displays, writeClientIds = null) {
   const publicOptions = {
     ...connectorOptions(flags),
     bundlePath: displays.bundle,
@@ -929,9 +992,10 @@ async function setupConnectorPlans(flags, artifacts, clients, writeConnectors, d
     const profile = getClientProfile(client, publicOptions);
     const snippet = renderMcpConfig(client, publicOptions);
     const wizard = planConnectWizard(client, { platform: profile.platform }).clients[0];
-    const rawPlan = writeConnectors
+    const writeAllowed = writeClientIds === null || writeClientIds.has(client);
+    const rawPlan = writeConnectors && writeAllowed
       ? await connectClient(client, { ...writeOptions, dryRun: false })
-      : { ok: true, changed: true, dryRun: true };
+      : { ok: true, changed: !(writeConnectors && !writeAllowed), dryRun: true };
     const plan = publicConnectPlan(rawPlan, wizard, profile, snippet);
     connectors.push({
       client_id: client,
@@ -940,19 +1004,33 @@ async function setupConnectorPlans(flags, artifacts, clients, writeConnectors, d
       mcp_config_snippet: snippet,
       connect_command: `enigma connect ${client} --bundle ${commandPath(displays.bundle)}`,
       connect_plan: plan,
+      write_selected: writeAllowed,
+      write_skipped_reason: writeConnectors && !writeAllowed ? 'client_config_missing' : null,
       wizard,
     });
   }
   return connectors;
 }
 
+function publicSetupClientSelection(selection) {
+  return {
+    mode: selection.mode,
+    auto: selection.auto === true,
+    fallback_used: selection.fallback_used === true,
+    selected: selection.selected,
+    skipped: selection.skipped,
+  };
+}
+
 export async function setupCommand(flags, io) {
   const bundleInput = pathFlag(flags, ['bundle', 'file'], DEFAULT_BUNDLE);
   const outDirInput = pathFlag(flags, ['out-dir', 'outDir'], dirname(bundleInput));
-  const clients = setupClientIds(flags);
+  const requestedSelection = setupClientIds(flags);
   const overwrite = booleanFlag(flags, ['overwrite'], false);
   const dryRun = booleanFlag(flags, ['dry-run', 'dryRun'], false);
-  const writeConnectors = booleanFlag(flags, ['write-connectors', 'writeConnectors'], false) && !dryRun;
+  const writeConnectorsFlag = booleanFlag(flags, ['write-connectors', 'writeConnectors'], false);
+  const connectInstalled = booleanFlag(flags, ['connect-installed', 'connectInstalled'], false);
+  const connectorWritesRequested = (writeConnectorsFlag || connectInstalled) && !dryRun;
   const displays = setupPublicDisplays(bundleInput, outDirInput);
   const rawDisplays = setupRawDisplays(bundleInput, outDirInput);
   let artifacts;
@@ -961,9 +1039,24 @@ export async function setupCommand(flags, io) {
   } catch (error) {
     throw publicSetupError(error, rawDisplays, displays);
   }
-  const connectors = await setupConnectorPlans(flags, artifacts, clients, writeConnectors, displays);
+  const selection = connectInstalled || requestedSelection.auto
+    ? await setupAutoClientSelection(flags, artifacts, DEFAULT_SETUP_CLIENTS, connectInstalled ? 'connect_installed' : 'auto')
+    : {
+      ...requestedSelection,
+      fallback_used: false,
+      selected: requestedSelection.clients.map((clientId) => {
+        const profile = getClientProfile(clientId);
+        return publicSetupClientSelectionEntry({ client_id: clientId, display_name: profile.display_name }, requestedSelection.mode === 'default' ? 'default_setup_client' : 'explicit_client');
+      }),
+      skipped: [],
+      connectable_client_ids: null,
+    };
+  const clients = selection.clients;
+  const writeClientIds = connectInstalled ? selection.connectable_client_ids : null;
+  const connectors = await setupConnectorPlans(flags, artifacts, clients, connectorWritesRequested, displays, writeClientIds);
   const doctor = await setupDoctorChecks(flags, artifacts, clients, displays);
   const ok = artifacts.verifyReport.ok === true;
+  const anyConnectorWritePerformed = connectors.some((connector) => connector.connect_plan.writes_performed === true);
 
   print({
     ok,
@@ -971,7 +1064,10 @@ export async function setupCommand(flags, io) {
     command: 'enigma setup',
     dry_run: dryRun,
     artifacts_written: !dryRun,
-    client_configs_written: writeConnectors,
+    client_configs_written: writeConnectorsFlag && !dryRun ? true : anyConnectorWritePerformed,
+    client_config_write_requested: connectorWritesRequested,
+    connector_write_mode: connectInstalled ? 'installed_only' : (writeConnectorsFlag ? 'selected_clients' : 'plan_only'),
+    connect_installed: connectInstalled,
     bundle: displays.bundle,
     context_pack: displays.context_pack,
     export: displays.export,
@@ -985,10 +1081,19 @@ export async function setupCommand(flags, io) {
     provider_credentials_required: false,
     provider_native_memory_canonical: false,
     selected_clients: clients,
+    skipped_clients: selection.skipped,
+    client_selection: publicSetupClientSelection(selection),
+    connector_write_skips: connectors
+      .filter((connector) => connector.write_skipped_reason)
+      .map((connector) => ({
+        client_id: connector.client_id,
+        display_name: connector.display_name,
+        reason: connector.write_skipped_reason,
+      })),
     connectors,
     mcp_config_snippets: Object.fromEntries(connectors.map((connector) => [connector.client_id, connector.mcp_config_snippet])),
     connect_plans: Object.fromEntries(connectors.map((connector) => [connector.client_id, connector.connect_plan])),
-    next_commands: setupNextCommands(displays.bundle, displays.export, clients, writeConnectors),
+    next_commands: setupNextCommands(displays.bundle, displays.export, clients, connectorWritesRequested && (!connectInstalled || anyConnectorWritePerformed)),
     checks: doctor.checks,
     claim_boundaries: { ...SETUP_CLAIM_BOUNDARIES },
   }, io);
@@ -1902,7 +2007,8 @@ function usage() {
     setup_options: {
       '--bundle <path>': 'Bundle JSON to create. Defaults to .enigma/bundle.json.',
       '--out-dir <path>': 'Directory for context-pack.json, export.json, and verify-report.json. Defaults to the bundle directory.',
-      '--client <id>': `Client to plan; repeat or comma-separate. Defaults to ${DEFAULT_SETUP_CLIENTS.join(', ')}.`,
+      '--client <id|auto>': `Client to plan; repeat or comma-separate. Use auto to plan installed/config-present clients, falling back to ${DEFAULT_SETUP_CLIENTS.join(', ')}.`,
+      '--connect-installed': 'Auto-select installed/config-present clients and write only those existing client configs; missing client configs are reported and skipped.',
       '--memory-file <path>': 'Read local memory text from a file without echoing plaintext. Alias: --text-file.',
       '--memory-text <text>': 'Inline demo-only memory text. Avoid for private content because argv can be logged.',
       '--overwrite': 'Replace existing local setup artifacts.',

package/apps/relay/src/server.mjs

@@ -1296,13 +1296,34 @@ export async function loadRelayStateFromFile(path, options = {}) {
   }
 }
 
+function retryableRelayRenameError(error) {
+  return error?.code === 'EBUSY' || error?.code === 'EPERM' || error?.code === 'EACCES';
+}
+
+async function delayRelayRenameRetry(ms) {
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function renameRelayStateAtomically(tempPath, filePath) {
+  const delays = [10, 25, 50, 100, 200];
+  for (let attempt = 0; attempt <= delays.length; attempt += 1) {
+    try {
+      await rename(tempPath, filePath);
+      return;
+    } catch (error) {
+      if (attempt === delays.length || !retryableRelayRenameError(error)) throw error;
+      await delayRelayRenameRetry(delays[attempt]);
+    }
+  }
+}
+
 export async function saveRelayStateToFile(state, path) {
   const filePath = assertString(path, 'relay state file path');
   const snapshot = serializeRelayState(state);
   const tempPath = join(dirname(filePath), `.${basename(filePath)}.${randomBytes(6).toString('hex')}.tmp`);
   try {
     await writeFile(tempPath, `${JSON.stringify(snapshot, null, 2)}\n`, 'utf8');
-    await rename(tempPath, filePath);
+    await renameRelayStateAtomically(tempPath, filePath);
   } catch (error) {
     await unlink(tempPath).catch(() => undefined);
     throw error;

package/docs/developer-ecosystem.md

@@ -9,6 +9,27 @@ For most developers, start with the installed CLI before reading the SDK interna
 ```sh
 npm install -g enigma-memory
 enigma setup --overwrite
+```
+
+`enigma setup --overwrite` is the safe default. It writes local Enigma artifacts under the workspace `.enigma` path and emits deterministic, public-safe JSON without printing raw memory plaintext. It does not write third-party app configs.
+
+To let setup auto-detect installed or already-configured clients and report the connector plan without mutating client configs:
+
+```sh
+enigma setup --client auto --overwrite
+```
+
+To explicitly write connector entries for installed/config-present clients only:
+
+```sh
+enigma setup --connect-installed --overwrite
+```
+
+`--client auto` selects clients found by connector detection and falls back to the default setup client list when none are present. The setup output lists selected clients, skipped clients, and skip reasons. `--connect-installed` implies auto selection, writes only for installed/config-present clients, and skips missing configs instead of creating every default client config. Only explicit write flags mutate client configs; `enigma connect <client>` without `--dry-run` remains the single-client write path, and existing `enigma setup --write-connectors` behavior for explicit/default clients is unchanged. Treat provider-native memory as non-canonical cache only; the local Enigma vault is canonical.
+
+After setup, use the same local vault from the CLI or connected clients:
+
+```sh
 enigma remember --text-file ./memory.txt
 enigma search --query "..."
 enigma context --query "..." --optimize
@@ -16,8 +37,6 @@ enigma verify --export ./.enigma/export.json
 enigma connect claude-desktop --dry-run
 ```
 
-`enigma setup --overwrite` writes local Enigma artifacts under the workspace `.enigma` path and emits deterministic, public-safe JSON. It does not write third-party app configs unless you explicitly run `enigma connect <client>` without `--dry-run`. Treat provider-native memory as cache only; the local Enigma vault is canonical.
-
 ## Copyable starting points
 
 - SDK/API guide: [`docs/sdk-api.md`](./sdk-api.md)
@@ -41,7 +60,7 @@ The example app prints ids, counts, roots, and verification status only. It does
 
 ## CLI and CI loop
 
-The CI example installs Node 24, installs the published `enigma-memory@0.1.6` package, runs:
+The CI example installs Node 24, installs the published `enigma-memory@0.1.8` package, runs:
 
 ```sh
 npx --yes --package enigma-memory enigma setup --overwrite
@@ -65,7 +84,7 @@ Use the workflow as a template in a consumer repository. It is intentionally lim
 
 ## MCP client loop
 
-The same installed package can be used by Claude Desktop, Cursor, Kimi Code, or any generic MCP client. Copy one snippet, replace the bundle path with the local path from your setup output, and restart the client.
+The same installed package can be used by Claude Desktop, Cursor, Kimi Code, or any generic MCP client. The smooth setup path is `enigma setup --client auto --overwrite` to plan detected clients, then `enigma setup --connect-installed --overwrite` only when you explicitly want setup to write installed/config-present client configs. Manual snippets remain useful when a client needs a copied entry; replace the bundle path with the local path from your setup output, and restart the client.
 
 Claude Desktop:
 

package/docs/sdk-api.md

@@ -1,6 +1,6 @@
 # SDK and API guide
 
-This guide covers the public package imports for `enigma-memory@0.1.6`. The SDK runs locally by default: vaults, passports, context packs, receipts, relay/gateway demo state, storage contracts, metering artifacts, and settlement artifacts are package-level developer surfaces. They are not evidence of hosted Enigma cloud, provider-side deletion, provider model forgetting, token ROI, invoice savings, compliance certification, or benchmark leadership.
+This guide covers the public package imports for `enigma-memory@0.1.8`. The SDK runs locally by default: vaults, passports, context packs, receipts, relay/gateway demo state, storage contracts, metering artifacts, and settlement artifacts are package-level developer surfaces. They are not evidence of hosted Enigma cloud, provider-side deletion, provider model forgetting, token ROI, invoice savings, compliance certification, or benchmark leadership.
 
 ## Install and import style
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "enigma-memory",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "type": "module",
   "description": "Provider-agnostic AI memory passport and offline-verifiable proof layer.",
   "license": "Apache-2.0",

package/packages/mcp-server/src/index.js

@@ -17,7 +17,7 @@ import {
 const DEFAULT_BUNDLE = '.enigma/bundle.json';
 const JSONRPC_VERSION = '2.0';
 const MCP_PROTOCOL_VERSION = '2024-11-05';
-const SERVER_INFO = Object.freeze({ name: 'enigma-mcp-server', version: '0.1.6' });
+const SERVER_INFO = Object.freeze({ name: 'enigma-mcp-server', version: '0.1.8' });
 const JSON_RPC_ID_PATTERN = /^[A-Za-z0-9._:-]{1,128}$/;
 const JSON_RPC_ERROR = Object.freeze({
   INVALID_REQUEST: -32600,

package/scripts/build-installer-assets.mjs

@@ -6,7 +6,7 @@ import { fileURLToPath } from 'node:url';
 
 export const INSTALLER_ASSET_SCHEMA = 'enigma.installer_assets.v1';
 export const INSTALLER_ASSET_PACKAGE = 'enigma-memory';
-export const INSTALLER_ASSET_VERSION = '0.1.6';
+export const INSTALLER_ASSET_VERSION = '0.1.8';
 export const INSTALLER_ASSET_GENERATED_AT = '1970-01-01T00:00:00.000Z';
 
 const SCRIPT_PATH = fileURLToPath(import.meta.url);

package/scripts/run-standard-memory-benchmarks.mjs

@@ -995,7 +995,7 @@ function buildSuiteReport(datasetRows, topK, options) {
     generated_at: options.generated_at ?? new Date().toISOString(),
     package: {
       name: 'enigma-memory',
-      version: '0.1.6',
+      version: '0.1.8',
     },
     public_safe: true,
     top_k: topK,