@bcmyguest/openmem 0.0.0-stage → 0.8.0

package/providers/mem0/lib/smoke.mjs

@@ -0,0 +1,179 @@
+/**
+ * Smoke test for a mem0 REST server (replaces the manifest HTTP smoke, which has no header
+ * support): GET /docs, POST /memories (verbatim, infer false), POST /search must find the
+ * fact, then delete what was created. Cleanup runs on every outcome.
+ */
+import path from "node:path";
+import { readKey } from "./env-file.mjs";
+import { clean, describeError, redact, request } from "./http.mjs";
+import { capturedKey } from "./secret.mjs";
+import { ensureState, resolveEnvFile } from "./state.mjs";
+import { displayUrl, resolveApiUrl, urlProblem } from "./url.mjs";
+
+/** @typedef {import("../../../wizard/lib/provider-wizard/helpers.mjs").ProviderWizardHelpers} Helpers */
+
+export const SMOKE_USER = "wizard-smoke";
+export const SMOKE_RUN = "wizard-smoke-doc";
+export const SMOKE_FACT = "Wizard smoke test: the project codename is heron.";
+
+const RETAIN_BODY = {
+  messages: [{ role: "user", content: SMOKE_FACT }],
+  user_id: SMOKE_USER,
+  agent_id: "openmem-wizard",
+  run_id: SMOKE_RUN,
+  infer: false,
+};
+const SEARCH_BODY = {
+  query: "What is the project codename?",
+  filters: { user_id: SMOKE_USER },
+};
+
+class SmokeFailure extends Error {}
+
+/** Server ids are UUIDs; anything else is never put in a URL or printed. */
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+
+/** @param {any} json @returns {string[]} */
+function memoryIds(json) {
+  const list = Array.isArray(json) ? json : Array.isArray(json?.results) ? json.results : json?.id ? [json] : [];
+  return list.map((r) => r?.id).filter((id) => typeof id === "string" && SAFE_ID.test(id));
+}
+
+/** @param {any} json @returns {string} */
+function memoryText(json) {
+  const list = Array.isArray(json) ? json : Array.isArray(json?.results) ? json.results : [];
+  return list.map((r) => String(r?.memory ?? r?.text ?? "")).join("\n");
+}
+
+/**
+ * The key the indexer would send: the env file first (the indexer reads only that), then the
+ * key captured from the environment, then process.env (a caller that skipped init).
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+function smokeKey(ctx, h) {
+  const fromFile = readKey(resolveEnvFile(ctx, h));
+  if (fromFile) return { key: fromFile, fromFile: true };
+  return { key: capturedKey() || (process.env.MEM0_API_KEY || "").trim(), fromFile: false };
+}
+
+/**
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+export async function smoke(ctx, h) {
+  ensureState(ctx);
+  const raw = resolveApiUrl(ctx, h);
+  const issue = urlProblem(raw);
+  if (issue) {
+    h.problem(ctx, `mem0 API URL: ${issue}`);
+    return;
+  }
+  const base = displayUrl(raw);
+
+  if (ctx.dry) {
+    h.info(`[dry-run] mem0 smoke test against ${base}:`);
+    h.info("[dry-run]   1. GET /docs must answer 2xx");
+    h.info(`[dry-run]   2. POST /memories one fact (infer false, user_id ${SMOKE_USER}, run_id ${SMOKE_RUN})`);
+    h.info("[dry-run]   3. POST /search the codename; the result must contain 'heron'");
+    h.info("[dry-run]   4. DELETE /memories/{id} for every memory created in step 2");
+    return;
+  }
+
+  // Everything that can throw sits inside the try, so cleanup always runs and an error never
+  // carries the key (messages are fixed text plus a short, key-free reason).
+  let key = "";
+  /** @type {string[]} */
+  let ids = [];
+  let failure = "";
+  /** @param {{ status: number, text: string }} res @param {string} what */
+  const failed = (res, what) => {
+    if (res.status === 401 || res.status === 403) {
+      return new SmokeFailure(
+        `${what}: the mem0 server answered ${res.status}. Put MEM0_API_KEY in ${resolveEnvFile(ctx, h)} ` +
+          "(mode 600) or run the server with AUTH_DISABLED, then rerun",
+      );
+    }
+    const body = clean(redact(res.text, key));
+    return new SmokeFailure(`${what}: the mem0 server answered ${res.status}${body ? ` (${body})` : ""}`);
+  };
+
+  h.info(`smoke test: mem0 at ${base}`);
+  try {
+    let fromFile = true;
+    try {
+      ({ key, fromFile } = smokeKey(ctx, h));
+    } catch (e) {
+      throw new SmokeFailure(
+        `cannot read the mem0 env file ${resolveEnvFile(ctx, h)} (${clean(/** @type {any} */ (e)?.code || "error", 40)})`,
+      );
+    }
+    if (key && !fromFile) {
+      h.warn(
+        `the API key comes from the environment only; the indexer reads ${path.basename(resolveEnvFile(ctx, h))} ` +
+          "(put MEM0_API_KEY there)",
+      );
+    }
+
+    // 1. Reachability (open route, no key).
+    const docs = await request(base, "GET", "/docs", { timeoutMs: 10000 });
+    if (!docs.ok) throw failed(docs, "GET /docs");
+    h.ok("GET /docs answered");
+
+    // 2. Retain verbatim. infer:false must return at least one results[].id (same rule as the sink).
+    const retain = await request(base, "POST", "/memories", { key, body: RETAIN_BODY, timeoutMs: 120000 });
+    if (!retain.ok) throw failed(retain, "POST /memories");
+    ids = memoryIds(retain.json);
+    if (!ids.length) {
+      throw new SmokeFailure(
+        "POST /memories returned no memory ids (empty results); the server must store with infer:false and return results[].id",
+      );
+    }
+    h.ok(`stored the smoke fact (${ids.length} memory)`);
+
+    // 3. Search must find it.
+    const search = await request(base, "POST", "/search", { key, body: SEARCH_BODY, timeoutMs: 120000 });
+    if (!search.ok) throw failed(search, "POST /search");
+    if (!/heron/i.test(memoryText(search.json))) {
+      throw new SmokeFailure(
+        "POST /search did not return the smoke fact: check the mem0 server's embedder key and provider " +
+          "configuration, and its logs",
+      );
+    }
+    h.ok("POST /search found the smoke fact");
+  } catch (e) {
+    failure = e instanceof SmokeFailure ? e.message : `mem0 request failed (${clean(redact(describeError(e), key), 80)})`;
+  }
+
+  // 4. Cleanup, whatever happened above: delete this run's memories and any the wizard's fixed
+  // user_id/run_id left behind earlier (a failed cleanup, an interrupted run).
+  try {
+    const found = new Set(ids);
+    try {
+      const listed = await request(
+        base,
+        "GET",
+        `/memories?user_id=${SMOKE_USER}&run_id=${SMOKE_RUN}&top_k=1000`,
+        { key, timeoutMs: 30000 },
+      );
+      if (listed.ok) for (const id of memoryIds(listed.json)) found.add(id);
+    } catch {
+      // The lookup is best effort; this run's own ids are still deleted below.
+    }
+    let removed = 0;
+    for (const id of found) {
+      try {
+        const res = await request(base, "DELETE", `/memories/${encodeURIComponent(id)}`, { key, timeoutMs: 30000 });
+        if (res.ok || res.status === 404) removed++;
+        else h.warn(`could not delete smoke memory ${clean(id, 128)}: the server answered ${res.status}`);
+      } catch (e) {
+        h.warn(`could not delete smoke memory ${clean(id, 128)}: ${clean(redact(describeError(e), key), 80)}`);
+      }
+    }
+    if (found.size && removed === found.size) h.ok("deleted the smoke memories");
+  } catch (e) {
+    h.warn(`smoke cleanup failed: ${clean(redact(describeError(e), key), 80)}`);
+  }
+
+  if (failure) h.die(failure);
+}

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

