@bcmyguest/openmem 0.0.0-stage → 0.8.0

package/cli/mcp/notebooklm-hindsight-rest.mjs

@@ -0,0 +1,45 @@
+/** Hindsight REST helpers for notebooklm::* banks (shared by MCP server and provider adapter). */
+
+export async function listBanks(apiUrl, fetchFn = fetch) {
+  const res = await fetchFn(`${apiUrl}/v1/default/banks`);
+  if (!res.ok) throw new Error(`GET /v1/default/banks → ${res.status} ${res.statusText}`);
+  const data = await res.json();
+  return Array.isArray(data?.banks) ? data.banks : Array.isArray(data) ? data : [];
+}
+
+export async function listMemories(apiUrl, bankId, query, opts = {}, fetchFn = fetch) {
+  const limit = Number.isFinite(opts.limit) ? Math.max(0, Math.floor(opts.limit)) : 20;
+  const offset = Number.isFinite(opts.offset) ? Math.max(0, Math.floor(opts.offset)) : 0;
+  const qs = new URLSearchParams({ q: query, limit: String(limit), offset: String(offset) });
+  const url = `${apiUrl}/v1/default/banks/${encodeURIComponent(bankId)}/memories/list?${qs}`;
+  const res = await fetchFn(url);
+  const text = await res.text();
+  if (!res.ok) throw new Error(`GET memories/list ${bankId} → ${res.status}: ${text.slice(0, 400)}`);
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+export async function recallBank(apiUrl, bankId, query, fetchFn = fetch, opts = {}) {
+  const url = `${apiUrl}/v1/default/banks/${encodeURIComponent(bankId)}/memories/recall`;
+  const body = {
+    query,
+    budget: opts.budget || "low",
+    max_tokens: opts.max_tokens ?? 1024,
+    include: { entities: null, chunks: null, source_facts: null },
+  };
+  const res = await fetchFn(url, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  const text = await res.text();
+  if (!res.ok) throw new Error(`POST recall ${bankId} → ${res.status}: ${text.slice(0, 400)}`);
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}

package/cli/mcp/notebooklm-provider.mjs

@@ -0,0 +1,225 @@
+import fs from "node:fs";
+import { cogneeDatasetName } from "./export/cognee-dataset-name.mjs";
+import { mem0ScopeId } from "./mem0-scope-id.mjs";
+import { bankAllowed, filterNotebooklmBanks, isNotebooklmBank } from "./notebooklm-banks.mjs";
+import { listBanks, listMemories, recallBank } from "./notebooklm-hindsight-rest.mjs";
+import { search as cogneeSearch } from "../cognee-mcp.mjs";
+
+function readStateBanks(statePath) {
+  if (!statePath || !fs.existsSync(statePath)) return [];
+  try {
+    const data = JSON.parse(fs.readFileSync(statePath, "utf8"));
+    const docs = data?.documents && typeof data.documents === "object" ? data.documents : {};
+    const banks = new Set();
+    for (const row of Object.values(docs)) {
+      if (row?.bank && isNotebooklmBank(String(row.bank))) banks.add(String(row.bank));
+    }
+    return [...banks];
+  } catch {
+    return [];
+  }
+}
+
+function mem0Headers(ctx) {
+  /** @type {Record<string, string>} */
+  const headers = {};
+  if (ctx.mem0?.apiKey) headers["X-API-Key"] = ctx.mem0.apiKey;
+  return headers;
+}
+
+async function mem0Get(base, path, headers, fetchFn) {
+  const res = await fetchFn(`${base.replace(/\/$/, "")}${path}`, { headers });
+  const text = await res.text();
+  if (!res.ok) throw new Error(`GET ${path} → ${res.status}: ${text.slice(0, 300)}`);
+  return JSON.parse(text);
+}
+
+function mem0MemoryText(row) {
+  return row?.memory ?? row?.text ?? row?.content ?? row?.data ?? "";
+}
+
+/** @param {import("./context.mjs").McpContext} ctx @param {string[]} allowlist @param {typeof fetch} fetchFn */
+export async function listNotebooklmBanks(ctx, allowlist, fetchFn = fetch) {
+  if (ctx.provider === "hindsight") {
+    const url = ctx.hindsightUrl || "http://127.0.0.1:8888";
+    return filterNotebooklmBanks(await listBanks(url, fetchFn), allowlist).map((b) => ({
+      bank_id: b.bank_id || b.id || b.name,
+      fact_count: b.fact_count ?? null,
+      name: b.name ?? null,
+    }));
+  }
+  if (ctx.provider === "mem0") {
+    const base = ctx.mem0?.baseUrl;
+    if (!base) throw new Error("mem0 API URL not configured");
+    const headers = mem0Headers(ctx);
+    const statePath = process.env.NOTEBOOKLM_STATE || "";
+    const candidates = new Set();
+    if (allowlist.includes("*")) {
+      for (const b of readStateBanks(statePath)) candidates.add(b);
+      if (!candidates.size && !statePath) {
+        throw new Error(
+          "mem0: set NOTEBOOKLM_STATE to the sync state.json path, or list explicit notebooklmAccess.banks",
+        );
+      }
+    }
+    for (const entry of allowlist) {
+      if (entry === "*") continue;
+      candidates.add(entry.startsWith("notebooklm::") ? entry : `notebooklm::${entry}`);
+    }
+    const out = [];
+    for (const bankId of candidates) {
+      if (!bankAllowed(bankId, allowlist)) continue;
+      const uid = encodeURIComponent(mem0ScopeId(bankId));
+      const json = await mem0Get(base, `/memories?user_id=${uid}&top_k=1000`, headers, fetchFn);
+      const results = Array.isArray(json?.results) ? json.results : [];
+      if (results.length || !allowlist.includes("*")) {
+        out.push({ bank_id: bankId, fact_count: results.length, name: null });
+      }
+    }
+    return out;
+  }
+  if (ctx.provider === "cognee") {
+    const base = ctx.cognee?.baseUrl;
+    if (!base) throw new Error("Cognee API URL not configured");
+    const headers = { ...(ctx.cognee?.apiKey ? { "X-Api-Key": ctx.cognee.apiKey } : {}) };
+    const res = await fetchFn(`${base.replace(/\/$/, "")}/api/v1/datasets`, { headers });
+    const text = await res.text();
+    if (!res.ok) throw new Error(`GET datasets → ${res.status}: ${text.slice(0, 300)}`);
+    const datasets = JSON.parse(text);
+    const list = Array.isArray(datasets) ? datasets : datasets?.datasets || [];
+    const byBank = new Map();
+    for (const ds of list) {
+      const id = ds.id ?? ds.dataset_id;
+      if (!id) continue;
+      const dataRes = await fetchFn(`${base.replace(/\/$/, "")}/api/v1/datasets/${id}/data?limit=5`, { headers });
+      if (!dataRes.ok) continue;
+      const page = await dataRes.json();
+      const rows = Array.isArray(page) ? page : page?.data || [];
+      for (const row of rows) {
+        const meta = row?.external_metadata ?? row?.externalMetadata;
+        let bank = null;
+        if (Array.isArray(meta)) {
+          for (const m of meta) if (m?.bank) bank = m.bank;
+        } else if (meta && typeof meta === "object" && meta.bank) bank = meta.bank;
+        else if (typeof meta === "string") {
+          try {
+            const parsed = JSON.parse(meta);
+            if (parsed?.bank) bank = parsed.bank;
+          } catch {
+            /* ignore */
+          }
+        }
+        if (bank && isNotebooklmBank(bank) && bankAllowed(bank, allowlist)) {
+          byBank.set(bank, { bank_id: bank, fact_count: null, name: ds.name ?? null });
+        }
+      }
+    }
+    return [...byBank.values()];
+  }
+  throw new Error(`notebooklm MCP does not support provider ${ctx.provider}`);
+}
+
+/** @param {import("./context.mjs").McpContext} ctx @param {{ bankId: string, query: string, mode: string, limit: number, hindsightApiUrl?: string }} opts @param {typeof fetch} fetchFn */
+export async function searchNotebooklmBank(ctx, opts, fetchFn = fetch) {
+  const { bankId, query, mode, limit, hindsightApiUrl } = opts;
+  if (ctx.provider === "hindsight") {
+    const apiUrl = ctx.hindsightUrl || hindsightApiUrl || "http://127.0.0.1:8888";
+    if (mode === "recall") {
+      return { bank_id: bankId, query, mode, result: await recallBank(apiUrl, bankId, query, fetchFn) };
+    }
+    const listed = await listMemories(apiUrl, bankId, query, { limit }, fetchFn);
+    const items = Array.isArray(listed?.items)
+      ? listed.items.map((m) => ({
+          id: m.id ?? m.memory_id ?? null,
+          type: m.type ?? null,
+          text: m.text ?? m.content ?? null,
+        }))
+      : listed;
+    return {
+      bank_id: bankId,
+      query,
+      mode: "list",
+      total: listed?.total ?? null,
+      limit: listed?.limit ?? limit,
+      offset: listed?.offset ?? 0,
+      items,
+    };
+  }
+  if (ctx.provider === "mem0") {
+    const base = ctx.mem0?.baseUrl;
+    if (!base) throw new Error("mem0 API URL not configured");
+    const headers = { "content-type": "application/json", ...mem0Headers(ctx) };
+    const uid = mem0ScopeId(bankId);
+    if (mode === "recall") {
+      const res = await fetchFn(`${base.replace(/\/$/, "")}/search`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ query, filters: { user_id: uid }, top_k: limit }),
+      });
+      const text = await res.text();
+      if (!res.ok) throw new Error(`POST /search → ${res.status}: ${text.slice(0, 300)}`);
+      return { bank_id: bankId, query, mode: "recall", result: JSON.parse(text) };
+    }
+    const json = await mem0Get(
+      base,
+      `/memories?user_id=${encodeURIComponent(uid)}&top_k=${Math.min(limit, 1000)}`,
+      mem0Headers(ctx),
+      fetchFn,
+    );
+    const q = query.toLowerCase();
+    const results = (Array.isArray(json?.results) ? json.results : []).filter((r) =>
+      mem0MemoryText(r).toLowerCase().includes(q),
+    );
+    return {
+      bank_id: bankId,
+      query,
+      mode: "list",
+      items: results.slice(0, limit).map((r) => ({
+        id: r.id ?? null,
+        type: null,
+        text: mem0MemoryText(r),
+      })),
+    };
+  }
+  if (ctx.provider === "cognee") {
+    const dataset = cogneeDatasetName(bankId);
+    if (mode === "recall") {
+      const result = await cogneeSearch(
+        { baseUrl: ctx.cognee.baseUrl, apiKey: ctx.cognee?.apiKey },
+        { query, datasets: [dataset] },
+        fetchFn,
+      );
+      return { bank_id: bankId, query, mode: "recall", result };
+    }
+    const base = ctx.cognee.baseUrl.replace(/\/$/, "");
+    const headers = { ...(ctx.cognee?.apiKey ? { "X-Api-Key": ctx.cognee.apiKey } : {}) };
+    const dsRes = await fetchFn(`${base}/api/v1/datasets`, { headers });
+    const dsText = await dsRes.text();
+    if (!dsRes.ok) throw new Error(`GET datasets → ${dsRes.status}`);
+    const datasets = JSON.parse(dsText);
+    const list = Array.isArray(datasets) ? datasets : datasets?.datasets || [];
+    const match = list.find((d) => (d.name || d.dataset_name) === dataset);
+    if (!match?.id) throw new Error(`Cognee dataset not found for bank ${bankId}`);
+    const q = query.toLowerCase();
+    const items = [];
+    let offset = 0;
+    while (items.length < limit) {
+      const pageRes = await fetchFn(`${base}/api/v1/datasets/${match.id}/data?limit=50&offset=${offset}`, { headers });
+      if (!pageRes.ok) break;
+      const page = await pageRes.json();
+      const rows = Array.isArray(page) ? page : page?.data || [];
+      if (!rows.length) break;
+      for (const row of rows) {
+        const text = row?.text ?? row?.content ?? row?.data ?? "";
+        if (String(text).toLowerCase().includes(q)) {
+          items.push({ id: row.id ?? null, type: null, text: String(text) });
+          if (items.length >= limit) break;
+        }
+      }
+      offset += rows.length;
+      if (rows.length < 50) break;
+    }
+    return { bank_id: bankId, query, mode: "list", items };
+  }
+  throw new Error(`notebooklm MCP does not support provider ${ctx.provider}`);
+}

