@bcmyguest/openmem 0.0.0-stage → 0.8.0

package/providers/hindsight/lib/meridian.mjs

@@ -0,0 +1,307 @@
+/**
+ * Detect-only "Claude subscription (Meridian)" backend: probe a Meridian proxy the user
+ * already runs, write the LiteLLM route from docs/meridian-litellm.md, and keep
+ * MERIDIAN_API_KEY in litellm.env. The wizard never installs or starts Meridian.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fetchStatus, openAiModelIds } from "./probe.mjs";
+import { ensureLitellmEnv } from "./stack-env.mjs";
+import { storedOr } from "./state.mjs";
+
+/** @typedef {import("../../../wizard/lib/provider-wizard/helpers.mjs").ProviderWizardHelpers} Helpers */
+
+export const MERIDIAN_DEFAULT_PORT = "3456";
+export const MERIDIAN_DEFAULT_BASE = `http://127.0.0.1:${MERIDIAN_DEFAULT_PORT}`;
+/** Guide defaults (docs/meridian-litellm.md#route-file). */
+export const MERIDIAN_RETAIN_DEFAULT = "claude-haiku-5-5";
+export const MERIDIAN_REFLECT_DEFAULT = "claude-sonnet-5-5";
+export const MERIDIAN_TERMS_URL = "https://www.anthropic.com/legal/consumer-terms";
+export const MERIDIAN_GUIDE = "docs/meridian-litellm.md";
+/** litellm.env value when Meridian runs without a key; LiteLLM still needs a non-empty one. */
+export const MERIDIAN_NO_KEY = "placeholder";
+
+const BRIDGE_TIMEOUT_MS = 2000;
+const PROBE_TIMEOUT_MS = 5000;
+
+/** IPv4 address of the default Docker bridge (docker0), which `host-gateway` resolves to. */
+export function dockerBridgeIp() {
+  const nics = os.networkInterfaces().docker0 || [];
+  const v4 = nics.find((n) => n.family === "IPv4" || n.family === 4);
+  return v4 ? v4.address : "";
+}
+
+/** @param {string} base */
+export function normalizeMeridianBase(base) {
+  return base.trim().replace(/\/+$/, "").replace(/\/v1$/, "");
+}
+
+/** @param {string} hostname */
+function isLoopback(hostname) {
+  return hostname === "localhost" || hostname === "[::1]" || hostname.startsWith("127.");
+}
+
+/** @param {URL} u */
+function portOf(u) {
+  return u.port || (u.protocol === "https:" ? "443" : "80");
+}
+
+/**
+ * The api_base the LiteLLM container uses: host.docker.internal for a loopback URL,
+ * otherwise the URL itself. No /v1: LiteLLM appends /v1/messages.
+ * @param {string} hostBase
+ */
+export function containerApiBase(hostBase) {
+  const u = new URL(hostBase);
+  if (!isLoopback(u.hostname)) return `${u.protocol}//${u.host}`;
+  return `http://host.docker.internal:${portOf(u)}`;
+}
+
+/**
+ * First usable model: a valid candidate, else `preferred` when listed, else the first id
+ * matching `family`, else the first id, else `preferred`.
+ * @param {string[]} ids ids from Meridian's /v1/models (may be empty)
+ * @param {string} preferred
+ * @param {RegExp} family
+ * @param {string[]} candidates explicit or stored choices, in priority order
+ */
+export function pickModel(ids, preferred, family, candidates = []) {
+  const valid = (m) => Boolean(m) && (ids.length ? ids.includes(m) : m.startsWith("claude-"));
+  const hit = candidates.find(valid);
+  if (hit) return hit;
+  if (!ids.length || ids.includes(preferred)) return preferred;
+  return ids.find((id) => family.test(id)) || ids[0];
+}
+
+/**
+ * Where an existing Meridian key comes from: the environment, Meridian's own env file
+ * (the guide's ~/.config/meridian/meridian.env), or litellm.env.
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ * @returns {{ key: string, source: string }}
+ */
+export function existingMeridianKey(ctx, h) {
+  if (process.env.MERIDIAN_API_KEY) {
+    return { key: process.env.MERIDIAN_API_KEY, source: "MERIDIAN_API_KEY from the environment" };
+  }
+  const fromMeridian = h.envValue(ctx.meridianEnvFile, "MERIDIAN_API_KEY");
+  if (fromMeridian) return { key: fromMeridian, source: ctx.meridianEnvFile };
+  const fromLitellm = h.envValue(ctx.litellmEnv, "MERIDIAN_API_KEY");
+  if (fromLitellm && fromLitellm !== MERIDIAN_NO_KEY) return { key: fromLitellm, source: ctx.litellmEnv };
+  return { key: "", source: "" };
+}
+
+/**
+ * Probe Meridian from the host: /health (open), /v1/models (needs the key when set), and
+ * /health on the Docker bridge address to tell a loopback-only bind from 0.0.0.0.
+ * @param {string} base host URL without /v1
+ * @param {string} key MERIDIAN_API_KEY or ""
+ * @param {string} bridgeIp docker0 IPv4, or "" when unknown
+ */
+export async function probeMeridian(base, key, bridgeIp) {
+  const headers = key ? { "x-api-key": key } : {};
+  const health = await fetchStatus(`${base}/health`, { timeoutMs: PROBE_TIMEOUT_MS });
+  const models = await fetchStatus(`${base}/v1/models`, { headers, timeoutMs: PROBE_TIMEOUT_MS });
+  const u = new URL(base);
+  /** @type {"ok"|"unreachable"|"unknown"|"n/a"} */
+  let bridge = "n/a";
+  const answered = health.status > 0 || models.status > 0;
+  if (answered && isLoopback(u.hostname)) {
+    if (!bridgeIp) bridge = "unknown";
+    else {
+      const viaBridge = await fetchStatus(`http://${bridgeIp}:${portOf(u)}/health`, {
+        timeoutMs: BRIDGE_TIMEOUT_MS,
+      });
+      bridge = viaBridge.status > 0 ? "ok" : "unreachable";
+    }
+  }
+  return {
+    answered,
+    healthOk: health.status >= 200 && health.status < 300,
+    modelsStatus: models.status,
+    ids: models.status === 200 ? openAiModelIds(models.json) : [],
+    bridge,
+  };
+}
+
+/** @param {string[]} names @param {Helpers} h */
+function showModels(names, h) {
+  for (const n of names) h.info(`      ${n}`);
+}
+
+/**
+ * What the probe says about reachability from the LiteLLM container.
+ * @param {{ meridianBase: string, apiBase: string, dockerBridgeIp: string, meridianEnvFile: string }} ctx
+ * @param {(file: string, key: string) => string} envValue
+ * @param {Awaited<ReturnType<typeof probeMeridian>>} probe
+ * @returns {{ level: "ok"|"warn"|"info", text: string } | null}
+ */
+export function bridgeReport(ctx, envValue, probe) {
+  const u = new URL(ctx.meridianBase);
+  const port = portOf(u);
+  const bindHint = `Restart Meridian with MERIDIAN_HOST=0.0.0.0 (${MERIDIAN_GUIDE}#run-meridian).`;
+  const declaredHost = process.env.MERIDIAN_HOST || envValue(ctx.meridianEnvFile, "MERIDIAN_HOST");
+  if (probe.bridge === "ok") {
+    return {
+      level: "ok",
+      text: `Meridian also answers on the Docker bridge address ${ctx.dockerBridgeIp}:${port}; LiteLLM calls ${ctx.apiBase}. A firewall can still block containers; run the guide's smoke test.`,
+    };
+  }
+  if (probe.bridge === "unreachable") {
+    return {
+      level: "warn",
+      text: `Meridian answers on ${u.host} but not on the Docker bridge address ${ctx.dockerBridgeIp}:${port}: it binds 127.0.0.1 only, so the LiteLLM container cannot reach ${ctx.apiBase}. ${bindHint}`,
+    };
+  }
+  if (declaredHost && isLoopback(declaredHost)) {
+    return {
+      level: "warn",
+      text: `MERIDIAN_HOST is ${declaredHost}: the LiteLLM container cannot reach a loopback-only Meridian. ${bindHint}`,
+    };
+  }
+  if (isLoopback(u.hostname)) {
+    return {
+      level: "info",
+      text: `LiteLLM calls Meridian at ${ctx.apiBase}. On Linux, a Meridian bound to 127.0.0.1 (its default) is unreachable from the container; run it with MERIDIAN_HOST=0.0.0.0.`,
+    };
+  }
+  return null;
+}
+
+/**
+ * Interactive and --yes Meridian questions. Fills ctx.meridianBase, ctx.meridianKey,
+ * ctx.apiBase, ctx.model and ctx.reflectModel.
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+export async function chooseMeridian(ctx, h) {
+  h.info(`The wizard does not install or start Meridian; see ${MERIDIAN_GUIDE}.`);
+  if (ctx.dockerBridgeIp === undefined) ctx.dockerBridgeIp = dockerBridgeIp();
+  const port = h.envValue(ctx.meridianEnvFile, "MERIDIAN_PORT") || MERIDIAN_DEFAULT_PORT;
+  const defaultBase =
+    process.env.MERIDIAN_BASE ||
+    storedOr(ctx, h, "meridian", "MEMORY_MERIDIAN_URL", `http://127.0.0.1:${port}`);
+  ctx.meridianBase = normalizeMeridianBase(await h.ask(ctx, "Meridian URL from this host", defaultBase));
+  try {
+    ctx.apiBase = containerApiBase(ctx.meridianBase);
+  } catch {
+    h.die(`not a URL: ${ctx.meridianBase}`);
+  }
+
+  const existing = existingMeridianKey(ctx, h);
+  const typed = await h.ask(
+    ctx,
+    `MERIDIAN_API_KEY (typed input is visible; blank uses ${existing.source || "no key"})`,
+    "",
+  );
+  ctx.meridianKey = typed || existing.key;
+
+  const probe = await probeMeridian(ctx.meridianBase, ctx.meridianKey, ctx.dockerBridgeIp);
+  if (!probe.answered) {
+    h.warn(
+      `Meridian is not answering on ${ctx.meridianBase}. Start it first (npm install -g @rynfar/meridian; claude login; meridian), see ${MERIDIAN_GUIDE}. The route uses the guide's default models.`,
+    );
+  } else {
+    h.ok(`Meridian answers on ${ctx.meridianBase}${probe.healthOk ? "" : " (/health not OK)"}`);
+    if (probe.modelsStatus === 401 || probe.modelsStatus === 403) {
+      h.warn(
+        `Meridian rejected ${ctx.meridianKey ? "the key" : "a request without a key"} on /v1/models (HTTP ${probe.modelsStatus}): set MERIDIAN_API_KEY to the key Meridian runs with.`,
+      );
+    } else if (probe.ids.length) {
+      h.ok(`Meridian lists ${probe.ids.length} models`);
+      showModels(probe.ids, h);
+    } else h.warn(`Meridian returned no model list (HTTP ${probe.modelsStatus}); using the guide's defaults`);
+  }
+  const bridge = bridgeReport(ctx, h.envValue, probe);
+  if (bridge) h[bridge.level](bridge.text);
+  if (!ctx.meridianKey) {
+    h.warn("No MERIDIAN_API_KEY: with MERIDIAN_HOST=0.0.0.0 anyone on the network can use your subscription.");
+  }
+
+  const retainDefault = pickModel(probe.ids, MERIDIAN_RETAIN_DEFAULT, /haiku/, [
+    process.env.PM_DEFAULT_MODEL,
+    storedOr(ctx, h, "meridian", "MEMORY_MODEL", ""),
+  ]);
+  const reflectDefault = pickModel(probe.ids, MERIDIAN_REFLECT_DEFAULT, /sonnet/, [
+    process.env.PM_REFLECT_MODEL,
+    storedOr(ctx, h, "meridian", "MEMORY_REFLECT_MODEL", ""),
+  ]);
+  ctx.model = await h.ask(ctx, "Meridian retain / consolidate model", retainDefault);
+  ctx.reflectModel = await h.ask(ctx, "Meridian reflect model (needs tool calls)", reflectDefault);
+  for (const m of [ctx.model, ctx.reflectModel]) {
+    if (probe.ids.length && !probe.ids.includes(m)) h.warn(`${m} is not listed by Meridian's /v1/models`);
+  }
+}
+
+/**
+ * One alias of the guide's route file.
+ * @param {string} alias
+ * @param {string} model
+ * @param {string} apiBase
+ */
+function renderAlias(alias, model, apiBase) {
+  return (
+    `  - model_name: ${alias}\n` +
+    "    litellm_params:\n" +
+    `      model: anthropic/${model}\n` +
+    `      api_base: ${apiBase}\n` +
+    "      api_key: os.environ/MERIDIAN_API_KEY\n" +
+    "      max_tokens: 4096\n" +
+    "      timeout: 300\n" +
+    '      additional_drop_params: ["reasoning_effort"]\n'
+  );
+}
+
+/**
+ * The route file from docs/meridian-litellm.md#route-file. The key stays in litellm.env.
+ * @param {Record<string, any>} ctx
+ */
+export function renderMeridianRoutes(ctx) {
+  const reflect = ctx.reflectModel || ctx.model;
+  return (
+    "# Written by ./setup: LiteLLM routes for Hindsight, backend Meridian on the host (Claude subscription).\n" +
+    `# See ${MERIDIAN_GUIDE}. MERIDIAN_API_KEY lives in ~/.config/hindsight/litellm.env.\n` +
+    "# No thinking parameter: Meridian rejects thinking: disabled on Haiku 5.5, so reasoning_effort is dropped.\n" +
+    "model_list:\n" +
+    renderAlias("memory-retain", ctx.model, ctx.apiBase) +
+    renderAlias("memory-reflect", reflect, ctx.apiBase) +
+    renderAlias("memory-consolidate", ctx.model, ctx.apiBase) +
+    "\ngeneral_settings:\n  master_key: os.environ/LITELLM_MASTER_KEY\n"
+  );
+}
+
+/**
+ * Set MERIDIAN_API_KEY in litellm.env (mode 600), creating the file with a master key
+ * when it does not exist yet. Never prints the value.
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+export function writeMeridianKey(ctx, h) {
+  const value = ctx.meridianKey || h.envValue(ctx.litellmEnv, "MERIDIAN_API_KEY") || MERIDIAN_NO_KEY;
+  if (/[\r\n]/.test(value)) h.die("MERIDIAN_API_KEY must be one line");
+  if (ctx.dry) {
+    h.info(`[dry-run] set MERIDIAN_API_KEY in ${ctx.litellmEnv} (mode 600; value not printed)`);
+    return;
+  }
+  h.ensureConfigDir(ctx);
+  ensureLitellmEnv(ctx.litellmEnv);
+  const lines = fs.readFileSync(ctx.litellmEnv, "utf8").replace(/\n$/, "").split("\n");
+  const line = `MERIDIAN_API_KEY=${value}`;
+  const at = lines.findIndex((l) => l.startsWith("MERIDIAN_API_KEY="));
+  if (at >= 0 && lines[at] === line) {
+    fs.chmodSync(ctx.litellmEnv, 0o600);
+    h.ok(`${ctx.litellmEnv} already has MERIDIAN_API_KEY`);
+    return;
+  }
+  if (at >= 0) lines[at] = line;
+  else {
+    if (value === MERIDIAN_NO_KEY) lines.push("# Meridian runs without MERIDIAN_API_KEY; LiteLLM needs a non-empty value.");
+    lines.push(line);
+  }
+  const tmp = path.join(path.dirname(ctx.litellmEnv), `.litellm.env.${process.pid}`);
+  fs.writeFileSync(tmp, `${lines.join("\n")}\n`, { mode: 0o600 });
+  fs.chmodSync(tmp, 0o600);
+  fs.renameSync(tmp, ctx.litellmEnv);
+  h.ok(`set MERIDIAN_API_KEY in ${ctx.litellmEnv} (mode 600)`);
+}

package/providers/hindsight/lib/model-backend.mjs

@@ -0,0 +1,243 @@
+/**
+ * Hindsight model routing: how the LiteLLM proxy in front of Hindsight reaches an LLM
+ * (lemond, Ollama, a custom OpenAI-compatible URL or Meridian), plus the reflect-model question and
+ * `lemonade pull`. The meta wizard knows none of this; it calls configureModelRouting.
+ */
+import { applyRoute, litellmConfig, saveConf } from "./litellm-routes.mjs";
+import {
+  chooseMeridian,
+  containerApiBase,
+  existingMeridianKey,
+  MERIDIAN_DEFAULT_BASE,
+  MERIDIAN_REFLECT_DEFAULT,
+  normalizeMeridianBase,
+  writeMeridianKey,
+} from "./meridian.mjs";
+import { ollamaModelNames, openAiModelIds } from "./probe.mjs";
+import {
+  backendDefault,
+  ensureState,
+  OLLAMA_COMPOSE_API_BASE,
+  OLLAMA_HOST_API_BASE,
+  storedOr,
+} from "./state.mjs";
+
+/** @typedef {import("../../../wizard/lib/provider-wizard/helpers.mjs").ProviderWizardHelpers} Helpers */
+
+/**
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+async function pickBackend(ctx, h) {
+  const def = backendDefault(ctx, h);
+  if (ctx.yes) {
+    ctx.backend = def;
+    return;
+  }
+  h.info("Pick a backend first; only that server is contacted.");
+  h.info("1) lemond   2) ollama   3) custom OpenAI-compatible URL   4) Claude subscription (Meridian)");
+  const defNum = { lemond: "1", ollama: "2", custom: "3", meridian: "4" }[def] || "1";
+  const choice = await h.ask(ctx, "Model backend (1-4)", defNum);
+  switch (choice) {
+    case "1":
+      ctx.backend = "lemond";
+      break;
+    case "2":
+      ctx.backend = "ollama";
+      break;
+    case "3":
+      ctx.backend = "custom";
+      break;
+    case "4":
+      ctx.backend = "meridian";
+      break;
+    default:
+      h.die("choose 1, 2, 3 or 4");
+  }
+}
+
+/** @param {Record<string, any>} ctx @param {Helpers} h */
+function probeLemond(ctx, h) {
+  const body = h.curlJson(`${ctx.lemondBase}/v1/models`);
+  ctx.lemondJson = body;
+  ctx.lemondNames = openAiModelIds(typeof body === "object" ? body : null);
+}
+
+/** @param {Record<string, any>} ctx @param {Helpers} h */
+function probeOllama(ctx, h) {
+  const body = h.curlJson(`${ctx.ollamaBase}/api/tags`);
+  ctx.ollamaJson = body;
+  ctx.ollamaNames = ollamaModelNames(body);
+}
+
+/** @param {string[]} names @param {Helpers} h */
+function showModels(names, h) {
+  for (const n of names) h.info(`      ${n}`);
+}
+
+/** @param {Record<string, any>} ctx @param {Helpers} h */
+async function askReflectModel(ctx, h) {
+  const defaultAnswer =
+    process.env.PM_REFLECT_MODEL ||
+    storedOr(ctx, h, ctx.backend, "MEMORY_REFLECT_MODEL", "");
+  const answer = await h.ask(
+    ctx,
+    "Separate reflect model (type shipped for the shipped reflect route)",
+    defaultAnswer,
+  );
+  if (answer === "" || answer === "shipped") ctx.reflectModel = "";
+  else ctx.reflectModel = answer;
+}
+
+/** @param {Record<string, any>} ctx @param {Helpers} h */
+async function pullLemondModels(ctx, h) {
+  if (!ctx.lemondJson) return;
+  const names = new Set();
+  for (const line of litellmConfig(ctx).split("\n")) {
+    const m = line.match(/^\s*model: openai\/(.+)/);
+    if (m) names.add(m[1]);
+  }
+  for (const name of names) {
+    if (!name || ctx.lemondNames.includes(name)) continue;
+    h.warn(`${name} is not downloaded in lemond`);
+    if (await h.confirm(ctx, `Run lemonade pull ${name} now?`, "y")) {
+      if (h.commandExists("lemonade")) {
+        await h.act(ctx, `lemonade pull ${name}`, "lemonade", ["pull", name]);
+      } else h.warn(`lemonade is not on PATH: run 'lemonade pull ${name}' on this host`);
+    }
+  }
+}
+
+/** @param {Record<string, any>} ctx @param {Helpers} h */
+async function chooseLemond(ctx, h) {
+  ctx.apiBase = "http://host.docker.internal:13305/v1";
+  const defaultModel = storedOr(
+    ctx,
+    h,
+    "lemond",
+    "MEMORY_MODEL",
+    process.env.PM_DEFAULT_MODEL || ctx.lemondDefaultModel,
+  );
+  if (!ctx.lemondJson) {
+    h.warn(`lemond is not answering on ${ctx.lemondBase}; the model list is unavailable`);
+  } else if (!ctx.lemondNames.includes(ctx.lemondDefaultModel)) {
+    h.warn(`${ctx.lemondDefaultModel} is not listed by lemond`);
+  }
+  ctx.model = await h.ask(ctx, "lemond model id", defaultModel);
+  await askReflectModel(ctx, h);
+  await pullLemondModels(ctx, h);
+}
+
+/** @param {Record<string, any>} ctx @param {Helpers} h */
+async function chooseOllama(ctx, h) {
+  const defaultModel = storedOr(
+    ctx,
+    h,
+    "ollama",
+    "MEMORY_MODEL",
+    process.env.PM_DEFAULT_MODEL || ctx.ollamaDefaultModel,
+  );
+  // Compose Ollama publishes 127.0.0.1:11434, so a saved compose choice must win over the host probe.
+  if (storedOr(ctx, h, "ollama", "MEMORY_OLLAMA_IN_COMPOSE", "0") === "1") {
+    ctx.ollamaInCompose = true;
+    ctx.apiBase = OLLAMA_COMPOSE_API_BASE;
+    h.info("Keeping Ollama in Docker (compose profile ollama); LiteLLM calls http://ollama:11434.");
+  } else if (ctx.ollamaJson) {
+    ctx.ollamaInCompose = false;
+    ctx.apiBase = OLLAMA_HOST_API_BASE;
+  } else {
+    h.warn(`Ollama is not answering on ${ctx.ollamaBase}`);
+    const useDocker = await h.confirm(
+      ctx,
+      "Ollama is not on this host. Run it in Docker (compose profile ollama)?",
+      "y",
+    );
+    ctx.ollamaInCompose = useDocker;
+    ctx.apiBase = useDocker ? OLLAMA_COMPOSE_API_BASE : OLLAMA_HOST_API_BASE;
+    if (useDocker) {
+      h.info("LiteLLM will call http://ollama:11434; the wizard pulls the model after the stack starts.");
+    }
+  }
+  ctx.model = await h.ask(ctx, "Ollama model", defaultModel);
+  await askReflectModel(ctx, h);
+}
+
+/** @param {Record<string, any>} ctx @param {Helpers} h */
+async function chooseCustom(ctx, h) {
+  const defaultBase = storedOr(ctx, h, "custom", "MEMORY_API_BASE", ctx.customDefaultBase);
+  const defaultModel = storedOr(ctx, h, "custom", "MEMORY_MODEL", ctx.lemondDefaultModel);
+  h.info("The litellm container calls this URL. Host services use host.docker.internal.");
+  h.info("Example: lemond http://host.docker.internal:13305/v1. For a Claude subscription through Meridian, pick backend 4.");
+  ctx.apiBase = await h.ask(ctx, "OpenAI-compatible base URL", defaultBase);
+  ctx.model = await h.ask(ctx, "Model id the server serves", defaultModel);
+  await askReflectModel(ctx, h);
+}
+
+/**
+ * Step "3. Model backend": choose lemond, Ollama, a custom URL or Meridian, write the LiteLLM route
+ * override when the choice differs from the shipped routes, and record it in wizard.conf.
+ * With the Clack UI done (ctx.skipBackendStep) the answers come from PM_BACKEND,
+ * PM_DEFAULT_MODEL, MEMORY_API_BASE and PM_REFLECT_MODEL instead (Meridian adds
+ * MERIDIAN_BASE and MERIDIAN_API_KEY).
+ *
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+export async function chooseModelBackend(ctx, h) {
+  ensureState(ctx);
+  h.step("3. Model backend");
+  if (ctx.skipBackendStep) {
+    if (!process.env.PM_BACKEND) h.die("PM_BACKEND missing with WIZARD_SKIP_BACKEND_STEP");
+    if (!process.env.PM_DEFAULT_MODEL) h.die("PM_DEFAULT_MODEL missing with WIZARD_SKIP_BACKEND_STEP");
+    ctx.backend = process.env.PM_BACKEND;
+    ctx.model = process.env.PM_DEFAULT_MODEL;
+    ctx.apiBase = process.env.MEMORY_API_BASE || "";
+    ctx.reflectModel = process.env.PM_REFLECT_MODEL || "";
+    ctx.ollamaInCompose = process.env.MEMORY_OLLAMA_IN_COMPOSE === "1";
+    if (ctx.backend === "ollama" && !ctx.apiBase) {
+      ctx.apiBase = ctx.ollamaInCompose ? OLLAMA_COMPOSE_API_BASE : OLLAMA_HOST_API_BASE;
+    }
+    if (ctx.backend === "meridian") {
+      ctx.meridianBase = normalizeMeridianBase(process.env.MERIDIAN_BASE || MERIDIAN_DEFAULT_BASE);
+      ctx.apiBase ||= containerApiBase(ctx.meridianBase);
+      ctx.reflectModel ||= MERIDIAN_REFLECT_DEFAULT;
+      ctx.meridianKey = existingMeridianKey(ctx, h).key;
+    }
+    h.ok(`backend ${ctx.backend}, model ${ctx.model} (setup UI)`);
+    await applyRoute(ctx, h);
+    if (ctx.backend === "meridian") writeMeridianKey(ctx, h);
+    saveConf(ctx, h);
+    return;
+  }
+  await pickBackend(ctx, h);
+  switch (ctx.backend) {
+    case "lemond":
+      probeLemond(ctx, h);
+      if (ctx.lemondJson) {
+        h.ok(`lemond answers on ${ctx.lemondBase}`);
+        showModels(ctx.lemondNames, h);
+      } else h.info(`lemond: not answering on ${ctx.lemondBase}`);
+      await chooseLemond(ctx, h);
+      break;
+    case "ollama":
+      probeOllama(ctx, h);
+      if (ctx.ollamaJson) {
+        h.ok(`Ollama answers on ${ctx.ollamaBase}`);
+        showModels(ctx.ollamaNames, h);
+      } else h.info(`Ollama: not answering on ${ctx.ollamaBase}`);
+      await chooseOllama(ctx, h);
+      break;
+    case "custom":
+      await chooseCustom(ctx, h);
+      break;
+    case "meridian":
+      await chooseMeridian(ctx, h);
+      break;
+    default:
+      h.die(`unknown backend ${ctx.backend}`);
+  }
+  h.ok(`backend ${ctx.backend}, model ${ctx.model}`);
+  await applyRoute(ctx, h);
+  if (ctx.backend === "meridian") writeMeridianKey(ctx, h);
+  saveConf(ctx, h);
+}

package/providers/hindsight/lib/notebooklm-mcp-install.mjs

@@ -0,0 +1,127 @@
+/**
+ * When notebooklmAccess.enabled, merge a "notebooklm" stdio MCP into ~/.cursor/mcp.json.
+ * Never overwrites existing "hindsight" or "codegraph" entries. Dry-run safe.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { resolveAccess, loadCodingAgentConfig } from "../../../cli/notebooklm-mcp.mjs";
+
+/** @typedef {import("../../../wizard/lib/provider-wizard/helpers.mjs").ProviderWizardHelpers} Helpers */
+
+/** @param {string} repoRoot */
+export function notebooklmMcpScriptPath(repoRoot) {
+  return path.resolve(repoRoot, "cli/notebooklm-mcp.mjs");
+}
+
+/**
+ * @param {Record<string, any>} mcp
+ * @param {string} scriptPath absolute path to cli/notebooklm-mcp.mjs
+ * @param {{ agentJson?: string }} [opts]
+ * @returns {{ mcp: Record<string, any>, changed: boolean, skipped?: string }}
+ */
+export function mergeNotebooklmMcpServer(mcp, scriptPath, opts = {}) {
+  const out = { ...mcp };
+  const servers = { ...(mcp.mcpServers && typeof mcp.mcpServers === "object" ? mcp.mcpServers : {}) };
+  // Absolute node + explicit config path: Cursor Agent's PATH may resolve a different
+  // `node`, and a symlink ~/.hindsight/coding-agent.json → shipped template used to
+  // make the process exit before handshake ("Connection closed").
+  const nodeBin = process.execPath;
+  const agentJson =
+    opts.agentJson ||
+    process.env.HINDSIGHT_CODING_AGENT_JSON ||
+    path.join(process.env.HOME || "", ".hindsight", "coding-agent.json");
+  const next = {
+    type: "stdio",
+    command: nodeBin,
+    args: [scriptPath],
+    env: {
+      HINDSIGHT_CODING_AGENT_JSON: agentJson,
+    },
+  };
+  const prev = servers.notebooklm;
+  const same =
+    prev &&
+    prev.command === next.command &&
+    Array.isArray(prev.args) &&
+    prev.args.length === 1 &&
+    prev.args[0] === scriptPath &&
+    prev.type === "stdio" &&
+    prev.env?.HINDSIGHT_CODING_AGENT_JSON === next.env.HINDSIGHT_CODING_AGENT_JSON;
+  if (same) return { mcp: { ...out, mcpServers: servers }, changed: false, skipped: "already configured" };
+  servers.notebooklm = next;
+  // Preserve sibling servers by reference identity of keys we did not touch.
+  return { mcp: { ...out, mcpServers: servers }, changed: true };
+}
+
+/**
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+export async function installNotebooklmMcp(ctx, h) {
+  const agentPath = ctx.agentJson || path.join(ctx.home, ".hindsight", "coding-agent.json");
+  const tracked = path.join(ctx.repoRoot, "config/coding-agent.json");
+  let cfg = null;
+  for (const p of [agentPath, tracked]) {
+    try {
+      if (fs.existsSync(p)) {
+        cfg = loadCodingAgentConfig(p);
+        break;
+      }
+    } catch {
+      /* try next */
+    }
+  }
+  if (!cfg) {
+    h.info("notebooklm MCP: no coding-agent.json yet; skip Cursor mcp.json merge");
+    return;
+  }
+  const access = resolveAccess(cfg);
+  if (!access.enabled) {
+    h.info("notebooklmAccess.enabled is false; skip registering notebooklm MCP in ~/.cursor/mcp.json");
+    return;
+  }
+
+  const script = notebooklmMcpScriptPath(ctx.repoRoot);
+  if (!fs.existsSync(script)) {
+    h.warn(`notebooklm MCP script missing: ${script}`);
+    return;
+  }
+
+  const mcpPath = path.join(ctx.home, ".cursor", "mcp.json");
+  let existing = {};
+  if (fs.existsSync(mcpPath)) {
+    try {
+      existing = JSON.parse(fs.readFileSync(mcpPath, "utf8"));
+    } catch (err) {
+      h.warn(`cannot parse ${mcpPath}: ${err instanceof Error ? err.message : err}`);
+      return;
+    }
+  }
+
+  // Guard: never clobber unrelated servers (merge only adds/updates "notebooklm").
+  const beforeHindsight = existing.mcpServers?.hindsight;
+  const beforeCodegraph = existing.mcpServers?.codegraph;
+  const { mcp, changed, skipped } = mergeNotebooklmMcpServer(existing, script, {
+    agentJson: path.resolve(agentPath),
+  });
+  if (beforeHindsight && mcp.mcpServers?.hindsight !== beforeHindsight) {
+    h.warn("refusing to alter hindsight MCP entry");
+    return;
+  }
+  if (beforeCodegraph && mcp.mcpServers?.codegraph !== beforeCodegraph) {
+    h.warn("refusing to alter codegraph MCP entry");
+    return;
+  }
+
+  if (!changed) {
+    h.ok(`notebooklm MCP already in ${mcpPath}${skipped ? ` (${skipped})` : ""}`);
+    return;
+  }
+  if (ctx.dry) {
+    h.info(`[dry-run] merge notebooklm MCP into ${mcpPath} → node ${script}`);
+    return;
+  }
+  fs.mkdirSync(path.dirname(mcpPath), { recursive: true });
+  fs.writeFileSync(mcpPath, `${JSON.stringify(mcp, null, 2)}\n`);
+  h.ok(`registered notebooklm MCP in ${mcpPath}`);
+}