@pyxmate/memory 1.27.0 → 1.27.1

package/dist/chunk-QR5K7ETI.mjs

@@ -0,0 +1,793 @@
+import {
+  PERSISTENT_MEMORY_SECTION
+} from "./chunk-QD7G23CN.mjs";
+import {
+  EXIT
+} from "./chunk-4DXEQC6X.mjs";
+
+// src/cli/commands/mcp-install.ts
+import { spawnSync as nodeSpawnSync } from "child_process";
+import { existsSync as existsSync3 } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+
+// src/cli/commands/mcp-install-merge.ts
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "fs";
+import { dirname } from "path";
+function mergeWriteJsonMcpEntry(opts) {
+  const { filePath, serverName, entry } = opts;
+  let existingDoc = {};
+  if (existsSync(filePath)) {
+    const raw = readFileSync(filePath, "utf8").trim();
+    if (raw.length > 0) {
+      try {
+        const parsed = JSON.parse(raw);
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+          return {
+            exitCode: EXIT.USAGE,
+            status: "parse-error",
+            message: `Refusing to write: ${filePath} is not a JSON object at its root.
+Fix the file manually, then re-run.
+`
+          };
+        }
+        existingDoc = parsed;
+      } catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        return {
+          exitCode: EXIT.USAGE,
+          status: "parse-error",
+          message: `Refusing to write: ${filePath} contains invalid JSON (${reason}).
+Fix the file manually, then re-run.
+`
+        };
+      }
+    }
+  }
+  const rawServers = existingDoc.mcpServers;
+  const servers = rawServers !== null && typeof rawServers === "object" && !Array.isArray(rawServers) ? { ...rawServers } : {};
+  const existingEntry = servers[serverName];
+  if (existingEntry !== void 0) {
+    if (entriesEqual(existingEntry, entry)) {
+      return {
+        exitCode: EXIT.OK,
+        status: "already-installed",
+        message: `pyx-memory is already installed in ${filePath} (no changes written).
+`
+      };
+    }
+    return {
+      exitCode: EXIT.USAGE,
+      status: "conflict",
+      message: `Refusing to overwrite existing \`${serverName}\` entry in ${filePath}.
+
+Found:
+${indent(JSON.stringify(existingEntry, null, 2))}
+
+Proposed:
+${indent(JSON.stringify(entry, null, 2))}
+
+Remove or rename the existing entry, then re-run.
+`
+    };
+  }
+  servers[serverName] = entry;
+  const nextDoc = { ...existingDoc, mcpServers: servers };
+  const payload = `${JSON.stringify(nextDoc, null, 2)}
+`;
+  const parent = dirname(filePath);
+  if (!existsSync(parent)) {
+    mkdirSync(parent, { recursive: true });
+  }
+  const tmpPath = `${filePath}.tmp`;
+  writeFileSync(tmpPath, payload, { mode: 384 });
+  renameSync(tmpPath, filePath);
+  return {
+    exitCode: EXIT.OK,
+    status: "installed",
+    message: `Installed \`${serverName}\` MCP server entry in ${filePath}.
+`
+  };
+}
+function entriesEqual(a, b) {
+  if (a === null || typeof a !== "object") return false;
+  const left = a;
+  if (left.command !== b.command) return false;
+  if (!arraysEqual(left.args, b.args)) return false;
+  if (!recordsEqual(left.env, b.env)) return false;
+  return true;
+}
+function arraysEqual(a, b) {
+  const left = Array.isArray(a) ? a : void 0;
+  const right = b;
+  if (left === void 0 && right === void 0) return true;
+  if (left === void 0 || right === void 0)
+    return (left ?? []).length === 0 && (right ?? []).length === 0;
+  if (left.length !== right.length) return false;
+  for (let i = 0; i < left.length; i++) {
+    if (left[i] !== right[i]) return false;
+  }
+  return true;
+}
+function recordsEqual(a, b) {
+  const left = a !== null && typeof a === "object" && !Array.isArray(a) ? a : void 0;
+  const right = b;
+  if (left === void 0 && right === void 0) return true;
+  const leftKeys = left ? Object.keys(left) : [];
+  const rightKeys = right ? Object.keys(right) : [];
+  if (leftKeys.length === 0 && rightKeys.length === 0) return true;
+  if (leftKeys.length !== rightKeys.length) return false;
+  for (const k of leftKeys) {
+    if (left?.[k] !== right?.[k]) return false;
+  }
+  return true;
+}
+function indent(text) {
+  return text.split("\n").map((line) => `  ${line}`).join("\n");
+}
+
+// src/cli/commands/memory-rules-merge.ts
+import { randomUUID } from "crypto";
+import {
+  chmodSync,
+  existsSync as existsSync2,
+  linkSync,
+  lstatSync,
+  mkdirSync as mkdirSync2,
+  readFileSync as readFileSync2,
+  realpathSync,
+  renameSync as renameSync2,
+  rmSync,
+  statSync,
+  writeFileSync as writeFileSync2
+} from "fs";
+import { dirname as dirname2 } from "path";
+var RULES_BEGIN_MARKER = "<!-- pyx-memory:begin (managed by `pyx-mem mcp install`; edit outside these markers) -->";
+var RULES_END_MARKER = "<!-- pyx-memory:end -->";
+var BEGIN_MARKER_PREFIX = "<!-- pyx-memory:begin";
+var PM_HEADING_RE = /^ {0,3}##[ \t]+Persistent Memory[ \t]*$/;
+var H1_OR_H2_RE = /^ {0,3}#{1,2}[ \t]+\S/;
+var FENCE_RE = /^ {0,3}(`{3,}|~{3,})/;
+var CLOSING_FENCE_RE = /^ {0,3}(`{3,}|~{3,})[ \t]*$/;
+var BEGIN_MARKER_RE = /^ {0,3}<!-- pyx-memory:begin(?:[ \t][^>]*)?-->[ \t]*$/;
+var END_MARKER_RE = /^ {0,3}<!-- pyx-memory:end -->[ \t]*$/;
+function isBeginMarker(line) {
+  return BEGIN_MARKER_RE.test(line);
+}
+function isEndMarker(line) {
+  return END_MARKER_RE.test(line);
+}
+function fenceMask(lines) {
+  const mask = new Array(lines.length).fill(false);
+  let openIdx = -1;
+  let delim = "";
+  let openLen = 0;
+  for (let i = 0; i < lines.length; i++) {
+    const fence = FENCE_RE.exec(lines[i] ?? "")?.[1];
+    if (!fence) continue;
+    if (openIdx === -1) {
+      openIdx = i;
+      delim = fence.charAt(0);
+      openLen = fence.length;
+      continue;
+    }
+    if (CLOSING_FENCE_RE.test(lines[i] ?? "") && fence.charAt(0) === delim && fence.length >= openLen) {
+      for (let j = openIdx; j <= i; j++) mask[j] = true;
+      openIdx = -1;
+      delim = "";
+      openLen = 0;
+    }
+  }
+  return mask;
+}
+function nextH1OrH2(lines, mask, from) {
+  for (let i = from; i < lines.length; i++) {
+    const line = lines[i];
+    if (line !== void 0 && !mask[i] && H1_OR_H2_RE.test(line)) return i;
+  }
+  return lines.length;
+}
+function findCompleteManagedRange(lines, mask) {
+  let begin = -1;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line === void 0 || mask[i]) continue;
+    if (isBeginMarker(line)) begin = i;
+    else if (begin !== -1 && isEndMarker(line)) return [begin, i + 1];
+  }
+  return null;
+}
+function findBeginLines(lines, mask) {
+  const found = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line !== void 0 && !mask[i] && isBeginMarker(line)) found.push(i);
+  }
+  return found;
+}
+function findLegacyPyxRange(lines, mask) {
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line === void 0 || mask[i] || !PM_HEADING_RE.test(line)) continue;
+    const end = nextH1OrH2(lines, mask, i + 1);
+    const own = lines.slice(i, end).filter((l, k) => !mask[i + k] && !isBeginMarker(l) && !isEndMarker(l));
+    if (own.join("\n").toLowerCase().includes("pyx-memory")) return [i, end];
+  }
+  return null;
+}
+function spliceBlock(lines, from, toExclusive, blockLines) {
+  const before = lines.slice(0, from);
+  const after = lines.slice(toExclusive);
+  while (before.length && (before[before.length - 1] ?? "").trim() === "") before.pop();
+  while (after.length && (after[0] ?? "").trim() === "") after.shift();
+  const out = [...before];
+  if (out.length) out.push("");
+  out.push(...blockLines);
+  if (after.length) out.push("");
+  out.push(...after);
+  return out;
+}
+function joinWithTrailingNewline(lines, eol) {
+  const body = lines.join(eol);
+  return body.endsWith(eol) ? body : `${body}${eol}`;
+}
+var BOM = "\uFEFF";
+function mergeMemoryRules(existing, section) {
+  const bom = existing.startsWith(BOM) ? BOM : "";
+  const merged = mergeBody(existing.slice(bom.length), section);
+  return { ...merged, content: bom + merged.content };
+}
+function mergeBody(existing, section) {
+  if (section.includes(BEGIN_MARKER_PREFIX) || section.includes(RULES_END_MARKER)) {
+    throw new Error("pyx-memory rules section must not contain the managed markers.");
+  }
+  const eol = existing.includes("\r\n") ? "\r\n" : "\n";
+  const blockLines = [RULES_BEGIN_MARKER, ...section.split(/\r?\n/), RULES_END_MARKER];
+  const normalized = existing.replace(/\r\n/g, "\n");
+  if (normalized.trim().length === 0) {
+    return { content: joinWithTrailingNewline(blockLines, eol), action: "created" };
+  }
+  let lines = normalized.split("\n");
+  let mask = fenceMask(lines);
+  const complete = findCompleteManagedRange(lines, mask);
+  if (complete) {
+    const next2 = spliceBlock(lines, complete[0], complete[1], blockLines);
+    return { content: joinWithTrailingNewline(next2, eol), action: "updated" };
+  }
+  const orphans = new Set(findBeginLines(lines, mask));
+  if (orphans.size > 0) {
+    lines = lines.filter((_, i) => !orphans.has(i));
+    mask = fenceMask(lines);
+  }
+  const legacy = findLegacyPyxRange(lines, mask);
+  if (legacy) {
+    const next2 = spliceBlock(lines, legacy[0], legacy[1], blockLines);
+    return { content: joinWithTrailingNewline(next2, eol), action: "updated" };
+  }
+  const next = spliceBlock(lines, lines.length, lines.length, blockLines);
+  return { content: joinWithTrailingNewline(next, eol), action: "appended" };
+}
+function refreshMemoryRules(file, section) {
+  const bom = file.startsWith(BOM) ? BOM : "";
+  const refreshed = refreshBody(file.slice(bom.length), section);
+  return refreshed === null ? null : bom + refreshed;
+}
+function refreshBody(existing, section) {
+  const lines = existing.replace(/\r\n/g, "\n").split("\n");
+  const complete = findCompleteManagedRange(lines, fenceMask(lines));
+  if (!complete) return null;
+  const [first, last] = [complete[0], complete[1] - 1];
+  const starts = [0];
+  for (let i = 0; i < existing.length; i++) if (existing[i] === "\n") starts.push(i + 1);
+  const from = starts[first] ?? 0;
+  const lastStart = starts[last] ?? 0;
+  const to = lastStart + (lines[last] ?? "").length;
+  const eol = existing.slice(from).match(/\r?\n/)?.[0] ?? "\n";
+  const block = [RULES_BEGIN_MARKER, ...section.split(/\r?\n/), RULES_END_MARKER].join(eol);
+  return existing.slice(0, from) + block + existing.slice(to);
+}
+function changedDuringWrite(filePath) {
+  return new Error(`${filePath} changed while updating the pyx-memory rules; retry.`);
+}
+function readUtf8Strict(path) {
+  try {
+    return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(readFileSync2(path));
+  } catch (err) {
+    if (err instanceof TypeError) {
+      throw new Error(`${path} is not valid UTF-8; the pyx-memory rules were not changed.`);
+    }
+    throw err;
+  }
+}
+function writeMemoryRulesFile(opts) {
+  const { filePath, section } = opts;
+  const fileExists = existsSync2(filePath);
+  if (!fileExists && lstatSync(filePath, { throwIfNoEntry: false })?.isSymbolicLink()) {
+    throw new Error(`${filePath} is a broken link; fix or remove it, then retry.`);
+  }
+  const target = fileExists ? realpathSync(filePath) : filePath;
+  const existing = fileExists ? readUtf8Strict(target) : "";
+  let merged = null;
+  if (!opts.refreshOnly) merged = mergeMemoryRules(existing, section);
+  else {
+    const content = refreshMemoryRules(existing, section);
+    if (content !== null) merged = { content, action: "updated" };
+  }
+  if (merged === null || merged.content === existing) {
+    return {
+      action: "unchanged",
+      filePath,
+      message: `pyx-memory rules already current in ${filePath} (no changes written).
+`
+    };
+  }
+  const parent = dirname2(target);
+  if (!existsSync2(parent)) mkdirSync2(parent, { recursive: true });
+  const mode = fileExists ? statSync(target).mode & 511 : 420;
+  const tmpPath = `${target}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    writeFileSync2(tmpPath, merged.content, { mode });
+    chmodSync(tmpPath, mode);
+    if (fileExists) {
+      if (readUtf8Strict(target) !== existing) throw changedDuringWrite(filePath);
+      renameSync2(tmpPath, target);
+    } else {
+      try {
+        linkSync(tmpPath, target);
+      } catch (err) {
+        if (err.code === "EEXIST") throw changedDuringWrite(filePath);
+        throw err;
+      }
+      rmSync(tmpPath);
+    }
+  } catch (err) {
+    rmSync(tmpPath, { force: true });
+    throw err;
+  }
+  const verb = merged.action === "created" ? "Wrote" : merged.action === "appended" ? "Added" : "Updated";
+  return {
+    action: merged.action,
+    filePath,
+    message: `${verb} the pyx-memory rules in ${filePath}.
+`
+  };
+}
+
+// src/cli/commands/mcp-install.ts
+var VALID_SCOPES = /* @__PURE__ */ new Set(["local", "user", "project"]);
+var SERVER_NAME = "pyx-memory";
+function pyxMemArgs(remote) {
+  return remote ? ["mcp", "--remote"] : ["mcp"];
+}
+function mcpEntry(remote) {
+  return { command: "pyx-mem", args: pyxMemArgs(remote) };
+}
+function mcpInstallClaudeCodeCommand(opts = {}) {
+  const scope = opts.scope ?? "local";
+  if (!validateScope(scope)) return EXIT.USAGE;
+  const remote = opts.remote ?? false;
+  const spawnSync = opts._spawnSync ?? nodeSpawnSync;
+  const probe = spawnSync("claude", ["--version"], { stdio: "pipe" });
+  if (probe.error || probe.status !== 0) {
+    printClaudeCodeManualInstructions(scope, remote);
+    return EXIT.OK;
+  }
+  const cmd = ["mcp", "add", SERVER_NAME, "-s", scope, "--", "pyx-mem", ...pyxMemArgs(remote)];
+  const res = spawnSync("claude", cmd, { stdio: "inherit" });
+  if (res.status !== 0) {
+    process.stderr.write(`\`claude ${cmd.join(" ")}\` exited with code ${res.status ?? "null"}.
+`);
+    printClaudeCodeManualInstructions(scope, remote);
+    return EXIT.USAGE;
+  }
+  process.stdout.write(
+    `Installed pyx-memory MCP server in Claude Code (scope: ${scope}).
+Restart Claude Code to make the tools available. No API key was written to .mcp.json \u2014 credentials live in the OS credential store.
+To populate the knowledge graph, YOU pass entities and relationships (or triples) \u2014 a multi-entity store needs at least one connecting edge or it is refused. The server does not extract for you unless a self-host operator configured a BYO extraction endpoint (then store_memory can forward extractEntities:true). Images require caller-provided descriptions/hooks.
+`
+  );
+  return EXIT.OK;
+}
+function printClaudeCodeManualInstructions(scope, remote) {
+  process.stdout.write(
+    [
+      "The `claude` CLI is not on PATH, or the install command failed.",
+      "",
+      "Run this once Claude Code is installed:",
+      `  claude mcp add ${SERVER_NAME} -s ${scope} -- pyx-mem ${pyxMemArgs(remote).join(" ")}`,
+      "",
+      "Or add this entry manually to your Claude Code MCP config (.mcp.json):",
+      JSON.stringify({ mcpServers: { [SERVER_NAME]: mcpEntry(remote) } }, null, 2),
+      "",
+      "Do NOT add your pyx-memory API key here. Run `pyx-mem login` to store it in the OS credential store.",
+      ""
+    ].join("\n")
+  );
+}
+function mcpInstallCodexCommand(opts = {}) {
+  const scope = opts.scope ?? "user";
+  if (!validateScope(scope)) return EXIT.USAGE;
+  const remote = opts.remote ?? false;
+  const spawnSync = opts._spawnSync ?? nodeSpawnSync;
+  const home = opts._homeDir ?? homedir();
+  const codexHome = (opts._env ?? process.env).CODEX_HOME;
+  const probe = spawnSync("codex", ["--version"], { stdio: "pipe" });
+  if (probe.error || probe.status !== 0) {
+    printCodexManualInstructions(home, remote, codexHome);
+    return EXIT.OK;
+  }
+  const cmd = [
+    "mcp",
+    "add",
+    SERVER_NAME,
+    ...codexHome ? ["--env", `CODEX_HOME=${codexHome}`] : [],
+    "--",
+    "pyx-mem",
+    ...pyxMemArgs(remote)
+  ];
+  const res = spawnSync("codex", cmd, { stdio: "inherit" });
+  if (res.status !== 0) {
+    process.stderr.write(`\`codex ${cmd.join(" ")}\` exited with code ${res.status ?? "null"}.
+`);
+    printCodexManualInstructions(home, remote, codexHome);
+    return EXIT.USAGE;
+  }
+  process.stdout.write(
+    `Installed pyx-memory MCP server in Codex CLI.
+Restart Codex CLI to make the tools available. No API key was written to config.toml \u2014 credentials live in the OS credential store.
+`
+  );
+  return EXIT.OK;
+}
+function printCodexManualInstructions(home, remote, codexHome) {
+  const configPath = join(codexHome ?? join(home, ".codex"), "config.toml");
+  process.stdout.write(
+    [
+      "The `codex` CLI is not on PATH, or the install command failed.",
+      "",
+      "Run this once Codex CLI is installed:",
+      `  codex mcp add ${SERVER_NAME}${codexHome ? ` --env ${JSON.stringify(`CODEX_HOME=${codexHome}`)}` : ""} -- pyx-mem ${pyxMemArgs(remote).join(" ")}`,
+      "",
+      `Or add this section manually to ${configPath}:`,
+      "",
+      `[mcp_servers.${SERVER_NAME}]`,
+      `command = "pyx-mem"`,
+      `args = ${JSON.stringify(pyxMemArgs(remote))}`,
+      ...codexHome ? [`env = { CODEX_HOME = ${JSON.stringify(codexHome)} }`] : [],
+      "",
+      "Do NOT add your pyx-memory API key here. Run `pyx-mem login` to store it in the OS credential store.",
+      ""
+    ].join("\n")
+  );
+}
+function mcpInstallCursorCommand(opts = {}) {
+  const scope = opts.scope ?? "user";
+  if (!validateScope(scope)) return EXIT.USAGE;
+  const home = opts._homeDir ?? homedir();
+  const filePath = scope === "project" ? join(process.cwd(), ".cursor", "mcp.json") : join(home, ".cursor", "mcp.json");
+  return writeJsonAndReport(filePath, "Cursor", mcpEntry(opts.remote ?? false));
+}
+function mcpInstallClineCommand(opts = {}) {
+  const scope = opts.scope ?? "user";
+  if (!validateScope(scope)) return EXIT.USAGE;
+  const remote = opts.remote ?? false;
+  process.stdout.write(
+    [
+      "Cline MCP config is managed through the Cline UI in VS Code (the file",
+      "path differs by OS, VS Code variant, and Cline version).",
+      "",
+      "1. Open VS Code (or Cursor / Windsurf running the Cline extension).",
+      "2. Click the Cline icon in the sidebar.",
+      '3. Click "MCP Servers" \u2192 "Configure MCP Servers".',
+      `4. Add this entry under "mcpServers":`,
+      "",
+      JSON.stringify({ mcpServers: { [SERVER_NAME]: mcpEntry(remote) } }, null, 2),
+      "",
+      "5. Save the file. Cline will reload the MCP servers automatically.",
+      "",
+      "Do NOT add your pyx-memory API key here. Run `pyx-mem login` to store it in the OS credential store.",
+      ""
+    ].join("\n")
+  );
+  return EXIT.OK;
+}
+function mcpInstallContinueCommand(opts = {}) {
+  const scope = opts.scope ?? "user";
+  if (!validateScope(scope)) return EXIT.USAGE;
+  const remote = opts.remote ?? false;
+  const home = opts._homeDir ?? homedir();
+  const yamlPath = join(home, ".continue", "mcpServers", `${SERVER_NAME}.yaml`);
+  process.stdout.write(
+    [
+      "Continue uses YAML config. The recommended way to add an MCP server is a",
+      "standalone block file:",
+      "",
+      `  ${yamlPath}`,
+      "",
+      "Create that file with these contents:",
+      "",
+      `name: ${SERVER_NAME}`,
+      "version: 0.0.1",
+      "schema: v1",
+      "mcpServers:",
+      `  - name: ${SERVER_NAME}`,
+      `    command: pyx-mem`,
+      `    args:`,
+      ...pyxMemArgs(remote).map((arg) => `      - ${arg}`),
+      "",
+      "Continue auto-loads new YAML blocks on next chat session \u2014 no restart",
+      "needed in most setups.",
+      "",
+      "Do NOT add your pyx-memory API key here. Run `pyx-mem login` to store it in the OS credential store.",
+      ""
+    ].join("\n")
+  );
+  return EXIT.OK;
+}
+function mcpInstallWindsurfCommand(opts = {}) {
+  const scope = opts.scope ?? "user";
+  if (!validateScope(scope)) return EXIT.USAGE;
+  const home = opts._homeDir ?? homedir();
+  const filePath = join(home, ".codeium", "windsurf", "mcp_config.json");
+  return writeJsonAndReport(filePath, "Windsurf", mcpEntry(opts.remote ?? false));
+}
+function mcpInstallGeminiCliCommand(opts = {}) {
+  const scope = opts.scope ?? "user";
+  if (!validateScope(scope)) return EXIT.USAGE;
+  const remote = opts.remote ?? false;
+  const spawnSync = opts._spawnSync ?? nodeSpawnSync;
+  const home = opts._homeDir ?? homedir();
+  const probe = spawnSync("gemini", ["--version"], { stdio: "pipe" });
+  if (probe.error || probe.status !== 0) {
+    return writeJsonAndReport(geminiConfigPath(home, scope), "Gemini CLI", mcpEntry(remote));
+  }
+  const geminiScope = scope === "local" ? "project" : scope;
+  const cmd = ["mcp", "add", "-s", geminiScope, SERVER_NAME, "pyx-mem", ...pyxMemArgs(remote)];
+  const res = spawnSync("gemini", cmd, { stdio: "inherit" });
+  if (res.status !== 0) {
+    process.stderr.write(`\`gemini ${cmd.join(" ")}\` exited with code ${res.status ?? "null"}.
+`);
+    return writeJsonAndReport(geminiConfigPath(home, scope), "Gemini CLI", mcpEntry(remote));
+  }
+  process.stdout.write(
+    `Installed pyx-memory MCP server in Gemini CLI (scope: ${geminiScope}).
+Restart Gemini CLI to make the tools available. No API key was written to settings.json \u2014 credentials live in the OS credential store.
+`
+  );
+  return EXIT.OK;
+}
+function geminiConfigPath(home, scope) {
+  return scope === "project" ? join(process.cwd(), ".gemini", "settings.json") : join(home, ".gemini", "settings.json");
+}
+function mcpInstallPiCommand(opts = {}) {
+  const scope = opts.scope ?? "user";
+  if (!validateScope(scope)) return EXIT.USAGE;
+  const home = opts._homeDir ?? homedir();
+  const filePath = scope === "user" ? join(home, ".pi", "agent", "mcp.json") : join(process.cwd(), ".pi", "mcp.json");
+  return writeJsonAndReport(filePath, "Pi", mcpEntry(opts.remote ?? false), {
+    prereq: "pi has no native MCP support \u2014 install the third-party adapter once:\n  pi install npm:pi-mcp-adapter"
+  });
+}
+function mcpInstallOhMyPiCommand(opts = {}) {
+  const scope = opts.scope ?? "user";
+  if (!validateScope(scope)) return EXIT.USAGE;
+  const home = opts._homeDir ?? homedir();
+  const filePath = scope === "user" ? join(home, ".omp", "agent", "mcp.json") : join(process.cwd(), ".omp", "mcp.json");
+  return writeJsonAndReport(filePath, "oh-my-pi", mcpEntry(opts.remote ?? false));
+}
+function mcpInstallOpenClawCommand(opts = {}) {
+  const scope = opts.scope ?? "user";
+  if (!validateScope(scope)) return EXIT.USAGE;
+  const remote = opts.remote ?? false;
+  const spawnSync = opts._spawnSync ?? nodeSpawnSync;
+  const probe = spawnSync("openclaw", ["--version"], { stdio: "pipe" });
+  if (probe.error || probe.status !== 0) {
+    printOpenClawManualInstructions(remote);
+    return EXIT.OK;
+  }
+  const entryJson = JSON.stringify(mcpEntry(remote));
+  const cmd = ["mcp", "set", SERVER_NAME, entryJson];
+  const res = spawnSync("openclaw", cmd, { stdio: "inherit" });
+  if (res.status !== 0) {
+    process.stderr.write(
+      `\`openclaw ${cmd.join(" ")}\` exited with code ${res.status ?? "null"}.
+`
+    );
+    printOpenClawManualInstructions(remote);
+    return EXIT.USAGE;
+  }
+  process.stdout.write(
+    `Installed pyx-memory MCP server in OpenClaw.
+Restart OpenClaw to make the tools available. No API key was written to openclaw.json \u2014 credentials live in the OS credential store.
+`
+  );
+  return EXIT.OK;
+}
+function printOpenClawManualInstructions(remote) {
+  const entry = mcpEntry(remote);
+  const entryJson = JSON.stringify(entry);
+  process.stdout.write(
+    [
+      "The `openclaw` CLI is not on PATH, or the install command failed.",
+      "",
+      "Run this once OpenClaw is installed:",
+      `  openclaw mcp set ${SERVER_NAME} '${entryJson}'`,
+      "",
+      "Or add this entry manually under `mcp.servers` in your OpenClaw config",
+      "(run `openclaw config file` to print the active config path):",
+      "",
+      JSON.stringify({ mcp: { servers: { [SERVER_NAME]: entry } } }, null, 2),
+      "",
+      "Do NOT add your pyx-memory API key here. Run `pyx-mem login` to store it in the OS credential store.",
+      ""
+    ].join("\n")
+  );
+}
+function mcpInstallHermesCommand(opts = {}) {
+  const scope = opts.scope ?? "user";
+  if (!validateScope(scope)) return EXIT.USAGE;
+  const remote = opts.remote ?? false;
+  const spawnSync = opts._spawnSync ?? nodeSpawnSync;
+  const probe = spawnSync("hermes", ["--version"], { stdio: "pipe" });
+  if (probe.error || probe.status !== 0) {
+    printHermesManualInstructions(remote);
+    return EXIT.OK;
+  }
+  const cmd = ["mcp", "add", SERVER_NAME, "--command", "pyx-mem", "--args", ...pyxMemArgs(remote)];
+  const res = spawnSync("hermes", cmd, { stdio: "inherit" });
+  if (res.status !== 0) {
+    process.stderr.write(`\`hermes ${cmd.join(" ")}\` exited with code ${res.status ?? "null"}.
+`);
+    printHermesManualInstructions(remote);
+    return EXIT.USAGE;
+  }
+  process.stdout.write(
+    `Installed pyx-memory MCP server in Hermes.
+Restart Hermes to make the tools available. No API key was written to config.yaml \u2014 credentials live in the OS credential store.
+`
+  );
+  return EXIT.OK;
+}
+function printHermesManualInstructions(remote) {
+  process.stdout.write(
+    [
+      "The `hermes` CLI is not on PATH, or the install command failed.",
+      "",
+      "Run this once Hermes is installed:",
+      `  hermes mcp add ${SERVER_NAME} --command pyx-mem --args ${pyxMemArgs(remote).join(" ")}`,
+      "",
+      "Or add this block under `mcp_servers:` in your Hermes config",
+      "(typically ~/.hermes/config.yaml):",
+      "",
+      `${SERVER_NAME}:`,
+      "  command: pyx-mem",
+      "  args:",
+      ...pyxMemArgs(remote).map((arg) => `    - ${arg}`),
+      "",
+      "Do NOT add your pyx-memory API key here. Run `pyx-mem login` to store it in the OS credential store.",
+      ""
+    ].join("\n")
+  );
+}
+var RULES_FILE_TARGETS = {
+  "claude-code": { envDir: "CLAUDE_CONFIG_DIR", dir: [".claude"], file: "CLAUDE.md" },
+  codex: { envDir: "CODEX_HOME", dir: [".codex"], file: "AGENTS.md" },
+  "gemini-cli": { dir: [".gemini"], file: "GEMINI.md" },
+  "oh-my-pi": { dir: [".omp", "agent"], file: "RULES.md" }
+};
+function rulesFilePath(target, opts) {
+  if (!Object.hasOwn(RULES_FILE_TARGETS, target)) return void 0;
+  const spec = RULES_FILE_TARGETS[target];
+  const env = opts._env ?? (opts._homeDir === void 0 ? process.env : {});
+  const configDir = spec.envDir ? env[spec.envDir] : void 0;
+  return configDir ? join(configDir, spec.file) : join(opts._homeDir ?? homedir(), ...spec.dir, spec.file);
+}
+function installMemoryRules(opts) {
+  const filePath = rulesFilePath(opts.target, opts);
+  if (!filePath) return;
+  if (opts.noRules) {
+    process.stdout.write(
+      'Skipped writing the memory rules (--no-rules). The tools are installed, but the agent will reach for memory only when you ask; add the "## Persistent Memory" rules yourself to change that.\n'
+    );
+    return;
+  }
+  const result = writeMemoryRulesFile({ filePath, section: PERSISTENT_MEMORY_SECTION });
+  process.stdout.write(result.message);
+}
+function installMemoryRulesOnly(target, opts = {}) {
+  if (target === void 0 || !rulesFilePath(target, opts)) {
+    process.stderr.write(
+      `Error: \`pyx-mem mcp rules\` needs a host with a known rules file: ${Object.keys(RULES_FILE_TARGETS).join(", ")}.
+`
+    );
+    return EXIT.USAGE;
+  }
+  installMemoryRules({ ...opts, target, noRules: false });
+  return EXIT.OK;
+}
+function reconcileMemoryRules(opts = {}) {
+  const section = opts.section ?? PERSISTENT_MEMORY_SECTION;
+  for (const target of Object.keys(RULES_FILE_TARGETS)) {
+    const filePath = rulesFilePath(target, opts);
+    try {
+      if (!existsSync3(filePath)) continue;
+      const result = writeMemoryRulesFile({ filePath, section, refreshOnly: true });
+      if (result.action !== "unchanged") {
+        process.stderr.write(
+          `pyx-memory: refreshed the "## Persistent Memory" rules in ${filePath}
+`
+        );
+      }
+    } catch {
+    }
+  }
+}
+var MAX_SERVER_RULES_BYTES = 16 * 1024;
+async function syncMemoryRulesFromServer(client, opts = {}) {
+  try {
+    const { tools } = await client.listTools();
+    if (!tools.some((tool) => tool.name === "get_memory_rules")) {
+      reconcileMemoryRules(opts);
+      return;
+    }
+    const result = await client.callTool({ name: "get_memory_rules", arguments: {} });
+    const [first] = result.content ?? [];
+    const section = first?.type === "text" ? first.text : void 0;
+    if (result.isError || !section || !isRulesSection(section)) {
+      throw new Error('the server returned no valid "## Persistent Memory" section');
+    }
+    reconcileMemoryRules({ ...opts, section });
+  } catch (err) {
+    process.stderr.write(
+      `pyx-memory: left the installed memory rules unchanged \u2014 could not fetch current rules (${err instanceof Error ? err.message : String(err)}).
+`
+    );
+  }
+}
+function isRulesSection(text) {
+  return text.startsWith("## Persistent Memory\n") && Buffer.byteLength(text, "utf8") <= MAX_SERVER_RULES_BYTES && !text.includes("<!-- pyx-memory:") && !/^\s*(```|~~~)/m.test(text);
+}
+function validateScope(scope) {
+  if (VALID_SCOPES.has(scope)) return true;
+  process.stderr.write(`Error: invalid --scope \`${scope}\`. Expected: local | user | project.
+`);
+  return false;
+}
+function writeJsonAndReport(filePath, agentLabel, entry, opts = {}) {
+  const result = mergeWriteJsonMcpEntry({
+    filePath,
+    serverName: SERVER_NAME,
+    entry
+  });
+  const stream = result.exitCode === EXIT.OK ? process.stdout : process.stderr;
+  stream.write(result.message);
+  if (result.status === "installed") {
+    process.stdout.write(
+      `Restart ${agentLabel} to make the tools available. No API key was written \u2014 credentials live in the OS credential store.
+`
+    );
+  }
+  if ((result.status === "installed" || result.status === "already-installed") && opts.prereq) {
+    process.stdout.write(`Prerequisite: ${opts.prereq}
+`);
+  }
+  return result.exitCode;
+}
+
+export {
+  mcpInstallClaudeCodeCommand,
+  mcpInstallCodexCommand,
+  mcpInstallCursorCommand,
+  mcpInstallClineCommand,
+  mcpInstallContinueCommand,
+  mcpInstallWindsurfCommand,
+  mcpInstallGeminiCliCommand,
+  mcpInstallPiCommand,
+  mcpInstallOhMyPiCommand,
+  mcpInstallOpenClawCommand,
+  mcpInstallHermesCommand,
+  installMemoryRules,
+  installMemoryRulesOnly,
+  reconcileMemoryRules,
+  syncMemoryRulesFromServer
+};