@bcmyguest/openmem 0.0.0-stage → 0.6.3

package/providers/mem0/lib/mcp-install.mjs

@@ -0,0 +1,165 @@
+/**
+ * Merge a usable mem0 MCP into ~/.cursor/mcp.json for the self-hosted REST server.
+ *
+ * Upstream stdio bridge: npx -y @yeyuan98/mem0-mcp (fronts MEM0_BASE_URL with X-API-Key).
+ * Official Mem0 MCP is cloud-only (https://mcp.mem0.ai); the OSS docs page is gone.
+ *
+ * mcp.json never holds MEM0_API_KEY. The launcher (cli/mem0-mcp.mjs) loads the key from
+ * MEM0_ENV_FILE / ~/.config/personal-memory/mem0.env when the process env lacks it.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { envValue } from "../../../wizard/lib/paths.mjs";
+import { DEFAULT_API_URL, defaultEnvFile } from "./state.mjs";
+
+/** Sibling MCP servers this merge must never rewrite. */
+export const MEM0_MCP_PROTECTED = Object.freeze(["hindsight", "codegraph", "notebooklm"]);
+
+/** npm package that speaks the open-source REST API (not platform mcp.mem0.ai). */
+export const MEM0_MCP_NPM_PACKAGE = "@yeyuan98/mem0-mcp";
+
+/** @param {string} [pkgRoot] absolute package / checkout root */
+export function mem0McpScriptPath(pkgRoot) {
+  const root =
+    pkgRoot ||
+    path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../..");
+  return path.resolve(root, "cli/mem0-mcp.mjs");
+}
+
+/**
+ * MEM0_API_URL from env, stack .env, wizard.conf, then default. Never returns secrets.
+ * @param {{ home: string, stackRoot: string, env?: NodeJS.ProcessEnv }} opts
+ */
+export function resolveMem0ApiUrl({ home, stackRoot, env = process.env }) {
+  const candidates = [
+    env.MEM0_API_URL,
+    env.PM_MEM0_API_URL,
+    envValue(path.join(stackRoot, ".env"), "MEM0_API_URL"),
+    envValue(path.join(home, ".config/hindsight/wizard.conf"), "MEM0_API_URL"),
+  ];
+  const first = candidates.map((v) => String(v || "").trim()).find(Boolean);
+  return (first || DEFAULT_API_URL).replace(/\/+$/, "");
+}
+
+/**
+ * Path to the API key file (path only — never read the key here).
+ * @param {{ home: string, stackRoot: string, env?: NodeJS.ProcessEnv }} opts
+ */
+export function resolveMem0EnvFilePath({ home, stackRoot, env = process.env }) {
+  const candidates = [
+    env.MEM0_ENV_FILE,
+    envValue(path.join(stackRoot, ".env"), "MEM0_ENV_FILE"),
+  ];
+  const raw = candidates.map((v) => String(v || "").trim()).find(Boolean);
+  if (!raw) return defaultEnvFile(home);
+  if (raw.startsWith("~/")) return path.join(home, raw.slice(2));
+  if (path.isAbsolute(raw)) return raw;
+  return path.resolve(stackRoot, raw);
+}
+
+/**
+ * Cursor mcp.json entry: node launcher → npx @yeyuan98/mem0-mcp.
+ * Sets MEM0_API_URL + MEM0_BASE_URL (upstream reads BASE_URL). Path to key file only.
+ * @param {{ apiUrl: string, scriptPath: string, envFile?: string }} opts
+ */
+export function mem0McpEntry({ apiUrl, scriptPath, envFile }) {
+  const url = String(apiUrl || "").replace(/\/+$/, "");
+  /** @type {Record<string, string>} */
+  const env = {
+    MEM0_API_URL: url,
+    MEM0_BASE_URL: url,
+  };
+  if (envFile) env.MEM0_ENV_FILE = envFile;
+  return {
+    command: "node",
+    args: [scriptPath],
+    env,
+  };
+}
+
+/**
+ * @param {Record<string, any>} mcp
+ * @param {{ apiUrl: string, scriptPath: string, envFile?: string }} opts
+ * @returns {{ mcp: Record<string, any>, changed: boolean, skipped?: string, refused?: string }}
+ */
+export function mergeMem0McpServer(mcp, opts) {
+  const entry = mem0McpEntry(opts);
+  const out = { ...mcp };
+  const servers = {
+    ...(mcp.mcpServers && typeof mcp.mcpServers === "object" ? mcp.mcpServers : {}),
+  };
+  const before = Object.fromEntries(MEM0_MCP_PROTECTED.map((k) => [k, servers[k]]));
+  const prev = servers.mem0;
+  const same = prev && JSON.stringify(prev) === JSON.stringify(entry);
+  if (same) {
+    return { mcp: { ...out, mcpServers: servers }, changed: false, skipped: "already configured" };
+  }
+  servers.mem0 = entry;
+  for (const k of MEM0_MCP_PROTECTED) {
+    if (before[k] !== undefined && servers[k] !== before[k]) {
+      return { mcp, changed: false, refused: `refusing to alter ${k} MCP entry` };
+    }
+  }
+  return { mcp: { ...out, mcpServers: servers }, changed: true };
+}
+
+/**
+ * @param {{
+ *   home: string,
+ *   repoRoot: string,
+ *   stackRoot: string,
+ *   dry?: boolean,
+ *   env?: NodeJS.ProcessEnv,
+ * }} ctx
+ * @param {{ info: Function, ok: Function, warn: Function }} h
+ */
+export async function installMem0Mcp(ctx, h) {
+  const env = ctx.env || process.env;
+  const apiUrl = resolveMem0ApiUrl({ home: ctx.home, stackRoot: ctx.stackRoot, env });
+  const envFile = resolveMem0EnvFilePath({ home: ctx.home, stackRoot: ctx.stackRoot, env });
+  const scriptPath = mem0McpScriptPath(ctx.repoRoot);
+  if (!fs.existsSync(scriptPath)) {
+    h.warn(`mem0 MCP launcher missing: ${scriptPath}`);
+    return { changed: false };
+  }
+
+  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 { changed: false };
+    }
+  }
+
+  const { mcp, changed, skipped, refused } = mergeMem0McpServer(existing, {
+    apiUrl,
+    scriptPath,
+    envFile,
+  });
+  if (refused) {
+    h.warn(refused);
+    return { changed: false, refused };
+  }
+  if (!changed) {
+    h.ok(`mem0 MCP already in ${mcpPath}${skipped ? ` (${skipped})` : ""}`);
+    return { changed: false, skipped };
+  }
+  if (ctx.dry) {
+    h.info(
+      `[dry-run] merge mem0 MCP into ${mcpPath} → node ${scriptPath}` +
+        ` (MEM0_API_URL=${apiUrl}; key via ${envFile} or MEM0_API_KEY in the agent env — never written to mcp.json)`,
+    );
+    return { changed: true, dry: true };
+  }
+  fs.mkdirSync(path.dirname(mcpPath), { recursive: true });
+  fs.writeFileSync(mcpPath, `${JSON.stringify(mcp, null, 2)}\n`);
+  h.ok(`registered mem0 MCP in ${mcpPath}`);
+  h.info(
+    `API key: export MEM0_API_KEY from ${envFile} (or leave it for the launcher to load). Never put the key in mcp.json.`,
+  );
+  return { changed: true };
+}

