@dinasor/mnemo-cli 0.0.4 → 0.0.6

package/CHANGELOG.md

@@ -6,6 +6,26 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Mnemo u
 
 ## [Unreleased]
 
+## [0.0.6] - 2026-02-22
+
+### Added
+- `npx @dinasor/mnemo-cli@latest` now launches a smart interactive wizard when run in a TTY, guiding users through vector mode enablement, provider selection, and API key setup in a beautiful ANSI UI.
+- Wizard automatically detects existing API keys in the shell environment or project `.env` and skips the key prompt when a real value is already present.
+- API key entered during the wizard is immediately appended to the project's `.env` file and injected into the current process environment.
+- Dependency preflight check displays Node.js, Git, Python, pip, and all required Python packages (with live "checking…" → installed/will-be-installed status) before running the installer.
+- `--yes` / `-y` flag skips the wizard entirely for non-interactive / CI use while still showing the dependency check.
+- Success box at the end of install shows next steps: `vector_health → vector_sync` hint and `mnemo-codebase-optimizer` skill reminder for seeding codebase memory.
+
+### Changed
+- `package.json` version aligned to `0.0.6` (was stale at `0.0.1`).
+
+## [0.0.5] - 2026-02-22
+
+### Fixed
+- Vector `.env` loading now treats blank/unresolved MCP placeholder values (for example `${env:GEMINI_API_KEY}`) as missing and correctly hydrates `GEMINI_API_KEY`/`OPENAI_API_KEY` from project `.env`.
+- Vector provider resolution now ignores unresolved `MNEMO_PROVIDER` placeholders and falls back to valid runtime values (`gemini` when key is present, otherwise `openai`).
+- `.env` key parser now strips BOM characters from key names to prevent silent misses on Windows-generated files.
+
 ## [0.0.4] - 2026-02-22
 
 ### Added
@@ -75,7 +95,9 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Mnemo u
 - Version string drift between installer metadata and generated output by using `VERSION` as single source of truth.
 - Python fallback handling in memory query flows that previously depended on a single interpreter name.
 
-[Unreleased]: https://github.com/DiNaSoR/Mnemo/compare/v0.0.4...HEAD
+[Unreleased]: https://github.com/DiNaSoR/Mnemo/compare/v0.0.6...HEAD
+[0.0.6]: https://github.com/DiNaSoR/Mnemo/compare/v0.0.5...v0.0.6
+[0.0.5]: https://github.com/DiNaSoR/Mnemo/compare/v0.0.4...v0.0.5
 [0.0.4]: https://github.com/DiNaSoR/Mnemo/releases/tag/v0.0.4
 [0.0.3]: https://github.com/DiNaSoR/Mnemo/releases/tag/v0.0.3
 [0.0.2]: https://github.com/DiNaSoR/Mnemo/releases/tag/v0.0.2

package/README.md

@@ -28,13 +28,24 @@ Run from the **target project root**.
 ### Any OS (npx, recommended)
 
 ```sh
-# Installs into your current project folder
+# Interactive wizard — guides you through every option (recommended)
 npx @dinasor/mnemo-cli@latest
+```
+
+The wizard will ask you:
+
+1. **Vector mode** — enable semantic / embedding-based memory recall?
+2. **Provider** — Gemini (`GEMINI_API_KEY`) or OpenAI (`OPENAI_API_KEY`)?
+3. **API key** — enter now (saved to `.env`), already in `.env`, or skip.
 
-# Optional flags (cross-platform)
+It then runs a live dependency check (Node · Git · Python · pip · packages) and launches the installer.
+
+```sh
+# Non-interactive (CI / scripting) — skip wizard, use flags directly
+npx @dinasor/mnemo-cli@latest --yes
+npx @dinasor/mnemo-cli@latest --enable-vector --vector-provider gemini --yes
 npx @dinasor/mnemo-cli@latest --dry-run
 npx @dinasor/mnemo-cli@latest --force
-npx @dinasor/mnemo-cli@latest --enable-vector --vector-provider gemini
 ```
 
 ### Windows (PowerShell)
@@ -79,6 +90,38 @@ vector_sync
 
 ---
 
+## 🧠 Seeding memory for an existing codebase
+
+After installing Mnemo in a project that already has code, use the bundled
+`mnemo-codebase-optimizer` skill to fill memory quickly and accurately.
+
+**In Cursor (or any agent that loads `.cursor/skills/`):**
+
+1. Open the project.
+2. Start a new conversation and say:
+
+   > Use the **mnemo-codebase-optimizer** skill to seed memory for this codebase.
+
+   Or load the skill directly:
+
+   ```text
+   @.cursor/skills/mnemo-codebase-optimizer/SKILL.md
+   ```
+
+3. The agent will map architecture, ownership, dev workflows, risks, commands,
+   and write optimized `memo.md`, `hot-rules.md`, `active-context.md`, lessons,
+   and a journal summary — then validate retrieval quality.
+
+The skill is installed automatically by `memory.ps1` / `memory_mac.sh` and lives at:
+
+```text
+.cursor/skills/mnemo-codebase-optimizer/
+  SKILL.md        ← skill prompt + checklist
+  reference.md    ← memory file templates + retrieval queries
+```
+
+---
+
 ## 🧩 IDE setup guide (per project)
 
 Use the section that matches your IDE. Each project should run Mnemo install once.
