@bcmyguest/openmem 0.6.3 → 0.9.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

@@ -1,9 +1,18 @@
 /**
  * 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
+ * (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,
@@ -26,9 +35,9 @@ async function pickBackend(ctx, h) {
     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);
+  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";
@@ -39,8 +48,11 @@ async function pickBackend(ctx, h) {
     case "3":
       ctx.backend = "custom";
       break;
+    case "4":
+      ctx.backend = "meridian";
+      break;
     default:
-      h.die("choose 1, 2 or 3");
+      h.die("choose 1, 2, 3 or 4");
   }
 }
 
@@ -125,7 +137,12 @@ async function chooseOllama(ctx, h) {
     "MEMORY_MODEL",
     process.env.PM_DEFAULT_MODEL || ctx.ollamaDefaultModel,
   );
-  if (ctx.ollamaJson) {
+  // 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 {
@@ -150,17 +167,18 @@ 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");
+  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 or a custom URL, write the LiteLLM route
+ * 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.
+ * 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
@@ -179,8 +197,15 @@ export async function chooseModelBackend(ctx, h) {
     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;
   }
@@ -205,10 +230,14 @@ export async function chooseModelBackend(ctx, h) {
     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/probe.mjs

@@ -31,3 +31,24 @@ export function normalizeOpenAiBase(base) {
   if (!b.endsWith("/v1")) b += "/v1";
   return b;
 }
+
+/**
+ * GET `url` and report the HTTP status (0 when nothing answered) and the parsed JSON body.
+ * @param {string} url
+ * @param {{ headers?: Record<string, string>, timeoutMs?: number }} [opts]
+ * @returns {Promise<{ status: number, json: any }>}
+ */
+export async function fetchStatus(url, { headers = {}, timeoutMs = TIMEOUT_MS } = {}) {
+  try {
+    const res = await fetch(url, { headers, signal: AbortSignal.timeout(timeoutMs) });
+    let json = null;
+    try {
+      json = await res.json();
+    } catch {
+      json = null;
+    }
+    return { status: res.status, json };
+  } catch {
+    return { status: 0, json: null };
+  }
+}

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

@@ -4,11 +4,14 @@
  * Runs as a plain Node script step (no wizard context), so it only reads process
  * environment and the paths it is given.
  */
-import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { ensureLitellmEnv } from "../../../wizard/lib/litellm-env.mjs";
 import { envValue } from "../../../wizard/lib/paths.mjs";
 
+// Moved to wizard/lib/litellm-env.mjs (mem0 shares it); re-exported for existing importers.
+export { ensureLitellmEnv };
+
 /**
  * @param {{ repo: string, home: string, env: NodeJS.ProcessEnv }} opts
  * @returns {{ entries: [string, string][], drop: string[], report: string[] }}
@@ -25,17 +28,7 @@ export function prepareStackEnv({ repo, home, env }) {
     throw new Error(`MEMORY_BACKEND must be lemond or ollama (got: ${backend})`);
   }
 
-  if (!fs.existsSync(litellmEnv)) {
-    const key = crypto.randomBytes(24).toString("hex");
-    const body =
-      "# LiteLLM proxy secrets. Read by the litellm compose service. Do not commit.\n" +
-      `LITELLM_MASTER_KEY=sk-${key}\n` +
-      "# lemond ignores the key; any non-empty value works.\n" +
-      "LEMOND_API_KEY=placeholder\n" +
-      "# Hosted models: add the provider key here, e.g. ANTHROPIC_API_KEY=..., and reference it as os.environ/ANTHROPIC_API_KEY.\n";
-    fs.writeFileSync(litellmEnv, body, { mode: 0o600 });
-    console.log(`created ${litellmEnv} (mode 600)`);
-  }
+  if (ensureLitellmEnv(litellmEnv)) console.log(`created ${litellmEnv} (mode 600)`);
 
   const litellmConfig = fs.existsSync(overrideConfig)
     ? overrideConfig

package/providers/hindsight/lib/state.mjs

@@ -9,7 +9,7 @@ export const OLLAMA_HOST_API_BASE = "http://host.docker.internal:11434";
 /** LiteLLM api_base when Ollama is the compose `ollama` service. */
 export const OLLAMA_COMPOSE_API_BASE = "http://ollama:11434";
 
-export const BACKENDS = ["lemond", "ollama", "custom"];
+export const BACKENDS = ["lemond", "ollama", "custom", "meridian"];
 
 /**
  * Fill the Hindsight fields of the wizard context. Idempotent: a field that is already
@@ -23,6 +23,8 @@ export function ensureState(ctx) {
     litellmEnv: path.join(hs, "litellm.env"),
     litellmOverride: path.join(hs, "litellm.yaml"),
     agentJson: path.join(ctx.home || "", ".hindsight/coding-agent.json"),
+    /** Meridian's own env file from docs/meridian-litellm.md (read for MERIDIAN_API_KEY/HOST/PORT). */
+    meridianEnvFile: path.join(ctx.home || "", ".config/meridian/meridian.env"),
     lemondBase: "http://127.0.0.1:13305",
     ollamaBase: "http://127.0.0.1:11434",
     lemondDefaultModel: LEMOND_DEFAULT_MODEL,
