@bcmyguest/openmem 0.0.0-stage → 0.6.3

package/providers/mem0/OPERATOR.md

@@ -0,0 +1,124 @@
+# mem0 operator runbook (URL-only)
+
+This stack does **not** run a mem0 container. You run a [self-hosted mem0 REST
+server](https://docs.mem0.ai/open-source/features/rest-api); `./setup` only points
+the shared indexer at it.
+
+**Not** the hosted platform at `https://api.mem0.ai`. That API shape differs
+(`/v1/…`); the indexer sink and wizard smoke talk to the open-source REST
+server only (no `/v1/` prefix).
+
+## What `./setup` owns vs what you own
+
+| You (provider-native) | This stack |
+| --- | --- |
+| Start the mem0 REST server (JWT, Postgres/pgvector, dashboard) | Write `MEM0_API_URL` / `MEM0_INDEXER_URL` into the stack `.env` |
+| 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 |
+
+## URLs
+
+- **`MEM0_API_URL`** — host view (what you curl from this machine), e.g.
+  `http://127.0.0.1:18888`. Default port in the manifest is **18888**.
+- **`MEM0_INDEXER_URL`** — container view. `./setup` derives it from
+  `MEM0_API_URL` by rewriting loopback hosts (`127.0.0.1`, `localhost`,
+  `0.0.0.0`, `[::1]`) to `host.docker.internal`. Do not hand-edit it to
+  `127.0.0.1` inside the container; validation requires it to match that rewrite.
+
+## Linux loopback
+
+`host.docker.internal` is the docker bridge gateway, **not** the host's
+`127.0.0.1`. A mem0 process bound only to `127.0.0.1` is unreachable from the
+indexer container. Bind the server to `0.0.0.0` (or the bridge IP), or put a
+real hostname in `MEM0_API_URL`. An `https://localhost` URL becomes
+`https://host.docker.internal`, which usually fails TLS name checks — use a
+hostname the certificate covers.
+
+## API key file
+
+```text
+~/.config/personal-memory/mem0.env   # mode 600; directory mode 700
+MEM0_API_KEY=<key>
+```
+
+Never put `MEM0_API_KEY` in the stack `.env` (mode 644), `wizard.conf`, or
+`config.toml`. Override the path with `MEM0_ENV_FILE` / `[memory.mem0] env_file`
+if needed; then `./setup` must record that path in the stack `.env`.
+
+With **`AUTH_DISABLED=true`** on the server (development only), no key is
+required. Auth-enabled servers need a key or smoke/indexer calls return 401.
+
+## Embedder
+
+Search fails if the server's embedder is misconfigured. Smoke looks for the
+fact stored with `infer: false`; a miss points at the embedder key and server
+logs, not at this stack.
+
+## Cleartext keys
+
+Over plain `http://` to a non-loopback host, `X-API-Key` travels in cleartext.
+Prefer `https://`, or keep the server on loopback / the same host.
+
+## Coding agents
+
+There is no `pluginPackage`. Agents talk to your server via the Python SDK,
+the self-hosted MCP bridge, or direct REST (`POST /memories`, `POST /search`). The
+wizard's coding-agent step prints those paths and can register Cursor MCP; see
+`providers/mem0/lib/coding-agent.mjs`.
+
+### Cursor MCP (`~/.cursor/mcp.json`)
+
+Mem0's official MCP (`https://mcp.mem0.ai`) is **platform/cloud only**. For a
+self-hosted REST server this repo registers [`@yeyuan98/mem0-mcp`](https://www.npmjs.com/package/@yeyuan98/mem0-mcp)
+via the launcher `cli/mem0-mcp.mjs` (loads the key from the env file, then
+`npx -y @yeyuan98/mem0-mcp`).
+
+```sh
+MEMORY_PROVIDER=mem0 npx openmem install-mcp --yes
+# checkout: MEMORY_PROVIDER=mem0 npx . install-mcp --yes
+# or accept the coding-agent MCP confirm in setup
+```
+
+Shape written (URL and env-file **path** only — never the key value):
+
+```json
+{
+  "mcpServers": {
+    "mem0": {
+      "command": "node",
+      "args": ["/path/to/openmem/cli/mem0-mcp.mjs"],
+      "env": {
+        "MEM0_API_URL": "http://127.0.0.1:18888",
+        "MEM0_BASE_URL": "http://127.0.0.1:18888",
+        "MEM0_ENV_FILE": "~/.config/personal-memory/mem0.env"
+      }
+    }
+  }
+}
+```
+
+**API key:** the launcher reads `MEM0_API_KEY` from `MEM0_ENV_FILE` when the
+variable is not already in the process environment. You can also
+`export MEM0_API_KEY=…` (e.g. `set -a; source ~/.config/personal-memory/mem0.env; set +a`)
+before starting Cursor so the agent inherits it. **Never** put `MEM0_API_KEY` in
+`mcp.json`. Existing `hindsight` / `codegraph` / `notebooklm` servers are left alone.
+
+Restart Cursor Agent after install.
+
+### Switch to / from mem0
+
+```sh
+npx openmem switch mem0 --yes
+# later: npx openmem switch hindsight --yes
+# checkout: npx . 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).
+
+## Compose
+
+`providers/mem0/compose.yaml` defines no mem0 service — only env +
+`extra_hosts` on the shared `indexer`. Profile `mem0` selects that fragment.

package/providers/mem0/compose.yaml

@@ -0,0 +1,57 @@
+# mem0 compose fragment (URL-only mode). Layered over compose.yaml; the wizard passes both, then `up -d`:
+#   docker compose -f compose.yaml -f providers/mem0/compose.yaml --profile mem0 up -d
+# Add `-f compose.override.yaml` when you use the generated secret masks (Compose skips that file once -f is given).
+#
+# URL-only: this fragment defines NO service. The indexer talks to a mem0 REST server you already run (usually on
+# the host, or on another machine); nothing here starts, builds or pulls a mem0 container. The reason is that the
+# current self-hosted mem0 server (JWT/API-key auth, dashboard, Postgres + pgvector) has no current published image:
+# `mem0/mem0-api-server:latest` on Docker Hub predates the auth. A mem0 service is a documented follow-up: build
+# `server/` from a pinned mem0 git ref next to `pgvector/pgvector:pg17`, pinned and verified. Until then there is no
+# `mem0` profile service, so `--profile mem0` only selects this fragment; it starts the provider-neutral indexer
+# and its state-init step and nothing else.
+#
+# What the base compose.yaml gives you:
+#   - `indexer` and `indexer-state-init` have no profile and no provider dependency, so they start for every
+#     provider. This fragment points the indexer at the mem0 server.
+#   - `litellm` and `hindsight` carry the profile "hindsight" and do not start under this profile.
+# Compose still interpolates every service before it filters by profile, so the stack .env needs LITELLM_CONFIG
+# even though litellm never runs here. scripts/setup.mjs (providers/mem0/lib/stack-env.mjs) writes an inert value.
+#
+# Loopback caveat (Linux): host.docker.internal resolves to the docker bridge gateway, not to the host's 127.0.0.1.
+# A mem0 server bound only to 127.0.0.1 is therefore NOT reachable from the indexer container. Bind it to 0.0.0.0
+# or to the docker bridge IP, or give MEM0_API_URL a real hostname. An https://localhost URL is rewritten to
+# https://host.docker.internal, which will not match the server certificate name (use a hostname the certificate
+# covers). ./setup prints a note when MEM0_API_URL is a loopback address.
+#
+# Stack .env keys read here (written by ./setup):
+#   MEM0_INDEXER_URL  the server as the indexer container sees it. The wizard derives it from MEM0_API_URL (the host
+#                     view) by rewriting localhost, 127.0.0.1, 0.0.0.0 and [::1] to host.docker.internal.
+#   MEM0_ENV_FILE     optional; default ~/.config/personal-memory/mem0.env. Holds ONLY MEM0_API_KEY=... for the
+#                     indexer (mode 600, outside the repo). Not needed when the server runs with AUTH_DISABLED.
+#                     mem0's own server secrets (JWT_SECRET, ADMIN_API_KEY, embedder keys) are the operator's concern
+#                     and never go through this stack.
+
+services:
+  indexer:
+    environment:
+      # Selects indexer/sinks/mem0.py and gives it the server URL (container view, not the host view).
+      MEMORY_SINK: mem0
+      MEMORY_API_URL: ${MEM0_INDEXER_URL:?run ./setup (mem0 API URL)}
+    # required: false lets `config` and `up` run before the key file exists (Compose 2.24+).
+    env_file:
+      - path: ${MEM0_ENV_FILE:-${HOME}/.config/personal-memory/mem0.env}
+        required: false
+    # Reach a server on the host through host.docker.internal.
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    # No depends_on: the server is external, and the indexer's watcher retries until it answers.
+
+  notebooklm:
+    environment:
+      MEMORY_SINK: mem0
+      MEMORY_API_URL: ${MEM0_INDEXER_URL:?run ./setup (mem0 API URL)}
+    env_file:
+      - path: ${MEM0_ENV_FILE:-${HOME}/.config/personal-memory/mem0.env}
+        required: false
+    extra_hosts:
+      - "host.docker.internal:host-gateway"

package/providers/mem0/lib/coding-agent.mjs

@@ -0,0 +1,58 @@
+/**
+ * Step "8. Coding-agent plugin", mem0 half: there is no npx pluginPackage for the
+ * self-hosted REST server. Print concrete SDK / MCP / direct-REST paths, then
+ * optionally merge the mem0 MCP into ~/.cursor/mcp.json (--yes or confirm).
+ */
+import { installMem0Mcp } from "./mcp-install.mjs";
+import { ensureState } from "./state.mjs";
+import { displayUrl, resolveApiUrl, urlProblem } from "./url.mjs";
+
+/** @typedef {import("../../../wizard/lib/provider-wizard/helpers.mjs").ProviderWizardHelpers} Helpers */
+
+const SDK_DOCS = "https://docs.mem0.ai/open-source/python-quickstart";
+const MCP_PACKAGE = "https://www.npmjs.com/package/@yeyuan98/mem0-mcp";
+const REST_DOCS = "https://docs.mem0.ai/open-source/features/rest-api";
+const OPERATOR = "providers/mem0/OPERATOR.md";
+
+/**
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+export async function setupCodingAgent(ctx, h) {
+  ensureState(ctx);
+  const raw = resolveApiUrl(ctx, h);
+  const base = urlProblem(raw) ? "(set MEM0_API_URL)" : displayUrl(raw);
+
+  h.info("mem0 has no coding-agent pluginPackage; use the self-hosted server directly:");
+  h.info(`  1. SDK  — pip install mem0ai, point Memory at ${base} (see ${SDK_DOCS})`);
+  h.info(
+    `  2. MCP  — MEMORY_PROVIDER=mem0 npm run install-mcp -- --yes` +
+      ` (npx @yeyuan98/mem0-mcp via cli/mem0-mcp.mjs; see ${MCP_PACKAGE} and ${OPERATOR})`,
+  );
+  h.info(
+    `  3. REST — POST ${base}/memories and POST ${base}/search with X-API-Key` +
+      ` (see ${REST_DOCS}; stack wiring in ${OPERATOR})`,
+  );
+
+  const codeRoot = ctx.packageRoot || ctx.repoRoot;
+  const stackRoot = ctx.repoRoot;
+  const wantMcp =
+    Boolean(ctx.yes) ||
+    (await h.confirm(ctx, "Register mem0 MCP in ~/.cursor/mcp.json now?", "y"));
+  if (wantMcp) {
+    await installMem0Mcp(
+      {
+        home: ctx.home,
+        repoRoot: codeRoot,
+        stackRoot,
+        dry: Boolean(ctx.dry),
+        env: process.env,
+      },
+      h,
+    );
+  } else {
+    h.info("skip MCP merge; later: MEMORY_PROVIDER=mem0 npm run install-mcp -- --yes");
+  }
+
+  h.ok("coding-agent: documented SDK / MCP / REST paths (pluginPackage remains null)");
+}

package/providers/mem0/lib/config.mjs

@@ -0,0 +1,45 @@
+/**
+ * mem0's slice of ~/.config/personal-memory/config.toml: the [memory.mem0] table
+ * (api_url, optional env_file). Never a key.
+ */
+import { ensureState } from "./state.mjs";
+
+/**
+ * @param {Record<string, unknown>} cfg merged TOML config
+ * @returns {{ apiUrl: string, envFile: string }}
+ */
+export function defaultsFromConfig(cfg) {
+  const memory = /** @type {Record<string, unknown>} */ (cfg?.memory || {});
+  const mem0 = /** @type {Record<string, unknown>} */ (memory.mem0 || {});
+  return {
+    apiUrl: mem0.api_url != null ? String(mem0.api_url).trim() : "",
+    envFile: mem0.env_file != null ? String(mem0.env_file).trim() : "",
+  };
+}
+
+/**
+ * Seed ctx.mem0 from [memory.mem0]. Env vars still win over these (see resolveApiUrl).
+ * @param {Record<string, any>} ctx
+ */
+export function applyConfig(ctx) {
+  const state = ensureState(ctx);
+  const d = defaultsFromConfig(ctx.pmMerged || {});
+  if (d.apiUrl && !state.apiUrl) state.apiUrl = d.apiUrl;
+  if (d.envFile && !state.tomlEnvFile) state.tomlEnvFile = d.envFile;
+}
+
+/**
+ * Tables merged into config.toml: `memory.mem0`, which the wizard merges into [memory] (it
+ * always sets `provider` itself).
+ * @param {Record<string, any>} ctx
+ * @param {string} url the resolved host-view server URL
+ * @returns {Record<string, Record<string, unknown>>}
+ */
+export function configToml(ctx, url) {
+  const state = ensureState(ctx);
+  /** @type {Record<string, unknown>} */
+  const mem0 = { api_url: url };
+  const envFile = (process.env.MEM0_ENV_FILE || state.tomlEnvFile || "").trim();
+  if (envFile) mem0.env_file = envFile;
+  return { memory: { mem0 } };
+}

package/providers/mem0/lib/configure.mjs

@@ -0,0 +1,135 @@
+/**
+ * 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 { 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;
+  ui.note("Next: Docker, indexing, and starting the stack.", "mem0 configured");
+  return handoff;
+}

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 };
+}