package/providers/mem0/lib/secret.mjs

@@ -0,0 +1,30 @@
+/**
+ * Holds the API key the operator handed over through the environment, out of process.env.
+ * The `init` hook runs before preflight spawns docker and curl, so capturing it there keeps
+ * the key out of every child process environment. The value lives in this module only: it is
+ * not a property of the wizard context and is never serialised.
+ */
+
+let captured = "";
+
+/**
+ * Move PM_MEM0_API_KEY (the Clack hand-off) and MEM0_API_KEY out of process.env. The hand-off
+ * wins. Nothing is restored. When neither variable is set an earlier capture is kept.
+ */
+export function captureKeyFromEnv() {
+  const handoff = (process.env.PM_MEM0_API_KEY || "").trim();
+  const plain = (process.env.MEM0_API_KEY || "").trim();
+  delete process.env.PM_MEM0_API_KEY;
+  delete process.env.MEM0_API_KEY;
+  if (handoff || plain) captured = handoff || plain;
+}
+
+/** The captured key, or "". */
+export function capturedKey() {
+  return captured;
+}
+
+/** Forget the captured key (tests). */
+export function clearCapturedKey() {
+  captured = "";
+}

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,216 @@
+/**
+ * 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 { 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;
+}
+
+/**
+ * @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.
+  const litellmConfig =
+    (env.LITELLM_CONFIG || "").trim() || envValue(stackEnv, "LITELLM_CONFIG").trim() || shippedLitellmConfig();
+
+  const profiles = ["mem0"];
+  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}`];
+
+  // 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 "";
+}