@bcmyguest/openmem 0.0.0-stage → 0.8.0

package/cli/notebooklm-mcp.mjs

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+/**
+ * Opt-in stdio MCP: list/search notebooklm::* banks on the active memory provider.
+ * Config: ~/.hindsight/coding-agent.json (notebooklmAccess); API from MEMORY_PROVIDER + stack env.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { isMainModule } from "./is-main.mjs";
+import { resolveMcpContext } from "./mcp/context.mjs";
+import { listNotebooklmBanks, searchNotebooklmBank } from "./mcp/notebooklm-provider.mjs";
+import { resolveStackRoot } from "./stack.mjs";
+
+export { PREFIX, bankAllowed, filterNotebooklmBanks, isNotebooklmBank, notebooklmSlug } from "./mcp/notebooklm-banks.mjs";
+export { listBanks, listMemories, recallBank } from "./mcp/notebooklm-hindsight-rest.mjs";
+
+export const DEFAULT_API_URL = "http://127.0.0.1:8888";
+export const DEFAULT_CONFIG = path.join(os.homedir(), ".hindsight", "coding-agent.json");
+
+/** @param {Record<string, any> | null | undefined} cfg */
+export function resolveAccess(cfg) {
+  const access = cfg?.notebooklmAccess && typeof cfg.notebooklmAccess === "object" ? cfg.notebooklmAccess : {};
+  return {
+    enabled: access.enabled === true,
+    banks: Array.isArray(access.banks) && access.banks.length ? access.banks.map(String) : ["*"],
+    apiUrl: String(cfg?.apiUrl || DEFAULT_API_URL).replace(/\/$/, ""),
+  };
+}
+
+export function loadCodingAgentConfig(configPath = DEFAULT_CONFIG) {
+  return JSON.parse(fs.readFileSync(configPath, "utf8"));
+}
+
+import { bankAllowed } from "./mcp/notebooklm-banks.mjs";
+
+const TOOLS = [
+  {
+    name: "notebooklm_list_banks",
+    description:
+      "List notebooklm::* banks on the active memory provider (filtered by notebooklmAccess.banks). Returns bank_id and fact_count.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  },
+  {
+    name: "notebooklm_search",
+    description:
+      "Search one allowlisted notebooklm::* bank. Default mode=list is fast full-text (memories/list, no LLM). " +
+      "Use mode=recall only when you need Hindsight LLM synthesis — often 30–90s on CPU and may hit MCP timeouts. " +
+      "Prefer short keyword queries (e.g. \"time series\") over long phrases. Read-only.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        bank_id: { type: "string", description: "e.g. notebooklm::my-notebook" },
+        query: { type: "string", description: "Full-text keywords (list) or natural-language (recall)" },
+        mode: {
+          type: "string",
+          enum: ["list", "recall"],
+          description: "list (default, fast) or recall (LLM, slow)",
+        },
+        limit: { type: "integer", description: "list mode page size (default 20)" },
+      },
+      required: ["bank_id", "query"],
+      additionalProperties: false,
+    },
+  },
+];
+
+function textResult(value, isError = false) {
+  const text = typeof value === "string" ? value : JSON.stringify(value, null, 2);
+  return { content: [{ type: "text", text }], isError };
+}
+
+/** @param {{ apiUrl: string, banks: string[], enabled?: boolean, ctx?: import("./mcp/context.mjs").McpContext }} access @param {string} name @param {Record<string, unknown>} [args] @param {typeof fetch} [fetchFn] */
+export async function callTool(access, name, args = {}, fetchFn = fetch) {
+  if (access.enabled !== true) {
+    return textResult(
+      "notebooklmAccess.enabled is not true in coding-agent.json; " +
+        "set notebooklmAccess.enabled to true (and keep ~/.hindsight/coding-agent.json as a real file, not a symlink to the shipped template).",
+      true,
+    );
+  }
+  if (!access.ctx) return textResult("MCP context not initialized (internal error)", true);
+  if (name === "notebooklm_list_banks") {
+    const filtered = await listNotebooklmBanks(access.ctx, access.banks, fetchFn);
+    return textResult({ banks: filtered, count: filtered.length, provider: access.ctx.provider });
+  }
+  if (name === "notebooklm_search") {
+    const bankId = String(args.bank_id || "");
+    const query = String(args.query || "");
+    const mode = String(args.mode || "list").toLowerCase() === "recall" ? "recall" : "list";
+    if (!bankId || !query) return textResult("bank_id and query are required", true);
+    if (!bankAllowed(bankId, access.banks)) {
+      return textResult(`bank not allowlisted or not a notebooklm::* bank: ${bankId}`, true);
+    }
+    const limit = args.limit != null ? Number(args.limit) : 20;
+    const payload = await searchNotebooklmBank(
+      access.ctx,
+      { bankId, query, mode, limit, hindsightApiUrl: access.apiUrl },
+      fetchFn,
+    );
+    return textResult(payload);
+  }
+  return textResult(`unknown tool: ${name}`, true);
+}
+
+/** @param {Record<string, any>} msg @param {{ apiUrl: string, banks: string[] }} access @param {typeof fetch} [fetchFn] */
+export async function handleMessage(msg, access, fetchFn = fetch) {
+  const { id, method, params } = msg;
+  if (method === "initialize") {
+    // Echo client protocol (Cursor Agent uses 2025-11-25); fall back for older clients.
+    const protocolVersion =
+      typeof params?.protocolVersion === "string" && params.protocolVersion
+        ? params.protocolVersion
+        : "2024-11-05";
+    return {
+      jsonrpc: "2.0",
+      id,
+      result: {
+        protocolVersion,
+        capabilities: { tools: {} },
+        serverInfo: { name: "notebooklm", version: "0.1.0" },
+      },
+    };
+  }
+  if (method === "notifications/initialized" || method === "initialized") return null;
+  if (method === "tools/list") return { jsonrpc: "2.0", id, result: { tools: TOOLS } };
+  if (method === "tools/call") {
+    try {
+      return { jsonrpc: "2.0", id, result: await callTool(access, params?.name, params?.arguments || {}, fetchFn) };
+    } catch (err) {
+      return { jsonrpc: "2.0", id, result: textResult(err instanceof Error ? err.message : String(err), true) };
+    }
+  }
+  if (method === "ping") return { jsonrpc: "2.0", id, result: {} };
+  if (id === undefined) return null;
+  return { jsonrpc: "2.0", id, error: { code: -32601, message: `Method not found: ${method}` } };
+}
+
+/** @param {"ndjson" | "content-length"} framing */
+function writeMessage(obj, framing = "ndjson") {
+  if (obj == null) return;
+  const body = JSON.stringify(obj);
+  // Cursor Agent CLI speaks NDJSON on stdio (same as Hindsight MCP). Content-Length is kept for LSP-style clients.
+  if (framing === "content-length") {
+    process.stdout.write(`Content-Length: ${Buffer.byteLength(body, "utf8")}\r\n\r\n${body}`);
+    return;
+  }
+  process.stdout.write(`${body}\n`);
+}
+
+/** Content-Length frames or NDJSON; reply using the same framing the request used. */
+export async function serveStdio(input, onMsg) {
+  let buf = Buffer.alloc(0);
+  for await (const chunk of input) {
+    buf = Buffer.concat([buf, Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)]);
+    while (buf.length) {
+      const asStr = buf.toString("utf8");
+      const crlf = asStr.indexOf("\r\n\r\n");
+      const lf = asStr.indexOf("\n\n");
+      const headerEnd = crlf >= 0 ? crlf : lf;
+      const sepLen = crlf >= 0 ? 4 : lf >= 0 ? 2 : -1;
+      if (sepLen > 0 && /content-length\s*:/i.test(asStr.slice(0, headerEnd))) {
+        const m = /Content-Length:\s*(\d+)/i.exec(asStr.slice(0, headerEnd));
+        if (!m) {
+          buf = buf.subarray(Buffer.byteLength(asStr.slice(0, headerEnd + sepLen), "utf8"));
+          continue;
+        }
+        const len = Number(m[1]);
+        const headerBytes = Buffer.byteLength(asStr.slice(0, headerEnd + sepLen), "utf8");
+        if (buf.length < headerBytes + len) break;
+        const body = buf.subarray(headerBytes, headerBytes + len).toString("utf8");
+        buf = buf.subarray(headerBytes + len);
+        let msg;
+        try {
+          msg = JSON.parse(body);
+        } catch (err) {
+          writeMessage(
+            {
+              jsonrpc: "2.0",
+              id: null,
+              error: { code: -32700, message: `Parse error: ${err instanceof Error ? err.message : err}` },
+            },
+            "content-length",
+          );
+          continue;
+        }
+        writeMessage(await onMsg(msg), "content-length");
+        continue;
+      }
+      const nl = asStr.indexOf("\n");
+      if (nl < 0) break;
+      const line = asStr.slice(0, nl).trim();
+      buf = buf.subarray(Buffer.byteLength(asStr.slice(0, nl + 1), "utf8"));
+      if (!line.startsWith("{")) continue;
+      try {
+        writeMessage(await onMsg(JSON.parse(line)), "ndjson");
+      } catch {
+        /* skip bad line */
+      }
+    }
+  }
+}
+
+async function main() {
+  const pkgRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+  const configPath = process.env.HINDSIGHT_CODING_AGENT_JSON || DEFAULT_CONFIG;
+  let cfg = null;
+  let access;
+  try {
+    cfg = loadCodingAgentConfig(configPath);
+    access = resolveAccess(cfg);
+    const home = process.env.HOME || os.homedir();
+    const stack = resolveStackRoot({ pkgRoot, env: process.env, home });
+    access.ctx = resolveMcpContext({ home, stackRoot: stack.root, repoRoot: pkgRoot, env: process.env });
+  } catch (err) {
+    // Stay alive so Cursor's MCP client does not report "Connection closed".
+    // Tools return isError until coding-agent.json is readable.
+    console.error(`notebooklm-mcp: cannot read ${configPath}: ${err instanceof Error ? err.message : err}`);
+    access = { enabled: false, banks: ["*"], apiUrl: DEFAULT_API_URL, ctx: null };
+  }
+  if (!access.enabled) {
+    console.error(
+      "notebooklm-mcp: notebooklmAccess.enabled is not true; tools will error until it is enabled " +
+        `(config: ${configPath}).`,
+    );
+  }
+  process.stdin.resume();
+  await serveStdio(process.stdin, (msg) => handleMessage(msg, access));
+}
+
+if (isMainModule(import.meta.url)) {
+  main().catch((err) => {
+    console.error(`notebooklm-mcp: ${err instanceof Error ? err.message : err}`);
+    process.exit(1);
+  });
+}

