@lotargo/memory_plugin 1.4.601 → 1.4.621

package/README.md

@@ -139,7 +139,39 @@ The plugin has been verified inside the **Google Jules** cloud workspace environ
   npm install -g @lotargo/memory_plugin && memory_plugin setup
   ```
 - **Verification**: All current tools and capabilities have been verified inside the Google Jules cloud workspace. Google Jules automatically discovers the registered MCP server upon workspace initialization and seamlessly interacts with the full set of memory & RAG tools — `remember`, `recall`, `forget`, `update_fact`, `memory_info`, `link_knowledge`, `ingest_document`, `query_knowledge_base`, and `manage_knowledge_base` — including project-scoped memory, knowledge linking, and snapshot export/import.
-- **Current Limitation**: All memory stores and vector indexes operate locally within the workspace environment. Cross-session cloud synchronization across different Jules runs is planned for upcoming releases.
+- **Current Limitation**: All memory stores and vector indexes operate locally within the workspace environment. For cross-session cloud synchronization (Turso `only-cloud` / `hybrid-sync`) inside headless environments like Jules, authenticate without a browser using the token/env methods below.
+
+### Headless Turso Authentication (Docker, Google Jules, VPS/VDS)
+
+Browser OAuth requires a desktop session, so headless deployments use token- or env-based login. The **Turso account API token is the primary source of truth**: it resolves an org/database and mints a per-database token via the Platform API, exactly like the browser flow, and the resulting session is stored encrypted. In priority order, secrets resolve as **env `TURSO_API_TOKEN` → stored API-token session → env `TURSO_DB_URL`/`TURSO_DB_TOKEN` → stored browser/database session**:
+
+| Method | Command | Notes |
+| :----- | :------ | :---- |
+| Account API token | `memory_plugin login --api-key <TOKEN> [--org <ORG>] [--database <DB>]` | Preferred. Validates the token, resolves org/db, mints and stores a per-database token |
+| Direct endpoint | `memory_plugin login --db-url libsql://<db>-<org>.turso.io --db-token <TOKEN>` | No Platform API calls; org/db derived from the URL |
+| Environment | `memory_plugin login --from-env` | Imports `TURSO_DB_URL`+`TURSO_DB_TOKEN` (preferred) or `TURSO_API_TOKEN` |
+| Remove API key | `memory_plugin logout --api-key` | Removes only the API token; the resolved database session is kept |
+| Status | `memory_plugin auth-status` | Shows source (env / api-key / store), authorized flag, API-key flag, endpoint, org, database and mode |
+
+One-shot headless setup (no browser, no interactive `login`):
+
+```bash
+memory_plugin setup --api-key <TURSO_API_TOKEN> --mode hybrid-sync   # auth + set sync mode in one step
+memory_plugin setup --mode only-cloud                                # mode only, if already authorized
+```
+
+Supported environment variables (usable without any `login` step — `loadSecrets()` picks them up automatically):
+
+- `TURSO_API_TOKEN` — account API token (requires Platform API access). On first use the plugin mints a per-database JWT on the fly without touching the encrypted store; optional `TURSO_ORG`, `TURSO_DATABASE` / `TURSO_DB_NAME`, `TURSO_USERNAME`
+- `TURSO_DB_URL` / `TURSO_URL` + `TURSO_DB_TOKEN` / `TURSO_TOKEN` — direct database credentials
+
+The interactive TUI (`memory_plugin cli` → `[CLOUD] ...`) offers a method chooser: Browser OAuth, account API token, database URL + token, or import from environment — plus `[API KEY] Set / Replace Account API Token` and `[API KEY] Remove Account API Token` menu entries. For example, to run a Google Jules workspace with cloud sync:
+
+```bash
+export TURSO_API_TOKEN="eyJhbGciOi..."
+memory_plugin setup --api-key "$TURSO_API_TOKEN" --mode hybrid-sync   # or rely on env auto-detection
+memory_plugin auth-status
+```
 
 ---
 

package/mcp-server/admin/auth.js

@@ -1,8 +1,8 @@
 import http from "node:http";
 import crypto from "node:crypto";
 import { spawn } from "node:child_process";
-import { saveSecrets, deleteSecrets } from "../config/auth_store.js";
-import { updateConfig } from "../config/config_manager.js";
+import { saveSecrets, deleteSecrets, loadSecrets, resolveEnvSecrets, getSecretsSource } from "../config/auth_store.js";
+import { getConfig, updateConfig } from "../config/config_manager.js";
 
 export const TURSO_API_BASE = () => process.env.TURSO_API_BASE || "https://api.turso.tech";
 
@@ -273,6 +273,86 @@ function dbHostname(org, dbName) {
   return `${dbName}-${org}.turso.io`;
 }
 
+// Shared post-auth resolution: validate happens in the caller. Steps:
+//   1. Resolve an organization (explicit, first available, or username fallback).
+//   2. Pick or create a database.
+//   3. Mint a full-access token for that database.
+//   4. Persist the encrypted token + dbUrl and mark the session as authorized.
+async function finalizeCloudLogin({ token, username, org = null, databaseName = null, autoCreate = true, persist = true, apiToken = null }) {
+  const accountUsername = username || "user";
+
+  // Step 1: resolve organization + database namespace
+  const orgs = await listOrganizations(token);
+  let orgSlug;
+  let orgName;
+  if (orgs && orgs.length > 0) {
+    const requested = org ? orgs.find((o) => (o.slug || o.name || o.id) === org) : null;
+    const chosen = requested || orgs[0];
+    orgSlug = chosen.slug || chosen.name || chosen.id || String(chosen);
+    orgName = chosen.name || orgSlug;
+  } else {
+    // Personal accounts are not listed in /v1/organizations, but their own
+    // username acts as the organization namespace in the Platform API.
+    orgSlug = accountUsername;
+    orgName = accountUsername;
+    console.log(`  [CLOUD] No organizations found. Using personal account "${orgSlug}" as the database namespace.`);
+  }
+
+  const dbs = await listDatabases(token, orgSlug);
+  if (dbs.length > 0) {
+    console.log(`\n  [CLOUD] Databases in organization "${orgName}":`);
+    dbs.forEach((d, i) => console.log(`    ${i + 1}. ${d.name}`));
+  }
+
+  let dbName = databaseName;
+  if (!dbName) {
+    if (dbs.length > 0) {
+      dbName = dbs[0].name;
+      console.log(`\n  [CLOUD] Using existing database: "${dbName}"`);
+    } else if (autoCreate) {
+      dbName = `memory-${accountUsername}`;
+      console.log(`\n  [CLOUD] No database found. Creating "${dbName}"...`);
+      await createDatabase(token, orgSlug, dbName);
+      console.log(`  [OK] Database "${dbName}" created.`);
+    } else {
+      throw new Error("No databases found and autoCreate is disabled.");
+    }
+  }
+
+  // Step 2: mint a full-access token for the database
+  console.log("  [CLOUD] Issuing database access token...");
+  const dbJwt = await createDatabaseToken(token, orgSlug, dbName);
+  if (!dbJwt) {
+    throw new Error("Failed to create database auth token.");
+  }
+
+  const dbUrl = `libsql://${dbHostname(orgSlug, dbName)}`;
+
+  // Step 3: persist secrets and mark authorized
+  if (persist) {
+    saveSecrets({
+      token: dbJwt,
+      dbUrl,
+      username: accountUsername,
+      org: orgSlug,
+      db: dbName,
+      authorized: true,
+      ...(apiToken ? { apiToken } : {}),
+    });
+  }
+  updateConfig({ tursoUrl: dbUrl, authorized: true, username: accountUsername });
+
+  return {
+    token: dbJwt,
+    dbUrl,
+    username: accountUsername,
+    org: orgSlug,
+    db: dbName,
+    authorized: true,
+    ...(apiToken ? { apiToken } : {}),
+  };
+}
+
 // Perform the full cloud login flow:
 //   1. OAuth browser flow against Turso (api.turso.tech).
 //   2. Validate the received account JWT.