package/cli/mcp/pmm-records.mjs

@@ -0,0 +1,23 @@
+/** PMM record ordering and duplicate fingerprints (export/import). */
+
+/**
+ * Stable sort for deterministic exports and diffs.
+ * @param {object[]} records
+ */
+export function sortPmmRecords(records) {
+  return [...records].sort((a, b) => {
+    const sa = String(a.scope_key ?? "");
+    const sb = String(b.scope_key ?? "");
+    if (sa !== sb) return sa.localeCompare(sb);
+    const ia = String(a.id ?? "");
+    const ib = String(b.id ?? "");
+    if (ia !== ib) return ia.localeCompare(ib);
+    return String(a.content ?? "").localeCompare(String(b.content ?? ""));
+  });
+}
+
+/** @param {string} content */
+export function pmmContentFingerprint(content) {
+  const t = String(content || "").trim().replace(/\s+/g, " ");
+  return t;
+}

package/cli/mcp/portability.mjs

@@ -0,0 +1,158 @@
+/** PMM (Personal Memory Manifest) export/import — orchestrator over provider adapters. */
+
+import { runProviderExport } from "./export/index.mjs";
+import { exportMem0 } from "./export/mem0.mjs";
+import { pmmContentFingerprint, sortPmmRecords } from "./pmm-records.mjs";
+
+export const PMM_VERSION = 1;
+export const PMM_SUPPORTED_MAJOR = 1;
+
+/**
+ * @param {unknown} version
+ */
+export function assertPmmVersion(version) {
+  const n = Number(version);
+  if (!Number.isFinite(n) || Math.floor(n) !== n) {
+    throw new Error(`unsupported pmm_version ${String(version)}`);
+  }
+  const major = n;
+  if (major !== PMM_SUPPORTED_MAJOR) {
+    throw new Error(`unsupported PMM major version ${major} (supported: ${PMM_SUPPORTED_MAJOR})`);
+  }
+}
+
+/**
+ * @param {{ provider: string, scope: Record<string, unknown>, records: object[] }} parts
+ */
+export function buildPmm(parts) {
+  return {
+    pmm_version: PMM_VERSION,
+    exported_at: new Date().toISOString(),
+    source_provider: parts.provider,
+    scope: parts.scope,
+    records: sortPmmRecords(parts.records || []),
+  };
+}
+
+/**
+ * @param {ReturnType<typeof buildPmm>} pmm
+ * @param {string} format
+ */
+export function serializePmm(pmm, format) {
+  if (format === "jsonl") {
+    const header = { ...pmm, records: undefined };
+    const lines = [JSON.stringify(header), ...(pmm.records || []).map((r) => JSON.stringify(r))];
+    return `${lines.join("\n")}\n`;
+  }
+  return pmm;
+}
+
+/**
+ * @param {string} data
+ * @returns {{ pmm: ReturnType<typeof buildPmm> }}
+ */
+export function parsePmm(data) {
+  const trimmed = String(data || "").trim();
+  if (!trimmed) throw new Error("import data is empty");
+  let document = null;
+  try { document = JSON.parse(trimmed); } catch { /* JSONL contains multiple JSON objects. */ }
+  if (document && typeof document === "object" && !Array.isArray(document)) {
+    const pmm = document;
+    assertPmmVersion(pmm.pmm_version);
+    return { pmm: { ...pmm, records: sortPmmRecords(pmm.records || []) } };
+  }
+  /** @type {ReturnType<typeof buildPmm>["records"]} */
+  const records = [];
+  let meta = null;
+  for (const line of trimmed.split("\n")) {
+    const row = line.trim();
+    if (!row) continue;
+    const obj = JSON.parse(row);
+    if (obj.pmm_version === PMM_VERSION && obj.source_provider) {
+      meta = obj;
+      if (Array.isArray(obj.records)) records.push(...obj.records);
+    } else if (obj.content != null) {
+      records.push(obj);
+    }
+  }
+  if (!meta) throw new Error("jsonl import requires a PMM header line or a single JSON object");
+  assertPmmVersion(meta.pmm_version);
+  return { pmm: { ...meta, records: sortPmmRecords(records) } };
+}
+
+/**
+ * @param {ReturnType<typeof buildPmm>} pmm
+ * @param {import("./context.mjs").resolveMcpContext extends (...a: any) => infer R ? R : never} ctx
+ * @param {typeof fetch} fetchFn
+ */
+async function mem0ExistingKeys(ctx, userId, fetchFn) {
+  const { records } = await exportMem0(ctx, { user_id: userId }, fetchFn);
+  const ids = new Set();
+  const fingerprints = new Set();
+  for (const r of records) {
+    if (r.id) ids.add(String(r.id));
+    fingerprints.add(pmmContentFingerprint(String(r.content || "")));
+  }
+  return { ids, fingerprints };
+}
+
+/**
+ * @param {import("./context.mjs").resolveMcpContext extends (...a: any) => infer R ? R : never} ctx
+ * @param {{ bank?: string, format?: string }} args
+ * @param {typeof fetch} fetchFn
+ */
+export async function memoryExport(ctx, args, fetchFn = fetch) {
+  const format = String(args.format || "json").toLowerCase();
+  const { scope, records, note } = await runProviderExport(ctx.provider, ctx, args, fetchFn);
+  const pmm = buildPmm({ provider: ctx.provider, scope, records });
+  if (note) pmm.note = note;
+  return serializePmm(pmm, format);
+}
+
+/**
+ * @param {import("./context.mjs").resolveMcpContext extends (...a: any) => infer R ? R : never} ctx
+ * @param {string} data
+ * @param {{ merge_strategy?: string }} args
+ * @param {typeof fetch} fetchFn
+ * @param {(ctx: any, name: string, toolArgs: object, fetchFn: typeof fetch) => Promise<any>} addFn
+ */
+export async function memoryImport(ctx, data, args, fetchFn, addFn) {
+  const { pmm } = parsePmm(data);
+  const strategy = String(args.merge_strategy || "skip_duplicates");
+  /** @type {string[]} */
+  const imported = [];
+  /** @type {string[]} */
+  const skipped = [];
+  /** @type {Map<string, { ids: Set<string>, fingerprints: Set<string> }>} */
+  const mem0Seen = new Map();
+  for (const rec of pmm.records || []) {
+    const content = String(rec.content || "").trim();
+    if (!content) continue;
+    const bank = String(rec.scope_key || pmm.scope?.bank || pmm.scope?.user_id || "openmem-mcp");
+    if (strategy === "skip_duplicates" && ctx.provider === "mem0") {
+      if (!mem0Seen.has(bank)) mem0Seen.set(bank, await mem0ExistingKeys(ctx, bank, fetchFn));
+      const seen = mem0Seen.get(bank);
+      const fp = pmmContentFingerprint(content);
+      if ((rec.id && seen.ids.has(String(rec.id))) || seen.fingerprints.has(fp)) {
+        skipped.push(rec.id ? String(rec.id) : fp.slice(0, 40));
+        continue;
+      }
+      seen.fingerprints.add(fp);
+      if (rec.id) seen.ids.add(String(rec.id));
+    }
+    const result = await addFn(ctx, "memory_add", { content, bank }, fetchFn);
+    if (result?.isError) {
+      throw new Error(`memory import failed in bank ${bank}: ${result.content?.[0]?.text || "memory_add returned an error"}`);
+    }
+    imported.push(rec.id ? String(rec.id) : content.slice(0, 40));
+  }
+  return {
+    pmm_version: PMM_VERSION,
+    target_provider: ctx.provider,
+    source_provider: pmm.source_provider,
+    merge_strategy: strategy,
+    imported_count: imported.length,
+    skipped_count: skipped.length,
+    cross_provider: pmm.source_provider !== ctx.provider,
+  };
+}

