memax-cli 0.0.1 → 0.1.0-alpha.10

package/src/commands/setup.ts

@@ -0,0 +1,1129 @@
+import chalk from "chalk";
+import {
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  existsSync,
+  chmodSync,
+} from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir, platform } from "node:os";
+import { execSync } from "node:child_process";
+import { apiPost } from "../lib/api.js";
+import { loadConfig } from "../lib/config.js";
+
+// --- Agent definitions ---
+
+interface AgentDef {
+  name: string;
+  id: string;
+  configPath: string; // global MCP config file
+  format: "json-mcpServers" | "json-servers" | "toml";
+  /** Key under which MCP servers live */
+  mcpKey: string;
+  hasHooks: boolean;
+  /** Global instruction file path (e.g. ~/.claude/CLAUDE.md) — null if none */
+  globalInstructionFile: string | null;
+  detect: () => boolean; // is this agent likely installed?
+}
+
+function getAgents(): AgentDef[] {
+  const home = homedir();
+  const cwd = process.cwd();
+
+  return [
+    {
+      name: "Claude Code",
+      id: "claude-code",
+      configPath: join(home, ".claude", "settings.json"),
+      format: "json-mcpServers",
+      mcpKey: "mcpServers",
+      hasHooks: true,
+      globalInstructionFile: join(home, ".claude", "CLAUDE.md"),
+      detect: () =>
+        existsSync(join(home, ".claude")) || commandExists("claude"),
+    },
+    {
+      name: "Cursor",
+      id: "cursor",
+      configPath: join(home, ".cursor", "mcp.json"),
+      format: "json-mcpServers",
+      mcpKey: "mcpServers",
+      hasHooks: false,
+      globalInstructionFile: null, // project-level .cursorrules only
+      detect: () =>
+        existsSync(join(home, ".cursor")) || commandExists("cursor"),
+    },
+    {
+      name: "Windsurf",
+      id: "windsurf",
+      configPath: join(home, ".codeium", "windsurf", "mcp_config.json"),
+      format: "json-mcpServers",
+      mcpKey: "mcpServers",
+      hasHooks: false,
+      globalInstructionFile: null, // project-level .windsurfrules only
+      detect: () =>
+        existsSync(join(home, ".codeium", "windsurf")) ||
+        commandExists("windsurf"),
+    },
+    {
+      name: "Gemini CLI",
+      id: "gemini",
+      configPath: join(home, ".gemini", "settings.json"),
+      format: "json-mcpServers",
+      mcpKey: "mcpServers",
+      hasHooks: true,
+      globalInstructionFile: join(home, ".gemini", "GEMINI.md"),
+      detect: () =>
+        existsSync(join(home, ".gemini")) || commandExists("gemini"),
+    },
+    {
+      name: "GitHub Copilot CLI",
+      id: "copilot",
+      configPath: join(home, ".copilot", "mcp-config.json"),
+      format: "json-mcpServers",
+      mcpKey: "mcpServers",
+      hasHooks: false,
+      globalInstructionFile: null, // uses .github/copilot-instructions.md (project-level)
+      detect: () =>
+        existsSync(join(home, ".copilot")) || commandExists("gh copilot"),
+    },
+    {
+      name: "Copilot (VS Code)",
+      id: "vscode",
+      configPath: join(".vscode", "mcp.json"),
+      format: "json-servers",
+      mcpKey: "servers",
+      hasHooks: false,
+      globalInstructionFile: null,
+      detect: () => existsSync(".vscode") || commandExists("code"),
+    },
+    {
+      name: "Codex CLI",
+      id: "codex",
+      configPath: join(home, ".codex", "config.toml"),
+      format: "toml",
+      mcpKey: "mcp_servers",
+      hasHooks: false,
+      globalInstructionFile: join(home, ".codex", "AGENTS.md"),
+      detect: () => existsSync(join(home, ".codex")) || commandExists("codex"),
+    },
+    {
+      name: "OpenClaw",
+      id: "openclaw",
+      configPath: join(home, ".openclaw", "openclaw.json"),
+      format: "json-mcpServers",
+      mcpKey: "mcp.servers",
+      hasHooks: false,
+      globalInstructionFile: null, // OpenClaw has its own memory system
+      detect: () =>
+        existsSync(join(home, ".openclaw")) || commandExists("openclaw"),
+    },
+    {
+      name: "OpenCode",
+      id: "opencode",
+      configPath: join(cwd, ".opencode", "opencode.jsonc"),
+      format: "json-mcpServers",
+      mcpKey: "mcp",
+      hasHooks: false,
+      globalInstructionFile: null, // project-level only
+      detect: () =>
+        existsSync(join(cwd, ".opencode")) || commandExists("opencode"),
+    },
+  ];
+}
+
+// --- Setup command ---
+
+interface SetupOptions {
+  mcp?: boolean;
+  hooks?: boolean;
+  instructions?: boolean;
+  all?: boolean;
+  local?: boolean;
+  print?: boolean;
+  only?: string;
+  skip?: string;
+}
+
+export async function setupCommand(options: SetupOptions): Promise<void> {
+  const enableMcp = options.all || options.mcp;
+  const enableHooks = options.all || options.hooks;
+  const enableInstructions = options.all || options.instructions;
+
+  if (!enableMcp && !enableHooks && !enableInstructions && !options.print) {
+    printUsage();
+    return;
+  }
+
+  // --print: just output config JSON for manual copy/paste
+  if (options.print) {
+    await printMcpConfigs(options.local ?? false);
+    return;
+  }
+
+  // Remote mode (default): need API key for auth
+  const useRemote = !options.local;
+  let apiKey: string | undefined;
+
+  if (useRemote && enableMcp) {
+    apiKey = await ensureApiKey();
+    if (!apiKey) {
+      console.error(
+        chalk.red(
+          "\n  Could not create API key. Log in first: memax login\n" +
+            "  Or use --local for local MCP server.\n",
+        ),
+      );
+      process.exit(1);
+    }
+  }
+
+  // Local mode: need memax binary
+  let memaxBin: MemaxBin | null = null;
+  if (!useRemote || enableHooks) {
+    memaxBin = resolveMemaxBin();
+    if (!memaxBin && !useRemote) {
+      console.error(
+        chalk.red(
+          "\n  Could not find memax binary.\n  Install globally: npm install -g memax-cli@alpha\n",
+        ),
+      );
+      process.exit(1);
+    }
+  }
+
+  // Filter agents
+  const allAgents = getAgents();
+  const onlySet = options.only
+    ? new Set(options.only.split(",").map((s) => s.trim().toLowerCase()))
+    : null;
+  const skipSet = options.skip
+    ? new Set(options.skip.split(",").map((s) => s.trim().toLowerCase()))
+    : new Set<string>();
+
+  const agents = allAgents.filter((a) => {
+    if (skipSet.has(a.id)) return false;
+    if (onlySet) return onlySet.has(a.id);
+    return a.detect();
+  });
+
+  if (agents.length === 0) {
+    console.log(chalk.yellow("\n  No supported AI agents detected.\n"));
+    console.log(chalk.gray("  Supported agents:"));
+    for (const a of allAgents) {
+      console.log(chalk.gray(`    • ${a.name} (--only ${a.id})`));
+    }
+    console.log(
+      chalk.gray("\n  Use --only to force setup for a specific agent.\n"),
+    );
+    return;
+  }
+
+  console.log(chalk.bold("\n  Memax Setup\n"));
+  if (useRemote) {
+    console.log(chalk.gray("  Mode: remote server (recommended)\n"));
+  } else {
+    console.log(chalk.gray("  Mode: local CLI\n"));
+  }
+
+  const results: { agent: string; changes: string[] }[] = [];
+
+  for (const agent of agents) {
+    const changes: string[] = [];
+
+    // MCP setup
+    if (enableMcp) {
+      try {
+        if (useRemote) {
+          setupMcpRemote(agent, apiKey!);
+        } else {
+          setupMcp(agent, memaxBin!);
+        }
+        changes.push(useRemote ? "MCP server (remote)" : "MCP server (local)");
+      } catch (err) {
+        console.log(
+          chalk.red(
+            `  ✗ ${agent.name}: MCP setup failed — ${(err as Error).message}`,
+          ),
+        );
+      }
+    }
+
+    // Hook setup (only for agents that support it — needs local binary)
+    if (enableHooks && agent.hasHooks && memaxBin) {
+      try {
+        setupHooks(agent, memaxBin);
+        changes.push("Context injection hook");
+      } catch (err) {
+        console.log(
+          chalk.red(
+            `  ✗ ${agent.name}: Hook setup failed — ${(err as Error).message}`,
+          ),
+        );
+      }
+    }
+
+    // Inject memax instructions into agent's global instruction file
+    if (enableInstructions && agent.globalInstructionFile) {
+      try {
+        injectInstructions(agent.globalInstructionFile);
+        changes.push("Instructions injected");
+      } catch (err) {
+        console.log(
+          chalk.red(
+            `  ✗ ${agent.name}: Instruction injection failed — ${(err as Error).message}`,
+          ),
+        );
+      }
+    }
+
+    if (changes.length > 0) {
+      results.push({ agent: agent.name, changes });
+    }
+  }
+
+  // Print summary
+  if (results.length === 0) {
+    console.log(chalk.yellow("  No changes made.\n"));
+    return;
+  }
+
+  console.log(chalk.green("  Configured:\n"));
+  for (const r of results) {
+    console.log(chalk.white(`  ${r.agent}`));
+    for (const c of r.changes) {
+      console.log(chalk.gray(`    ✓ ${c}`));
+    }
+  }
+
+  console.log(chalk.gray("\n  MCP tools available to all configured agents:"));
+  console.log(
+    chalk.gray("    • memax_recall — semantic search your knowledge"),
+  );
+  console.log(chalk.gray("    • memax_push   — save knowledge from sessions"));
+  console.log(chalk.gray("    • memax_get    — read full note by ID"));
+  console.log(chalk.gray("    • memax_search — browse notes by category"));
+
+  if (enableHooks) {
+    const hookAgents = results.filter((r) =>
+      r.changes.includes("Context injection hook"),
+    );
+    if (hookAgents.length > 0) {
+      console.log(
+        chalk.gray(
+          `\n  Hooks installed for: ${hookAgents.map((r) => r.agent).join(", ")}`,
+        ),
+      );
+      console.log(
+        chalk.gray(
+          "  Every prompt gets relevant context injected automatically.",
+        ),
+      );
+    }
+  }
+
+  console.log(
+    chalk.gray("\n  Restart your agents for changes to take effect.\n"),
+  );
+}
+
+export async function teardownCommand(options: {
+  only?: string;
+}): Promise<void> {
+  const allAgents = getAgents();
+  const onlySet = options.only
+    ? new Set(options.only.split(",").map((s) => s.trim().toLowerCase()))
+    : null;
+
+  const agents = onlySet
+    ? allAgents.filter((a) => onlySet.has(a.id))
+    : allAgents;
+
+  let removed = false;
+
+  for (const agent of agents) {
+    try {
+      // Claude Code uses its own CLI
+      if (agent.id === "claude-code") {
+        if (commandExists("claude")) {
+          try {
+            execSync("claude mcp remove memax", { stdio: "pipe" });
+            console.log(chalk.gray(`  Removed MCP from ${agent.name}`));
+            removed = true;
+          } catch {
+            // Not installed
+          }
+        }
+        if (agent.hasHooks && existsSync(agent.configPath)) {
+          if (removeHooks(agent)) removed = true;
+        }
+        if (
+          agent.globalInstructionFile &&
+          removeInstructions(agent.globalInstructionFile)
+        ) {
+          console.log(chalk.gray(`  Removed instructions from ${agent.name}`));
+          removed = true;
+        }
+        continue;
+      }
+
+      if (!existsSync(agent.configPath)) continue;
+
+      if (agent.format === "toml") {
+        if (removeMcpToml(agent)) removed = true;
+      } else {
+        if (removeMcpJson(agent)) removed = true;
+      }
+      if (agent.hasHooks && removeHooks(agent)) removed = true;
+      if (
+        agent.globalInstructionFile &&
+        removeInstructions(agent.globalInstructionFile)
+      ) {
+        console.log(chalk.gray(`  Removed instructions from ${agent.name}`));
+        removed = true;
+      }
+    } catch {
+      // Skip agents we can't clean up
+    }
+  }
+
+  if (!removed) {
+    console.log(chalk.yellow("\n  No Memax integrations found to remove.\n"));
+    return;
+  }
+
+  console.log(
+    chalk.green(
+      "\n  Memax integrations removed.\n  Restart your agents for changes to take effect.\n",
+    ),
+  );
+}
+
+// --- Remote MCP setup ---
+
+async function ensureApiKey(): Promise<string | undefined> {
+  try {
+    const result = await apiPost<{ key: string }>("/v1/auth/api-keys", {
+      name: "mcp-setup",
+      expires_in_days: 0, // no expiry
+    });
+    return result.key;
+  } catch {
+    return undefined;
+  }
+}
+
+function getApiUrl(): string {
+  return loadConfig().api_url;
+}
+
+function setupMcpRemote(agent: AgentDef, apiKey: string): void {
+  const mcpUrl = `${getApiUrl()}/mcp`;
+
+  // Claude Code uses its own CLI
+  if (agent.id === "claude-code") {
+    if (!commandExists("claude")) {
+      throw new Error("claude CLI not found in PATH");
+    }
+    try {
+      execSync("claude mcp remove memax", { stdio: "pipe" });
+    } catch {
+      // Not installed yet
+    }
+    // Claude Code HTTP transport
+    execSync(
+      `claude mcp add memax --transport http ${mcpUrl} --header "Authorization: Bearer ${apiKey}"`,
+      { stdio: "pipe" },
+    );
+    return;
+  }
+
+  // Codex TOML
+  if (agent.format === "toml") {
+    mkdirSync(dirname(agent.configPath), { recursive: true });
+    let content = "";
+    if (existsSync(agent.configPath)) {
+      content = readFileSync(agent.configPath, "utf-8");
+    }
+    content = content.replace(/\[mcp_servers\.memax\][\s\S]*?(?=\n\[|$)/, "");
+    content = content.trim();
+    if (content) content += "\n\n";
+    content += `[mcp_servers.memax]\ntype = "url"\nurl = "${mcpUrl}"\n\n[mcp_servers.memax.headers]\nAuthorization = "Bearer ${apiKey}"\n`;
+    writeFileSync(agent.configPath, content);
+    return;
+  }
+
+  // JSON-based agents
+  mkdirSync(dirname(agent.configPath), { recursive: true });
+  let config: Record<string, unknown> = {};
+  if (existsSync(agent.configPath)) {
+    try {
+      config = JSON.parse(readFileSync(agent.configPath, "utf-8"));
+    } catch {
+      // Start fresh
+    }
+  }
+
+  const servers = (getNestedKey(config, agent.mcpKey) ?? {}) as Record<
+    string,
+    unknown
+  >;
+  // Copilot CLI uses "http", others use "url" or no type field
+  const mcpType = agent.id === "copilot" ? "http" : "url";
+  servers.memax = {
+    type: mcpType,
+    url: mcpUrl,
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+    },
+  };
+  setNestedKey(config, agent.mcpKey, servers);
+  writeFileSync(agent.configPath, JSON.stringify(config, null, 2) + "\n");
+}
+
+async function printMcpConfigs(local: boolean): Promise<void> {
+  const apiUrl = getApiUrl();
+
+  console.log(chalk.bold("\n  Memax MCP Configuration\n"));
+
+  if (local) {
+    const bin = resolveMemaxBin();
+    const cmd = bin ? bin.command : "memax";
+    const args = bin ? [...bin.args, "mcp", "serve"] : ["mcp", "serve"];
+
+    console.log(chalk.gray("  Mode: local (stdio)\n"));
+    console.log(
+      chalk.white("  For most agents (Claude Code, Cursor, Gemini, etc.):\n"),
+    );
+    console.log(
+      JSON.stringify(
+        {
+          mcpServers: {
+            memax: { command: cmd, args },
+          },
+        },
+        null,
+        2,
+      )
+        .split("\n")
+        .map((l) => "  " + l)
+        .join("\n"),
+    );
+  } else {
+    let apiKey: string | undefined;
+    try {
+      apiKey = await ensureApiKey();
+    } catch {
+      // Not logged in
+    }
+
+    const keyDisplay = apiKey ?? "mxk_your_api_key_here";
+    const mcpUrl = `${apiUrl}/mcp`;
+
+    console.log(chalk.gray("  Mode: remote server (recommended)\n"));
+
+    console.log(chalk.white("  For Claude Code:\n"));
+    console.log(
+      chalk.gray(
+        `  claude mcp add memax --transport http ${mcpUrl} --header "Authorization: Bearer ${keyDisplay}"`,
+      ),
+    );
+
+    console.log(chalk.white("\n  For Cursor, Copilot, Gemini, Windsurf:\n"));
+    console.log(
+      JSON.stringify(
+        {
+          mcpServers: {
+            memax: {
+              type: "url",
+              url: mcpUrl,
+              headers: {
+                Authorization: `Bearer ${keyDisplay}`,
+              },
+            },
+          },
+        },
+        null,
+        2,
+      )
+        .split("\n")
+        .map((l) => "  " + l)
+        .join("\n"),
+    );
+
+    console.log(chalk.white("\n  For Codex CLI (~/.codex/config.toml):\n"));
+    console.log(chalk.gray(`  [mcp_servers.memax]`));
+    console.log(chalk.gray(`  type = "url"`));
+    console.log(chalk.gray(`  url = "${mcpUrl}"`));
+    console.log(chalk.gray(`\n  [mcp_servers.memax.headers]`));
+    console.log(chalk.gray(`  Authorization = "Bearer ${keyDisplay}"`));
+
+    if (apiKey) {
+      console.log(chalk.yellow("\n  API key created: mcp-setup"));
+      console.log(chalk.gray("  Manage keys: memax auth list-keys"));
+    } else {
+      console.log(
+        chalk.yellow(
+          "\n  Not logged in — replace mxk_your_api_key_here with a real key.",
+        ),
+      );
+      console.log(
+        chalk.gray("  Run: memax login && memax auth create-key --name mcp"),
+      );
+    }
+  }
+
+  console.log();
+}
+
+// --- Local MCP setup per agent ---
+
+function setupMcp(agent: AgentDef, bin: MemaxBin): void {
+  // Claude Code has its own CLI for MCP management
+  if (agent.id === "claude-code") {
+    setupMcpClaudeCode(bin);
+    return;
+  }
+
+  mkdirSync(dirname(agent.configPath), { recursive: true });
+
+  if (agent.format === "toml") {
+    setupMcpToml(agent, bin);
+    return;
+  }
+
+  // JSON-based agents
+  let config: Record<string, unknown> = {};
+  if (existsSync(agent.configPath)) {
+    try {
+      config = JSON.parse(readFileSync(agent.configPath, "utf-8"));
+    } catch {
+      // Start fresh
+    }
+  }
+
+  const servers = (getNestedKey(config, agent.mcpKey) ?? {}) as Record<
+    string,
+    unknown
+  >;
+  servers.memax = {
+    command: bin.command,
+    args: [...bin.args, "mcp", "serve"],
+  };
+  setNestedKey(config, agent.mcpKey, servers);
+
+  writeFileSync(agent.configPath, JSON.stringify(config, null, 2) + "\n");
+}
+
+function setupMcpClaudeCode(bin: MemaxBin): void {
+  // Claude Code uses its own CLI for MCP — settings.json mcpServers is ignored
+  if (!commandExists("claude")) {
+    throw new Error("claude CLI not found in PATH");
+  }
+
+  // Remove existing first (idempotent)
+  try {
+    execSync("claude mcp remove memax", { stdio: "pipe" });
+  } catch {
+    // Not installed yet — fine
+  }
+
+  // claude mcp add <name> -- <command> [args...]
+  const allArgs = [...bin.args, "mcp", "serve"];
+  const cmd = `claude mcp add memax -- ${bin.command} ${allArgs.join(" ")}`;
+
+  try {
+    execSync(cmd, { stdio: "pipe" });
+  } catch (err) {
+    throw new Error(`claude mcp add failed: ${(err as Error).message}`);
+  }
+}
+
+function setupMcpToml(agent: AgentDef, bin: MemaxBin): void {
+  // Codex uses TOML — append or update the memax section
+  let content = "";
+  if (existsSync(agent.configPath)) {
+    content = readFileSync(agent.configPath, "utf-8");
+  }
+
+  // Remove existing memax section if present
+  content = content.replace(/\[mcp_servers\.memax\][\s\S]*?(?=\n\[|$)/, "");
+
+  const args = [...bin.args, "mcp", "serve"].map((a) => `"${a}"`).join(", ");
+
+  content = content.trim();
+  if (content) content += "\n\n";
+  content += `[mcp_servers.memax]\ncommand = "${bin.command}"\nargs = [${args}]\n`;
+
+  writeFileSync(agent.configPath, content);
+}
+
+// --- Hook setup ---
+
+function setupHooks(agent: AgentDef, bin: MemaxBin): void {
+  if (agent.id === "claude-code") {
+    setupClaudeCodeHooks(agent, bin);
+  } else if (agent.id === "gemini") {
+    setupGeminiHooks(agent, bin);
+  }
+}
+
+function setupClaudeCodeHooks(agent: AgentDef, bin: MemaxBin): void {
+  const hookScript = writeHookScript(bin);
+
+  let config: Record<string, unknown> = {};
+  if (existsSync(agent.configPath)) {
+    try {
+      config = JSON.parse(readFileSync(agent.configPath, "utf-8"));
+    } catch {
+      // Start fresh
+    }
+  }
+
+  const hooks = (config.hooks ?? {}) as Record<string, unknown[]>;
+
+  // Remove existing memax hooks
+  if (hooks["UserPromptSubmit"]) {
+    hooks["UserPromptSubmit"] = (
+      hooks["UserPromptSubmit"] as Array<{
+        hooks?: Array<{ command?: string }>;
+      }>
+    ).filter((h) => !h.hooks?.some((hh) => hh.command?.includes("memax")));
+  }
+
+  hooks["UserPromptSubmit"] = [
+    ...((hooks["UserPromptSubmit"] as unknown[]) ?? []),
+    {
+      matcher: "",
+      hooks: [{ type: "command", command: hookScript, timeout: 30 }],
+    },
+  ];
+
+  // Stop hook: auto-capture session learnings on session end
+  const captureScript = writeCaptureHookScript(bin);
+  if (hooks["Stop"]) {
+    hooks["Stop"] = (
+      hooks["Stop"] as Array<{ hooks?: Array<{ command?: string }> }>
+    ).filter((h) => !h.hooks?.some((hh) => hh.command?.includes("memax")));
+  }
+  hooks["Stop"] = [
+    ...((hooks["Stop"] as unknown[]) ?? []),
+    {
+      matcher: "",
+      hooks: [{ type: "command", command: captureScript, timeout: 60 }],
+    },
+  ];
+
+  config.hooks = hooks;
+  writeFileSync(agent.configPath, JSON.stringify(config, null, 2) + "\n");
+}
+
+function setupGeminiHooks(agent: AgentDef, bin: MemaxBin): void {
+  const hookScript = writeHookScript(bin);
+
+  let config: Record<string, unknown> = {};
+  if (existsSync(agent.configPath)) {
+    try {
+      config = JSON.parse(readFileSync(agent.configPath, "utf-8"));
+    } catch {
+      // Start fresh
+    }
+  }
+
+  const hooks = (config.hooks ?? {}) as Record<string, unknown[]>;
+
+  // Remove existing memax hooks from both old ("Startup") and correct event
+  for (const event of ["Startup", "BeforeAgent"]) {
+    if (hooks[event]) {
+      hooks[event] = (
+        hooks[event] as Array<{ hooks?: Array<{ command?: string }> }>
+      ).filter((h) => !h.hooks?.some((hh) => hh.command?.includes("memax")));
+      if ((hooks[event] as unknown[]).length === 0) delete hooks[event];
+    }
+  }
+
+  // BeforeAgent fires after user submits a prompt — equivalent to Claude Code's PrePromptSubmit
+  hooks["BeforeAgent"] = [
+    ...((hooks["BeforeAgent"] as unknown[]) ?? []),
+    {
+      matcher: "",
+      hooks: [{ type: "command", command: hookScript, timeout: 30 }],
+    },
+  ];
+
+  config.hooks = hooks;
+  writeFileSync(agent.configPath, JSON.stringify(config, null, 2) + "\n");
+}
+
+// --- Teardown helpers ---
+
+function removeMcpJson(agent: AgentDef): boolean {
+  if (!existsSync(agent.configPath)) return false;
+
+  try {
+    const config = JSON.parse(readFileSync(agent.configPath, "utf-8"));
+    const servers = getNestedKey(config, agent.mcpKey);
+    if (!servers?.memax) return false;
+
+    delete servers.memax;
+    if (Object.keys(servers).length === 0)
+      deleteNestedKey(config, agent.mcpKey);
+
+    writeFileSync(agent.configPath, JSON.stringify(config, null, 2) + "\n");
+    console.log(chalk.gray(`  Removed MCP from ${agent.name}`));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function removeMcpToml(agent: AgentDef): boolean {
+  if (!existsSync(agent.configPath)) return false;
+
+  let content = readFileSync(agent.configPath, "utf-8");
+  const before = content;
+  content = content.replace(/\[mcp_servers\.memax\][\s\S]*?(?=\n\[|$)/, "");
+
+  if (content === before) return false;
+
+  writeFileSync(agent.configPath, content.trim() + "\n");
+  console.log(chalk.gray(`  Removed MCP from ${agent.name}`));
+  return true;
+}
+
+function removeHooks(agent: AgentDef): boolean {
+  if (!existsSync(agent.configPath)) return false;
+
+  try {
+    const config = JSON.parse(readFileSync(agent.configPath, "utf-8"));
+    const hooks = config.hooks as Record<string, unknown[]> | undefined;
+    if (!hooks) return false;
+
+    let removed = false;
+    for (const event of Object.keys(hooks)) {
+      const before = (hooks[event] as unknown[]).length;
+      hooks[event] = (
+        hooks[event] as Array<{
+          hooks?: Array<{ command?: string }>;
+          command?: string;
+        }>
+      ).filter(
+        (h) =>
+          !h.command?.includes("memax") &&
+          !h.hooks?.some((hh) => hh.command?.includes("memax")),
+      );
+      if ((hooks[event] as unknown[]).length < before) removed = true;
+      if ((hooks[event] as unknown[]).length === 0) delete hooks[event];
+    }
+
+    if (Object.keys(hooks).length === 0) delete config.hooks;
+    if (removed) {
+      writeFileSync(agent.configPath, JSON.stringify(config, null, 2) + "\n");
+      console.log(chalk.gray(`  Removed hooks from ${agent.name}`));
+    }
+    return removed;
+  } catch {
+    return false;
+  }
+}
+
+// --- Shared helpers ---
+
+interface MemaxBin {
+  command: string;
+  args: string[];
+  shell: string;
+}
+
+function resolveMemaxBin(): MemaxBin | null {
+  // 1. Global install — use absolute path so agents find it without shell PATH
+  if (commandExists("memax")) {
+    try {
+      const which = platform() === "win32" ? "where memax" : "which memax";
+      const absPath = execSync(which, { encoding: "utf-8", stdio: "pipe" })
+        .trim()
+        .split("\n")[0];
+      if (absPath) {
+        return { command: absPath, args: [], shell: absPath };
+      }
+    } catch {
+      // fall through
+    }
+    return { command: "memax", args: [], shell: "memax" };
+  }
+
+  // 2. Local repo build (faster than npx, always up-to-date during dev)
+  const localBuild = join(process.cwd(), "packages", "cli", "dist", "index.js");
+  if (existsSync(localBuild)) {
+    return {
+      command: "node",
+      args: [localBuild],
+      shell: `node ${localBuild}`,
+    };
+  }
+
+  // 3. npx as last resort (slow startup — agents may timeout on first run)
+  try {
+    execSync("npx --yes memax-cli --version", {
+      encoding: "utf-8",
+      timeout: 15000,
+      stdio: "pipe",
+    });
+    return {
+      command: "npx",
+      args: ["-y", "memax-cli"],
+      shell: "npx -y memax-cli",
+    };
+  } catch {
+    // npx failed
+  }
+
+  return null;
+}
+
+function commandExists(cmd: string): boolean {
+  try {
+    const which = platform() === "win32" ? "where" : "which";
+    execSync(`${which} ${cmd}`, { stdio: "pipe" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Nested key helpers for configs like openclaw's "mcp.servers"
+function getNestedKey(
+  obj: Record<string, unknown>,
+  key: string,
+): Record<string, unknown> | undefined {
+  const parts = key.split(".");
+  let current: unknown = obj;
+  for (const part of parts) {
+    if (current == null || typeof current !== "object") return undefined;
+    current = (current as Record<string, unknown>)[part];
+  }
+  return current as Record<string, unknown> | undefined;
+}
+
+function setNestedKey(
+  obj: Record<string, unknown>,
+  key: string,
+  value: unknown,
+): void {
+  const parts = key.split(".");
+  let current: Record<string, unknown> = obj;
+  for (let i = 0; i < parts.length - 1; i++) {
+    if (!(parts[i] in current) || typeof current[parts[i]] !== "object") {
+      current[parts[i]] = {};
+    }
+    current = current[parts[i]] as Record<string, unknown>;
+  }
+  current[parts[parts.length - 1]] = value;
+}
+
+function deleteNestedKey(obj: Record<string, unknown>, key: string): void {
+  const parts = key.split(".");
+  let current: Record<string, unknown> = obj;
+  for (let i = 0; i < parts.length - 1; i++) {
+    if (!(parts[i] in current) || typeof current[parts[i]] !== "object") return;
+    current = current[parts[i]] as Record<string, unknown>;
+  }
+  delete current[parts[parts.length - 1]];
+}
+
+// --- Instruction injection ---
+
+const MEMAX_INSTRUCTION_BLOCK = `
+<!-- memax:start -->
+## Memax — Persistent Memory
+
+You have access to Memax, a persistent cloud knowledge hub shared across all your AI agents.
+Use it proactively — don't wait for the user to ask.
+
+**At session start:** Use memax_recall to check for relevant context about the current project or task.
+**During work:** When you discover important decisions, architecture details, debugging solutions,
+or useful context — use memax_push to save them for future sessions.
+**At session end:** Summarize key decisions, learnings, or context worth remembering and push them.
+
+**What to remember:** Architecture decisions, API conventions, deployment processes, debugging
+solutions, team preferences, project-specific knowledge. If you'd want to know it in a future
+session, push it now.
+
+**What NOT to remember:** Ephemeral task details, file contents (they're in git), obvious things.
+
+Available tools: memax_recall (search), memax_push (save), memax_get (read full note),
+memax_search (browse), memax_forget (delete outdated memories).
+<!-- memax:end -->
+`.trim();
+
+function injectInstructions(filePath: string): void {
+  mkdirSync(dirname(filePath), { recursive: true });
+
+  let content = "";
+  if (existsSync(filePath)) {
+    content = readFileSync(filePath, "utf-8");
+  }
+
+  // Remove existing memax block (idempotent)
+  content = content.replace(
+    /\n?<!-- memax:start -->[\s\S]*?<!-- memax:end -->\n?/,
+    "",
+  );
+
+  // Append the block
+  content = content.trimEnd() + "\n\n" + MEMAX_INSTRUCTION_BLOCK + "\n";
+
+  writeFileSync(filePath, content);
+}
+
+function removeInstructions(filePath: string): boolean {
+  if (!existsSync(filePath)) return false;
+
+  const content = readFileSync(filePath, "utf-8");
+  const cleaned = content.replace(
+    /\n?<!-- memax:start -->[\s\S]*?<!-- memax:end -->\n?/,
+    "",
+  );
+
+  if (cleaned === content) return false;
+
+  writeFileSync(filePath, cleaned.trimEnd() + "\n");
+  return true;
+}
+
+function writeHookScript(bin: MemaxBin): string {
+  const hooksDir = join(homedir(), ".memax", "hooks");
+  mkdirSync(hooksDir, { recursive: true });
+
+  const isWindows = platform() === "win32";
+  const scriptName = isWindows ? "context-inject.cmd" : "context-inject.sh";
+  const scriptPath = join(hooksDir, scriptName);
+
+  if (isWindows) {
+    writeFileSync(scriptPath, WIN_HOOK.replace(/\$MEMAX/g, bin.shell));
+  } else {
+    writeFileSync(scriptPath, UNIX_HOOK.replace(/\$MEMAX/g, bin.shell));
+    chmodSync(scriptPath, 0o755);
+  }
+
+  return scriptPath;
+}
+
+function writeCaptureHookScript(bin: MemaxBin): string {
+  const hooksDir = join(homedir(), ".memax", "hooks");
+  mkdirSync(hooksDir, { recursive: true });
+
+  const isWindows = platform() === "win32";
+  const scriptName = isWindows ? "session-capture.cmd" : "session-capture.sh";
+  const scriptPath = join(hooksDir, scriptName);
+
+  if (isWindows) {
+    writeFileSync(scriptPath, WIN_CAPTURE_HOOK.replace(/\$MEMAX/g, bin.shell));
+  } else {
+    writeFileSync(scriptPath, UNIX_CAPTURE_HOOK.replace(/\$MEMAX/g, bin.shell));
+    chmodSync(scriptPath, 0o755);
+  }
+
+  return scriptPath;
+}
+
+function printUsage(): void {
+  const agents = getAgents();
+  const detected = agents.filter((a) => a.detect());
+
+  console.log(
+    chalk.bold("\n  Memax Setup — Configure AI Agent Integrations\n"),
+  );
+
+  if (detected.length > 0) {
+    console.log(chalk.gray("  Detected agents:"));
+    for (const a of detected) {
+      const hookNote = a.hasHooks ? " (MCP + hooks)" : " (MCP)";
+      console.log(chalk.white(`    • ${a.name}${hookNote}`));
+    }
+    console.log();
+  }
+
+  console.log(chalk.gray("  Usage:\n"));
+  console.log(
+    chalk.gray(
+      "    memax setup --mcp               Remote MCP server for all detected agents",
+    ),
+  );
+  console.log(
+    chalk.gray(
+      "    memax setup --instructions      Inject memax usage instructions into agent configs",
+    ),
+  );
+  console.log(
+    chalk.gray(
+      "    memax setup --all               MCP + hooks + instructions",
+    ),
+  );
+  console.log(
+    chalk.gray(
+      "    memax setup --mcp --local       Use local CLI instead of remote server",
+    ),
+  );
+  console.log(
+    chalk.gray("    memax setup --print        Print MCP config to copy/paste"),
+  );
+  console.log(chalk.gray("    memax setup --mcp --only claude-code,cursor"));
+  console.log(
+    chalk.gray("    memax teardown             Remove all integrations\n"),
+  );
+
+  console.log(chalk.gray("  Supported agents:"));
+  for (const a of agents) {
+    const status = a.detect()
+      ? chalk.green("detected")
+      : chalk.gray("not found");
+    console.log(
+      chalk.gray(`    ${a.id.padEnd(14)} ${a.name.padEnd(20)} ${status}`),
+    );
+  }
+  console.log();
+}
+
+const UNIX_HOOK = `#!/bin/bash
+# Memax context injection — installed by: memax setup --hooks
+set -e
+INPUT=$(cat)
+PROMPT=$(echo "$INPUT" | jq -r '.prompt // empty')
+CWD=$(echo "$INPUT" | jq -r '.cwd // empty')
+if [ -z "$PROMPT" ] || [ \${#PROMPT} -lt 10 ]; then exit 0; fi
+case "$PROMPT" in [Yy]|[Yy]es|[Nn]|[Nn]o|ok|OK|sure|Sure|thanks|Thanks|y|n) exit 0 ;; esac
+if [ -n "$CWD" ]; then cd "$CWD" 2>/dev/null || true; fi
+CONTEXT=$($MEMAX recall "$PROMPT" --hook --limit 5 --max-tokens 3000 2>/dev/null) || exit 0
+if [ -n "$CONTEXT" ] && [ "$CONTEXT" != "<memax-context>" ]; then echo "$CONTEXT"; fi
+exit 0
+`;
+
+const WIN_HOOK = `@echo off
+REM Memax context injection — installed by: memax setup --hooks
+set /p INPUT=
+for /f "tokens=*" %%a in ('echo %INPUT% ^| jq -r ".prompt // empty"') do set PROMPT=%%a
+if "%PROMPT%"=="" exit /b 0
+$MEMAX recall "%PROMPT%" --hook --limit 5 --max-tokens 3000 2>nul
+exit /b 0
+`;
+
+const UNIX_CAPTURE_HOOK = `#!/bin/bash
+# Memax session capture — installed by: memax setup --hooks
+# Fires on session end (Stop hook). Pipes session data to memax capture-session.
+set -e
+INPUT=$(cat)
+SUMMARY=$(echo "$INPUT" | jq -r '.transcript // .summary // empty' 2>/dev/null)
+if [ -z "$SUMMARY" ]; then exit 0; fi
+if [ \${#SUMMARY} -lt 50 ]; then exit 0; fi
+echo "$SUMMARY" | $MEMAX capture-session --agent claude-code 2>/dev/null || true
+exit 0
+`;
+
+const WIN_CAPTURE_HOOK = `@echo off
+REM Memax session capture — installed by: memax setup --hooks
+set /p INPUT=
+$MEMAX capture-session --agent claude-code --summary "%INPUT%" 2>nul
+exit /b 0
+`;