package/cli/openmem-mcp.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+/**
+ * Unified openmem MCP: stable memory_* tools delegating to the active provider.
+ *
+ *   openmem-mcp
+ *   node cli/openmem-mcp.mjs
+ *
+ * Provider: MEMORY_PROVIDER → ~/.config/hindsight/wizard.conf → hindsight.
+ * Stack/env resolution matches install-mcp (HINDSIGHT_URL, mem0 URL + key file, Cognee URL).
+ */
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { isMainModule } from "./is-main.mjs";
+import { resolveMcpContext } from "./mcp/context.mjs";
+import { startContextStore } from "./mcp/context-store.mjs";
+import { handleUnifiedMessage } from "./mcp/memory-facade.mjs";
+import { serveStdio } from "./mcp/stdio.mjs";
+import { resolveStackRoot } from "./stack.mjs";
+
+const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+async function main() {
+  const home = process.env.HOME || os.homedir();
+  const stack = resolveStackRoot({ pkgRoot: PKG_ROOT, env: process.env, home });
+  const ctx = resolveMcpContext({ home, stackRoot: stack.root, repoRoot: PKG_ROOT, env: process.env });
+  // Session-file TTL cleanup (docs/context-store.md, "Retention"), at most once a day; never throws.
+  await startContextStore(process.env, { home, stackRoot: stack.root });
+  process.stdin.resume();
+  await serveStdio(process.stdin, (msg) => handleUnifiedMessage(msg, ctx));
+}
+
+if (isMainModule(import.meta.url)) {
+  main().catch((err) => {
+    console.error(`openmem-mcp: ${err instanceof Error ? err.message : err}`);
+    process.exit(1);
+  });
+}