@@ -285,6 +365,7 @@ export async function loginToCloud({
   simulatedParams = null,
   autoCreate = true,
   databaseName = null,
+  org = null,
 } = {}) {
   const state = crypto.randomBytes(16).toString("hex");
   const loginUrl = `${TURSO_API_BASE()}/?port=${customPort}&redirect=true&state=${state}&type=cli`;
@@ -324,57 +405,200 @@ export async function loginToCloud({
   const accountUsername = username || userInfo?.username || userInfo?.name || "user";
   console.log(`  [OK] Token is valid. User: ${accountUsername}`);
 
-  // Step 3: resolve organization + database
-  const orgs = await listOrganizations(token);
-  let org;
-  let orgName;
-  if (orgs && orgs.length > 0) {
-    org = orgs[0].slug || orgs[0].name || orgs[0].id || String(orgs[0]);
-    orgName = orgs[0].name || org;
-  } else {
-    // Personal accounts are not listed in /v1/organizations, but their own
-    // username acts as the organization namespace in the Platform API.
-    org = accountUsername;
-    orgName = accountUsername;
-    console.log(`  [CLOUD] No organizations found. Using personal account "${org}" as the database namespace.`);
+  const secrets = await finalizeCloudLogin({ token, username: accountUsername, org, databaseName, autoCreate });
+
+  console.log(`\n  \x1b[32m[OK] Successfully signed in to the cloud! Endpoint: ${secrets.dbUrl}\x1b[0m`);
+  return secrets;
+}
+
+// Headless login with a Turso account API token (no browser, no loopback).
+// Create one at https://console.turso.tech or via `turso auth api-tokens create`.
+// The same Platform API is used to resolve the organization + database and to
+// mint a per-database token, exactly like the browser flow.
+export async function loginWithApiToken({
+  token,
+  org = null,
+  databaseName = null,
+  autoCreate = true,
+  username = null,
+  persist = true,
+} = {}) {
+  if (!token) throw new Error("An account API token is required.");
+  console.log("\n  [CLOUD] Validating account API token...");
+  let userInfo = null;
+  try {
+    userInfo = await validateTursoToken(token);
+  } catch (err) {
+    throw new Error(`Token validation failed: ${err.message}`);
   }
+  const accountUsername = username || userInfo?.username || userInfo?.name || "user";
+  console.log(`  [OK] API token is valid. User: ${accountUsername}`);
 
-  const dbs = await listDatabases(token, org);
-  if (dbs.length > 0) {
-    console.log(`\n  [CLOUD] Databases in organization "${orgName}":`);
-    dbs.forEach((d, i) => console.log(`    ${i + 1}. ${d.name}`));
+  const secrets = await finalizeCloudLogin({
+    token,
+    username: accountUsername,
+    org,
+    databaseName,
+    autoCreate,
+    persist,
+    apiToken: persist ? token : null,
+  });
+
+  console.log(`\n  \x1b[32m[OK] Successfully signed in to the cloud! Endpoint: ${secrets.dbUrl}\x1b[0m`);
+  return secrets;
+}
+
+// Direct headless login with an existing database URL + auth token.
+// No Platform API calls are made; org/db are derived from the endpoint.
+export async function loginWithDatabaseToken({
+  token,
+  dbUrl,
+  username = "",
+  org = "",
+  db = "",
+  validate = true,
+} = {}) {
+  if (!token || !dbUrl) throw new Error("Both a database auth token and a libsql:// URL are required.");
+
+  // Derive org + database name from the endpoint (libsql://<db>-<org>.turso.io)
+  let resolvedOrg = org;
+  let resolvedDb = db;
+  const m = String(dbUrl).match(/^libsql:\/\/(.+)\.turso\.io$/);
+  if (m) {
+    const host = m[1];
+    const sep = host.lastIndexOf("-");
+    if (sep > 0) {
+      resolvedDb = resolvedDb || host.slice(0, sep);
+      resolvedOrg = resolvedOrg || host.slice(sep + 1);
+    }
   }
 
-  let dbName = databaseName;
-  if (!dbName) {
-    if (dbs.length > 0) {
-      dbName = dbs[0].name;
-      console.log(`\n  [CLOUD] Using existing database: "${dbName}"`);
-    } else if (autoCreate) {
-      dbName = `memory-${accountUsername}`;
-      console.log(`\n  [CLOUD] No database found. Creating "${dbName}"...`);
-      await createDatabase(token, org, dbName);
-      console.log(`  [OK] Database "${dbName}" created.`);
-    } else {
-      throw new Error("No databases found and autoCreate is disabled.");
+  if (validate) {
+    console.log("  [CLOUD] Validating database token against the endpoint...");
+    try {
+      const { createClient } = await import("@libsql/client");
+      const client = createClient({ url: dbUrl, authToken: token });
+      await client.execute("SELECT 1");
+      client.close();
+      console.log("  [OK] Database token validated.");
+    } catch (err) {
+      throw new Error(`Database token validation failed: ${err.message}`);
     }
   }
 
-  // Step 4: mint a full-access token for the database
-  console.log("  [CLOUD] Issuing database access token...");
-  const dbJwt = await createDatabaseToken(token, org, dbName);
-  if (!dbJwt) {
-    throw new Error("Failed to create database auth token.");
+  saveSecrets({ token, dbUrl, username, org: resolvedOrg, db: resolvedDb, authorized: true });
+  updateConfig({ tursoUrl: dbUrl, authorized: true, username });
+
+  console.log(`\n  \x1b[32m[OK] Successfully signed in to the cloud! Endpoint: ${dbUrl}\x1b[0m`);
+  return { token, dbUrl, username, org: resolvedOrg, db: resolvedDb, authorized: true };
+}
+
+// Pick up credentials from the environment or MEMORY_DIR/.env.
+// - TURSO_DB_URL + TURSO_DB_TOKEN: direct endpoint login (preferred, no API calls).
+// - TURSO_API_TOKEN: account API-token flow resolving org/db via the Platform API.
+// When persist is true the resolved secrets are also written to the encrypted store.
+export async function loginFromEnv({ persist = false } = {}) {
+  const env = resolveEnvSecrets();
+  if (!env) {
+    return { ok: false, reason: "No cloud secrets found in the environment or MEMORY_DIR/.env." };
   }
 
-  const dbUrl = `libsql://${dbHostname(org, dbName)}`;
+  if (env.dbUrl && env.token) {
+    const secrets = {
+      token: env.token,
+      dbUrl: env.dbUrl,
+      username: env.username || "",
+      org: env.org || "",
+      db: env.database || "",
+      authorized: true,
+    };
+    if (persist) saveSecrets(secrets);
+    updateConfig({ tursoUrl: env.dbUrl, authorized: true, username: secrets.username });
+    console.log(`\n  \x1b[32m[OK] Cloud credentials imported from the environment! Endpoint: ${env.dbUrl}\x1b[0m`);
+    return { ok: true, secrets, source: "env" };
+  }
 
-  // Step 5: persist secrets and mark authorized
-  saveSecrets({ token: dbJwt, dbUrl, username: accountUsername, org, db: dbName, authorized: true });
-  updateConfig({ tursoUrl: dbUrl, authorized: true, username: accountUsername });
+  if (env.apiToken) {
+    // Resolve lazily; the raw API token stays in the environment and is NOT
+    // persisted to the encrypted store (explicit `login --api-token` does that).
+    const secrets = await loginWithApiToken({
+      token: env.apiToken,
+      org: env.org || null,
+      databaseName: env.database || null,
+      username: env.username || null,
+      persist: false,
+    });
+    return { ok: true, secrets: { ...secrets, apiToken: env.apiToken }, source: "env" };
+  }
 
-  console.log(`\n  \x1b[32m[OK] Successfully signed in to the cloud! Endpoint: ${dbUrl}\x1b[0m`);
-  return { token: dbJwt, dbUrl, username: accountUsername, org, db: dbName, authorized: true };
+  return {
+    ok: false,
+    reason: "Incomplete cloud secrets. Set TURSO_DB_URL + TURSO_DB_TOKEN (preferred) or TURSO_API_TOKEN (with optional TURSO_ORG / TURSO_DATABASE).",
+  };
+}
+
+// Async resolution of the working cloud credentials (a DB URL + auth token).
+// Used by database.js at startup so a raw TURSO_API_TOKEN environment token
+// (which can only call the Platform API, not libsql) gets minted into a
+// per-database JWT without any interactive step.
+export async function resolveCloudSecrets() {
+  const secrets = loadSecrets();
+  if (!secrets) return null;
+  if (secrets.apiToken && secrets.needsResolution) {
+    const resolved = await loginWithApiToken({
+      token: secrets.apiToken,
+      org: secrets.org || null,
+      databaseName: secrets.db || null,
+      username: secrets.username || null,
+      persist: false,
+    });
+    return { ...resolved, source: "env" };
+  }
+  return secrets;
+}
+
+// Store/replace a Turso account API token. Alias of the headless login flow:
+// the token is validated, an org/database is resolved and a per-database JWT
+// is minted, then both the API token and the resolved session are persisted.
+export async function setApiKey(token, { org = null, databaseName = null } = {}) {
+  if (!token || typeof token !== "string" || !token.trim()) {
+    throw new Error("An account API token is required.");
+  }
+  const secrets = await loginWithApiToken({ token: token.trim(), org, databaseName });
+  return { ok: true, secrets };
+}
+
+// Remove a stored API token. The resolved database session is kept as a plain
+// browser/database session so an already-synced deployment keeps working.
+export function clearApiKey() {
+  const existing = loadSecrets();
+  if (!existing || !existing.apiToken) return { removed: false };
+  const rest = { ...existing };
+  delete rest.apiToken;
+  if (rest.token && rest.dbUrl) {
+    saveSecrets({ ...rest, authorized: true });
+    return { removed: true, keptDbSession: true };
+  }
+  deleteSecrets();
+  return { removed: true, keptDbSession: false };
+}
+
+// Non-throwing status report used by `auth-status` and the TUI.
+export function getAuthStatus() {
+  const secrets = loadSecrets();
+  const config = getConfig();
+  const source = getSecretsSource();
+  return {
+    source: source || "none",
+    configured: !!(secrets?.dbUrl || config.tursoUrl),
+    authorized: !!config.authorized || source === "env" || source === "api-key",
+    hasApiKey: !!secrets?.apiToken,
+    dbUrl: secrets?.dbUrl || config.tursoUrl || "",
+    username: secrets?.username || config.username || "",
+    org: secrets?.org || "",
+    database: secrets?.db || "",
+    mode: config.mode || "only-local",
+  };
 }
 
 // Logout and reset configurations

package/mcp-server/cli.js

@@ -662,9 +662,43 @@ export async function runCli() {
 
   if (cliArgs.includes("login")) {
     console.log("\n  [CLOUD] Starting Turso cloud authorization...");
-    const { loginToCloud } = await import("./admin/auth.js");
+    const loginIdx = cliArgs.indexOf("login");
+    const loginArgs = cliArgs.slice(loginIdx + 1);
+    const flagValue = (name) => {
+      const i = loginArgs.indexOf(name);
+      return i >= 0 && loginArgs[i + 1] ? loginArgs[i + 1] : null;
+    };
+    const { loginToCloud, loginWithApiToken, loginWithDatabaseToken, loginFromEnv } = await import("./admin/auth.js");
     try {
-      const secrets = await loginToCloud();
+      let secrets;
+      if (loginArgs.includes("--from-env")) {
+        // Headless: pick up TURSO_DB_URL / TURSO_DB_TOKEN / TURSO_API_TOKEN from env or .env
+        const res = await loginFromEnv({ persist: false });
+        if (!res.ok) throw new Error(res.reason);
+        secrets = res.secrets;
+      } else if (loginArgs.includes("--db-url") && loginArgs.includes("--db-token")) {
+        // Headless: direct database URL + token (no Platform API calls)
+        secrets = await loginWithDatabaseToken({
+          dbUrl: flagValue("--db-url"),
+          token: flagValue("--db-token"),
+          username: flagValue("--username") || "",
+          org: flagValue("--org") || "",
+          db: flagValue("--database") || "",
+          validate: !loginArgs.includes("--no-validate"),
+        });
+      } else if (loginArgs.includes("--token") || loginArgs.includes("--api-token") || loginArgs.includes("--api-key")) {
+        // Headless: account API token resolved via the Turso Platform API
+        const token = flagValue("--token") || flagValue("--api-token") || flagValue("--api-key");
+        if (!token) throw new Error("Missing token value. Usage: memory_plugin login --api-token <TOKEN> [--org <ORG>] [--database <DB>]");
+        secrets = await loginWithApiToken({
+          token,
+          org: flagValue("--org") || null,
+          databaseName: flagValue("--database") || null,
+        });
+      } else {
+        // Default: interactive browser OAuth flow
+        secrets = await loginToCloud();
+      }
       console.log(`\n  \x1b[32m[OK] Successfully signed in to the cloud! Connected to endpoint: ${secrets.dbUrl}\x1b[0m\n`);
     } catch (e) {
       console.error(`\n  \x1b[31m[ERROR] Authorization failed: ${e.message}\x1b[0m\n`);
@@ -674,8 +708,22 @@ export async function runCli() {
   }
 
   if (cliArgs.includes("logout")) {
+    const { logoutFromCloud, clearApiKey } = await import("./admin/auth.js");
+    if (cliArgs.includes("--api-key")) {
+      // Headless: remove only the stored account API token
+      const res = clearApiKey();
+      if (res.removed) {
+        console.log(
+          res.keptDbSession
+            ? "  \x1b[32m[OK] API token removed. The resolved database session is kept and stays authorized.\x1b[0m\n"
+            : "  \x1b[32m[OK] API token removed. Encrypted secrets purged.\x1b[0m\n"
+        );
+      } else {
+        console.log("  [*] No stored API token to remove.\x1b[0m\n");
+      }
+      return;
+    }
     console.log("\n  [CLOUD] Signing out of the cloud...");
-    const { logoutFromCloud } = await import("./admin/auth.js");
     const deleted = logoutFromCloud();
     if (deleted) {
       console.log("  \x1b[32m[OK] You have been signed out. Encrypted secrets removed. Mode reverted to only-local.\x1b[0m\n");
@@ -685,6 +733,22 @@ export async function runCli() {
     return;
   }
 
+  if (cliArgs.includes("auth-status") || cliArgs.includes("auth_status") || cliArgs.includes("auth")) {
+    const { getAuthStatus } = await import("./admin/auth.js");
+    const st = getAuthStatus();
+    console.log("\n  [CLOUD] Authentication status:");
+    console.log(`    Source:        ${st.source}`);
+    console.log(`    Authorized:    ${st.authorized ? "YES" : "no"}`);
+    console.log(`    API Key:       ${st.hasApiKey ? "SET" : "not set"}`);
+    console.log(`    Endpoint:      ${st.dbUrl || "(none)"}`);
+    console.log(`    Username:      ${st.username || "(unknown)"}`);
+    console.log(`    Organization:  ${st.org || "(unknown)"}`);
+    console.log(`    Database:      ${st.database || "(unknown)"}`);
+    console.log(`    Mode:          ${st.mode}`);
+    console.log("");
+    return;
+  }
+
   let running = true;
   let selectedIndex = 0;
 
@@ -793,19 +857,35 @@ export async function runCli() {
           {
             label: "[CLOUD] Login to Turso Cloud",
             value: "cloud_login",
-            info: "Perform secure OAuth/Device login flow with loopback listener and local AES-256 key encryption",
+            info: "Browser OAuth, account API token, database URL+token, or import from environment (.env) — token/env methods work headless in Docker, Google Jules and VPS",
           },
           {
             label: "[CLOUD] Logout",
             value: "cloud_logout",
             info: "Sign out, purge encrypted secrets, and revert mode to only-local",
           },
+          {
+            label: "[API KEY] Set / Replace Account API Token",
+            value: "cloud_api_set",
+            info: "Paste a Turso account API token to authorize headless (Docker, Google Jules, VPS) — validated and persisted",
+          },
+          {
+            label: "[API KEY] Remove Account API Token",
+            value: "cloud_api_clear",
+            info: "Delete the stored API token; the resolved database session is kept",
+          },
           {
             label: "Operational Mode",
             badge: config.mode.toUpperCase(),
             value: "cloud_mode",
             info: "Choose Operational Mode: only-local | only-cloud | hybrid-sync",
           },
+          {
+            label: "Conflict Strategy",
+            badge: (config.conflictStrategy || "merge").toUpperCase(),
+            value: "conflict_strategy",
+            info: "How hybrid-sync resolves differing local vs cloud stores: merge | cloud-wins | local-wins",
+          },
         ],
       },
       {
@@ -1829,10 +1909,40 @@ export async function runCli() {
       }
       case "cloud_login": {
         console.clear();
-        console.log("\n  [CLOUD] Starting Turso cloud authorization...");
-        const { loginToCloud } = await import("./admin/auth.js");
+        console.log("\n  [CLOUD] Turso cloud authorization\n");
+        const methodItems = [
+          { label: "Browser OAuth (GUI)", value: "browser", info: "Opens the system browser for the loopback OAuth flow (requires a desktop session)" },
+          { label: "Account API Token", value: "api_token", info: "Paste a Turso account API token — works headless (Docker, Google Jules, VPS/VDS)" },
+          { label: "Database URL + Token", value: "db_token", info: "Paste a libsql:// endpoint and its database auth token — no Platform API needed" },
+          { label: "Import From Environment", value: "env", info: "Pick up TURSO_DB_URL / TURSO_DB_TOKEN / TURSO_API_TOKEN from env vars or MEMORY_DIR/.env" },
+          { label: "< Cancel", value: "cancel", info: "Return to the main menu" },
+        ];
+        const methodRes = await selectSimpleMenu({
+          title: "CHOOSE LOGIN METHOD",
+          subtitle: "Browser login needs a GUI. Token / env methods work in Docker, Google Jules and on VPS/VDS.",
+          items: methodItems,
+        });
+        if (methodRes.action !== "select" || methodRes.value === "cancel") break;
+
+        const { loginToCloud, loginWithApiToken, loginWithDatabaseToken, loginFromEnv } = await import("./admin/auth.js");
         try {
-          const secrets = await loginToCloud();
+          let secrets;
+          if (methodRes.value === "browser") {
+            secrets = await loginToCloud();
+          } else if (methodRes.value === "api_token") {
+            const token = await promptText("Paste your Turso account API token\n  (create one at https://console.turso.tech or via `turso auth api-tokens create`)");
+            if (!token) throw new Error("Empty API token.");
+            secrets = await loginWithApiToken({ token });
+          } else if (methodRes.value === "db_token") {
+            const dbUrl = await promptText("Paste your database URL (libsql://<database>-<org>.turso.io)");
+            const token = await promptText("Paste your database auth token");
+            if (!dbUrl || !token) throw new Error("Empty URL or token.");
+            secrets = await loginWithDatabaseToken({ dbUrl, token, validate: false });
+          } else if (methodRes.value === "env") {
+            const res = await loginFromEnv({ persist: true });
+            if (!res.ok) throw new Error(res.reason);
+            secrets = res.secrets;
+          }
           console.log(`\n  \x1b[32m[OK] Successfully signed in to the cloud! Connected to endpoint: ${secrets.dbUrl}\x1b[0m\n`);
         } catch (e) {
           console.error(`\n  \x1b[31m[ERROR] Authorization failed: ${e.message}\x1b[0m\n`);
@@ -1853,6 +1963,42 @@ export async function runCli() {
         await waitForEnter();
         break;
       }
+      case "cloud_api_set": {
+        console.clear();
+        console.log("\n  [API KEY] Set / replace the Turso account API token\n");
+        const { setApiKey } = await import("./admin/auth.js");
+        try {
+          const token = await promptText(
+            "Paste your Turso account API token\n  (create one at https://console.turso.tech or via `turso auth api-tokens create`)"
+          );
+          if (!token) throw new Error("Empty API token.");
+          const res = await setApiKey(token);
+          console.log(
+            `\n  \x1b[32m[OK] API token stored. Authorized as "${res.secrets.username}" — endpoint: ${res.secrets.dbUrl}\x1b[0m\n`
+          );
+        } catch (e) {
+          console.error(`\n  \x1b[31m[ERROR] Failed to set API key: ${e.message}\x1b[0m\n`);
+        }
+        await waitForEnter();
+        break;
+      }
+      case "cloud_api_clear": {
+        console.clear();
+        console.log("\n  [API KEY] Removing the stored account API token...");
+        const { clearApiKey } = await import("./admin/auth.js");
+        const res = clearApiKey();
+        if (res.removed) {
+          console.log(
+            res.keptDbSession
+              ? "  \x1b[32m[OK] API token removed. The resolved database session is kept and stays authorized.\x1b[0m\n"
+              : "  \x1b[32m[OK] API token removed. Encrypted secrets purged.\x1b[0m\n"
+          );
+        } else {
+          console.log("  [*] No stored API token to remove.\x1b[0m\n");
+        }
+        await waitForEnter();
+        break;
+      }
       case "cloud_mode": {
         const modeItems = [
           { label: "only-local (Local only)", value: "only-local", info: "Fully private, offline-first mode (everything stored on disk)" },
@@ -1872,6 +2018,26 @@ export async function runCli() {
         }
         break;
       }
+      case "conflict_strategy": {
+        const strategyItems = [
+          { label: "merge (Union local + cloud)", value: "merge", info: "Facts from both sides are merged and deduplicated — no data loss (recommended)" },
+          { label: "cloud-wins (Cloud overwrites local)", value: "cloud-wins", info: "On conflict, the cloud copy replaces the local store" },
+          { label: "local-wins (Local overwrites cloud)", value: "local-wins", info: "On conflict, the local copy replaces the cloud store" },
+        ];
+        const initialIdx = Math.max(0, strategyItems.findIndex((i) => i.value === (config.conflictStrategy || "merge")));
+        const subRes = await selectSimpleMenu({
+          title: "CHOOSE CONFLICT STRATEGY",
+          subtitle: "How hybrid-sync resolves differing local vs cloud stores",
+          items: strategyItems,
+          initialIndex: initialIdx,
+        });
+
+        if (subRes.action === "select") {
+          updateConfig({ conflictStrategy: subRes.value });
+          console.log(`\n  [OK] Conflict strategy set to: ${subRes.value}`);
+        }
+        break;
+      }
       case "enable_prompt": {
         const { enableGlobalPrompt } = await import("./prompt_manager.js");
         const results = await enableGlobalPrompt();

package/mcp-server/config/auth_store.js

@@ -95,24 +95,69 @@ export function decryptData(encryptedStr) {
   return decrypted;
 }
 
-// Save secrets securely
-export function saveSecrets(secrets) {
-  ensureDirSync();
-  const plainText = JSON.stringify(secrets);
-  const encrypted = encryptData(plainText);
-  fs.writeFileSync(SECRETS_FILE, encrypted, "utf-8");
+// Load a KEY=VALUE .env file from MEMORY_DIR (global environment override for
+// headless / Docker / CI deployments). Values may optionally be quoted.
+function loadEnvFile() {
+  const envFile = path.join(MEMORY_DIR, ".env");
+  if (!fs.existsSync(envFile)) return {};
+  try {
+    const out = {};
+    const raw = fs.readFileSync(envFile, "utf-8");
+    for (const line of raw.split(/\r?\n/)) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("#")) continue;
+      const eq = trimmed.indexOf("=");
+      if (eq <= 0) continue;
+      const key = trimmed.slice(0, eq).trim();
+      let value = trimmed.slice(eq + 1).trim();
+      if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+        value = value.slice(1, -1);
+      }
+      if (key) out[key] = value;
+    }
+    return out;
+  } catch {
+    return {};
+  }
 }
 
-// Load secrets securely
-export function loadSecrets() {
-  if (!fs.existsSync(SECRETS_FILE)) {
-    return null;
+const ENV_DB_URL_KEYS = ["TURSO_DB_URL", "TURSO_URL"];
+const ENV_DB_TOKEN_KEYS = ["TURSO_DB_TOKEN", "TURSO_TOKEN"];
+
+function firstDefined(source, keys) {
+  for (const k of keys) {
+    const v = source[k];
+    if (v && String(v).trim()) return String(v).trim();
   }
+  return null;
+}
+
+// Resolve cloud credentials from the environment (process.env) or a
+// MEMORY_DIR/.env file — the headless alternative to browser OAuth login.
+// Supported vars: TURSO_DB_URL / TURSO_URL, TURSO_DB_TOKEN / TURSO_TOKEN,
+// TURSO_API_TOKEN, TURSO_ORG, TURSO_DATABASE / TURSO_DB_NAME, TURSO_USERNAME.
+// Returns null when no cloud secrets are present at all.
+export function resolveEnvSecrets() {
+  const fileVars = loadEnvFile();
+  const merged = { ...fileVars, ...process.env };
+  const dbUrl = firstDefined(merged, ENV_DB_URL_KEYS);
+  const token = firstDefined(merged, ENV_DB_TOKEN_KEYS);
+  const apiToken = firstDefined(merged, ["TURSO_API_TOKEN"]);
+  const org = firstDefined(merged, ["TURSO_ORG"]);
+  const database = firstDefined(merged, ["TURSO_DATABASE", "TURSO_DB_NAME"]);
+  const username = firstDefined(merged, ["TURSO_USERNAME"]);
+  if (!dbUrl && !token && !apiToken) return null;
+  return { dbUrl, token, apiToken, org, database, username, source: "env" };
+}
+
+// Read the encrypted store file ONLY (no environment merge). Returns the raw
+// parsed record, or null when the file is missing / undecryptable.
+function readStoredSecrets() {
+  if (!fs.existsSync(SECRETS_FILE)) return null;
   try {
     const encrypted = fs.readFileSync(SECRETS_FILE, "utf-8").trim();
     if (!encrypted) return null;
-    const decrypted = decryptData(encrypted);
-    return JSON.parse(decrypted);
+    return JSON.parse(decryptData(encrypted));
   } catch (err) {
     console.error(
       "Failed to decrypt or load cloud secrets:",
@@ -123,6 +168,73 @@ export function loadSecrets() {
   }
 }
 
+// Where are cloud credentials coming from right now?
+//   "env"     — TURSO_API_TOKEN / TURSO_DB_URL + TURSO_DB_TOKEN from env or .env
+//   "api-key" — a stored Turso account API-token session (takes priority over browser)
+//   "store"   — a stored browser OAuth / database-token session
+//   null      — nothing configured
+export function getSecretsSource() {
+  const envSecrets = resolveEnvSecrets();
+  if (envSecrets && (envSecrets.apiToken || envSecrets.dbUrl)) return "env";
+  const stored = readStoredSecrets();
+  if (stored) return stored.apiToken ? "api-key" : "store";
+  return null;
+}
+
+// Save secrets securely
+export function saveSecrets(secrets) {
+  ensureDirSync();
+  const plainText = JSON.stringify(secrets);
+  const encrypted = encryptData(plainText);
+  fs.writeFileSync(SECRETS_FILE, encrypted, "utf-8");
+}
+
+// Load secrets securely. Priority (highest first):
+//   1. Env account API token (TURSO_API_TOKEN) — reused from the store when a
+//      session was already minted for this exact token, else returned with
+//      needsResolution: true so callers can mint a DB JWT asynchronously.
+//   2. Env database URL + token (TURSO_DB_URL + TURSO_DB_TOKEN).
+//   3. Encrypted store: an API-key session beats a browser/database-token session.
+// The env sources let Docker, Google Jules and VPS deployments work without
+// any interactive login step.
+export function loadSecrets() {
+  const envSecrets = resolveEnvSecrets();
+  if (envSecrets && envSecrets.apiToken) {
+    const stored = readStoredSecrets();
+    if (stored && stored.apiToken === envSecrets.apiToken && stored.dbUrl) {
+      return { ...stored, source: "api-key" };
+    }
+    return {
+      token: envSecrets.apiToken,
+      apiToken: envSecrets.apiToken,
+      dbUrl: envSecrets.dbUrl || "",
+      org: envSecrets.org || "",
+      db: envSecrets.database || "",
+      username: envSecrets.username || "",
+      authorized: true,
+      source: "env",
+      needsResolution: true,
+    };
+  }
+  if (envSecrets && envSecrets.dbUrl && envSecrets.token) {
+    return {
+      token: envSecrets.token,
+      dbUrl: envSecrets.dbUrl,
+      org: envSecrets.org || "",
+      db: envSecrets.database || "",
+      username: envSecrets.username || "",
+      authorized: true,
+      source: "env",
+    };
+  }
+  const stored = readStoredSecrets();
+  if (stored) {
+    if (stored.apiToken) return { ...stored, source: "api-key" };
+    return stored;
+  }
+  return null;
+}
+
 // Delete secrets from disk
 export function deleteSecrets() {
   if (fs.existsSync(SECRETS_FILE)) {

package/mcp-server/config/config_manager.js

@@ -15,6 +15,7 @@ export const DEFAULT_CONFIG = {
   onnxThreads: 0,          // ONNX WASM threads: 0 = auto-detect CPU cores, or 1-16
   executionDevice: "cpu",  // "cpu" | "webgpu"
   mode: "only-local",     // "only-local" | "only-cloud" | "hybrid-sync"
+  conflictStrategy: "merge", // "merge" | "cloud-wins" | "local-wins"
   tursoUrl: "",           // Connection endpoint URL for Turso DB
   failoverUrl: "",        // Failover connection endpoint URL (Fly.io + LiteFS)
   authorized: false,      // True once the user completed cloud login (token stored encrypted)

package/mcp-server/db/database.js

@@ -4,7 +4,7 @@ import { existsSync, mkdirSync } from "fs";
 import { MEMORY_DIR } from "../memory.js";
 import { runMigrations } from "./migrations.js";
 import { getConfig } from "../config/config_manager.js";
-import { loadSecrets } from "../config/auth_store.js";
+import { resolveCloudSecrets } from "../admin/auth.js";
 import { createClient } from "@libsql/client";
 
 let dbInstance = null;
@@ -159,7 +159,9 @@ async function openDatabase(customPath, mode) {
   let cloudClient = null;
   let failoverClient = null;
   if (mode === "only-cloud" || mode === "hybrid-sync") {
-    const secrets = loadSecrets();
+    // Resolve working cloud credentials. An env TURSO_API_TOKEN (which can only
+    // call the Platform API) is lazily minted into a per-database JWT here.
+    const secrets = await resolveCloudSecrets();
     const tursoUrl = customPath && customPath.startsWith("libsql:") ? customPath : (secrets?.dbUrl || config.tursoUrl);
     const failoverUrl = config.failoverUrl || "";
     const token = secrets?.token;

package/mcp-server/db/sync_queue.js

@@ -1,5 +1,15 @@
+import { readFile, readdir } from "fs/promises";
+import { join, basename } from "path";
+import { MEMORY_DIR, GLOBAL_KEY, buildMemoryContent, extractFacts, writeMemoryFile, storeFilePath, memoryFileName } from "../memory.js";
+
 let isSyncing = false;
 
+// Reverse sync (cloud -> local) throttling: only pull at most once per window
+// even if readMemory triggers it frequently (recall hits every keystroke).
+let lastReverseSync = 0;
+let isReverseSyncing = false;
+const REVERSE_SYNC_INTERVAL_MS = 5000;
+
 async function processSyncTask(db, task) {
   if (task.action === "write_memory") {
     await db.cloudClient.execute({
@@ -162,6 +172,161 @@ export async function enqueueSyncTask(action, keyOrId, payload = null) {
   });
 }
 
+// Map a store key to its local file path, mirroring memory.js naming.
+function localFilePath(key) {
+  return join(MEMORY_DIR, memoryFileName(key));
+}
+
+// Enumerate local store files as { key, path }.
+async function enumerateLocalStores() {
+  const files = await readdir(MEMORY_DIR).catch(() => []);
+  const stores = [];
+  for (const f of files) {
+    if (!f.endsWith(".md")) continue;
+    const fp = join(MEMORY_DIR, f);
+    let content = "";
+    try {
+      content = await readFile(fp, "utf-8");
+    } catch (e) {
+      continue;
+    }
+    const meta = content.match(/<!-- path: (.+?) -->/);
+    const key = f === `${GLOBAL_KEY}.md` ? GLOBAL_KEY : (meta ? meta[1].trim() : f.slice(0, -3));
+    stores.push({ key, path: fp, file: f });
+  }
+  return stores;
+}
+
+// Reverse sync: pull cloud state down to local stores, resolving conflicts
+// according to config.conflictStrategy ("merge" | "cloud-wins" | "local-wins").
+//
+// Returns a summary of what happened for diagnostics.
+async function pullFromCloud(db) {
+  const { getConfig } = await import("../config/config_manager.js");
+  const config = getConfig();
+  const strategy = config.conflictStrategy || "merge";
+
+  const summary = { pulled: 0, pushed: 0, merged: 0, cloudWins: 0, localWins: 0, unchanged: 0, conflicts: 0 };
+
+  // 1. Enumerate cloud notebooks. In hybrid-sync the wrapper's prepare() routes
+  // to the LOCAL sqlite, so cloud reads/writes must go through cloudClient directly.
+  const cloudRes = await db.cloudClient.execute("SELECT key, content FROM notebooks;");
+  const cloudRows = cloudRes.rows || [];
+  const cloudByKey = new Map(cloudRows.map((r) => [r.key, r.content || ""]));
+
+  // 2. Enumerate local store files.
+  const localStores = await enumerateLocalStores();
+  const localByKey = new Map(localStores.map((s) => [s.key, s.path]));
+  const localContentByKey = new Map();
+  for (const s of localStores) {
+    try {
+      localContentByKey.set(s.key, await readFile(s.path, "utf-8"));
+    } catch (e) {}
+  }
+
+  const allKeys = new Set([...cloudByKey.keys(), ...localByKey.keys()]);
+
+  // Upsert a notebook row directly on the cloud client.
+  const upsertCloud = async (key, content) => {
+    await db.cloudClient.execute({
+      sql: `
+        INSERT INTO notebooks (key, content, updated_at)
+        VALUES (?, ?, ?)
+        ON CONFLICT(key) DO UPDATE SET content = excluded.content, updated_at = excluded.updated_at;
+      `,
+      args: [key, content, Date.now()],
+    });
+  };
+
+  // 3. Reconcile each key.
+  for (const key of allKeys) {
+    const cloudContent = cloudByKey.get(key);
+    const localPath = localByKey.get(key);
+    const localContent = localContentByKey.get(key) || "";
+
+    const cloudFacts = cloudContent !== undefined ? extractFacts(cloudContent) : null;
+    const localFacts = extractFacts(localContent);
+    const cloudHas = cloudFacts !== null && cloudFacts.length > 0;
+    const localHas = localFacts.length > 0;
+
+    if (cloudFacts === null) {
+      // Store exists only locally -> push up.
+      if (localHas) {
+        await upsertCloud(key, localContent);
+        summary.pushed++;
+      }
+      continue;
+    }
+
+    if (!localHas) {
+      // Store exists only in cloud -> pull down.
+      if (cloudHas) {
+        await writeMemoryFile(key, cloudContent);
+        summary.pulled++;
+      }
+      continue;
+    }
+
+    // Both exist.
+    if (localContent === cloudContent) {
+      summary.unchanged++;
+      continue;
+    }
+
+    summary.conflicts++;
+    if (strategy === "cloud-wins") {
+      await writeMemoryFile(key, cloudContent);
+      summary.cloudWins++;
+    } else if (strategy === "local-wins") {
+      await upsertCloud(key, localContent);
+      summary.localWins++;
+    } else {
+      // merge: union of fact lines, deduped, local order first then cloud-only.
+      const seen = new Set();
+      const mergedFacts = [];
+      for (const l of [...localFacts, ...cloudFacts]) {
+        if (!seen.has(l)) {
+          seen.add(l);
+          mergedFacts.push(l);
+        }
+      }
+      const mergedContent = buildMemoryContent(key, mergedFacts);
+      await writeMemoryFile(key, mergedContent);
+      await upsertCloud(key, mergedContent);
+      summary.merged++;
+    }
+  }
+
+  return summary;
+}
+
+// Trigger a reverse sync now (regardless of throttle). Used after the push queue
+// drains so both directions stay in sync.
+export async function syncFromCloud() {
+  if (isReverseSyncing) return { skipped: true };
+  isReverseSyncing = true;
+  try {
+    const { getDatabase } = await import("./database.js");
+    const db = await getDatabase();
+    if (db.mode !== "hybrid-sync" || !db.cloudClient) return { skipped: true };
+    lastReverseSync = Date.now();
+    return await pullFromCloud(db);
+  } finally {
+    isReverseSyncing = false;
+  }
+}
+
+// Throttled reverse sync, safe to call on every recall/read.
+export async function ensureReverseSync() {
+  if (Date.now() - lastReverseSync < REVERSE_SYNC_INTERVAL_MS) return { throttled: true };
+  return syncFromCloud();
+}
+
+// Reset the reverse-sync throttle (used by tests and manual syncs).
+export function resetReverseSyncThrottle() {
+  lastReverseSync = 0;
+}
+
 export async function triggerBackgroundSync() {
   if (isSyncing) return;
   isSyncing = true;
@@ -203,6 +368,9 @@ export async function triggerBackgroundSync() {
         break;
       }
     }
+
+    // Push queue drained — now pull cloud state back down (reverse sync).
+    await syncFromCloud();
   } catch (err) {
     console.error("Error during background sync execution:", err.message);
   } finally {

package/mcp-server/index.js

@@ -39,7 +39,7 @@ if (cliArgs.includes("setup") || cliArgs.includes("install") || cliArgs.includes
   process.exit(0);
 }
 
-if (cliArgs.includes("cli") || cliArgs.includes("config") || cliArgs.includes("--cli") || cliArgs.includes("-c") || cliArgs.includes("login") || cliArgs.includes("logout")) {
+if (cliArgs.includes("cli") || cliArgs.includes("config") || cliArgs.includes("--cli") || cliArgs.includes("-c") || cliArgs.includes("login") || cliArgs.includes("logout") || cliArgs.includes("auth-status") || cliArgs.includes("auth_status") || cliArgs.includes("auth")) {
   const { runCli } = await import("./cli.js");
   await runCli();
   process.exit(0);

package/mcp-server/memory.js

@@ -142,6 +142,15 @@ export async function readMemory(key) {
   }
 
   const fp = memoryPath(key);
+  if (config.mode === "hybrid-sync") {
+    // Pull cloud state down first so cloud-only records appear locally.
+    try {
+      const { ensureReverseSync } = await import("./db/sync_queue.js");
+      await ensureReverseSync();
+    } catch (err) {
+      console.error("Failed to reverse-sync before read:", err.message);
+    }
+  }
   if (existsSync(fp)) {
     const content = await readFile(fp, "utf-8");
     return content.split("\n").filter((l) => l.startsWith("- ["));
@@ -154,7 +163,8 @@ export async function readMemoryRaw(key) {
   return (await readMemory(key)).map((e) => e.slice(2));
 }
 
-export async function writeMemory(key, entries) {
+// Build the markdown store content for a key from a list of fact lines.
+export function buildMemoryContent(key, entries) {
   const lines = [];
   if (key === GLOBAL_KEY) {
     lines.push("# Global Memory", "");
@@ -164,7 +174,22 @@ export async function writeMemory(key, entries) {
       lines.push(`<!-- path: ${key} -->`, "");
     }
   }
-  const content = lines.join("\n") + "\n" + (entries.length ? entries.join("\n") + "\n" : "");
+  return lines.join("\n") + "\n" + (entries.length ? entries.join("\n") + "\n" : "");
+}
+
+// Extract fact lines (`- [date] ...`) from a store content string.
+export function extractFacts(content) {
+  return (content || "").split("\n").filter((l) => l.startsWith("- ["));
+}
+
+// Write a store file directly to disk WITHOUT enqueueing a cloud sync task.
+// Used by the sync worker to apply pulled cloud state without re-queueing.
+export async function writeMemoryFile(key, content) {
+  await writeFile(memoryPath(key), content);
+}
+
+export async function writeMemory(key, entries) {
+  const content = buildMemoryContent(key, entries);
 
   const { getConfig } = await import("./config/config_manager.js");
   const config = getConfig();

package/mcp-server/setup.js

@@ -15,10 +15,42 @@ export async function runSetup() {
   const doAntigravity = !hasSpecificFlag || args.includes("--antigravity") || args.includes("--gemini");
   const doCodex = !hasSpecificFlag || args.includes("--codex");
 
+  // Headless cloud setup: --api-key <TURSO_API_TOKEN> and/or --mode <only-local|only-cloud|hybrid-sync>
+  const VALID_MODES = ["only-local", "only-cloud", "hybrid-sync"];
+  const apiKeyArg = flagValue(args, "--api-key");
+  const modeArg = flagValue(args, "--mode");
+  if (modeArg && !VALID_MODES.includes(modeArg)) {
+    console.log(`  [WARN] Unknown --mode "${modeArg}". Allowed: ${VALID_MODES.join(", ")}`);
+  }
+
   console.log("\nSetting up @lotargo/memory_plugin...\n");
   const home = homedir();
   let configuredCount = 0;
 
+  // 0. Headless cloud authentication (Google Jules / CI / VPS)
+  if (apiKeyArg) {
+    try {
+      const { loginWithApiToken } = await import("./admin/auth.js");
+      const secrets = await loginWithApiToken({ token: apiKeyArg });
+      if (modeArg && VALID_MODES.includes(modeArg)) {
+        const { updateConfig } = await import("./config/config_manager.js");
+        updateConfig({ mode: modeArg });
+      }
+      console.log(`  [OK] Cloud: authorized as "${secrets.username}" via API token. Endpoint: ${secrets.dbUrl}`);
+      configuredCount++;
+    } catch (err) {
+      console.log("  [FAIL] Cloud setup failed:", err.message);
+    }
+  } else if (modeArg && VALID_MODES.includes(modeArg)) {
+    try {
+      const { updateConfig } = await import("./config/config_manager.js");
+      updateConfig({ mode: modeArg });
+      console.log(`  [OK] Cloud: sync mode set to "${modeArg}"`);
+    } catch (err) {
+      console.log("  [SKIP] Cloud mode update skipped:", err.message);
+    }
+  }
+
   // 1. OpenCode (~/.config/opencode/opencode.json)
   if (doOpenCode) {
     try {
@@ -229,3 +261,12 @@ export async function runSetup() {
   console.log(`\nSetup complete. Configured ${configuredCount} environment(s).\n`);
 }
 
+// Read the value following --flag, or null when absent / followed by another flag.
+function flagValue(args, flag) {
+  const idx = args.indexOf(flag);
+  if (idx === -1 || idx + 1 >= args.length) return null;
+  const value = args[idx + 1];
+  if (value.startsWith("--")) return null;
+  return value;
+}
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotargo/memory_plugin",
-  "version": "1.4.601",
+  "version": "1.4.621",
   "description": "100% local hybrid RAG memory for AI coding agents (OpenCode, Claude Code, Codex, Antigravity). MCP server + plugin: persistent user facts, document ingestion, vector + SQLite FTS5 retrieval across sessions.",
   "type": "module",
   "main": "opencode-plugin/index.js",