package/cli/mcp/stdio.mjs

@@ -0,0 +1,65 @@
+/** MCP stdio framing (NDJSON + Content-Length). Shared by unified and provider MCP servers. */
+
+/** @param {unknown} obj @param {"ndjson" | "content-length"} framing */
+export function writeMessage(obj, framing = "ndjson") {
+  if (obj == null) return;
+  const body = JSON.stringify(obj);
+  if (framing === "content-length") {
+    process.stdout.write(`Content-Length: ${Buffer.byteLength(body, "utf8")}\r\n\r\n${body}`);
+    return;
+  }
+  process.stdout.write(`${body}\n`);
+}
+
+/** @param {AsyncIterable<Buffer | string>} input @param {(msg: Record<string, unknown>) => Promise<unknown>} onMsg */
+export async function serveStdio(input, onMsg) {
+  let buf = Buffer.alloc(0);
+  for await (const chunk of input) {
+    buf = Buffer.concat([buf, Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)]);
+    while (buf.length) {
+      const asStr = buf.toString("utf8");
+      const crlf = asStr.indexOf("\r\n\r\n");
+      const lf = asStr.indexOf("\n\n");
+      const headerEnd = crlf >= 0 ? crlf : lf;
+      const sepLen = crlf >= 0 ? 4 : lf >= 0 ? 2 : -1;
+      if (sepLen > 0 && /content-length\s*:/i.test(asStr.slice(0, headerEnd))) {
+        const m = /Content-Length:\s*(\d+)/i.exec(asStr.slice(0, headerEnd));
+        if (!m) {
+          buf = buf.subarray(Buffer.byteLength(asStr.slice(0, headerEnd + sepLen), "utf8"));
+          continue;
+        }
+        const len = Number(m[1]);
+        const headerBytes = Buffer.byteLength(asStr.slice(0, headerEnd + sepLen), "utf8");
+        if (buf.length < headerBytes + len) break;
+        const body = buf.subarray(headerBytes, headerBytes + len).toString("utf8");
+        buf = buf.subarray(headerBytes + len);
+        let msg;
+        try {
+          msg = JSON.parse(body);
+        } catch (err) {
+          writeMessage(
+            {
+              jsonrpc: "2.0",
+              id: null,
+              error: { code: -32700, message: `Parse error: ${err instanceof Error ? err.message : err}` },
+            },
+            "content-length",
+          );
+          continue;
+        }
+        writeMessage(await onMsg(msg), "content-length");
+        continue;
+      }
+      const nl = asStr.indexOf("\n");
+      if (nl < 0) break;
+      const line = asStr.slice(0, nl).trim();
+      buf = buf.subarray(Buffer.byteLength(asStr.slice(0, nl + 1), "utf8"));
+      if (!line.startsWith("{")) continue;
+      try {
+        writeMessage(await onMsg(JSON.parse(line)), "ndjson");
+      } catch {
+        /* skip bad line */
+      }
+    }
+  }
+}