@@ -41,6 +43,9 @@ export function ensureState(ctx) {
     portApi: "",
     portCp: "",
     hindsightUrl: "",
+    /** Meridian URL as seen from the host, and the key for litellm.env (backend meridian). */
+    meridianBase: "",
+    meridianKey: "",
   };
   for (const [key, value] of Object.entries(defaults)) {
     if (ctx[key] === undefined) ctx[key] = value;

package/providers/hindsight/lib/summary.mjs

@@ -1,6 +1,7 @@
 /** Hindsight's contribution to the wizard's closing summary. */
 import fs from "node:fs";
 import { composeCommandText } from "../../../wizard/lib/compose.mjs";
+import { MERIDIAN_GUIDE, MERIDIAN_TERMS_URL } from "./meridian.mjs";
 import { ensureState } from "./state.mjs";
 
 /**
@@ -19,14 +20,20 @@ export function summary(ctx) {
     `  control plane      http://127.0.0.1:${ctx.portCp}`,
     `  model              ${ctx.backend}, ${ctx.model} via ${modelWhere}`,
   ];
+  if (ctx.backend === "meridian") {
+    running.push(`  reflect model      ${ctx.reflectModel || ctx.model}`);
+    running.push(
+      `  Meridian           ${ctx.meridianBase || "(host URL not recorded)"} on the host (not managed by setup; LiteLLM calls ${ctx.apiBase})`,
+    );
+  }
   if (ctx.ollamaInCompose) {
     running.push(`  Ollama            http://127.0.0.1:11434 (compose service; LiteLLM uses http://ollama:11434)`);
   }
   const configFiles = [`  ${ctx.envFile}`];
   if (fs.existsSync(ctx.litellmOverride)) {
     configFiles.push(`  ${ctx.litellmOverride} (model routes; replaces config/litellm.*.yaml)`);
-  } else if (ctx.backend === "custom") {
-    configFiles.push(`  ${ctx.litellmOverride} (missing: custom backend needs it)`);
+  } else if (ctx.backend === "custom" || ctx.backend === "meridian") {
+    configFiles.push(`  ${ctx.litellmOverride} (missing: ${ctx.backend} backend needs it)`);
   } else configFiles.push(`  config/litellm.${ctx.backend}.yaml (shipped routes)`);
   const litellmUp = composeCommandText(ctx, "up", "-d", "litellm");
   const notes = [
@@ -34,6 +41,13 @@ export function summary(ctx) {
     `Reflect needs a capable model (memory-reflect alias). On a weak or remote LLM, edit ${ctx.litellmOverride} and point memory-reflect at Meridian, an OpenAI-compatible host, or a stronger local model — then: ${litellmUp}`,
     `Change later: rerun ./setup. For a route-only edit, run: ${litellmUp}`,
   ];
+  if (ctx.backend === "meridian") {
+    configFiles.push(`  ${ctx.litellmEnv} (MERIDIAN_API_KEY)`);
+    notes.push(
+      `Meridian must keep running on this host with MERIDIAN_HOST=0.0.0.0 so the LiteLLM container reaches it; see ${MERIDIAN_GUIDE}.`,
+      `Claude subscription use through Meridian is governed by Anthropic's Consumer Terms: ${MERIDIAN_TERMS_URL}`,
+    );
+  }
   if (ctx.smokeFailed) {
     notes.unshift(
       `Smoke retain/recall did not finish — stack is up; fix the model/LLM queue via http://127.0.0.1:${ctx.portCp} then re-run setup or: curl the wizard-smoke retain against ${ctx.hindsightUrl}`,

package/providers/hindsight/lib/validate.mjs

@@ -69,6 +69,12 @@ export function validateHindsight(ctx, h) {
   const model = conf("MEMORY_MODEL");
   const shipped = backend === "ollama" ? ctx.ollamaDefaultModel : ctx.lemondDefaultModel;
   const reflect = conf("MEMORY_REFLECT_MODEL");
+  if (backend === "meridian") {
+    if (!fs.existsSync(ctx.litellmOverride)) errors.push("meridian backend without litellm.yaml override");
+    if (!h.envValue(ctx.litellmEnv, "MERIDIAN_API_KEY")) errors.push("litellm.env missing MERIDIAN_API_KEY");
+    checks.push("Meridian route and key");
+    return;
+  }
   if (backend !== "custom" && model !== shipped && !reflect && !fs.existsSync(ctx.litellmOverride)) {
     errors.push("custom model without litellm.yaml override");
   }

package/providers/hindsight/wizard.mjs

@@ -44,8 +44,8 @@ export async function afterProvider(ctx, h) {
 }
 
 /**
- * Step "3. Model backend": lemond, Ollama or a custom OpenAI-compatible URL behind the
- * LiteLLM proxy.
+ * Step "3. Model backend": lemond, Ollama, a custom OpenAI-compatible URL or a Claude
+ * subscription through Meridian, behind the LiteLLM proxy.
  * @param {Record<string, any>} ctx
  * @param {Helpers} h
  */
@@ -78,6 +78,7 @@ export async function hydrate(ctx, h) {
   ctx.model = confGet(ctx, h, "MEMORY_MODEL") || ctx.lemondDefaultModel;
   ctx.apiBase = confGet(ctx, h, "MEMORY_API_BASE") || "";
   ctx.reflectModel = confGet(ctx, h, "MEMORY_REFLECT_MODEL") || "";
+  ctx.meridianBase = confGet(ctx, h, "MEMORY_MERIDIAN_URL") || "";
   ctx.ollamaInCompose = confGet(ctx, h, "MEMORY_OLLAMA_IN_COMPOSE") === "1";
   applyComposeProfiles(ctx);
 }

package/providers/mem0/OPERATOR.md

@@ -16,6 +16,7 @@ server only (no `/v1/` prefix).
 | Embedder / LLM keys for mem0 itself | Indexer sink (`MEMORY_SINK=mem0`) and host-gateway rewrite |
 | Create an API key (dashboard or `POST /api-keys`) | Store `MEM0_API_KEY` in `~/.config/personal-memory/mem0.env` (mode **600**) |
 | Optional `AUTH_DISABLED=true` (dev only) | Smoke: `GET /docs`, retain, search, delete-by-id |
+| Apply the printed `llm` / `embedder` blocks to mem0 (optional) | Optional stack LiteLLM for mem0's LLM: routes, `litellm.env`, profile `litellm` on `127.0.0.1` |
 
 ## URLs
 
@@ -76,7 +77,7 @@ via the launcher `cli/mem0-mcp.mjs` (loads the key from the env file, then
 
 ```sh
 MEMORY_PROVIDER=mem0 npx openmem install-mcp --yes
-# checkout: MEMORY_PROVIDER=mem0 npx . install-mcp --yes
+# checkout: MEMORY_PROVIDER=mem0 node cli/openmem.mjs install-mcp --yes
 # or accept the coding-agent MCP confirm in setup
 ```
 
@@ -111,14 +112,32 @@ Restart Cursor Agent after install.
 ```sh
 npx openmem switch mem0 --yes
 # later: npx openmem switch hindsight --yes
-# checkout: npx . switch mem0 --yes
+# checkout: node cli/openmem.mjs switch mem0 --yes
 ```
 
 Updates `wizard.conf` (and `config.toml` `[memory].provider` when present), restarts the stack
 unless `--no-stack`, and runs `install-mcp --provider-only` unless `--no-mcp`. Does **not**
 migrate memories. Flags: [README — Switch memory provider](../../README.md#switch-memory-provider).
 
+## Models through the stack LiteLLM
+
+Optional (wizard step 3, or `MEM0_LITELLM=1` under `--yes`): mem0's LLM, and
+its embedder when the backend has one, go through the stack LiteLLM. Inputs
+under `--yes`: `MEM0_LITELLM_BACKEND` (`ollama`, `custom`, `anthropic`,
+`meridian`), `MEM0_LITELLM_MODEL`, `MEM0_LITELLM_API_BASE`,
+`MEM0_LITELLM_EMBED_MODEL` (`none` keeps mem0's embedder),
+`MEM0_LITELLM_PORT` (default 4000), `ANTHROPIC_API_KEY`. The wizard writes
+`~/.config/personal-memory/mem0-litellm.yaml`, keeps keys in
+`~/.config/hindsight/litellm.env` (mode 600), and prints the mem0 `llm` /
+`embedder` blocks (provider `openai`, `openai_base_url`
+`http://127.0.0.1:<port>/v1`, `api_key` = `LITELLM_MASTER_KEY`). You apply
+them; the wizard never edits the mem0 server config. Key sources and limits:
+[docs/mem0.md](../../docs/mem0.md#models-through-the-stack-litellm-optional).
+
 ## Compose
 
 `providers/mem0/compose.yaml` defines no mem0 service — only env +
 `extra_hosts` on the shared `indexer`. Profile `mem0` selects that fragment.
+It also overlays the base `litellm` service: under profile `litellm` it
+publishes `127.0.0.1:${MEM0_LITELLM_PORT:-4000}` (never `0.0.0.0`) and its
+entrypoint exits unless `LITELLM_MASTER_KEY` starts with `sk-`.