package/cli/openmem.mjs

@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+/**
+ * openmem: npx entry point for the memory-stack setup wizard.
+ *
+ *   openmem [setup|configure|up|down|doctor|providers|init|context|--help|--version]
+ *
+ * The wizard code runs from this package (read-only, may be an npx cache). Everything it
+ * writes, and the compose files it drives, live in a stable stack root; see cli/stack.mjs.
+ * Real file, not a symlink: npm drops symlinks.
+ */
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { changedCount, formatReport, resolveStackRoot, syncStack } from "./stack.mjs";
+
+const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const pkg = JSON.parse(fs.readFileSync(path.join(PKG_ROOT, "package.json"), "utf8"));
+// The only place the CLI learns the package name; the bin name is a command, not the package.
+const BIN = "openmem";
+
+const HELP = `${BIN} ${pkg.version}: set up and run a self-hosted AI memory stack (docker compose).
+
+Usage (prefer npx once published: npx ${BIN} <command>):
+  ${BIN}                       interactive setup (same as: ${BIN} setup)
+  ${BIN} setup [flags]         interactive setup; flags go to the wizard (--yes, --dry-run, ...)
+  ${BIN} configure [flags]     non-interactive setup and start (wizard --yes)
+  ${BIN} up [flags]            start the stack with the saved configuration
+  ${BIN} down [flags]          stop the stack
+  ${BIN} doctor [flags]        validate the configuration without the smoke test
+  ${BIN} wiring [--json]       report provider, API URLs, and MCP alignment
+  ${BIN} feed-sync             fetch RSS/OpenAlex into feeds.out_dir (then indexer watches it)
+  ${BIN} schedule <install|remove> [--dry-run]  manage hourly feed sync with the OS scheduler
+  ${BIN} install-mcp [flags]   merge memory MCP servers into ~/.cursor/mcp.json
+  ${BIN} install-coding-agent [flags]  Hindsight plugin or MCP session path (Claude/Codex/OpenCode/Cursor)
+  ${BIN} context <on|off|status> [--dry-run]
+                               context management (smart compaction): config, agent wiring, proxy service
+  ${BIN} switch <provider> [flags]
+                               change MEMORY_PROVIDER (stack + MCP; no data migration)
+  ${BIN} providers [--json]    list memory providers and their status
+  ${BIN} init [--force] [--dry-run] [--json]
+                               create or upgrade the stack root without running the wizard
+  ${BIN} --version | --help
+
+Flags starting with "-" after no command are passed to the wizard: ${BIN} --dry-run --yes
+Run "${BIN} setup --help" for the wizard flags.
+
+Stack root (where .env, compose files and generated config live):
+  $PM_STACK_ROOT, else \${XDG_DATA_HOME:-~/.local/share}/personal-memory/stack
+  PM_USE_CHECKOUT=1 uses this package directory itself (a git checkout does so automatically).
+Upgrades overwrite only shipped files you did not modify; modified ones are reported as conflicts.
+Docs: docs/npx-install.md`;
+
+const WIZARD_TASKS = new Set(["configure", "up", "down", "doctor", "install-mcp", "install-coding-agent", "switch"]);
+
+/** @param {string} msg */
+function die(msg, code = 1) {
+  console.error(`${BIN}: ${msg}`);
+  process.exit(code);
+}
+
+/**
+ * Provider manifests shipped in the package.
+ *
+ * @returns {{ id: string, status: string, label: string, notes?: string }[]}
+ */
+function readProviders() {
+  const dir = path.join(PKG_ROOT, "providers");
+  /** @type {{ id: string, status: string, label: string, notes?: string }[]} */
+  const out = [];
+  let names = [];
+  try {
+    names = fs.readdirSync(dir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name).sort();
+  } catch {
+    return out;
+  }
+  for (const id of names) {
+    const file = path.join(dir, id, "manifest.json");
+    if (!fs.existsSync(file)) continue;
+    try {
+      const m = JSON.parse(fs.readFileSync(file, "utf8"));
+      out.push({ id: m.id || id, status: m.status || "unknown", label: m.label || id, notes: m.notes });
+    } catch {
+      out.push({ id, status: "invalid", label: `unreadable ${file}` });
+    }
+  }
+  return out;
+}
+
+/** @param {string[]} args */
+function cmdProviders(args) {
+  const list = readProviders();
+  if (args.includes("--json")) {
+    console.log(JSON.stringify(list, null, 2));
+    return;
+  }
+  const w = Math.max(2, ...list.map((p) => p.id.length));
+  console.log(`${"ID".padEnd(w)}  ${"STATUS".padEnd(12)}  LABEL`);
+  for (const p of list) console.log(`${p.id.padEnd(w)}  ${p.status.padEnd(12)}  ${p.label}`);
+  if (!list.length) console.log("(no provider manifests found)");
+}
+
+/**
+ * Materialize the stack root (no-op for a checkout).
+ *
+ * @param {{ force?: boolean, dryRun?: boolean, quiet?: boolean, json?: boolean }} [opts]
+ */
+function ensureStack(opts = {}) {
+  const sr = resolveStackRoot({ pkgRoot: PKG_ROOT });
+  if (!sr.copy) return { sr, report: null };
+  let report;
+  try {
+    report = syncStack({
+      pkgRoot: PKG_ROOT,
+      stackRoot: sr.root,
+      name: pkg.name,
+      version: pkg.version,
+      force: opts.force,
+      dryRun: opts.dryRun,
+    });
+  } catch (e) {
+    die(`cannot prepare the stack root ${sr.root}: ${/** @type {Error} */ (e).message}`);
+  }
+  if (!opts.quiet && !opts.json && (changedCount(report) || report.conflicts.length)) {
+    for (const line of formatReport(report)) console.error(line);
+  }
+  return { sr, report };
+}
+
+/** @param {string[]} args */
+function cmdInit(args) {
+  const force = args.includes("--force");
+  const dryRun = args.includes("--dry-run");
+  const json = args.includes("--json");
+  for (const a of args) {
+    if (!["--force", "--dry-run", "--json"].includes(a)) die(`init: unknown option ${a}`, 2);
+  }
+  const { sr, report } = ensureStack({ force, dryRun, json, quiet: true });
+  if (json) {
+    console.log(JSON.stringify({ stackRoot: sr.root, mode: sr.mode, source: sr.source, report }, null, 2));
+    return;
+  }
+  if (!report) {
+    console.log(`stack root: ${sr.root} (${sr.source}; used in place, nothing copied)`);
+    return;
+  }
+  for (const line of formatReport(report)) console.log(line);
+}
+
+/**
+ * Run a wizard script from the package against the stack root.
+ *
+ * @param {string} script path relative to the package root
+ * @param {string[]} args
+ * @param {string} stackRoot
+ */
+function runWizardScript(script, args, stackRoot) {
+  const r = spawnSync(process.execPath, [path.join(PKG_ROOT, script), ...args], {
+    cwd: stackRoot,
+    stdio: "inherit",
+    env: { ...process.env, PM_STACK_ROOT: stackRoot, PM_PACKAGE_ROOT: PKG_ROOT },
+  });
+  if (r.error) die(`failed to start the wizard: ${r.error.message}`);
+  if (r.signal) process.kill(process.pid, r.signal);
+  process.exit(r.status ?? 1);
+}
+
+const argv = process.argv.slice(2);
+const cmd = argv[0];
+
+if (cmd === "--version" || cmd === "-v" || cmd === "version") {
+  console.log(pkg.version);
+} else if (cmd === "--help" || cmd === "-h" || cmd === "help") {
+  console.log(HELP);
+} else if (cmd === "providers") {
+  cmdProviders(argv.slice(1));
+} else if (cmd === "init") {
+  cmdInit(argv.slice(1));
+} else if (cmd === "feed-sync") {
+  const r = spawnSync(process.execPath, [path.join(PKG_ROOT, "cli/feed-sync.mjs"), ...argv.slice(1)], {
+    stdio: "inherit",
+    env: process.env,
+  });
+  process.exit(r.status ?? 1);
+} else if (cmd === "schedule") {
+  const r = spawnSync(process.execPath, [path.join(PKG_ROOT, "cli/schedule.mjs"), ...argv.slice(1)], {
+    stdio: "inherit",
+    env: process.env,
+  });
+  process.exit(r.status ?? 1);
+} else if (cmd === "context") {
+  // on/off run compose from the stack root, so materialize it first.
+  const { sr } = ensureStack({ quiet: true });
+  const r = spawnSync(process.execPath, [path.join(PKG_ROOT, "cli/context-management.mjs"), ...argv.slice(1)], {
+    stdio: "inherit",
+    env: { ...process.env, PM_STACK_ROOT: sr.root },
+  });
+  process.exit(r.status ?? 1);
+} else if (cmd === "wiring") {
+  const r = spawnSync(process.execPath, [path.join(PKG_ROOT, "cli/wiring-report.mjs"), ...argv.slice(1)], {
+    stdio: "inherit",
+    env: process.env,
+  });
+  process.exit(r.status ?? 1);
+} else if (cmd === undefined || cmd === "setup" || cmd.startsWith("-")) {
+  const args = cmd === "setup" ? argv.slice(1) : argv;
+  // Wizard help does not need a stack root.
+  if (args.includes("--help") || args.includes("-h")) {
+    const sr = resolveStackRoot({ pkgRoot: PKG_ROOT });
+    runWizardScript("wizard/bin/setup.mjs", args, fs.existsSync(sr.root) ? sr.root : PKG_ROOT);
+  } else {
+    const { sr } = ensureStack();
+    runWizardScript("wizard/bin/setup.mjs", args, sr.root);
+  }
+} else if (WIZARD_TASKS.has(cmd)) {
+  const { sr } = ensureStack();
+  runWizardScript("wizard/bin/pm.mjs", argv, sr.root);
+} else {
+  console.error(`${BIN}: unknown command: ${cmd}\n`);
+  console.error(HELP);
+  process.exit(2);
+}