@@ -257,6 +300,7 @@ python3 scripts/memory/mnemo_vector.py health
 
 ## 📋 Requirements
 
+- **Node.js 18+** (for `npx @dinasor/mnemo-cli@latest`)
 - **PowerShell**: Windows PowerShell 5.1+ or PowerShell 7 (`pwsh`)
 - **Git**
 - **Optional**: Python 3 for SQLite FTS index
@@ -265,6 +309,9 @@ python3 scripts/memory/mnemo_vector.py health
   - API key: `OPENAI_API_KEY` or `GEMINI_API_KEY`
   - Auto-installed deps: `openai`, `sqlite-vec`, `mcp[cli]>=1.2.0,<2.0` (+ `google-genai` for Gemini)
 
+> The interactive wizard (`npx @dinasor/mnemo-cli@latest`) checks all of these
+> before running the installer and reports which packages are already installed.
+
 ## 🤝 Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md). Bug reports and feature requests use the issue templates in [.github/ISSUE_TEMPLATE/](.github/ISSUE_TEMPLATE/). Security issues go to [SECURITY.md](SECURITY.md).

package/VERSION

@@ -1 +1 @@
-0.0.4
+0.0.6

package/bin/mnemo.js

@@ -1,139 +1,551 @@
 #!/usr/bin/env node
+"use strict";
+
+/**
+ * Mnemo CLI — interactive wizard + cross-platform installer runner.
+ *
+ * When stdin is a TTY (and --yes is not passed) the wizard:
+ *   1. Asks whether to enable vector/semantic search mode.
+ *   2. Asks which embedding provider (gemini / openai).
+ *   3. Checks for an existing API key (env / .env file), or lets the user
+ *      enter one now (saved to project .env) or skip.
+ *   4. Checks all runtime dependencies and reports their status.
+ *   5. Runs memory.ps1 (Windows) or memory_mac.sh (POSIX).
+ *
+ * When --yes / -y is passed, or stdin is not a TTY, the wizard is skipped
+ * and the installer runs immediately using whatever flags were supplied.
+ */
 
 const { spawnSync } = require("child_process");
-const fs = require("fs");
+const fs   = require("fs");
 const path = require("path");
+const rl   = require("readline");
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+const PKG_ROOT = path.resolve(__dirname, "..");
+const CWD      = process.cwd();
+const IS_WIN   = process.platform === "win32";
+const ARGV     = process.argv.slice(2);
+
+// ─── ANSI color helpers ───────────────────────────────────────────────────────
+const HAS_COLOR = !!process.stdout.isTTY && !process.env.NO_COLOR;
+const esc  = (n) => HAS_COLOR ? `\x1b[${n}m` : "";
 
-const packageRoot = path.resolve(__dirname, "..");
-const cwd = process.cwd();
-const rawArgs = process.argv.slice(2);
-const wantsHelp = rawArgs.includes("--help") || rawArgs.includes("-h");
+const R   = esc(0);    // reset
+const BO  = esc(1);    // bold
+const DI  = esc(2);    // dim
+const CY  = esc(36);   // cyan
+const GR  = esc(32);   // green
+const YE  = esc(33);   // yellow
+const RE  = esc(31);   // red
+const WH  = esc(97);   // bright white
+const BCY = esc(96);   // bright cyan
+const BGR = esc(92);   // bright green
+const BRE = esc(91);   // bright red
+const BYE = esc(93);   // bright yellow
+const MG  = esc(35);   // magenta
 
