@bcmyguest/openmem 0.0.0-stage → 0.8.0

package/providers/mem0/lib/configure.mjs

@@ -0,0 +1,201 @@
+/**
+ * Step "3. mem0 server URL and API key" (the hook is still named configureModelRouting).
+ * mem0 v1 is URL-only: this asks for the REST server URL and the API key the indexer sends,
+ * keeps the key in the mode 600 env file and never anywhere else. Keys can also be placed in
+ * that file by hand.
+ */
+import path from "node:path";
+import { applyConfig, configToml } from "./config.mjs";
+import { dirTooOpen, fileMode, keyProblem, readKey, tooOpen, writeKey } from "./env-file.mjs";
+import { EMBED_BACKENDS, storedChoice } from "./litellm.mjs";
+import { capturedKey, captureKeyFromEnv } from "./secret.mjs";
+import { ensureState, envFileProblem, resolveEnvFile } from "./state.mjs";
+import { displayUrl, resolveApiUrl, urlProblem } from "./url.mjs";
+
+/** @typedef {import("../../../wizard/lib/provider-wizard/helpers.mjs").ProviderWizardHelpers} Helpers */
+
+/**
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+export async function configureUrlAndKey(ctx, h) {
+  const state = ensureState(ctx);
+  h.step("3. mem0 server URL and API key");
+  const interactive = !ctx.yes && !ctx.skipBackendStep;
+  if (ctx.skipBackendStep) h.info("mem0 URL and key come from the setup UI (environment)");
+
+  // URL.
+  let raw = resolveApiUrl(ctx, h);
+  if (interactive) {
+    raw = String(await h.ask(ctx, "mem0 REST server URL (as this host sees it)", raw)).trim().replace(/\/+$/, "");
+  }
+  const urlIssue = urlProblem(raw);
+  if (urlIssue) {
+    h.problem(ctx, `mem0 API URL: ${urlIssue}`);
+    return;
+  }
+  const url = displayUrl(raw);
+  state.apiUrl = url;
+  state.url = url;
+  process.env.MEM0_API_URL = url;
+  h.ok(`mem0 server ${url} (an external server you run; this stack does not start it)`);
+
+  // Key file.
+  const envFile = resolveEnvFile(ctx, h);
+  const fileIssue = envFileProblem(envFile);
+  if (fileIssue) {
+    h.problem(ctx, fileIssue);
+    return;
+  }
+  const existing = readKey(envFile);
+  // Normally captured by the init hook (before any child process starts); this covers a caller
+  // that skipped init and is a no-op once the variables are gone.
+  captureKeyFromEnv();
+  const key = capturedKey();
+  if (key) h.info("using the API key from the environment");
+
+  if (key) {
+    const keyIssue = keyProblem(key);
+    if (keyIssue) {
+      h.problem(ctx, keyIssue);
+      return;
+    }
+    if (ctx.dry) {
+      h.info(`[dry-run] write MEM0_API_KEY to ${envFile} (mode 600, directory mode 700)`);
+    } else {
+      const result = writeKey(envFile, key);
+      if (result === "unchanged") h.ok(`kept ${envFile} (same key, mode 600)`);
+      else h.ok(`${result === "created" ? "created" : "updated"} ${envFile} with MEM0_API_KEY (mode 600)`);
+    }
+  } else if (existing) {
+    h.ok(`kept the API key already in ${envFile}`);
+    if (tooOpen(envFile)) {
+      h.warn(`${envFile} is group/other accessible (mode ${fileMode(envFile).toString(8)}); run: chmod 600 ${envFile}`);
+    }
+  } else {
+    // No prompt here: helpers.ask echoes what is typed. The setup UI (Clack) asks with a masked prompt.
+    h.info(
+      `no API key given. A server with auth enabled (the default) needs one: put MEM0_API_KEY=<key> in ${envFile} (mode 600), ` +
+        "or rerun with MEM0_API_KEY (or PM_MEM0_API_KEY) in the environment under --yes. " +
+        "A server run with AUTH_DISABLED does not need a key.",
+    );
+  }
+  if (dirTooOpen(envFile)) {
+    h.warn(`${path.dirname(envFile)} is accessible to group or others; run: chmod 700 ${path.dirname(envFile)}`);
+  }
+
+  // Non-secret state: wizard.conf (+ config.toml) record the URL only.
+  if (ctx.dry) h.info(`[dry-run] record MEM0_API_URL in ${ctx.wizardConf} and [memory.mem0] in config.toml`);
+  else h.saveWizardConf(ctx, { MEM0_API_URL: url }, { pmSections: configToml(ctx, url) });
+}
+
+/**
+ * Clack front end: ask the URL and (masked) key, hand them to the wizard through the
+ * environment and skip the wizard's own prompts.
+ * @param {{ repoRoot: string, home: string, wizardConf: string, pmMerged?: Record<string, unknown> }} ctx
+ * @param {typeof import("@clack/prompts")} ui
+ * @param {Helpers} h
+ * @returns {Promise<Record<string, string>>}
+ */
+export async function clackSetup(ctx, ui, h) {
+  const stub = /** @type {Record<string, any>} */ (ctx);
+  ensureState(stub);
+  applyConfig(stub);
+  const current = resolveApiUrl(stub, h);
+  const existing = readKey(resolveEnvFile(stub, h));
+
+  const typed = await ui.text({
+    message: "mem0 REST server URL (as this host sees it)",
+    placeholder: current,
+    defaultValue: current,
+    validate: (v) => urlProblem(String(v || "").trim().replace(/\/+$/, "") || current) || undefined,
+  });
+  if (ui.isCancel(typed)) {
+    ui.cancel("Setup cancelled.");
+    process.exit(0);
+  }
+  const url = String(typed || "").trim().replace(/\/+$/, "") || current;
+
+  const secret = await ui.password({
+    message: existing
+      ? "mem0 API key (empty keeps the one in the env file)"
+      : "mem0 API key (empty if the server has auth disabled)",
+    validate: (v) => keyProblem(String(v || "").trim()) || undefined,
+  });
+  if (ui.isCancel(secret)) {
+    ui.cancel("Setup cancelled.");
+    process.exit(0);
+  }
+
+  /** @type {Record<string, string>} */
+  const handoff = { WIZARD_SKIP_BACKEND_STEP: "1", MEM0_API_URL: url };
+  const key = String(secret || "").trim();
+  if (key) handoff.PM_MEM0_API_KEY = key;
+  Object.assign(handoff, await clackLitellm(stub, ui, h));
+  ui.note("Next: Docker, indexing, and starting the stack.", "mem0 configured");
+  return handoff;
+}
+
+/**
+ * Clack questions for "route mem0's LLM through the stack LiteLLM". Returns the MEM0_LITELLM_*
+ * handoff (and ANTHROPIC_API_KEY when typed); the wizard step reads them under WIZARD_SKIP_BACKEND_STEP.
+ * @param {Record<string, any>} ctx
+ * @param {typeof import("@clack/prompts")} ui
+ * @param {Helpers} h
+ * @returns {Promise<Record<string, string>>}
+ */
+async function clackLitellm(ctx, ui, h) {
+  const exitIfCancel = (v) => {
+    if (ui.isCancel(v)) {
+      ui.cancel("Setup cancelled.");
+      process.exit(0);
+    }
+    return v;
+  };
+  const current = storedChoice(ctx, h);
+  const on = exitIfCancel(
+    await ui.confirm({
+      message: "Route mem0's LLM through the stack LiteLLM (same gateway as Hindsight; 127.0.0.1 only)?",
+      initialValue: current.enabled,
+    }),
+  );
+  if (!on) return { MEM0_LITELLM: "0" };
+  const backend = /** @type {string} */ (
+    exitIfCancel(
+      await ui.select({
+        message: "LiteLLM backend for mem0's LLM",
+        options: [
+          { value: "ollama", label: "Ollama", hint: "LLM and embeddings (nomic-embed-text)" },
+          { value: "custom", label: "Custom OpenAI-compatible URL", hint: "lemond, vLLM, OpenAI, ..." },
+          { value: "anthropic", label: "Anthropic API key", hint: "Claude; no embeddings" },
+          { value: "meridian", label: "Claude subscription (Meridian)", hint: "Anthropic Consumer Terms apply; no embeddings" },
+        ],
+        initialValue: current.backend,
+      }),
+    )
+  );
+  const c = storedChoice(ctx, h, backend);
+  /** @type {Record<string, string>} */
+  const out = { MEM0_LITELLM: "1", MEM0_LITELLM_BACKEND: backend };
+  if (backend === "ollama" || backend === "custom") {
+    out.MEM0_LITELLM_API_BASE = String(
+      exitIfCancel(await ui.text({ message: "Model server base URL (as the litellm container sees it)", placeholder: c.apiBase, defaultValue: c.apiBase })) || c.apiBase,
+    ).trim();
+  }
+  out.MEM0_LITELLM_MODEL = String(
+    exitIfCancel(await ui.text({ message: "Model id for mem0's LLM", placeholder: c.model, defaultValue: c.model })) || c.model,
+  ).trim();
+  if (EMBED_BACKENDS.includes(backend)) {
+    const def = c.embedModel || "none";
+    out.MEM0_LITELLM_EMBED_MODEL = String(
+      exitIfCancel(await ui.text({ message: "Embedding model through LiteLLM (none keeps mem0's own embedder)", placeholder: def, defaultValue: def })) || def,
+    ).trim();
+  }
+  if (backend === "anthropic") {
+    const secret = String(
+      exitIfCancel(await ui.password({ message: "ANTHROPIC_API_KEY for litellm.env (empty keeps the one there)" })) || "",
+    ).trim();
+    if (secret) out.PM_ANTHROPIC_API_KEY = secret;
+  }
+  return out;
+}