package/cli/mcp/unified-mcp-install.mjs

@@ -0,0 +1,65 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { mergeNamedMcpServer } from "../install-memory-mcp.mjs";
+
+/** @param {string} repoRoot */
+export function unifiedMcpScriptPath(repoRoot) {
+  return path.resolve(repoRoot, "cli/openmem-mcp.mjs");
+}
+
+/**
+ * @param {{ provider: string, scriptPath: string, stackRoot?: string }} opts
+ */
+export function unifiedMcpEntry({ provider, scriptPath, stackRoot }) {
+  /** @type {Record<string, string>} */
+  const env = { MEMORY_PROVIDER: provider };
+  if (stackRoot) env.PM_STACK_ROOT = stackRoot;
+  return {
+    command: "node",
+    args: [scriptPath],
+    env,
+  };
+}
+
+/**
+ * @param {{ home: string, repoRoot: string, stackRoot: string, provider: string, dry?: boolean }} opts
+ * @param {{ ok: Function, info: Function }} h
+ */
+export function installUnifiedMcp(opts, h) {
+  const mcpPath = path.join(opts.home, ".cursor/mcp.json");
+  const entry = unifiedMcpEntry({
+    provider: opts.provider,
+    scriptPath: unifiedMcpScriptPath(opts.repoRoot),
+    stackRoot: opts.stackRoot,
+  });
+  if (opts.dry) {
+    h.info(`[dry-run] merge openmem MCP into ${mcpPath}`);
+    return { changed: false };
+  }
+  const mcp = fs.existsSync(mcpPath) ? JSON.parse(fs.readFileSync(mcpPath, "utf8")) : {};
+  const { mcp: next, changed, skipped } = mergeNamedMcpServer(mcp, "openmem", entry, {
+    protect: ["hindsight", "codegraph", "notebooklm", "mem0", "cognee"],
+  });
+  const servers = { ...(next.mcpServers && typeof next.mcpServers === "object" ? next.mcpServers : {}) };
+  const droppedLegacy = Boolean(servers["personal-memory"]);
+  if (droppedLegacy) delete servers["personal-memory"];
+  const finalMcp = { ...next, mcpServers: servers };
+  const wrote = Boolean(changed) || droppedLegacy;
+  if (wrote) {
+    fs.mkdirSync(path.dirname(mcpPath), { recursive: true });
+    fs.writeFileSync(mcpPath, `${JSON.stringify(finalMcp, null, 2)}\n`);
+    h.ok(`openmem MCP → ${mcpPath}`);
+  } else if (skipped) {
+    h.info(`openmem MCP ${skipped}`);
+  } else {
+    h.info("openmem MCP already configured");
+  }
+  return { changed: wrote };
+}
+
+/** @param {string} [pkgRoot] */
+export function defaultUnifiedMcpScriptPath(pkgRoot) {
+  const root = pkgRoot || path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+  return unifiedMcpScriptPath(root);
+}