-function printHelp() {
-  console.log(`Mnemo CLI
+const bold   = (s) => `${BO}${s}${R}`;
+const dim    = (s) => `${DI}${s}${R}`;
+const cyan   = (s) => `${CY}${s}${R}`;
+const green  = (s) => `${GR}${s}${R}`;
+const yellow = (s) => `${YE}${s}${R}`;
 
-Usage:
-  npx @dinasor/mnemo-cli@latest [options]
+const TICK  = `${BGR}✓${R}`;
+const CROSS = `${BRE}✗${R}`;
+const WARN  = `${BYE}⚠${R}`;
+const ARROW = `${BCY}›${R}`;
 
-Options:
-  --dry-run
-  --force
-  --enable-vector
-  --vector-provider <openai|gemini>
-  --project-name <name>
-  --repo-root <path>   (defaults to current directory)
-  --help
-`);
+// ─── Layout helpers ───────────────────────────────────────────────────────────
+const W = 62; // box inner content width
+
+function padR(s, n) { return s + " ".repeat(Math.max(0, n - s.length)); }
+
+function banner(version) {
+  const bar  = "═".repeat(W);
+  const t1   = `Mnemo v${version}  ·  Memory Layer for AI Agents`;
+  const t2   = `Token-safe · Cursor · Claude Code · Codex & more`;
+  const pad1 = W - t1.length - 2;
+  const pad2 = W - t2.length - 2;
+  process.stdout.write("\n");
+  process.stdout.write(`${CY}╔${bar}╗${R}\n`);
+  process.stdout.write(`${CY}║${R}  ${WH}${BO}${t1}${R}${" ".repeat(Math.max(0, pad1))}${CY}║${R}\n`);
+  process.stdout.write(`${CY}║${R}  ${DI}${t2}${R}${" ".repeat(Math.max(0, pad2))}${CY}║${R}\n`);
+  process.stdout.write(`${CY}╚${bar}╝${R}\n`);
+  process.stdout.write("\n");
 }
 
-function fail(message) {
-  console.error(`[mnemo] ${message}`);
-  process.exit(1);
+function divider() {
+  process.stdout.write(`  ${DI}${"─".repeat(W - 2)}${R}\n`);
 }
 
-function mapWindowsArgs(args) {
-  const mapped = [];
-  let hasRepoRoot = false;
+function sectionHeader(title, step, total) {
+  divider();
+  const stepLabel = total ? `  ${DI}Step ${step}/${total}${R}` : "";
+  process.stdout.write(`\n  ${BCY}${BO}${title}${R}${stepLabel}\n\n`);
+}
 
-  for (let i = 0; i < args.length; i += 1) {
-    const arg = args[i];
+function successBox(vectorMode) {
+  const bar  = "═".repeat(W);
+  const t1   = `Setup complete!`;
+  const pad1 = W - t1.length - 2;
+  process.stdout.write("\n");
+  process.stdout.write(`${BGR}╔${bar}╗${R}\n`);
+  process.stdout.write(`${BGR}║${R}  ${WH}${BO}${t1}${R}${" ".repeat(Math.max(0, pad1))}${BGR}║${R}\n`);
+  if (vectorMode) {
+    const t2   = `Run vector_health → vector_sync in your IDE`;
+    const pad2 = W - t2.length - 2;
+    process.stdout.write(`${BGR}║${R}  ${DI}${t2}${R}${" ".repeat(Math.max(0, pad2))}${BGR}║${R}\n`);
+  }
+  const t3   = `Skill: .cursor/skills/mnemo-codebase-optimizer/`;
+  const pad3 = W - t3.length - 2;
+  process.stdout.write(`${BGR}║${R}  ${DI}${t3}${R}${" ".repeat(Math.max(0, pad3))}${BGR}║${R}\n`);
+  process.stdout.write(`${BGR}╚${bar}╝${R}\n`);
+  process.stdout.write("\n");
+}
 
-    if (arg === "--dry-run") {
-      mapped.push("-DryRun");
-      continue;
-    }
-    if (arg === "--force") {
-      mapped.push("-Force");
-      continue;
-    }
-    if (arg === "--enable-vector") {
-      mapped.push("-EnableVector");
-      continue;
-    }
-    if (arg === "--vector-provider") {
-      const value = args[i + 1];
-      if (!value) fail("Missing value for --vector-provider");
-      mapped.push("-VectorProvider", value);
-      i += 1;
-      continue;
-    }
-    if (arg === "--project-name") {
-      const value = args[i + 1];
-      if (!value) fail("Missing value for --project-name");
-      mapped.push("-ProjectName", value);
-      i += 1;
-      continue;
-    }
-    if (arg === "--repo-root") {
-      const value = args[i + 1];
-      if (!value) fail("Missing value for --repo-root");
-      mapped.push("-RepoRoot", value);
-      hasRepoRoot = true;
-      i += 1;
-      continue;
+// ─── .env utilities ───────────────────────────────────────────────────────────
+function readDotEnv(dir) {
+  const envPath = path.join(dir, ".env");
+  const result  = {};
+  if (!fs.existsSync(envPath)) return result;
+  try {
+    const text = fs.readFileSync(envPath, "utf8").replace(/^\uFEFF/, "");
+    for (const raw of text.split(/\r?\n/)) {
+      const line = raw.trim();
+      if (!line || line.startsWith("#")) continue;
+      const eq = line.indexOf("=");
+      if (eq < 1) continue;
+      const key = line.slice(0, eq).trim();
+      const val = line.slice(eq + 1).trim().replace(/^['"]|['"]$/g, "");
+      result[key] = val;
     }
+  } catch { /* ignore */ }
+  return result;
+}
 
-    if (arg.toLowerCase() === "-reporoot") {
-      hasRepoRoot = true;
+function appendDotEnv(dir, key, value) {
+  const envPath = path.join(dir, ".env");
+  try {
+    if (fs.existsSync(envPath)) {
+      let content = fs.readFileSync(envPath, "utf8");
+      const re    = new RegExp(`^${key}=.*$`, "m");
+      if (re.test(content)) {
+        fs.writeFileSync(envPath, content.replace(re, `${key}=${value}`));
+        return;
+      }
+      const nl = content.endsWith("\n") ? "" : "\n";
+      fs.appendFileSync(envPath, `${nl}${key}=${value}\n`);
+    } else {
+      fs.writeFileSync(envPath, `${key}=${value}\n`);
     }
-    mapped.push(arg);
+  } catch (e) {
+    process.stdout.write(`  ${WARN} Could not write .env: ${e.message}\n`);
   }
+}
+
+/**
+ * Returns true if the value is a real, usable string —
+ * not empty, not an unresolved Cursor MCP placeholder like ${env:FOO}.
+ */
+function isRealValue(v) {
+  if (!v) return false;
+  const s = v.trim();
+  if (!s) return false;
+  if (s.startsWith("${env:") && s.endsWith("}")) return false;
+  return true;
+}
+
+// ─── Dependency detection ─────────────────────────────────────────────────────
+function runCmd(cmd, args, opts = {}) {
+  return spawnSync(cmd, args, {
+    encoding: "utf8",
+    timeout: 15000,
+    windowsHide: true,
+    ...opts,
+  });
+}
+
+function checkNode() {
+  return { ver: process.version, ok: true };
+}
+
+function checkGit() {
+  const r = runCmd("git", ["--version"]);
+  if (r.status !== 0) return { ver: null, ok: false };
+  const m = (r.stdout || "").match(/git version (.+)/);
+  return { ver: m ? m[1].trim() : "?", ok: true };
+}
 
-  if (!hasRepoRoot && !wantsHelp) {
-    mapped.push("-RepoRoot", cwd);
+function findPython() {
+  const candidates = IS_WIN ? ["py", "python", "python3"] : ["python3", "python"];
+  for (const cmd of candidates) {
+    const r = runCmd(cmd, IS_WIN && cmd === "py" ? ["-3", "--version"] : ["--version"]);
+    if (r.status !== 0) continue;
+    const raw = (r.stdout || r.stderr || "").trim();
+    const m   = raw.match(/Python (\d+)\.(\d+)\.(\d+)/);
+    if (!m) continue;
+    const [, maj, min] = m.map(Number);
+    return {
+      cmd,
+      ver: `${maj}.${min}.${m[3]}`,
+      ok:  maj > 3 || (maj === 3 && min >= 10),
+    };
   }
-  return mapped;
+  return { cmd: null, ver: null, ok: false };
 }
 
-function mapPosixArgs(args) {
-  const mapped = [];
-  let hasRepoRoot = false;
+function checkPip(pythonCmd) {
+  const args = IS_WIN && pythonCmd === "py" ? ["-3", "-m", "pip", "--version"] : ["-m", "pip", "--version"];
+  const r    = runCmd(pythonCmd, args);
+  if (r.status !== 0) return { ver: null, ok: false };
+  const m = (r.stdout || "").match(/pip (\S+)/);
+  return { ver: m ? m[1] : "?", ok: true };
+}
 
-  for (let i = 0; i < args.length; i += 1) {
-    const arg = args[i];
-    mapped.push(arg);
+function checkPipPkg(pythonCmd, pkgName) {
+  const baseArgs = IS_WIN && pythonCmd === "py" ? ["-3"] : [];
+  const r = runCmd(pythonCmd, [...baseArgs, "-m", "pip", "show", pkgName]);
+  if (r.status !== 0) return { installed: false, ver: null };
+  const m = (r.stdout || "").match(/^Version:\s*(.+)$/m);
+  return { installed: true, ver: m ? m[1].trim() : "?" };
+}
 
-    if (arg === "--repo-root") {
-      if (!args[i + 1]) fail("Missing value for --repo-root");
-      mapped.push(args[i + 1]);
-      hasRepoRoot = true;
-      i += 1;
+function depRow(label, verStr, statusStr) {
+  const lc = padR(label, 22);
+  const vc = padR(verStr, 14);
+  process.stdout.write(`    ${DI}${lc}${R}  ${CY}${vc}${R}  ${statusStr}\n`);
+}
+
+async function runDependencyCheck(vectorMode, provider, pythonInfo) {
+  process.stdout.write("\n");
+  process.stdout.write(`  ${BCY}${BO}Checking requirements${R}\n`);
+  process.stdout.write(`  ${DI}${"─".repeat(50)}${R}\n`);
+  process.stdout.write("\n");
+
+  // Node.js — always present (we are running in it)
+  const node = checkNode();
+  depRow("Node.js", node.ver, `${TICK} ready`);
+
+  // Git
+  const git = checkGit();
+  depRow("Git", git.ver || "not found", git.ok ? `${TICK} ready` : `${WARN} recommended (not found)`);
+
+  if (vectorMode) {
+    // Python
+    const py = pythonInfo || findPython();
+    if (!py.ok) {
+      depRow(
+        "Python",
+        py.ver || "not found",
+        py.ver ? `${CROSS} Python 3.10+ required (found ${py.ver})` : `${CROSS} Python 3.10+ required`,
+      );
+    } else {
+      depRow("Python", py.ver, `${TICK} ready`);
+    }
+
+    if (py.cmd && py.ok) {
+      // pip
+      const pip = checkPip(py.cmd);
+      depRow("pip", pip.ver || "not found", pip.ok ? `${TICK} ready` : `${WARN} pip missing`);
+
+      if (pip.ok) {
+        process.stdout.write("\n");
+        process.stdout.write(`  ${DI}  Python packages (${provider} mode):${R}\n`);
+        process.stdout.write("\n");
+
+        const core  = ["openai", "sqlite-vec", "mcp"];
+        const extra = provider === "gemini" ? ["google-genai"] : [];
+        const pkgs  = [...core, ...extra];
+
+        for (const pkg of pkgs) {
+          // Show "checking…" then overwrite with result
+          const label = padR(pkg, 22);
+          process.stdout.write(`    ${DI}${label}${R}  ${DI}checking…${R}`);
+          const res = checkPipPkg(py.cmd, pkg);
+          // Overwrite the line
+          process.stdout.write(`\r${" ".repeat(W)}\r`);
+          depRow(
+            pkg,
+            res.ver || "",
+            res.installed ? `${TICK} installed` : `${WARN} will be installed by installer`,
+          );
+        }
+      }
     }
   }
 
-  if (!hasRepoRoot && !wantsHelp) {
-    mapped.push("--repo-root", cwd);
+  process.stdout.write("\n");
+}
+
+// ─── Interactive readline helpers ────────────────────────────────────────────
+function prompt(question) {
+  return new Promise((resolve) => {
+    const iface = rl.createInterface({ input: process.stdin, output: process.stdout });
+    iface.question(question, (answer) => {
+      iface.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+async function askYesNo(question, defaultYes = false) {
+  const hint = defaultYes ? `${DI}[Y/n]${R}` : `${DI}[y/N]${R}`;
+  const ans  = await prompt(`    ${ARROW} ${question} ${hint} `);
+  if (!ans) return defaultYes;
+  return /^y(es)?$/i.test(ans);
+}
+
+async function askChoice(question, choices, defaultIdx = 0) {
+  process.stdout.write(`    ${ARROW} ${question}\n\n`);
+  choices.forEach((ch, i) => {
+    const active = i === defaultIdx;
+    const num    = active ? `${BCY}${BO}[${i + 1}]${R}` : `${DI}[${i + 1}]${R}`;
+    process.stdout.write(`        ${num} ${ch}\n`);
+  });
+  process.stdout.write("\n");
+  const ans = await prompt(`    ${DI}Choice${R} ${DI}[${defaultIdx + 1}]${R}: `);
+  const num = parseInt(ans, 10);
+  if (!ans || isNaN(num) || num < 1 || num > choices.length) return defaultIdx;
+  return num - 1;
+}
+
+async function askText(question, hint = "") {
+  const hintStr = hint ? ` ${DI}${hint}${R}` : "";
+  return prompt(`    ${ARROW} ${question}${hintStr}: `);
+}
+
+// ─── Flag parser ──────────────────────────────────────────────────────────────
+function parseFlags(args) {
+  const flags = {
+    enableVector:   false,
+    vectorProvider: null,   // null = not yet specified
+    dryRun:         false,
+    force:          false,
+    projectName:    null,
+    repoRoot:       null,
+    yes:            false,
+    help:           false,
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i].toLowerCase();
+    switch (a) {
+      case "--enable-vector":
+      case "-enablevector":    flags.enableVector   = true; break;
+      case "--dry-run":
+      case "-dryrun":          flags.dryRun         = true; break;
+      case "--force":
+      case "-force":           flags.force          = true; break;
+      case "--yes": case "-y": flags.yes            = true; break;
+      case "--help": case "-h":flags.help           = true; break;
+      case "--vector-provider":
+      case "-vectorprovider":
+        flags.vectorProvider = args[++i]; break;
+      case "--project-name":
+      case "-projectname":
+        flags.projectName = args[++i]; break;
+      case "--repo-root":
+      case "-reporoot":
+        flags.repoRoot = args[++i]; break;
+      default:
+        // ignore unknown flags gracefully
+    }
   }
-  return mapped;
+  return flags;
 }
 
-if (wantsHelp) {
-  printHelp();
-  process.exit(0);
+// ─── Help ─────────────────────────────────────────────────────────────────────
+function printHelp(version) {
+  banner(version);
+  process.stdout.write(`${BO}Usage:${R}\n`);
+  process.stdout.write(`  npx @dinasor/mnemo-cli@latest [options]\n\n`);
+  process.stdout.write(`${BO}Options:${R}\n`);
+  const opt = (f, d) =>
+    process.stdout.write(`  ${CY}${padR(f, 32)}${R} ${DI}${d}${R}\n`);
+  opt("--enable-vector",              "Enable semantic vector search mode");
+  opt("--vector-provider <name>",     "Embedding provider: gemini | openai");
+  opt("--dry-run",                    "Preview without writing any files");
+  opt("--force",                      "Overwrite existing Mnemo files");
+  opt("--project-name <name>",        "Override the project name");
+  opt("--repo-root <path>",           "Target directory (default: cwd)");
+  opt("--yes / -y",                   "Non-interactive — skip wizard prompts");
+  opt("--help",                       "Show this help message");
+  process.stdout.write("\n");
+  process.stdout.write(`${BO}Examples:${R}\n`);
+  process.stdout.write(`  ${DI}# Interactive wizard (recommended first-time install)${R}\n`);
+  process.stdout.write(`  npx @dinasor/mnemo-cli@latest\n\n`);
+  process.stdout.write(`  ${DI}# Non-interactive with gemini vector mode${R}\n`);
+  process.stdout.write(`  npx @dinasor/mnemo-cli@latest --enable-vector --vector-provider gemini --yes\n\n`);
+  process.stdout.write(`  ${DI}# Dry-run to preview changes${R}\n`);
+  process.stdout.write(`  npx @dinasor/mnemo-cli@latest --dry-run\n\n`);
 }
 
-if (process.platform === "win32") {
-  const installer = path.join(packageRoot, "memory.ps1");
-  if (!fs.existsSync(installer)) {
-    fail(`Installer not found at ${installer}`);
+// ─── Installer arg builders ───────────────────────────────────────────────────
+function buildWindowsArgs(flags) {
+  const args = [];
+  if (flags.dryRun)         args.push("-DryRun");
+  if (flags.force)          args.push("-Force");
+  if (flags.enableVector)   args.push("-EnableVector");
+  if (flags.vectorProvider) args.push("-VectorProvider", flags.vectorProvider);
+  if (flags.projectName)    args.push("-ProjectName", flags.projectName);
+  args.push("-RepoRoot", flags.repoRoot || CWD);
+  return args;
+}
+
+function buildPosixArgs(flags) {
+  const args = [];
+  if (flags.dryRun)         args.push("--dry-run");
+  if (flags.force)          args.push("--force");
+  if (flags.enableVector)   args.push("--enable-vector");
+  if (flags.vectorProvider) args.push("--vector-provider", flags.vectorProvider);
+  if (flags.projectName)    args.push("--project-name", flags.projectName);
+  args.push("--repo-root", flags.repoRoot || CWD);
+  return args;
+}
+
+// ─── Main ─────────────────────────────────────────────────────────────────────
+async function main() {
+  const versionFile = path.join(PKG_ROOT, "VERSION");
+  const version     = fs.existsSync(versionFile)
+    ? fs.readFileSync(versionFile, "utf8").trim()
+    : "?";
+
+  const flags       = parseFlags(ARGV);
+  const interactive = !flags.yes && !!process.stdin.isTTY;
+
+  if (flags.help) {
+    printHelp(version);
+    process.exit(0);
+  }
+
+  banner(version);
+
+  // ── Step 1: Vector mode ────────────────────────────────────────────────────
+  let vectorMode = flags.enableVector;
+
+  if (!vectorMode && interactive) {
+    sectionHeader("Vector / Semantic Search Mode", 1, 3);
+    process.stdout.write(`  ${DI}Enables semantic vector recall via embedding model APIs.${R}\n`);
+    process.stdout.write(`  ${DI}Requires: Python 3.10+  ·  OpenAI or Gemini API key${R}\n\n`);
+    vectorMode = await askYesNo("Enable vector / semantic search mode?", false);
+    process.stdout.write("\n");
+  }
+
+  // ── Step 2: Provider ──────────────────────────────────────────────────────
+  let provider = flags.vectorProvider;
+
+  if (vectorMode && !provider && interactive) {
+    sectionHeader("Embedding Provider", 2, 3);
+    const choice = await askChoice("Which embedding provider do you want to use?", [
+      `${BGR}Gemini${R}     ${DI}GEMINI_API_KEY  ·  google-genai  (recommended)${R}`,
+      `${CY}OpenAI${R}     ${DI}OPENAI_API_KEY  ·  openai${R}`,
+    ], 0);
+    provider = choice === 0 ? "gemini" : "openai";
+    process.stdout.write("\n");
+  }
+
+  if (vectorMode && !provider) provider = "gemini"; // default
+
+  // ── Step 3: API key ───────────────────────────────────────────────────────
+  if (vectorMode && interactive) {
+    const keyName = provider === "gemini" ? "GEMINI_API_KEY" : "OPENAI_API_KEY";
+    const envVal  = process.env[keyName];
+    const dotEnv  = readDotEnv(flags.repoRoot || CWD);
+
+    const hasEnvKey    = isRealValue(envVal);
+    const hasDotEnvKey = isRealValue(dotEnv[keyName]);
+
+    if (hasEnvKey || hasDotEnvKey) {
+      sectionHeader("API Key", 3, 3);
+      const src = hasEnvKey ? "shell environment" : ".env file";
+      process.stdout.write(`  ${TICK} ${bold(keyName)} already present in ${src}\n\n`);
+    } else {
+      sectionHeader("API Key Setup", 3, 3);
+      process.stdout.write(`  ${WARN} ${bold(keyName)} is not set in your environment.\n\n`);
+
+      const choice = await askChoice(
+        "How do you want to provide the API key?",
+        [
+          `Enter key now     ${DI}→ appended to .env in project root${R}`,
+          `Skip (have .env)  ${DI}→ .env already contains the key${R}`,
+          `Skip for now      ${DI}→ set ${bold(keyName)} manually later${R}`,
+        ],
+        0,
+      );
+
+      process.stdout.write("\n");
+
+      if (choice === 0) {
+        const apiKey = (await askText(`Paste your ${bold(keyName)}`)).trim();
+        process.stdout.write("\n");
+        if (apiKey) {
+          appendDotEnv(flags.repoRoot || CWD, keyName, apiKey);
+          process.env[keyName] = apiKey;
+          process.stdout.write(`  ${TICK} Key appended to ${bold(".env")}\n`);
+        } else {
+          process.stdout.write(`  ${WARN} No key entered — set ${bold(keyName)} before using vector tools\n`);
+        }
+      } else if (choice === 1) {
+        process.stdout.write(`  ${TICK} Will load from ${bold(".env")} automatically\n`);
+      } else {
+        process.stdout.write(`  ${WARN} Skipped — set ${bold(keyName)} in your shell or .env before first use\n`);
+      }
+      process.stdout.write("\n");
+    }
+  }
+
+  // ── Dependency check ──────────────────────────────────────────────────────
+  const pythonInfo = findPython();
+  await runDependencyCheck(vectorMode, provider, pythonInfo);
+
+  // ── Run installer ─────────────────────────────────────────────────────────
+  flags.enableVector   = vectorMode;
+  if (vectorMode) flags.vectorProvider = provider;
+
+  divider();
+  process.stdout.write(`\n  ${BCY}${BO}Running Mnemo installer…${R}\n\n`);
+  divider();
+  process.stdout.write("\n");
+
+  let result;
+
+  if (IS_WIN) {
+    const installer = path.join(PKG_ROOT, "memory.ps1");
+    if (!fs.existsSync(installer)) {
+      process.stderr.write(`${CROSS} Installer not found: ${installer}\n`);
+      process.exit(1);
+    }
+    result = spawnSync(
+      "powershell",
+      ["-ExecutionPolicy", "Bypass", "-File", installer, ...buildWindowsArgs(flags)],
+      { stdio: "inherit" },
+    );
+  } else {
+    const installer = path.join(PKG_ROOT, "memory_mac.sh");
+    if (!fs.existsSync(installer)) {
+      process.stderr.write(`${CROSS} Installer not found: ${installer}\n`);
+      process.exit(1);
+    }
+    result = spawnSync("sh", [installer, ...buildPosixArgs(flags)], {
+      stdio: "inherit",
+    });
+  }
+
+  if (result.status === 0) {
+    successBox(vectorMode);
+    if (vectorMode) {
+      process.stdout.write(`  ${ARROW} Open your IDE, restart MCP, and run ${bold("vector_health")} → ${bold("vector_sync")}\n`);
+    }
+    process.stdout.write(`  ${ARROW} Use the ${bold("mnemo-codebase-optimizer")} skill to quickly seed memory for this codebase\n`);
+    process.stdout.write(`     ${DI}.cursor/skills/mnemo-codebase-optimizer/SKILL.md${R}\n`);
+    process.stdout.write("\n");
   }
 
-  const args = [
-    "-ExecutionPolicy",
-    "Bypass",
-    "-File",
-    installer,
-    ...mapWindowsArgs(rawArgs)
-  ];
-  const result = spawnSync("powershell", args, { stdio: "inherit" });
   process.exit(result.status ?? 1);
 }
 
-const installer = path.join(packageRoot, "memory_mac.sh");
-if (!fs.existsSync(installer)) {
-  fail(`Installer not found at ${installer}`);
-}
-const result = spawnSync("sh", [installer, ...mapPosixArgs(rawArgs)], {
-  stdio: "inherit"
+main().catch((err) => {
+  process.stderr.write(`\n${CROSS} Fatal error: ${err.message}\n`);
+  process.exit(1);
 });
-process.exit(result.status ?? 1);

package/memory_mac.sh

@@ -1862,6 +1862,17 @@ def _resolve_memory_root() -> Path:
     return script_repo / ".mnemo" / "memory"
 
 
+def _resolve_repo_root(memory_root: Path) -> Path:
+    root = memory_root.resolve()
+    if root.name == "memory" and root.parent.name in {".mnemo", ".cursor"}:
+        return root.parent.parent
+    cwd = Path.cwd().resolve()
+    for candidate in (cwd, *cwd.parents):
+        if candidate.joinpath(".mnemo", "memory").exists() or candidate.joinpath(".cursor", "memory").exists():
+            return candidate
+    return cwd
+
+
 def _parse_env_line(raw_line: str):
     line = raw_line.strip()
     if not line or line.startswith("#"):
@@ -1882,10 +1893,26 @@ def _parse_env_line(raw_line: str):
     return key, value
 
 
-def _load_project_env() -> None:
-    if os.getenv("GEMINI_API_KEY"):
-        return
-    env_path = Path(".env")
+def _is_missing_env_value(value):
+    if value is None:
+        return True
+    stripped = str(value).strip()
+    if not stripped:
+        return True
+    if stripped.startswith("${env:") and stripped.endswith("}"):
+        return True
+    return False
+
+
+def _get_env_value(name: str) -> str:
+    value = os.getenv(name)
+    if _is_missing_env_value(value):
+        return ""
+    return str(value).strip()
+
+
+def _load_project_env(repo_root: Path) -> None:
+    env_path = repo_root / ".env"
     if not env_path.exists():
         return
     try:
@@ -1894,16 +1921,28 @@ def _load_project_env() -> None:
             if not parsed:
                 continue
             key, value = parsed
-            os.environ.setdefault(key, value)
+            key = key.lstrip("\ufeff")
+            if _is_missing_env_value(os.getenv(key)):
+                os.environ[key] = value
     except OSError:
         pass
 
 
+def _resolve_provider() -> str:
+    configured = os.getenv("MNEMO_PROVIDER", "").strip().lower()
+    if configured.startswith("${env:") and configured.endswith("}"):
+        configured = ""
+    if configured in {"openai", "gemini"}:
+        return configured
+    return "gemini" if _get_env_value("GEMINI_API_KEY") else "openai"
+
+
 MEM_ROOT = _resolve_memory_root()
+REPO_ROOT = _resolve_repo_root(MEM_ROOT)
 _DB_OVERRIDE = os.getenv("MNEMO_DB_PATH", "").strip()
 DB_PATH = Path(_DB_OVERRIDE).expanduser().resolve() if _DB_OVERRIDE else (MEM_ROOT / "mnemo_vector.sqlite")
-_load_project_env()
-PROVIDER = os.getenv("MNEMO_PROVIDER", "gemini" if os.getenv("GEMINI_API_KEY") else "openai").lower()
+_load_project_env(REPO_ROOT)
+PROVIDER = _resolve_provider()
 
 SKIP_NAMES = {
     "README.md",
@@ -1930,14 +1969,14 @@ def _get_embed_client():
         return _EMBED_CLIENT
 
     if PROVIDER == "gemini":
-        key = os.getenv("GEMINI_API_KEY")
+        key = _get_env_value("GEMINI_API_KEY")
         if not key:
             raise RuntimeError("GEMINI_API_KEY is not set")
         from google import genai
         _EMBED_CLIENT = genai.Client(api_key=key)
         return _EMBED_CLIENT
 
-    key = os.getenv("OPENAI_API_KEY")
+    key = _get_env_value("OPENAI_API_KEY")
     if not key:
         raise RuntimeError("OPENAI_API_KEY is not set")
     from openai import OpenAI

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dinasor/mnemo-cli",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "Mnemo installer CLI for the current project folder.",
   "license": "MIT",
   "repository": {

package/scripts/memory/installer/templates/mnemo_vector.py

@@ -77,10 +77,26 @@ def _parse_env_line(raw_line: str) -> tuple[str, str] | None:
     return key, value
 
 
+def _is_missing_env_value(value: str | None) -> bool:
+    if value is None:
+        return True
+    stripped = value.strip()
+    if not stripped:
+        return True
+    # Cursor MCP placeholders can arrive as literal strings in some launches.
+    if stripped.startswith("${env:") and stripped.endswith("}"):
+        return True
+    return False
+
+
+def _get_env_value(name: str) -> str:
+    value = os.getenv(name)
+    if _is_missing_env_value(value):
+        return ""
+    return value.strip()
+
+
 def _load_project_env(repo_root: Path) -> None:
-    # Keep shell-provided values authoritative; only fill missing vars from .env.
-    if os.getenv("GEMINI_API_KEY"):
-        return
     env_path = repo_root / ".env"
     if not env_path.exists():
         return
@@ -90,17 +106,28 @@ def _load_project_env(repo_root: Path) -> None:
             if not parsed:
                 continue
             key, value = parsed
-            os.environ.setdefault(key, value)
+            key = key.lstrip("\ufeff")
+            if _is_missing_env_value(os.getenv(key)):
+                os.environ[key] = value
     except OSError:
         pass
 
 
+def _resolve_provider() -> str:
+    configured = os.getenv("MNEMO_PROVIDER", "").strip().lower()
+    if configured.startswith("${env:") and configured.endswith("}"):
+        configured = ""
+    if configured in {"openai", "gemini"}:
+        return configured
+    return "gemini" if _get_env_value("GEMINI_API_KEY") else "openai"
+
+
 MEM_ROOT = _resolve_memory_root()
 REPO_ROOT = _resolve_repo_root(MEM_ROOT)
 _load_project_env(REPO_ROOT)
 _DB_OVERRIDE = os.getenv("MNEMO_DB_PATH", "").strip()
 DB_PATH = Path(_DB_OVERRIDE).expanduser().resolve() if _DB_OVERRIDE else (MEM_ROOT / "mnemo_vector.sqlite")
-PROVIDER = os.getenv("MNEMO_PROVIDER", "gemini" if os.getenv("GEMINI_API_KEY") else "openai").lower()
+PROVIDER = _resolve_provider()
 
 SKIP_NAMES = {
     "README.md", "index.md", "lessons-index.json",
@@ -158,14 +185,14 @@ def _get_embed_client():
         return _EMBED_CLIENT
 
     if PROVIDER == "gemini":
-        key = os.getenv("GEMINI_API_KEY")
+        key = _get_env_value("GEMINI_API_KEY")
         if not key:
             raise RuntimeError("GEMINI_API_KEY is not set")
         from google import genai
         _EMBED_CLIENT = genai.Client(api_key=key)
         return _EMBED_CLIENT
 
-    key = os.getenv("OPENAI_API_KEY")
+    key = _get_env_value("OPENAI_API_KEY")
     if not key:
         raise RuntimeError("OPENAI_API_KEY is not set")
     from openai import OpenAI