@@ -0,0 +1,255 @@
+/**
+ * mem0's contribution to scripts/setup.mjs: the stack .env entries that point the indexer at an
+ * existing mem0 server, and the end-of-run notices about the indexer's API key file and about
+ * a loopback-only server. Runs as a plain Node script step (no wizard context), so it only reads
+ * process environment and the paths it is given. It reads the key file only to see whether a key
+ * exists (the same parse as docker compose) and never prints or returns the key.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { ensureLitellmEnv } from "../../../wizard/lib/litellm-env.mjs";
+import { envValue } from "../../../wizard/lib/paths.mjs";
+import { parseEnvValue } from "./dotenv.mjs";
+import { envFileProblem } from "./state.mjs";
+
+/** Hostnames that mean "this machine" on the host and so must become the host gateway in a container. */
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "0.0.0.0", "[::1]"]);
+
+/** Appended to every URL error. The messages never echo the URL, which may hold a secret. */
+const SECRET_HINT = "put MEM0_API_KEY in the mem0 env file instead of the URL";
+
+/**
+ * Parse and validate the mem0 server URL as the operator's host sees it.
+ * @param {string} hostUrl
+ * @returns {URL}
+ */
+function parseHostUrl(hostUrl) {
+  const text = String(hostUrl ?? "").trim();
+  // The URL parser silently drops tabs and newlines, so check the raw text: a newline would
+  // otherwise let one value write a second KEY=value line into the stack .env.
+  if (/[\x00-\x20\x7f]/.test(text)) {
+    throw new Error(`MEM0_API_URL must not contain spaces or control characters; ${SECRET_HINT}`);
+  }
+  if (text.includes("$")) {
+    throw new Error(`MEM0_API_URL must not contain '$' (compose would interpolate it); ${SECRET_HINT}`);
+  }
+  let url;
+  try {
+    url = new URL(text);
+  } catch {
+    throw new Error("MEM0_API_URL is not a valid URL (expected http://host:port or https://host:port)");
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new Error(`MEM0_API_URL must use http or https (got: ${url.protocol.replace(":", "")})`);
+  }
+  if (url.username || url.password) {
+    // The stack .env is world-readable; secrets belong in the mode 600 env file.
+    throw new Error(`MEM0_API_URL must not contain credentials; ${SECRET_HINT}`);
+  }
+  if (url.search || url.hash) {
+    throw new Error(`MEM0_API_URL must not contain a query or fragment; ${SECRET_HINT}`);
+  }
+  return url;
+}
+
+/**
+ * The normalized host-view URL (scheme, host, port and path; no trailing slash). This is what
+ * the stack .env stores as MEM0_API_URL, never the raw string.
+ * @param {string} hostUrl
+ * @returns {string}
+ */
+export function normalizeHostUrl(hostUrl) {
+  return parseHostUrl(hostUrl).toString().replace(/\/+$/, "");
+}
+
+/**
+ * The server URL as the indexer container sees it: loopback hosts become host.docker.internal;
+ * scheme, port and path are kept and a trailing slash is removed.
+ * @param {string} hostUrl URL as the operator's host sees it (for example http://127.0.0.1:18888)
+ * @returns {string}
+ */
+export function indexerUrl(hostUrl) {
+  const url = parseHostUrl(hostUrl);
+  if (LOOPBACK_HOSTS.has(url.hostname)) url.hostname = "host.docker.internal";
+  return url.toString().replace(/\/+$/, "");
+}
+
+/** Absolute path of the shipped LiteLLM config under the code root. */
+function shippedLitellmConfig() {
+  const moduleRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+  const root = path.resolve(process.env.PM_PACKAGE_ROOT || moduleRoot);
+  const file = path.join(root, "config", "litellm.lemond.yaml");
+  if (!fs.existsSync(file)) {
+    throw new Error("shipped config/litellm.lemond.yaml missing: broken install");
+  }
+  return file;
+}
+
+/**
+ * The env file path for a custom location: MEM0_ENV_FILE from the process environment, with a
+ * leading ~ expanded, or "" when the process does not set one.
+ * @param {NodeJS.ProcessEnv} env
+ * @param {string} [home]
+ */
+function customEnvFile(env, home) {
+  const raw = (env.MEM0_ENV_FILE || "").trim();
+  if (!raw) return "";
+  if (raw === "~" || raw.startsWith("~/")) return path.join(home || env.HOME || "", raw.slice(2));
+  return raw;
+}
+
+/**
+ * Check the stack LiteLLM option's inputs and make sure litellm.env has a master key.
+ * @param {{ home?: string, env: NodeJS.ProcessEnv }} opts
+ * @returns {{ config: string, port: string }}
+ */
+function litellmOption({ home, env }) {
+  const config = (env.MEM0_LITELLM_CONFIG || "").trim() || path.join(home || "", ".config/personal-memory/mem0-litellm.yaml");
+  if (!path.isAbsolute(config) || /[\x00-\x20\x7f$"'`\\]/.test(config)) {
+    throw new Error("MEM0_LITELLM_CONFIG must be an absolute path without spaces, quotes, '$' or backslashes");
+  }
+  if (!fs.existsSync(config)) throw new Error(`${config} is missing: rerun ./setup to write the mem0 LiteLLM routes`);
+  const port = (env.MEM0_LITELLM_PORT || "4000").trim();
+  if (!/^\d+$/.test(port) || Number(port) < 1 || Number(port) > 65535) {
+    throw new Error("MEM0_LITELLM_PORT must be a port number (1-65535)");
+  }
+  const litellmEnv = (env.LITELLM_ENV_FILE || "").trim() || path.join(home || "", ".config/hindsight/litellm.env");
+  if (ensureLitellmEnv(litellmEnv)) console.log(`created ${litellmEnv} (mode 600)`);
+  const key = envValue(litellmEnv, "LITELLM_MASTER_KEY");
+  if (!/^sk-\S+$/.test(key)) {
+    throw new Error(`LITELLM_MASTER_KEY=sk-... is missing from ${litellmEnv}; the loopback LiteLLM refuses to start without it`);
+  }
+  return { config, port };
+}
+
+/**
+ * @param {{ repo: string, home?: string, env: NodeJS.ProcessEnv }} opts
+ * @returns {{ entries: [string, string][], drop: string[], report: string[] }}
+ *   entries: KEY=value lines to add to the stack .env; drop: keys to remove first;
+ *   report: KEY=value strings echoed in the "wrote .env" line
+ */
+export function prepareStackEnv({ repo, home, env }) {
+  const stackEnv = path.join(repo, ".env");
+  const rawUrl = (env.MEM0_API_URL || envValue(stackEnv, "MEM0_API_URL")).trim();
+  if (!rawUrl) {
+    throw new Error(
+      "MEM0_API_URL is required (the mem0 server URL as this host sees it, e.g. http://127.0.0.1:18888); " +
+        "the wizard sets it before running setup",
+    );
+  }
+  const hostUrl = normalizeHostUrl(rawUrl);
+  const containerUrl = indexerUrl(rawUrl);
+
+  // compose.yaml interpolates every service before it filters by profile, and `litellm` mounts
+  // ${LITELLM_CONFIG:?...}. litellm is gated by the profile "hindsight", so under the mem0 profile it never
+  // runs and the value is inert; it only has to be set (to an existing file) for `docker compose config`
+  // and `up` to get past interpolation. Precedence: the operator's process env, then a non-empty value
+  // already in the stack .env, then the shipped config. LITELLM_CONFIG is always dropped and rewritten, which
+  // also removes an empty `LITELLM_CONFIG=` line that would still fail the `:?` check.
+  //
+  // With the stack LiteLLM option on (MEM0_LITELLM=1, set by the wizard), litellm runs under the profile "litellm":
+  // LITELLM_CONFIG is the mem0 route file, litellm.env must hold an sk- master key (created here when missing, the
+  // same file and mechanism as Hindsight), and MEM0_LITELLM_PORT is the loopback port.
+  const litellm = env.MEM0_LITELLM === "1" ? litellmOption({ home, env }) : null;
+  const litellmConfig =
+    litellm?.config ||
+    (env.LITELLM_CONFIG || "").trim() ||
+    envValue(stackEnv, "LITELLM_CONFIG").trim() ||
+    shippedLitellmConfig();
+
+  const profiles = ["mem0"];
+  if (litellm) profiles.push("litellm");
+  const notebookYml = path.join(home, ".config/hindsight/notebooklm.yml");
+  if (fs.existsSync(notebookYml) && /^enabled:\s*true\b/m.test(fs.readFileSync(notebookYml, "utf8"))) {
+    profiles.push("notebooklm");
+  }
+
+  /** @type {[string, string][]} */
+  const entries = [
+    ["MEM0_API_URL", hostUrl],
+    ["MEM0_INDEXER_URL", containerUrl],
+    ["MEMORY_API_URL", containerUrl],
+    // Like Hindsight, name the profile in the stack .env so a plain `docker compose config` agrees with the wizard.
+    ["COMPOSE_PROFILES", profiles.join(",")],
+    ["MEMORY_SINK", "mem0"],
+    ["LITELLM_CONFIG", litellmConfig],
+  ];
+  const drop = ["MEM0_API_URL", "MEM0_INDEXER_URL", "COMPOSE_PROFILES", "LITELLM_CONFIG", "MEMORY_API_URL", "MEMORY_SINK"];
+  const report = [`MEM0_INDEXER_URL=${containerUrl}`, `COMPOSE_PROFILES=${profiles.join(",")}`, `LITELLM_CONFIG=${litellmConfig}`];
+  if (litellm) {
+    entries.push(["MEM0_LITELLM_PORT", litellm.port]);
+    drop.push("MEM0_LITELLM_PORT");
+    report.push(`MEM0_LITELLM_PORT=${litellm.port}`);
+  }
+
+  // A custom key file location is a path, not a secret: persist it so a hand-run `docker compose`
+  // and `./pm up` read the same env_file as this run. With no custom path in the process
+  // environment an existing line is left alone (the wizard reads it back too).
+  const envFile = customEnvFile(env, home);
+  if (envFile) {
+    const problem = envFileProblem(envFile);
+    if (problem) throw new Error(`MEM0_ENV_FILE: ${problem}`);
+    entries.push(["MEM0_ENV_FILE", envFile]);
+    drop.push("MEM0_ENV_FILE");
+    report.push(`MEM0_ENV_FILE=${envFile}`);
+  }
+  return { entries, drop, report };
+}
+
+/**
+ * Printed at the end of setup: the indexer's mem0 key file is missing, has no key or is too open,
+ * and the server URL points at a loopback address the container may not reach.
+ * @param {{ repo?: string, home: string, env: NodeJS.ProcessEnv }} opts
+ * @returns {string[]}
+ */
+export function setupNotices({ repo, home, env }) {
+  const stackEnvFile = repo ? path.join(repo, ".env") : "";
+  const configured = customEnvFile(env, home) || (stackEnvFile ? customEnvFile({ MEM0_ENV_FILE: envValue(stackEnvFile, "MEM0_ENV_FILE") }, home) : "");
+  const file = configured || path.join(home, ".config/personal-memory/mem0.env");
+  // Same parse as docker compose: an empty, commented or unterminated value is no key.
+  const hasKey = fs.existsSync(file) && parseEnvValue(fs.readFileSync(file, "utf8"), "MEM0_API_KEY") !== "";
+  /** @type {string[]} */
+  const notes = [];
+  if (!hasKey) {
+    notes.push(
+      `NOTE: mem0 needs an API key for the indexer: put MEM0_API_KEY=... in ${file} (mode 600).`,
+      "      Not needed when the server runs with AUTH_DISABLED.",
+    );
+  }
+  if (fs.existsSync(file)) {
+    const mode = fs.statSync(file).mode & 0o777;
+    if (mode & 0o077) {
+      notes.push(
+        `NOTE: ${file} is readable by group or others (mode ${mode.toString(8)}). Run: chmod 600 ${file}`,
+      );
+    }
+    const dir = path.dirname(file);
+    const dirMode = fs.statSync(dir).mode & 0o777;
+    if (dirMode & 0o077) {
+      notes.push(`NOTE: ${dir} is accessible to group or others (mode ${dirMode.toString(8)}). Run: chmod 700 ${dir}`);
+    }
+  }
+
+  const rawUrl = (env.MEM0_API_URL || (stackEnvFile ? envValue(stackEnvFile, "MEM0_API_URL") : "")).trim();
+  if (rawUrl) {
+    try {
+      const url = parseHostUrl(rawUrl);
+      if (LOOPBACK_HOSTS.has(url.hostname)) {
+        notes.push(
+          "NOTE: MEM0_API_URL is a loopback address; the indexer container reaches it as host.docker.internal.",
+          "      On Linux a mem0 server bound only to 127.0.0.1 is NOT reachable that way: bind it to 0.0.0.0",
+          "      or the docker bridge IP, or use a hostname in MEM0_API_URL.",
+        );
+        if (url.protocol === "https:") {
+          notes.push(
+            "      An https loopback URL becomes host.docker.internal, which will not match the server certificate name.",
+          );
+        }
+      }
+    } catch {
+      // prepareStackEnv already rejected an unusable URL; nothing to add here.
+    }
+  }
+  return notes;
+}

package/providers/mem0/lib/state.mjs

@@ -0,0 +1,67 @@
+/**
+ * mem0 wizard state on the context object, the default URL, and the API key file path.
+ * mem0 v1 is URL-only: the operator runs a mem0 REST server and this stack points the
+ * indexer at it.
+ */
+import path from "node:path";
+
+/** A stock mem0 server publishes 8888, the Hindsight default; this repo avoids it. */
+export const DEFAULT_API_URL = "http://127.0.0.1:18888";
+
+/** @typedef {import("../../../wizard/lib/provider-wizard/helpers.mjs").ProviderWizardHelpers} Helpers */
+
+/**
+ * Fill the mem0 fields of the wizard context. Idempotent: a field that is already set
+ * (TOML mapping in `init`, a test) is kept.
+ * @param {Record<string, any>} ctx
+ */
+export function ensureState(ctx) {
+  const state = (ctx.mem0 ||= {});
+  const defaults = {
+    // [memory.mem0] api_url / env_file, filled by the init hook.
+    apiUrl: "",
+    tomlEnvFile: "",
+    // wizard.conf value, filled by the hydrate hook.
+    savedUrl: "",
+    // The validated host-view URL this run uses, set by resolvePorts / configureModelRouting.
+    url: "",
+  };
+  for (const [key, value] of Object.entries(defaults)) {
+    if (state[key] === undefined) state[key] = value;
+  }
+  return state;
+}
+
+/** @param {string} home */
+export function defaultEnvFile(home) {
+  return path.join(home || "", ".config/personal-memory/mem0.env");
+}
+
+/**
+ * The file that holds MEM0_API_KEY for the indexer: MEM0_ENV_FILE, then [memory.mem0]
+ * env_file, then MEM0_ENV_FILE in the stack .env (written by scripts/setup.mjs), then
+ * ~/.config/personal-memory/mem0.env.
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+export function resolveEnvFile(ctx, h) {
+  const state = ensureState(ctx);
+  const stackValue = ctx.repoRoot ? h.envValue(path.join(ctx.repoRoot, ".env"), "MEM0_ENV_FILE") : "";
+  const raw = (process.env.MEM0_ENV_FILE || state.tomlEnvFile || stackValue || "").trim();
+  if (!raw) return defaultEnvFile(ctx.home);
+  return h.expandHome(raw, ctx.home);
+}
+
+/**
+ * What is wrong with an env file path, or "". Compose interpolates the path in the
+ * indexer's `env_file` and the stack .env stores it, so it must be absolute and free of control
+ * characters, quotes, '$', backslashes, ' #' and leading or trailing spaces.
+ * @param {string} file
+ */
+export function envFileProblem(file) {
+  if (!path.isAbsolute(file)) return "the mem0 env file path must be absolute (MEM0_ENV_FILE or env_file)";
+  if (/[\x00-\x1f\x7f$"'`\\]/.test(file) || file.includes(" #") || file !== file.trim()) {
+    return "the mem0 env file path must not contain control characters, quotes, '$', backslashes, ' #' or edge spaces";
+  }
+  return "";
+}

package/providers/mem0/lib/summary.mjs

@@ -0,0 +1,88 @@
+/** mem0's contribution to the wizard's closing summary. */
+import path from "node:path";
+import { readKey } from "./env-file.mjs";
+import { LLM_ALIAS, litellmEnvFile, routesFile } from "./litellm.mjs";
+import { MERIDIAN_TERMS_URL } from "../../hindsight/lib/meridian.mjs";
+import { resolveEnvFile, ensureState } from "./state.mjs";
+import { containerUrl, displayUrl, resolveApiUrl, urlProblem } from "./url.mjs";
+
+/** @typedef {import("../../../wizard/lib/provider-wizard/helpers.mjs").ProviderWizardHelpers} Helpers */
+
+const DOCS = "https://docs.mem0.ai/open-source/features/rest-api";
+const OPERATOR = "providers/mem0/OPERATOR.md";
+
+/**
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ * @returns {{ running: string[], configFiles: string[], notes: string[], logServices: string[] }}
+ */
+export function summary(ctx, h) {
+  ensureState(ctx);
+  const raw = resolveApiUrl(ctx, h);
+  const valid = !urlProblem(raw);
+  const url = valid ? displayUrl(raw) : "(invalid URL)";
+  const envFile = resolveEnvFile(ctx, h);
+
+  const running = [
+    `  mem0 API           ${url}  external server (not managed by this stack)`,
+    `  indexer sink       mem0 -> ${valid ? containerUrl(raw) : "(invalid URL)"} (the container's view)`,
+  ];
+  const configFiles = [
+    `  ${envFile} (MEM0_API_KEY for the indexer, mode 600)`,
+    `  ${path.join(ctx.repoRoot, ".env")} (MEM0_API_URL, MEM0_INDEXER_URL; no secrets)`,
+  ];
+
+  // The stack LiteLLM option: this run's answer, else what the last configure run saved (`--up`, `--down`).
+  const saved = (k) => (ctx.wizardConf ? h.envValue(ctx.wizardConf, k) : "");
+  const litellm =
+    ctx.mem0?.litellm !== undefined
+      ? ctx.mem0.litellm
+      : saved("MEM0_LITELLM") === "1"
+        ? { backend: saved("MEM0_LITELLM_BACKEND"), model: saved("MEM0_LITELLM_MODEL"), port: saved("MEM0_LITELLM_PORT") || "4000" }
+        : null;
+  /** @type {string[]} */
+  const logServices = ["indexer"];
+  if (litellm) {
+    running.push(
+      `  LiteLLM (mem0)     http://127.0.0.1:${litellm.port}/v1  ${LLM_ALIAS} -> ${litellm.backend} ${litellm.model}; loopback only, master key required`,
+    );
+    configFiles.push(`  ${routesFile(ctx.home)} (mem0 LiteLLM routes)`, `  ${litellmEnvFile(ctx.home)} (LITELLM_MASTER_KEY and provider keys, mode 600)`);
+    logServices.push("litellm");
+  }
+
+  /** @type {string[]} */
+  const notes = [];
+  if (ctx.action === "down") return { running, configFiles, notes, logServices };
+  let loopback = false;
+  if (valid) {
+    const parsed = new URL(raw);
+    loopback = ["127.0.0.1", "localhost", "0.0.0.0", "[::1]"].includes(parsed.hostname);
+  }
+  let hasKey = false;
+  try {
+    hasKey = readKey(envFile) !== "";
+  } catch {
+    hasKey = false;
+  }
+  if (!hasKey) {
+    notes.push(
+      `API key: create one in your mem0 dashboard (port varies by install) or with POST /api-keys, then put MEM0_API_KEY=<key> in ${envFile} (mode 600). ` +
+        "A server run with AUTH_DISABLED=true needs none (development only).",
+    );
+  }
+  notes.push(
+    `The mem0 server is yours to run: first-time setup (JWT_SECRET, embedder keys) is provider-native — ${OPERATOR} and ${DOCS}`,
+    loopback
+      ? "The indexer container reaches a loopback server as host.docker.internal; on Linux a server bound only to 127.0.0.1 is not reachable that way: bind it to 0.0.0.0 or the docker bridge IP, or use a hostname in MEM0_API_URL."
+      : "The indexer container must be able to reach the server at the URL above (it uses the same host name).",
+  );
+  if (litellm) {
+    notes.push(
+      `mem0's LLM: point your mem0 config at http://127.0.0.1:${litellm.port}/v1 (provider openai, model ${LLM_ALIAS}, api_key = LITELLM_MASTER_KEY); ./setup printed the blocks. See docs/mem0.md.`,
+    );
+    if (litellm.backend === "meridian") {
+      notes.push(`Claude subscription use through Meridian is governed by Anthropic's Consumer Terms: ${MERIDIAN_TERMS_URL}`);
+    }
+  }
+  return { running, configFiles, notes, logServices };
+}