@bcmyguest/openmem 0.0.0-stage → 0.8.0

package/providers/mem0/lib/url.mjs

@@ -0,0 +1,106 @@
+/**
+ * The mem0 server URL as the operator's host sees it: resolution order, validation (the
+ * same rules as scripts/setup.mjs, through `indexerUrl`) and the announced
+ * `resolvePorts` step. mem0 has no local port to pick.
+ */
+import path from "node:path";
+import * as stackEnv from "./stack-env.mjs";
+import { DEFAULT_API_URL, ensureState, envFileProblem, resolveEnvFile, defaultEnvFile } from "./state.mjs";
+
+/** @typedef {import("../../../wizard/lib/provider-wizard/helpers.mjs").ProviderWizardHelpers} Helpers */
+
+/** @param {string} url */
+function stripSlash(url) {
+  return url.replace(/\/+$/, "");
+}
+
+/**
+ * The host-view URL: --api-url (ctx.apiUrl), MEM0_API_URL, PM_MEM0_API_URL, the context
+ * value ([memory.mem0] api_url), the stack .env, wizard.conf, then the default. Not
+ * validated; callers check it with `urlProblem`.
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ * @returns {string}
+ */
+export function resolveApiUrl(ctx, h) {
+  const state = ensureState(ctx);
+  const stackEnvFile = ctx.repoRoot ? path.join(ctx.repoRoot, ".env") : "";
+  const candidates = [
+    ctx.apiUrl,
+    process.env.MEM0_API_URL,
+    process.env.PM_MEM0_API_URL,
+    state.apiUrl,
+    stackEnvFile && h.envValue(stackEnvFile, "MEM0_API_URL"),
+    state.savedUrl || (ctx.wizardConf && h.envValue(ctx.wizardConf, "MEM0_API_URL")),
+  ];
+  const first = candidates.map((v) => String(v || "").trim()).find(Boolean);
+  return stripSlash(first || DEFAULT_API_URL);
+}
+
+/**
+ * What is wrong with a URL, or "". The message never echoes the URL (it may hold a secret).
+ * @param {string} url
+ * @returns {string}
+ */
+export function urlProblem(url) {
+  try {
+    stackEnv.indexerUrl(url);
+    return "";
+  } catch (e) {
+    return /** @type {Error} */ (e).message;
+  }
+}
+
+/**
+ * The URL in the form the stack .env stores (validated first, so no secret can be in it).
+ * @param {string} url
+ */
+export function displayUrl(url) {
+  try {
+    return typeof stackEnv.normalizeHostUrl === "function" ? stackEnv.normalizeHostUrl(url) : stripSlash(url);
+  } catch {
+    return stripSlash(url);
+  }
+}
+
+/**
+ * Container view of the URL, or "" when it does not validate.
+ * @param {string} url
+ */
+export function containerUrl(url) {
+  try {
+    return stackEnv.indexerUrl(url);
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Announced: validate the URL and export MEM0_API_URL (and a non-default env file) so
+ * compose and scripts/setup.mjs see them. No port probing: the server is external.
+ * A stop (`--down`) skips it so a bad URL never blocks shutting the stack down.
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+export async function resolvePorts(ctx, h) {
+  const state = ensureState(ctx);
+  if (ctx.action === "down") return;
+  const raw = resolveApiUrl(ctx, h);
+  const problem = urlProblem(raw);
+  if (problem) {
+    h.problem(ctx, `mem0 API URL: ${problem}`);
+    return;
+  }
+  const url = displayUrl(raw);
+  state.url = url;
+  process.env.MEM0_API_URL = url;
+  const envFile = resolveEnvFile(ctx, h);
+  const fileProblem = envFileProblem(envFile);
+  if (fileProblem) {
+    h.problem(ctx, fileProblem);
+    return;
+  }
+  // The indexer's env_file path is interpolated by compose from the process environment.
+  if (envFile !== defaultEnvFile(ctx.home)) process.env.MEM0_ENV_FILE = envFile;
+  h.ok(`mem0 server ${url} (external; no local port to check)`);
+}

package/providers/mem0/lib/validate.mjs

@@ -0,0 +1,158 @@
+/**
+ * mem0 checks that run after the meta wizard's provider-neutral validation, plus the
+ * `beforeStack` reachability and file-mode checks. Secrets must never be in the stack .env
+ * (it is mode 644), only in the mode 600 env file.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { describeError, request } from "./http.mjs";
+import { dirTooOpen, fileMode, readKey, tooOpen } from "./env-file.mjs";
+import { indexerUrl } from "./stack-env.mjs";
+import { defaultEnvFile, ensureState, envFileProblem, resolveEnvFile } from "./state.mjs";
+import { displayUrl, resolveApiUrl, urlProblem } from "./url.mjs";
+
+/** @typedef {import("../../../wizard/lib/provider-wizard/helpers.mjs").ProviderWizardHelpers} Helpers */
+
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "0.0.0.0", "[::1]"]);
+const HOSTED_MEM0 = /(^|\.)api\.mem0\.ai$/i;
+
+/**
+ * Warn when the server does not answer GET /docs; never fails (it may start later) and
+ * never sends the key. Also warns about an env file that others can read.
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+export async function beforeStack(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);
+  const envFile = resolveEnvFile(ctx, h);
+
+  if (ctx.dry) {
+    h.info(`[dry-run] check that ${base}/docs answers (a warning only: the server may start later)`);
+  } else {
+    try {
+      const res = await request(base, "GET", "/docs", { timeoutMs: 5000 });
+      if (res.ok) h.ok(`mem0 server answers at ${base}`);
+      else {
+        h.warn(
+          `mem0 server at ${base} answered ${res.status} for GET /docs. The indexer keeps retrying; ` +
+            "check the URL and that this is a mem0 REST server",
+        );
+      }
+    } catch (e) {
+      h.warn(
+        `mem0 server is not reachable at ${base} (${describeError(e)}). Start it before indexing; ` +
+          "the stack health check waits for it and fails when it never comes up",
+      );
+    }
+  }
+
+  if (tooOpen(envFile)) {
+    h.warn(`${envFile} is group/other accessible (mode ${fileMode(envFile).toString(8)}); run: chmod 600 ${envFile}`);
+  }
+  if (fs.existsSync(envFile) && dirTooOpen(envFile)) {
+    h.warn(`${path.dirname(envFile)} is accessible to group or others; run: chmod 700 ${path.dirname(envFile)}`);
+  }
+}
+
+/**
+ * Appends to ctx.validationErrors and ctx.validationChecks.
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+export function validateMem0(ctx, h) {
+  ensureState(ctx);
+  const errors = (ctx.validationErrors ||= []);
+  const checks = (ctx.validationChecks ||= []);
+
+  const apiUrl = resolveApiUrl(ctx, h);
+  const issue = urlProblem(apiUrl);
+  if (issue) errors.push(`mem0 API URL: ${issue}`);
+  else {
+    checks.push("mem0 API URL parses");
+    try {
+      const host = new URL(apiUrl).hostname;
+      if (HOSTED_MEM0.test(host)) {
+        errors.push(
+          "mem0 API URL points at api.mem0.ai (hosted platform); this sink is for the self-hosted REST server only — see providers/mem0/OPERATOR.md",
+        );
+      } else checks.push("mem0 API URL is not the hosted api.mem0.ai platform");
+    } catch {
+      // urlProblem already covered unparseable URLs.
+    }
+  }
+
+  const envFile = resolveEnvFile(ctx, h);
+  const fileIssue = envFileProblem(envFile);
+  if (fileIssue) errors.push(fileIssue);
+  else if (!fs.existsSync(envFile)) {
+    checks.push("mem0 env file absent (fine when the server has auth disabled)");
+  } else if (tooOpen(envFile)) {
+    errors.push(`${envFile} must not be group/other accessible (want mode 600)`);
+  } else checks.push("mem0 env file mode 600");
+
+  const stackEnv = path.join(ctx.repoRoot, ".env");
+  if (fs.existsSync(stackEnv)) {
+    const hostApi = h.envValue(stackEnv, "MEM0_API_URL");
+    const indexer = h.envValue(stackEnv, "MEM0_INDEXER_URL");
+    for (const key of ["MEM0_INDEXER_URL", "MEM0_API_URL"]) {
+      if (!h.envValue(stackEnv, key)) errors.push(`repo .env missing ${key}`);
+    }
+    if (hostApi && indexer) {
+      try {
+        const expected = indexerUrl(hostApi);
+        if (indexer !== expected) {
+          errors.push(
+            `repo .env MEM0_INDEXER_URL must match the rewrite of MEM0_API_URL (want ${expected}; rerun ./setup)`,
+          );
+        } else checks.push("repo .env MEM0_INDEXER_URL matches MEM0_API_URL rewrite");
+      } catch (e) {
+        errors.push(`repo .env MEM0_API_URL: ${/** @type {Error} */ (e).message}`);
+      }
+    }
+    if (/^\s*(?:export\s+)?MEM0_API_KEY\s*=/m.test(fs.readFileSync(stackEnv, "utf8"))) {
+      errors.push("repo .env must not hold MEM0_API_KEY (the stack .env is world-readable; use the mem0 env file)");
+    }
+    checks.push("repo .env mem0 URLs and no key");
+  }
+
+  // A custom key file must reach compose through the stack .env, or a hand-run compose would
+  // read the default file while the wizard reads another.
+  if (!fileIssue && fs.existsSync(stackEnv) && envFile !== defaultEnvFile(ctx.home)) {
+    if (h.envValue(stackEnv, "MEM0_ENV_FILE") !== envFile) {
+      errors.push("repo .env MEM0_ENV_FILE does not match the mem0 env file in use (rerun ./setup)");
+    } else checks.push("repo .env MEM0_ENV_FILE matches");
+  }
+
+  // Cleartext key over non-loopback http (warn only; same guidance as the sink).
+  if (!issue && !fileIssue) {
+    try {
+      const parsed = new URL(apiUrl);
+      let hasKey = false;
+      try {
+        hasKey = readKey(envFile) !== "";
+      } catch {
+        hasKey = false;
+      }
+      if (parsed.protocol === "http:" && !LOOPBACK_HOSTS.has(parsed.hostname) && hasKey) {
+        h.warn(
+          "MEM0_API_URL is plain http to a non-loopback host with an API key set; the key travels in cleartext — prefer https (see providers/mem0/OPERATOR.md)",
+        );
+      }
+    } catch {
+      // ignore
+    }
+  }
+
+  for (const file of ctx.memoryProvider?.compose?.files || []) {
+    const abs = path.join(ctx.repoRoot, file);
+    if (!fs.existsSync(abs)) errors.push(`missing compose file ${abs}`);
+    else checks.push(`compose fragment ${file} present`);
+  }
+}

package/providers/mem0/manifest.json

@@ -0,0 +1,47 @@
+{
+  "id": "mem0",
+  "label": "mem0",
+  "status": "supported",
+  "notes": "URL-only v1: the operator runs a mem0 REST server and this stack points the shared indexer at it; no mem0 container yet (docker mode is a follow-up). Operator runbook: providers/mem0/OPERATOR.md. Not api.mem0.ai. The API key lives in ~/.config/personal-memory/mem0.env (mode 600), never the stack .env. The wizard.* HTTP fields below are informational: the wizard's smoke hook replaces the generic HTTP smoke (it needs an X-API-Key header), and deletePath is admin-only upstream, so the hook deletes by memory id instead.",
+  "settings": {
+    "nativeDocs": "providers/mem0/OPERATOR.md (stack) and https://docs.mem0.ai/open-source/features/rest-api (upstream)",
+    "nativeConfigPaths": ["~/.config/personal-memory/mem0.env"],
+    "wizardOwns": ["indexer URL and the host-gateway rewrite", "API key file for the indexer (mode 600)", "index.yml sources (shared indexer)", "optional: stack LiteLLM routes for mem0's LLM on 127.0.0.1 (compose profile litellm); you apply the printed mem0 config"]
+  },
+  "compose": {
+    "profile": "mem0",
+    "files": ["providers/mem0/compose.yaml"],
+    "services": ["indexer"],
+    "healthService": null,
+    "healthPath": "/docs",
+    "hostPortEnv": "MEM0_PORT",
+    "defaultHostPort": 18888
+  },
+  "indexer": {
+    "apiUrlEnv": "MEM0_API_URL",
+    "sink": "mem0",
+    "sinkDriver": "mem0-rest"
+  },
+  "codingAgent": {
+    "pluginPackage": null,
+    "configTemplate": null
+  },
+  "wizardHooks": {
+    "module": "wizard.mjs",
+    "delegates": {}
+  },
+  "wizard": {
+    "note": "Informational: the mem0 smoke hook (providers/mem0/lib/smoke.mjs) replaces these HTTP fields because the generic smoke cannot send X-API-Key; deletePath is admin-only upstream and the hook deletes by memory id.",
+    "smokeBank": "wizard-smoke",
+    "retainMethod": "POST",
+    "retainPath": "/memories",
+    "retainBody": "{\"messages\":[{\"role\":\"user\",\"content\":\"Wizard smoke test: the project codename is heron.\"}],\"user_id\":\"wizard-smoke\",\"agent_id\":\"openmem-wizard\",\"run_id\":\"wizard-smoke-doc\",\"infer\":false}",
+    "recallMethod": "POST",
+    "recallPath": "/search",
+    "recallBody": "{\"query\":\"What is the project codename?\",\"filters\":{\"user_id\":\"wizard-smoke\"}}",
+    "recallMustMatch": "heron",
+    "recallHint": "check the mem0 server logs and its embedder key",
+    "deleteMethod": "DELETE",
+    "deletePath": "/memories?user_id={bank}"
+  }
+}

package/providers/mem0/wizard.mjs

@@ -0,0 +1,146 @@
+/**
+ * mem0 sub-wizard (hook API v2), URL-only: the operator runs a mem0 REST server (see
+ * https://docs.mem0.ai/open-source/features/rest-api) and this stack only points the shared
+ * indexer at it. The wizard asks for the server URL and API key, keeps the key in a mode 600
+ * env file (never the stack .env, wizard.conf or config.toml), and smoke tests the server.
+ * See lib/ for the implementations and docs/provider-wizard-hooks.md for the hook contract.
+ *
+ * This module must not import wizard/lib/run-wizard.mjs; it receives `helpers`.
+ */
+import { applyConfig, configToml as buildConfigToml } from "./lib/config.mjs";
+import { setupCodingAgent as printCodingAgentPaths } from "./lib/coding-agent.mjs";
+import { clackSetup as askInClack, configureUrlAndKey } from "./lib/configure.mjs";
+import { applyProfile, captureAnthropicKey, configureLitellm, stackEnvFor } from "./lib/litellm.mjs";
+import { captureKeyFromEnv } from "./lib/secret.mjs";
+import { smoke as mem0Smoke } from "./lib/smoke.mjs";
+import { ensureState } from "./lib/state.mjs";
+import { summary as mem0Summary } from "./lib/summary.mjs";
+import { resolveApiUrl, resolvePorts as resolveMem0Url } from "./lib/url.mjs";
+import { beforeStack as checkBeforeStack, validateMem0 } from "./lib/validate.mjs";
+
+// Called by scripts/setup.mjs (the stack .env writer), not by the wizard.
+export { prepareStackEnv, setupNotices } from "./lib/stack-env.mjs";
+
+/** @typedef {import('../../wizard/lib/provider-wizard/helpers.mjs').ProviderWizardHelpers} Helpers */
+
+/**
+ * Quiet: seed ctx.mem0 and read the [memory.mem0] table (api_url, env_file). Also takes the
+ * API key out of process.env (a module-private variable), before preflight starts docker and
+ * curl, so no child process inherits it.
+ * @param {Record<string, any>} ctx
+ */
+export async function init(ctx) {
+  captureKeyFromEnv();
+  captureAnthropicKey();
+  ensureState(ctx);
+  applyConfig(ctx);
+}
+
+/**
+ * Quiet: remember the URL saved in wizard.conf for `--up`.
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+export async function hydrate(ctx, h) {
+  const state = ensureState(ctx);
+  applyConfig(ctx);
+  state.savedUrl = (h.envValue(ctx.wizardConf, "MEM0_API_URL") || "").trim();
+  // `--up`: the stack LiteLLM option saved by the last configure run.
+  applyProfile(ctx, h.envValue(ctx.wizardConf, "MEM0_LITELLM") === "1");
+}
+
+/**
+ * Quiet: the HOST view of the server URL. Without this hook the manifest's hostPortEnv
+ * would derive http://127.0.0.1:<MEM0_PORT>, which is wrong for a remote server.
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ * @returns {string}
+ */
+export function apiBase(ctx, h) {
+  return resolveApiUrl(ctx, h);
+}
+
+/**
+ * Announced: there is no local port to choose. Validates the URL and exports
+ * MEM0_API_URL so compose and scripts/setup.mjs see it.
+ */
+export const resolvePorts = resolveMem0Url;
+
+/**
+ * Announced step "URL, key and login": server URL, API key into the mode 600 env file, then the
+ * optional "route mem0's LLM through the stack LiteLLM" (lib/litellm.mjs).
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+export async function configureModelRouting(ctx, h) {
+  await configureUrlAndKey(ctx, h);
+  const state = ensureState(ctx);
+  if (!state.url) return; // invalid URL: a dry run continues without the option
+  const keys = await configureLitellm(ctx, h);
+  applyProfile(ctx, Boolean(keys));
+  if (!keys) return;
+  // configureUrlAndKey saved MEM0_API_URL alone; save again with the option's keys (wizard.conf is rewritten whole).
+  if (ctx.dry) h.info(`[dry-run] record ${Object.keys(keys).join(", ")} in ${ctx.wizardConf}`);
+  else h.saveWizardConf(ctx, { MEM0_API_URL: state.url, ...keys }, { pmSections: buildConfigToml(ctx, state.url) });
+}
+
+/**
+ * Quiet: hand the URL to scripts/setup.mjs, which writes MEM0_API_URL, MEM0_INDEXER_URL,
+ * COMPOSE_PROFILES and LITELLM_CONFIG into the stack .env. Never a secret.
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+export function stackEnv(ctx, h) {
+  return {
+    description:
+      "scripts/setup.mjs: write .env (MEM0_API_URL, MEM0_INDEXER_URL, no secrets), compose.override.yaml",
+    env: { MEM0_API_URL: resolveApiUrl(ctx, h), ...stackEnvFor(ctx) },
+  };
+}
+
+/** Announced: print SDK / MCP / REST install paths (pluginPackage stays null). */
+export const setupCodingAgent = printCodingAgentPaths;
+
+/** Announced: warn (never fail) when the server is unreachable; check the env file mode. */
+export const beforeStack = checkBeforeStack;
+
+/** Announced: GET /docs, retain verbatim, search, delete (X-API-Key when a key exists). */
+export const smoke = mem0Smoke;
+
+/**
+ * Announced: appends to ctx.validationErrors / ctx.validationChecks.
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+export async function extendValidation(ctx, h) {
+  validateMem0(ctx, h);
+}
+
+/**
+ * Quiet: `[memory.mem0]` for config.toml (api_url, optional env_file; never a key).
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+export function configToml(ctx, h) {
+  return buildConfigToml(ctx, resolveApiUrl(ctx, h));
+}
+
+/**
+ * Quiet: lines for the closing summary.
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+export function summary(ctx, h) {
+  return mem0Summary(ctx, h);
+}
+
+/**
+ * Clack-only: ask the URL and the (masked) API key, return the environment that makes the
+ * wizard skip its own prompts (WIZARD_SKIP_BACKEND_STEP).
+ * @param {Record<string, any>} ctx
+ * @param {typeof import("@clack/prompts")} ui
+ * @param {Helpers} h
+ */
+export async function clackSetup(ctx, ui, h) {
+  return askInClack(ctx, ui, h);
+}

package/providers/zep/manifest.json

@@ -0,0 +1,29 @@
+{
+  "id": "zep",
+  "label": "Zep",
+  "status": "planned",
+  "notes": "Placeholder manifest. Zep Cloud/self-hosted API integration is not wired; track via issues before changing status.",
+  "settings": {
+    "nativeDocs": "https://docs.getzep.com/",
+    "nativeConfigPaths": [],
+    "wizardOwns": []
+  },
+  "compose": {
+    "profile": "zep",
+    "files": [],
+    "services": [],
+    "healthService": null,
+    "healthPath": null,
+    "hostPortEnv": null,
+    "defaultHostPort": null
+  },
+  "indexer": {
+    "apiUrlEnv": "ZEP_API_URL",
+    "sink": "zep"
+  },
+  "codingAgent": {
+    "pluginPackage": null,
+    "configTemplate": null
+  },
+  "wizard": {}
+}

package/proxy/config.yaml

@@ -0,0 +1,33 @@
+# LiteLLM config for the OpenMem context proxy (compose service context-proxy). See docs/context-proxy.md.
+#
+# Claude Code: requests on /v1/messages go to Anthropic. With no ANTHROPIC_API_KEY in the proxy environment, the
+# client's own credentials (Claude subscription OAuth or API key) pass through; the client sends the LiteLLM key in
+# the x-litellm-api-key header.
+#
+# OpenAI-format clients (/v1/chat/completions, /v1/responses) need explicit routes; the "*" catch-all below sends
+# every other model name to Anthropic. Add one entry per model, for example:
+#
+#   - model_name: gpt-5
+#     litellm_params:
+#       model: openai/gpt-5
+#       api_key: os.environ/OPENAI_API_KEY
+#
+# and put OPENAI_API_KEY in the env file (CONTEXT_PROXY_ENV_FILE).
+#
+# Codex with ChatGPT login needs no route: LiteLLM's built-in /backend-api/codex/{models,responses} pass-through
+# (PR #41522, in the pinned dev image) forwards the ChatGPT bearer to chatgpt.com; the client sends the LiteLLM key
+# in x-litellm-api-key. The hook sees those calls as call type pass_through_endpoint.
+model_list:
+  - model_name: "anthropic/*"
+    litellm_params:
+      model: "anthropic/*"
+  - model_name: "*"
+    litellm_params:
+      model: "anthropic/*"
+
+litellm_settings:
+  # Resolved relative to this file: proxy/openmem_context_hook.py
+  callbacks: openmem_context_hook.handler
+
+general_settings:
+  master_key: os.environ/LITELLM_MASTER_KEY

package/proxy/openmem_context/__init__.py

@@ -0,0 +1,6 @@
+"""OpenMem context proxy core: dependency-free request rewriting for LiteLLM."""
+
+from .core import process_request, process_usage, startup
+from .settings import Settings
+
+__all__ = ["Settings", "process_request", "process_usage", "startup"]