package/cli/roots.mjs

@@ -0,0 +1,85 @@
+/**
+ * Shared root and dependency handling for wizard/bin/setup.mjs and wizard/bin/pm.mjs.
+ *
+ * Contract (see docs/npx-install.md):
+ *   PM_STACK_ROOT    mutable stack root = the wizard's ctx.repoRoot (compose project dir,
+ *                    .env, generated files, docker build context)
+ *   PM_PACKAGE_ROOT  read-only code root (providers/ manifests and hooks, scripts/setup.mjs,
+ *                    wizard/lib)
+ * Unset, both default to the checkout root derived from the bin file's location.
+ *
+ * Node builtins only: this module runs before the wizard dependencies are verified.
+ */
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Compute both roots from the location of a file in wizard/bin and export them to the
+ * environment so child processes (scripts/setup.mjs, docker compose helpers) see them.
+ *
+ * @param {string} binFileUrl import.meta.url of wizard/bin/<file>.mjs
+ * @returns {{ pkgRoot: string, repo: string, packaged: boolean }}
+ */
+export function resolveWizardRoots(binFileUrl) {
+  const here = path.dirname(fileURLToPath(binFileUrl));
+  const derived = path.resolve(here, "../..");
+  const pkgRoot = path.resolve(process.env.PM_PACKAGE_ROOT || derived);
+  const repo = path.resolve(process.env.PM_STACK_ROOT || derived);
+  const packaged = derived.split(path.sep).includes("node_modules");
+  if (packaged && !process.env.PM_STACK_ROOT) {
+    console.error(
+      "openmem: this copy lives in an npm package directory, which is read-only and\n" +
+        "may be garbage-collected. Run it through the CLI instead (it sets up a stable stack root):\n" +
+        "  npx openmem   |   openmem   |   PM_STACK_ROOT=<dir> to choose one",
+    );
+    process.exit(1);
+  }
+  process.env.PM_PACKAGE_ROOT = pkgRoot;
+  process.env.PM_STACK_ROOT = repo;
+  return { pkgRoot, repo, packaged };
+}
+
+/**
+ * Is `name` resolvable from a file inside `fromDir`? Checks node_modules lookup
+ * directories on disk, so it works for ESM-only packages and hoisted installs.
+ *
+ * @param {string} fromDir
+ * @param {string} name
+ */
+function resolvable(fromDir, name) {
+  const req = createRequire(path.join(fromDir, "noop.js"));
+  const dirs = req.resolve.paths(name) || [];
+  return dirs.some((d) => fs.existsSync(path.join(d, name, "package.json")));
+}
+
+/**
+ * Make sure the wizard dependencies resolve. Packaged installs get them from npm; a
+ * checkout runs `npm install` once at the checkout root.
+ *
+ * @param {string} pkgRoot
+ * @param {boolean} packaged
+ */
+export function ensureWizardDeps(pkgRoot, packaged) {
+  const wizardDir = path.join(pkgRoot, "wizard", "bin");
+  const needed = ["@clack/prompts", "@iarna/toml"];
+  const missing = needed.filter((n) => !resolvable(wizardDir, n));
+  if (!missing.length) return;
+  if (packaged || !fs.existsSync(path.join(pkgRoot, "package.json"))) {
+    console.error(
+      `openmem: missing dependencies (${missing.join(", ")}); reinstall the package.`,
+    );
+    process.exit(1);
+  }
+  if (process.stderr.isTTY) process.stderr.write("Installing setup dependencies...\n");
+  const r = spawnSync("npm", ["install", "--no-fund", "--no-audit"], {
+    cwd: pkgRoot,
+    stdio: "inherit",
+  });
+  if (r.status !== 0) {
+    console.error(`npm install failed in ${pkgRoot}; run it there by hand`);
+    process.exit(r.status ?? 1);
+  }
+}