@bcmyguest/openmem 0.0.0-stage → 0.6.3

package/providers/hindsight/lib/config.mjs

@@ -0,0 +1,73 @@
+/**
+ * Hindsight's slice of ~/.config/personal-memory/config.toml: [stack] ports and the
+ * [model] table. The meta wizard owns [memory], [stack].project, [wizard] and [tasks].
+ */
+
+/**
+ * Flat Hindsight defaults from a merged TOML config.
+ * @param {Record<string, unknown>} cfg
+ */
+export function defaultsFromConfig(cfg) {
+  const stack = /** @type {Record<string, unknown>} */ (cfg.stack || {});
+  const model = /** @type {Record<string, unknown>} */ (cfg.model || {});
+  const lemond = /** @type {Record<string, unknown>} */ (model.lemond || {});
+  const ollama = /** @type {Record<string, unknown>} */ (model.ollama || {});
+  return {
+    apiPort: stack.api_port != null ? String(stack.api_port) : "",
+    cpPort: stack.control_plane_port != null ? String(stack.control_plane_port) : "",
+    modelBackend: String(model.backend || ""),
+    modelRetain: String(model.retain || ""),
+    modelReflect: String(model.reflect || ""),
+    modelApiBase: String(model.api_base || ""),
+    lemondHost: String(lemond.host || ""),
+    ollamaHost: String(ollama.host || ""),
+  };
+}
+
+/**
+ * Apply config defaults into process.env when env/CLI did not set them.
+ * @param {Record<string, unknown>} cfg
+ */
+export function applyConfigEnv(cfg) {
+  const d = defaultsFromConfig(cfg);
+  if (d.apiPort && !process.env.HINDSIGHT_PORT) process.env.HINDSIGHT_PORT = d.apiPort;
+  if (d.cpPort && !process.env.HINDSIGHT_CP_PORT) process.env.HINDSIGHT_CP_PORT = d.cpPort;
+  if (d.modelBackend && !process.env.PM_BACKEND) process.env.PM_BACKEND = d.modelBackend;
+  if (d.modelRetain && !process.env.PM_DEFAULT_MODEL) {
+    process.env.PM_DEFAULT_MODEL = d.modelRetain;
+  }
+  if (d.modelReflect && !process.env.PM_REFLECT_MODEL) {
+    process.env.PM_REFLECT_MODEL = d.modelReflect;
+  }
+  if (d.modelApiBase && !process.env.MEMORY_API_BASE) {
+    process.env.MEMORY_API_BASE = d.modelApiBase;
+  }
+  if (d.lemondHost && !process.env.LEMOND_BASE) process.env.LEMOND_BASE = d.lemondHost;
+}
+
+/**
+ * Tables merged into config.toml when the wizard saves it.
+ * @param {Record<string, any>} ctx
+ * @returns {Record<string, Record<string, unknown>>}
+ */
+export function configToml(ctx) {
+  const model = {
+    backend: ctx.backend,
+    retain: ctx.model,
+    reflect: ctx.reflectModel || "",
+    api_base: ctx.apiBase || "",
+  };
+  if (ctx.backend === "lemond" || ctx.lemondBase) {
+    model.lemond = { host: ctx.lemondBase };
+  }
+  if (ctx.backend === "ollama" || ctx.ollamaBase) {
+    model.ollama = { host: ctx.ollamaBase };
+  }
+  return {
+    stack: {
+      api_port: Number(ctx.portApi || 8888),
+      control_plane_port: Number(ctx.portCp || 9999),
+    },
+    model,
+  };
+}

package/providers/hindsight/lib/env-setup.mjs