package/providers/mem0/lib/dotenv.mjs

@@ -0,0 +1,71 @@
+/**
+ * Read one key from an env file the way docker compose's env_file loader does, so the key the
+ * wizard checks is the key the indexer container gets. Node builtins only: scripts/setup.mjs
+ * loads this through stack-env.mjs, without the wizard helpers.
+ *
+ * Rules (verified against `docker compose config`): an optional `export ` prefix and
+ * whitespace around the key and the `=`; CRLF line ends; a value starting with " or ' reads
+ * up to the matching quote (anything after it is ignored); otherwise leading whitespace is
+ * dropped, the value stops at a space followed by `#` (a tab or a leading `#` does not start a
+ * comment) and is trimmed; the last duplicate wins; an unterminated quote
+ * reads as empty (compose refuses to load such a file).
+ */
+
+/** @param {string} s */
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * The value after `=`.
+ * @param {string} rest
+ * @returns {string}
+ */
+function parseValue(rest) {
+  const trimmed = rest.replace(/^\s+/, "");
+  const quote = trimmed[0];
+  if (quote === '"' || quote === "'") {
+    let out = "";
+    for (let i = 1; i < trimmed.length; i++) {
+      const c = trimmed[i];
+      if (quote === '"' && c === "\\" && i + 1 < trimmed.length) {
+        const next = trimmed[i + 1];
+        if (next === '"' || next === "\\") {
+          out += next;
+          i++;
+          continue;
+        }
+      }
+      if (c === quote) return out;
+      out += c;
+    }
+    return "";
+  }
+  return trimmed.replace(/ #.*$/, "").trim();
+}
+
+/**
+ * The value of `key` in env file text: the last matching line, "" when absent or empty.
+ * @param {string} text
+ * @param {string} key
+ * @returns {string}
+ */
+export function parseEnvValue(text, key) {
+  const line = new RegExp(`^\\s*(?:export\\s+)?${escapeRegExp(key)}\\s*=(.*)$`);
+  let value = "";
+  for (const raw of String(text).split(/\r?\n/)) {
+    const m = line.exec(raw.replace(/\r$/, ""));
+    if (m) value = parseValue(m[1]);
+  }
+  return value;
+}
+
+/**
+ * True when any line assigns `key` (even to an empty value).
+ * @param {string} text
+ * @param {string} key
+ */
+export function assignsKey(text, key) {
+  const line = new RegExp(`^\\s*(?:export\\s+)?${escapeRegExp(key)}\\s*=`);
+  return String(text).split(/\r?\n/).some((l) => line.test(l));
+}

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

@@ -0,0 +1,110 @@
+/**
+ * The mem0 env file (default ~/.config/personal-memory/mem0.env): the indexer's MEM0_API_KEY,
+ * mode 600 in a mode 700 directory, outside the repo. Nothing here prints a key. Reads follow
+ * docker compose's env_file rules (see dotenv.mjs) so the wizard sees the key the indexer gets.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { parseEnvValue } from "./dotenv.mjs";
+
+const KEY_LINE = /^\s*(?:export\s+)?MEM0_API_KEY\s*=/;
+
+/**
+ * The key must survive an env_file parser (compose interpolates '$', treats '#' and quotes
+ * specially) and a single line. The message never echoes the key.
+ * @param {string} key
+ * @returns {string} problem text, or ""
+ */
+export function keyProblem(key) {
+  if (/[\x00-\x20\x7f"'`#$\\]/.test(key)) {
+    return "the API key has characters an env file cannot hold safely (whitespace, quotes, '#', '$', backslash)";
+  }
+  return "";
+}
+
+/**
+ * The MEM0_API_KEY value compose would load from the file (last duplicate wins, quotes and
+ * `export` handled), or "" when the file is absent, has no such line, or the value is empty.
+ * @param {string} file
+ */
+export function readKey(file) {
+  if (!fs.existsSync(file)) return "";
+  return parseEnvValue(fs.readFileSync(file, "utf8"), "MEM0_API_KEY");
+}
+
+/** @param {string} file @returns {number} permission bits, or -1 when the file is absent */
+export function fileMode(file) {
+  return fs.existsSync(file) ? fs.statSync(file).mode & 0o777 : -1;
+}
+
+/** True when group or others can read or write the file. */
+export function tooOpen(file) {
+  const mode = fileMode(file);
+  return mode >= 0 && (mode & 0o077) !== 0;
+}
+
+/**
+ * True when the file's directory exists and group or others can enter or list it. The file
+ * mode still protects the key; this is the extra hygiene the wizard warns about.
+ * @param {string} file
+ */
+export function dirTooOpen(file) {
+  const dir = path.dirname(file);
+  return fs.existsSync(dir) && (fs.statSync(dir).mode & 0o077) !== 0;
+}
+
+/**
+ * Follow a chain of symlinks (also dangling ones) to the path that would hold the data.
+ * @param {string} p
+ */
+function resolveLink(p) {
+  let current = p;
+  for (let i = 0; i < 16; i++) {
+    let stat;
+    try {
+      stat = fs.lstatSync(current);
+    } catch {
+      return current;
+    }
+    if (!stat.isSymbolicLink()) return current;
+    current = path.resolve(path.dirname(current), fs.readlinkSync(current));
+  }
+  throw new Error("too many symbolic links in the mem0 env file path");
+}
+
+/**
+ * Write `MEM0_API_KEY=<key>` into the file: other lines are kept, every existing key line is
+ * replaced by one. A symlinked file or directory keeps its link and the data lands at the
+ * target. The directory is created with mode 700; the file is replaced atomically through a
+ * temp file created exclusively (`wx`) with mode 600 beside it, so the key is never briefly
+ * readable by others.
+ * @param {string} file
+ * @param {string} key
+ * @returns {"created"|"updated"|"unchanged"}
+ */
+export function writeKey(file, key) {
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const target = resolveLink(path.join(fs.realpathSync(path.dirname(file)), path.basename(file)));
+  fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
+  const existed = fs.existsSync(target);
+  /** @type {string[]} */
+  let lines = [];
+  let previous = "";
+  if (existed) {
+    previous = fs.readFileSync(target, "utf8");
+    lines = previous.split(/\r?\n/);
+    while (lines.length && lines.at(-1) === "") lines.pop();
+  }
+  const kept = lines.filter((l) => !KEY_LINE.test(l));
+  const text = `${[...kept, `MEM0_API_KEY=${key}`].join("\n")}\n`;
+  if (existed && previous === text && !tooOpen(target)) return "unchanged";
+  const tmp = `${target}.tmp-${process.pid}-${Math.random().toString(36).slice(2, 10)}`;
+  try {
+    fs.writeFileSync(tmp, text, { flag: "wx", mode: 0o600 });
+    fs.chmodSync(tmp, 0o600);
+    fs.renameSync(tmp, target);
+  } finally {
+    fs.rmSync(tmp, { force: true });
+  }
+  return existed ? "updated" : "created";
+}

package/providers/mem0/lib/http.mjs

@@ -0,0 +1,69 @@
+/**
+ * Small fetch wrapper for the mem0 REST server. Every call goes to a path under the
+ * resolved mem0 URL; redirects are never followed (a custom header such as X-API-Key is
+ * not stripped on a cross-origin redirect), and errors never carry the key.
+ */
+
+/**
+ * @param {string} text
+ * @param {string} secret
+ */
+export function redact(text, secret) {
+  let out = String(text ?? "");
+  if (secret) out = out.split(secret).join("***");
+  return out;
+}
+
+/**
+ * Text from the server made safe to print: control characters (terminal escapes, newlines)
+ * become spaces and the length is capped.
+ * @param {unknown} text
+ * @param {number} [max]
+ */
+export function clean(text, max = 200) {
+  return String(text ?? "")
+    .replace(/[\u0000-\u001f\u007f-\u009f]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, max);
+}
+
+/** Short, key-free description of a fetch failure. @param {unknown} e */
+export function describeError(e) {
+  const err = /** @type {{ name?: string, message?: string, cause?: { code?: string } }} */ (e);
+  if (err?.name === "TimeoutError" || err?.name === "AbortError") return "timed out";
+  return err?.cause?.code || err?.message || "request failed";
+}
+
+/**
+ * @param {string} base resolved, validated mem0 URL (no trailing slash)
+ * @param {string} method
+ * @param {string} route path (and query) under the base, starting with '/'
+ * @param {{ key?: string, body?: unknown, timeoutMs?: number }} [opts]
+ * @returns {Promise<{ status: number, ok: boolean, text: string, json: any }>}
+ */
+export async function request(base, method, route, opts = {}) {
+  /** @type {Record<string, string>} */
+  const headers = { Accept: "application/json" };
+  if (opts.key) headers["X-API-Key"] = opts.key;
+  /** @type {RequestInit} */
+  const init = {
+    method,
+    headers,
+    redirect: "manual",
+    signal: AbortSignal.timeout(opts.timeoutMs ?? 15000),
+  };
+  if (opts.body !== undefined) {
+    headers["Content-Type"] = "application/json";
+    init.body = JSON.stringify(opts.body);
+  }
+  const res = await fetch(`${base}${route}`, init);
+  const text = await res.text();
+  let json = null;
+  try {
+    json = text ? JSON.parse(text) : null;
+  } catch {
+    json = null;
+  }
+  return { status: res.status, ok: res.status >= 200 && res.status < 300, text, json };
+}