package/cli/mem0-mcp.mjs

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+/**
+ * Stdio launcher for the self-hosted mem0 MCP bridge.
+ *
+ * Loads MEM0_API_KEY from MEM0_ENV_FILE / ~/.config/personal-memory/mem0.env when unset,
+ * maps MEM0_API_URL → MEM0_BASE_URL for @yeyuan98/mem0-mcp, then execs:
+ *   npx -y @yeyuan98/mem0-mcp
+ *
+ * Never prints the API key. Cursor mcp.json must not embed the secret — only the URL
+ * and optional MEM0_ENV_FILE path (see providers/mem0/lib/mcp-install.mjs).
+ */
+import { spawn } from "node:child_process";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { isMainModule } from "./is-main.mjs";
+import { readKey } from "../providers/mem0/lib/env-file.mjs";
+import { MEM0_MCP_NPM_PACKAGE } from "../providers/mem0/lib/mcp-install.mjs";
+import { defaultEnvFile } from "../providers/mem0/lib/state.mjs";
+
+const BIN = "mem0-mcp";
+
+/**
+ * @param {NodeJS.ProcessEnv} [env]
+ * @param {string} [home]
+ */
+export function resolveEnvFileForLaunch(env = process.env, home = process.env.HOME || os.homedir()) {
+  const raw = String(env.MEM0_ENV_FILE || "").trim();
+  if (!raw) return defaultEnvFile(home);
+  if (raw.startsWith("~/")) return path.join(home, raw.slice(2));
+  return path.isAbsolute(raw) ? raw : path.resolve(raw);
+}
+
+/**
+ * Prepare env for the upstream MCP: BASE_URL + API_KEY. Mutates a shallow copy only.
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {{ env: NodeJS.ProcessEnv, envFile: string, hadKeyInEnv: boolean }}
+ */
+export function prepareMem0McpEnv(env = process.env) {
+  const next = { ...env };
+  const apiUrl = String(next.MEM0_API_URL || next.MEM0_BASE_URL || "")
+    .trim()
+    .replace(/\/+$/, "");
+  if (apiUrl) {
+    next.MEM0_API_URL = apiUrl;
+    next.MEM0_BASE_URL = apiUrl;
+  }
+
+  const hadKeyInEnv = Boolean(String(next.MEM0_API_KEY || "").trim());
+  const envFile = resolveEnvFileForLaunch(next);
+  if (!hadKeyInEnv) {
+    const fromFile = readKey(envFile);
+    if (fromFile) next.MEM0_API_KEY = fromFile;
+  }
+
+  return { env: next, envFile, hadKeyInEnv };
+}
+
+/**
+ * @param {{ env?: NodeJS.ProcessEnv, spawnFn?: typeof spawn }} [opts]
+ * @returns {Promise<number>} exit code
+ */
+export function runMem0Mcp(opts = {}) {
+  const spawnFn = opts.spawnFn || spawn;
+  const { env, envFile } = prepareMem0McpEnv(opts.env || process.env);
+
+  if (!String(env.MEM0_BASE_URL || "").trim()) {
+    console.error(
+      `${BIN}: set MEM0_API_URL or MEM0_BASE_URL to your self-hosted mem0 REST server (e.g. http://127.0.0.1:18888)`,
+    );
+    return Promise.resolve(1);
+  }
+  if (!String(env.MEM0_API_KEY || "").trim()) {
+    console.error(
+      `${BIN}: MEM0_API_KEY missing. Put it in ${envFile} (mode 600) or export it in the agent environment.` +
+        ` (AUTH_DISABLED=true servers still need a non-empty placeholder for this MCP bridge.)`,
+    );
+    return Promise.resolve(1);
+  }
+
+  return new Promise((resolve) => {
+    const child = spawnFn("npx", ["-y", MEM0_MCP_NPM_PACKAGE], {
+      env,
+      stdio: "inherit",
+      shell: false,
+    });
+    child.on("error", (err) => {
+      console.error(`${BIN}: failed to start npx ${MEM0_MCP_NPM_PACKAGE}: ${err.message}`);
+      resolve(1);
+    });
+    child.on("exit", (code, signal) => {
+      if (signal) resolve(1);
+      else resolve(code == null ? 1 : code);
+    });
+  });
+}
+
+async function main() {
+  const code = await runMem0Mcp();
+  process.exit(code);
+}
+
+if (isMainModule(import.meta.url)) {
+  main().catch((err) => {
+    console.error(`${BIN}: ${err instanceof Error ? err.message : err}`);
+    process.exit(1);
+  });
+}