@@ -0,0 +1,71 @@
+/**
+ * Step "4. Secrets and env", Hindsight half: ~/.config/hindsight/hindsight.env from the
+ * shipped example, then the stack setup script (litellm.env, .env, compose.override.yaml),
+ * then wiring hindsight.env to the LiteLLM proxy.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { ensureState } from "./state.mjs";
+
+/** @typedef {import("../../../wizard/lib/provider-wizard/helpers.mjs").ProviderWizardHelpers} Helpers */
+
+/**
+ * True when hindsight.env points Hindsight at the LiteLLM proxy with the master key.
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+export function llmWired(ctx, h) {
+  if (h.envValue(ctx.envFile, "HINDSIGHT_API_LLM_BASE_URL") !== "http://litellm:4000/v1") {
+    return false;
+  }
+  const key = h.envValue(ctx.envFile, "HINDSIGHT_API_LLM_API_KEY");
+  const master = h.envValue(ctx.litellmEnv, "LITELLM_MASTER_KEY");
+  return Boolean(key && master && key === master);
+}
+
+/**
+ * Arguments for the meta wizard's stack setup script.
+ * @param {Record<string, any>} ctx
+ */
+export function stackEnv(ctx) {
+  ensureState(ctx);
+  let backend = ctx.backend;
+  if (backend === "custom") backend = "lemond";
+  /** @type {Record<string, string>} */
+  const env = { MEMORY_BACKEND: backend };
+  if (ctx.ollamaInCompose) env.MEMORY_OLLAMA_IN_COMPOSE = "1";
+  return {
+    description:
+      "scripts/setup.sh: write .env, litellm.env (mode 600 when new), compose.override.yaml",
+    env,
+  };
+}
+
+/**
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+export async function setupEnv(ctx, h) {
+  ensureState(ctx);
+  const example = path.join(ctx.repoRoot, "config/hindsight.env.example");
+  if (fs.existsSync(ctx.envFile)) h.ok(`kept ${ctx.envFile}`);
+  else if (ctx.dry) h.info(`[dry-run] create ${ctx.envFile} from config/hindsight.env.example (mode 600)`);
+  else {
+    fs.copyFileSync(example, ctx.envFile);
+    fs.chmodSync(ctx.envFile, 0o600);
+    h.ok(`created ${ctx.envFile} (mode 600)`);
+  }
+  await h.runStackSetup(ctx);
+  if (ctx.dry) {
+    h.info(
+      `[dry-run] run setup.sh --migrate-env unless ${ctx.envFile} already uses the LiteLLM proxy and master key`,
+    );
+  } else if (llmWired(ctx, h)) h.ok("Hindsight calls the LiteLLM proxy with the master key");
+  else if (await h.confirm(ctx, `Point ${ctx.envFile} at the LiteLLM proxy now (backs up the file, prints no values)?`, "y")) {
+    await h.runStackSetup(ctx, {
+      description: "migrate hindsight.env",
+      args: ["--migrate-env"],
+      env: {},
+    });
+  } else h.warn("Hindsight is not wired to the LiteLLM proxy; the stack will not work until you migrate");
+}

package/providers/hindsight/lib/litellm-routes.mjs

@@ -0,0 +1,187 @@
+import fs from "node:fs";
+import path from "node:path";
+import { configToml } from "./config.mjs";
+import { OLLAMA_HOST_API_BASE } from "./state.mjs";
+
+/** @typedef {import("../../../wizard/lib/provider-wizard/helpers.mjs").ProviderWizardHelpers} Helpers */
+
+/** Shipped litellm.<backend>.yaml api_base for the host-side model server. */
+function shippedApiBase(backend) {
+  if (backend === "ollama") return OLLAMA_HOST_API_BASE;
+  if (backend === "lemond") return "http://host.docker.internal:13305/v1";
+  return "";
+}
+
+/**
+ * @param {Record<string, any>} ctx
+ * @param {string} alias
+ * @param {string} litellmModel
+ */
+function renderRoute(ctx, alias, litellmModel) {
+  let out = `  - model_name: ${alias}\n    litellm_params:\n      model: ${litellmModel}\n      api_base: ${ctx.apiBase}\n`;
+  if (ctx.backend === "ollama") {
+    out += "      extra_body:\n        think: false\n";
+  } else {
+    out += "      api_key: os.environ/LEMOND_API_KEY\n      extra_body:\n        chat_template_kwargs:\n          enable_thinking: false\n";
+  }
+  return out;
+}
+
+/**
+ * @param {Record<string, any>} ctx
+ * @param {string} litellmModel
+ */
+function renderOverride(ctx, litellmModel) {
+  return (
+    "# Written by ./setup. Replaces config/litellm.*.yaml while this file exists.\n" +
+    "# Delete it, or rerun ./setup with the shipped model, to use the shipped routes again.\n" +
+    "# Thinking is off for all three aliases. Non-ollama servers get chat_template_kwargs; a server that rejects it needs a different route.\n" +
+    "model_list:\n" +
+    renderRoute(ctx, "memory-retain", litellmModel) +
+    renderRoute(ctx, "memory-reflect", litellmModel) +
+    renderRoute(ctx, "memory-consolidate", litellmModel) +
+    "general_settings:\n  master_key: os.environ/LITELLM_MASTER_KEY\n"
+  );
+}
+
+/**
+ * @param {Record<string, any>} ctx
+ * @param {string} litellmModel
+ * @param {string} reflectLitellmModel
+ */
+function renderShipped(ctx, litellmModel, reflectLitellmModel) {
+  const src = path.join(ctx.repoRoot, "config", `litellm.${ctx.backend}.yaml`);
+  const lines = fs.readFileSync(src, "utf8").split("\n");
+  const out = [
+    `# Written by ./setup from config/litellm.${ctx.backend}.yaml. Replaces the shipped routes while this file exists.`,
+    "# Delete it, or rerun ./setup with the shipped models, to use the shipped routes again.",
+  ];
+  let name = "";
+  for (const line of lines) {
+    const mn = line.match(/^  - model_name: (\S+)/);
+    if (mn) name = mn[1];
+    if (/^      api_base: /.test(line)) {
+      out.push(`      api_base: ${ctx.apiBase}`);
+      continue;
+    }
+    if (/^      model: /.test(line)) {
+      if (name !== "memory-reflect") out.push(`      model: ${litellmModel}`);
+      else if (reflectLitellmModel) out.push(`      model: ${reflectLitellmModel}`);
+      else out.push(line);
+      continue;
+    }
+    out.push(line);
+  }
+  return `${out.join("\n")}\n`;
+}
+
+/**
+ * @param {Record<string, any>} ctx
+ * @returns {string}
+ */
+export function litellmConfig(ctx) {
+  let prefix = "openai/";
+  if (ctx.backend === "ollama") prefix = "ollama_chat/";
+  if (ctx.backend === "custom") return renderOverride(ctx, `${prefix}${ctx.model}`);
+  let reflect = "";
+  if (ctx.reflectModel) reflect = `${prefix}${ctx.reflectModel}`;
+  return renderShipped(ctx, `${prefix}${ctx.model}`, reflect);
+}
+
+/**
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+export async function removeOverrideIfAsked(ctx, h) {
+  if (!fs.existsSync(ctx.litellmOverride)) return;
+  if (ctx.dry) {
+    h.info(`[dry-run] move ${ctx.litellmOverride} aside so the shipped ${ctx.backend} routes apply`);
+    return;
+  }
+  if (!(await h.confirm(ctx, `Move ${ctx.litellmOverride} aside so the shipped ${ctx.backend} routes apply?`, "y"))) {
+    h.warn("kept the override; it still takes precedence over the shipped routes");
+    return;
+  }
+  const bak = `${ctx.litellmOverride}.bak-${timestamp()}`;
+  fs.renameSync(ctx.litellmOverride, bak);
+  h.ok("moved the override aside");
+}
+
+/**
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+export async function writeOverride(ctx, h) {
+  if (ctx.dry) {
+    h.info(
+      `[dry-run] write ${ctx.litellmOverride} from config/litellm.${ctx.backend}.yaml: retain and consolidate -> ${ctx.model}, reflect -> ${ctx.reflectModel || "shipped"}, at ${ctx.apiBase}`,
+    );
+    return;
+  }
+  h.ensureConfigDir(ctx);
+  const content = litellmConfig(ctx);
+  const tmp = path.join(ctx.hsDir, `.litellm.yaml.${process.pid}`);
+  fs.writeFileSync(tmp, content, { mode: 0o644 });
+  if (fs.existsSync(ctx.litellmOverride)) {
+    const existing = fs.readFileSync(ctx.litellmOverride);
+    if (Buffer.compare(existing, Buffer.from(content)) === 0) {
+      fs.unlinkSync(tmp);
+      h.ok(`${ctx.litellmOverride} already has this route`);
+      return;
+    }
+    if (!(await h.confirm(ctx, `Replace ${ctx.litellmOverride} (the old file is kept as .bak)?`, "y"))) {
+      fs.unlinkSync(tmp);
+      h.warn("kept the existing override; it still takes precedence");
+      return;
+    }
+    fs.copyFileSync(ctx.litellmOverride, `${ctx.litellmOverride}.bak-${timestamp()}`);
+  }
+  fs.renameSync(tmp, ctx.litellmOverride);
+  h.ok(`wrote ${ctx.litellmOverride}`);
+}
+
+/**
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+export async function applyRoute(ctx, h) {
+  let shipped = "";
+  if (ctx.backend === "lemond") shipped = ctx.lemondDefaultModel;
+  if (ctx.backend === "ollama") shipped = ctx.ollamaDefaultModel;
+  const defaultBase = shippedApiBase(ctx.backend);
+  const apiMatchesShipped = !ctx.apiBase || ctx.apiBase === defaultBase;
+  if (ctx.backend !== "custom" && ctx.model === shipped && !ctx.reflectModel && apiMatchesShipped) {
+    await removeOverrideIfAsked(ctx, h);
+  } else {
+    await writeOverride(ctx, h);
+  }
+}
+
+function timestamp() {
+  const d = new Date();
+  const p = (n) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`;
+}
+
+/**
+ * Record the backend choice in wizard.conf (and config.toml).
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+export function saveConf(ctx, h) {
+  if (ctx.dry) {
+    h.info(`[dry-run] record backend ${ctx.backend} in ${ctx.wizardConf}`);
+    return;
+  }
+  h.saveWizardConf(
+    ctx,
+    {
+      MEMORY_BACKEND: ctx.backend,
+      MEMORY_MODEL: ctx.model,
+      MEMORY_API_BASE: ctx.apiBase,
+      MEMORY_REFLECT_MODEL: ctx.reflectModel,
+      MEMORY_OLLAMA_IN_COMPOSE: ctx.ollamaInCompose ? "1" : "0",
+    },
+    { pmSections: configToml(ctx) },
+  );
+}

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

@@ -0,0 +1,214 @@
+/**
+ * Hindsight model routing: how the LiteLLM proxy in front of Hindsight reaches an LLM
+ * (lemond, Ollama or a custom OpenAI-compatible URL), 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 { 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");
+  const defNum = def === "lemond" ? "1" : def === "ollama" ? "2" : "3";
+  const choice = await h.ask(ctx, "Model backend (1-3)", defNum);
+  switch (choice) {
+    case "1":
+      ctx.backend = "lemond";
+      break;
+    case "2":
+      ctx.backend = "ollama";
+      break;
+    case "3":
+      ctx.backend = "custom";
+      break;
+    default:
+      h.die("choose 1, 2 or 3");
+  }
+}
+
+/** @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,
+  );
+  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("Examples: lemond http://host.docker.internal:13305/v1 ; Meridian http://host.docker.internal:3456/v1");
+  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 or a custom URL, 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.
+ *
+ * @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;
+    }
+    h.ok(`backend ${ctx.backend}, model ${ctx.model} (setup UI)`);
+    await applyRoute(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;
+    default:
+      h.die(`unknown backend ${ctx.backend}`);
+  }
+  h.ok(`backend ${ctx.backend}, model ${ctx.model}`);
+  await applyRoute(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}`);
+}