@xmemo/client 0.4.136 → 0.4.138

package/README.md

@@ -1,5 +1,7 @@
 # XMemo CLI
 
+[![smithery badge](https://smithery.ai/badge/xmemo/xmemo)](https://smithery.ai/servers/xmemo/xmemo)
+
 `@xmemo/client` is the privacy-first command line entry point for XMemo client
 setup. It is intentionally small: the npm package contains only the CLI and
 setup helper code needed on a user's machine.
@@ -53,6 +55,8 @@ xmemo mcp config --client generic
 xmemo mcp config --client antigravity
 xmemo mcp add antigravity --write
 xmemo profile status codex
+xmemo profile install gemini
+xmemo profile install antigravity
 xmemo smoke --client codex
 xmemo privacy
 ```
@@ -65,6 +69,9 @@ xmemo privacy
   MCP OAuth flow; it does not write token values into project files.
 - The CLI generates one stable non-secret `XMEMO_AGENT_INSTANCE_ID` per local
   client profile and stores it in user-scoped config outside git.
+- `xmemo setup <client>` can install a marker-scoped XMemo memory behavior
+  profile for the selected agent. The profile contains instructions only; it
+  never embeds token values.
 - `xmemo login` stores the issued credential in the user-scoped XMemo CLI
   config directory, shows the approved account when the server provides it,
   and does not require extra token configuration afterward.
@@ -166,10 +173,27 @@ also include stable non-secret agent identity headers where the client format
 supports them. `--yes` remains accepted for Codex and Cursor as a compatibility
 no-op.
 
-`xmemo setup codex` is the recommended Codex path. It writes the Codex MCP
-config and installs the profile into the current project's `AGENTS.md` marker
-block. Use `--dry-run` to preview, `--profile-target <path>` to choose a
-different project instruction file, or `--no-profile` to configure MCP only.
+After writing MCP config, `xmemo setup <client>` prompts:
+
+```text
+Write XMemo memory behavior profile to <path>? [Y/n]
+```
+
+The default is `Y`, so pressing Enter writes a marker-scoped profile that nudges
+the agent to recall/search XMemo at the start of non-trivial work and remember
+high-signal decisions after meaningful changes. Use `n` or `--no-profile` to
+configure MCP only. Use `--dry-run` to preview without writing config or profile
+files, and `--profile-target <path>` to choose a different behavior profile
+target.
+
+Default behavior profile targets:
+
+```text
+codex       ./AGENTS.md
+cursor      ~/.cursor/memory-profile.md
+gemini      ~/.gemini/GEMINI.md
+antigravity ~/.gemini/antigravity/MEMORY.md
+```
 
 ## MCP setup
 
@@ -213,7 +237,7 @@ xmemo setup copilot
 xmemo mcp proxy
 ```
 
-`xmemo setup copilot` writes `memory-os` to Copilot CLI's user MCP config and
+`xmemo setup copilot` writes `XMemo` to Copilot CLI's user MCP config and
 does not include token or identity headers. Use `xmemo setup copilot --dry-run`
 to preview without writing. `xmemo mcp proxy` reads the token saved by
 `xmemo login` or `xmemo token add --from-stdin`, adds the XMemo bearer token and
@@ -235,9 +259,10 @@ xmemo setup codex
 xmemo smoke --client codex
 ```
 
-`setup codex` writes the MCP config to user-scoped Codex config and installs the
-XMemo Codex behavior profile into the current project's `AGENTS.md` between
-these markers. Use `xmemo setup codex --dry-run` to preview without writing.
+`setup codex` writes the MCP config to user-scoped Codex config and, by default,
+installs the XMemo Codex behavior profile into the current project's `AGENTS.md`
+between these markers. Use `xmemo setup codex --dry-run` to preview without
+writing or `xmemo setup codex --no-profile` to skip the behavior profile.
 
 ```html
 <!-- memory-os:codex-profile:start -->
@@ -262,9 +287,9 @@ Write it to the default Codex config path:
 xmemo mcp add codex --url "$XMEMO_URL" --write
 ```
 
-The generated config references `XMEMO_KEY` and does not include the token
-value. Codex custom identity headers are not written until the CLI format is
-verified to support them.
+The generated config references `XMEMO_KEY`, includes the non-secret
+`X-Memory-OS-Agent-ID` / `X-Memory-OS-Agent-Instance-ID` attribution headers,
+and does not include the token value.
 
 Codex MCP-depth checks:
 
@@ -279,7 +304,7 @@ xmemo smoke --client codex
 `xmemo mcp profile codex` prints the recommended memory behavior profile:
 recall/search at the start of non-trivial tasks, write back high-signal
 decisions and fixes, and never store secrets. `xmemo smoke --client codex`
-checks the local Codex TOML config for the `memory_os` MCP server,
+checks the local Codex TOML config for the `XMemo` MCP server,
 `bearer_token_env_var = "XMEMO_KEY"`, token presence in the environment, and
 absence of embedded token values.
 
@@ -299,10 +324,13 @@ lower-level equivalent remains:
 xmemo mcp add cursor --url "$XMEMO_URL" --write
 ```
 
-The CLI refuses to overwrite an existing `memory_os` MCP server entry. Edit the
-config manually if you need to rotate the endpoint. Cursor configs include
+The CLI refuses to overwrite an existing `XMemo`, `memory_os`, or `memory-os`
+MCP server entry. Edit the config manually if you need to rotate the endpoint.
+Cursor configs include
 `X-Memory-OS-Agent-ID` and `X-Memory-OS-Agent-Instance-ID`; the instance ID is
-non-secret and stored under the user's XMemo CLI config directory.
+non-secret and stored under the user's XMemo CLI config directory. By default,
+the setup prompt also installs a Cursor behavior profile at
+`~/.cursor/memory-profile.md`; answer `n` or pass `--no-profile` to skip it.
 
 ### Gemini CLI
 
@@ -323,10 +351,12 @@ This is deliberate — Gemini redacts environment variables matching
 `*KEY*`/`*TOKEN*`/`*AUTH*` during header expansion, so an `${XMEMO_KEY}`
 reference would not survive. OAuth avoids storing any secret in the config and
 still grants the full XMemo tool profile. After setup, restart Gemini CLI and
-run `/mcp` (or the first XMemo tool call) to complete the OAuth login.
+run `/mcp` (or the first XMemo tool call) to complete the OAuth login. By
+default, the setup prompt also installs a Gemini behavior profile at
+`~/.gemini/GEMINI.md`; answer `n` or pass `--no-profile` to skip it.
 
-The CLI refuses to overwrite an existing `memory_os` MCP server entry. Edit the
-config manually if you need to rotate the endpoint.
+The CLI refuses to overwrite an existing `XMemo`, `memory_os`, or `memory-os`
+MCP server entry. Edit the config manually if you need to rotate the endpoint.
 
 ### Antigravity
 
@@ -341,6 +371,8 @@ at `~/.gemini/antigravity/mcp_config.json`. It writes Antigravity's
 `serverUrl` shape plus `X-Memory-OS-Agent-ID` and
 `X-Memory-OS-Agent-Instance-ID` headers. Like Gemini CLI, the config carries
 **no token**: restart Antigravity and complete the MCP OAuth flow on first use.
+By default, the setup prompt also installs an Antigravity behavior profile at
+`~/.gemini/antigravity/MEMORY.md`; answer `n` or pass `--no-profile` to skip it.
 
 The lower-level equivalent is:
 
@@ -352,8 +384,8 @@ Use `xmemo setup antigravity` for normal installs because it performs discovery
 and chooses the recommended Antigravity path automatically. Use
 `xmemo mcp add antigravity --write` when you want the generic MCP writer
 directly, for example with `--url` or `--config` in advanced/multi-client setup.
-The CLI refuses to overwrite an existing `memory_os` MCP server entry. Edit the
-config manually if you need to rotate the endpoint.
+The CLI refuses to overwrite an existing `XMemo`, `memory_os`, or `memory-os`
+MCP server entry. Edit the config manually if you need to rotate the endpoint.
 
 ## Release model
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmemo/client",
-  "version": "0.4.136",
+  "version": "0.4.138",
   "description": "Privacy-first CLI and MCP setup helper for XMemo.",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -10,7 +10,7 @@ const PACKAGE_NAME = '@xmemo/client';
 const FALLBACK_PACKAGE_NAME = '@yonro/xmemo-client';
 const COMMAND_NAME = 'xmemo';
 const LEGACY_COMMAND_NAME = 'memory-os';
-const CLI_VERSION = '0.4.136';
+const CLI_VERSION = '0.4.138';
 const DEFAULT_SERVICE_URL = 'https://xmemo.dev';
 const TOKEN_ENV_VAR = 'XMEMO_KEY';
 const LEGACY_TOKEN_ENV_VAR = 'MEMORY_OS_MCP_TOKEN';
@@ -18,10 +18,19 @@ const AGENT_ID_ENV_VAR = 'XMEMO_AGENT_ID';
 const AGENT_INSTANCE_ENV_VAR = 'XMEMO_AGENT_INSTANCE_ID';
 const AGENT_ID_HEADER = 'X-Memory-OS-Agent-ID';
 const AGENT_INSTANCE_HEADER = 'X-Memory-OS-Agent-Instance-ID';
-const MCP_SERVER_NAME = 'memory_os';
+const MCP_SERVER_NAME = 'XMemo';
+const LEGACY_MCP_SERVER_NAMES = ['memory_os', 'memory-os'];
 const CODEX_PROFILE_TARGET = 'AGENTS.md';
 const CODEX_PROFILE_MARKER_START = '<!-- memory-os:codex-profile:start -->';
 const CODEX_PROFILE_MARKER_END = '<!-- memory-os:codex-profile:end -->';
+const CLIENT_PROFILE_TARGETS = {
+  cursor: '.cursor/rules/xmemo-memory.md',
+  'gemini-cli': 'GEMINI.md',
+  antigravity: 'GEMINI.md'
+};
+const CLIENT_PROFILE_MARKER_START = '<!-- xmemo:profile:start -->';
+const CLIENT_PROFILE_MARKER_END = '<!-- xmemo:profile:end -->';
+const PROFILE_MARKER_PREFIX = 'memory-os:memory-profile';
 const DEVICE_LOGIN_START_PATH = '/api/v1/auth/device/start';
 const DEVICE_LOGIN_TOKEN_PATH = '/api/v1/auth/device/token';
 const DEFAULT_PROXY_HOST = '127.0.0.1';
@@ -174,7 +183,7 @@ function writeHelp(io) {
   writeLine(io.stdout, `  ${COMMAND_NAME} update [--dry-run] [--json]`);
   writeLine(io.stdout, `  ${COMMAND_NAME} doctor [--base-url <https://api.example.com>] [--json]`);
   writeLine(io.stdout, `  ${COMMAND_NAME} discovery show [--base-url <https://api.example.com>] [--json]`);
-  writeLine(io.stdout, `  ${COMMAND_NAME} setup <codex|cursor|copilot|gemini|antigravity> [--url <https://api.example.com>] [--dry-run] [--json]`);
+  writeLine(io.stdout, `  ${COMMAND_NAME} setup <codex|cursor|copilot|gemini|antigravity> [--url <https://api.example.com>] [--dry-run] [--no-profile] [--json]`);
   writeLine(io.stdout, `  ${COMMAND_NAME} login [--from-stdin] [--base-url <url>] [--timeout-ms <ms>] [--http-timeout-ms <ms>] [--json]`);
   writeLine(io.stdout, `  ${COMMAND_NAME} auth status [--verify] [--base-url <url>] [--json]`);
   writeLine(io.stdout, `  ${COMMAND_NAME} status [--url <https://api.example.com>] [--json]`);
@@ -182,11 +191,11 @@ function writeHelp(io) {
   writeLine(io.stdout, `  ${COMMAND_NAME} token add --from-stdin`);
   writeLine(io.stdout, `  ${COMMAND_NAME} token set --from-stdin [--allow-plaintext]`);
   writeLine(io.stdout, `  ${COMMAND_NAME} mcp list`);
-  writeLine(io.stdout, `  ${COMMAND_NAME} mcp config --client <codex|cursor|copilot-cli|antigravity|generic> [--base-url <url>] [--json]`);
+  writeLine(io.stdout, `  ${COMMAND_NAME} mcp config --client <codex|cursor|copilot-cli|gemini-cli|antigravity|generic> [--base-url <url>] [--json]`);
   writeLine(io.stdout, `  ${COMMAND_NAME} mcp proxy [--port ${DEFAULT_PROXY_PORT}]`);
   writeLine(io.stdout, `  ${COMMAND_NAME} mcp profile codex [--json]`);
-  writeLine(io.stdout, `  ${COMMAND_NAME} profile install codex [--target AGENTS.md] [--dry-run|--json]`);
-  writeLine(io.stdout, `  ${COMMAND_NAME} profile uninstall codex [--target AGENTS.md] [--json]`);
+  writeLine(io.stdout, `  ${COMMAND_NAME} profile install <codex|cursor|gemini|antigravity> [--target <path>] [--dry-run|--json]`);
+  writeLine(io.stdout, `  ${COMMAND_NAME} profile uninstall <codex|cursor|gemini|antigravity> [--target <path>] [--json]`);
   writeLine(io.stdout, `  ${COMMAND_NAME} mcp add <${supportedMcpClientIds().join('|')}> [--url <https://api.example.com>] [--write] [--config <path>]`);
   writeLine(io.stdout, `  ${COMMAND_NAME} smoke --client codex [--config <path>] [--json]`);
   writeLine(io.stdout, `  ${COMMAND_NAME} env example [--shell bash|powershell|cmd] [--json]`);
@@ -388,10 +397,6 @@ async function setupCommand(args, io) {
   const dryRun = hasFlag(optionArgs, '--dry-run') || hasFlag(optionArgs, '--preview');
   const writeConfig = !dryRun && (hasFlag(optionArgs, '--write') || hasFlag(optionArgs, '--yes') || shortClientSetup);
   const timeoutMs = parsePositiveInteger(optionValue(optionArgs, '--timeout-ms') ?? '5000', '--timeout-ms');
-  const installProfile = shortClientSetup
-    && clientId === 'codex'
-    && writeConfig
-    && !hasFlag(optionArgs, '--no-profile');
 
   if (writeConfig && !clientId) {
     throw new UsageError(`Setup --write requires --client <${supportedSetupClientIds().join('|')}> so the CLI never writes broad config implicitly.`);
@@ -428,12 +433,32 @@ async function setupCommand(args, io) {
         setupPlan.selectedClient.written = true;
       }
 
-      if (clientId === 'codex' && shortClientSetup) {
+      if (shortClientSetup && profileClientConfig(clientId)) {
         const profileTarget = optionValue(optionArgs, '--profile-target')
           ?? optionValue(optionArgs, '--target')
-          ?? defaultCodexProfileTarget();
-        const profileResult = await codexProfileInstallResult(profileTarget, { write: installProfile });
-        setupPlan.selectedClient.codexProfile = profileResult;
+          ?? defaultProfileTarget(clientId, io.env);
+        let installProfile = false;
+        let prompted = false;
+        let skipped = false;
+        if (hasFlag(optionArgs, '--no-profile')) {
+          skipped = true;
+        } else if (dryRun) {
+          installProfile = false;
+        } else if (writeConfig) {
+          installProfile = outputJson || hasFlag(optionArgs, '--yes') || hasFlag(optionArgs, '--profile');
+          if (!installProfile && !outputJson) {
+            prompted = true;
+            installProfile = await confirmProfileInstall(clientId, profileTarget, io);
+          }
+        }
+        const profileResult = await profileInstallResult(clientId, profileTarget, { write: installProfile });
+        profileResult.prompted = prompted;
+        profileResult.accepted = installProfile;
+        profileResult.skipped = skipped;
+        setupPlan.selectedClient.behaviorProfile = profileResult;
+        if (clientId === 'codex') {
+          setupPlan.selectedClient.codexProfile = profileResult;
+        }
       }
     }
   }
@@ -451,30 +476,30 @@ async function profileCommand(args, io) {
   const subcommand = args[0] ?? 'help';
   if (subcommand === 'help' || subcommand === '--help' || subcommand === '-h') {
     writeLine(io.stdout, 'Profile commands:');
-    writeLine(io.stdout, `  ${COMMAND_NAME} profile install codex [--target AGENTS.md] [--dry-run|--json]`);
-    writeLine(io.stdout, `  ${COMMAND_NAME} profile status codex [--target AGENTS.md] [--json]`);
-    writeLine(io.stdout, `  ${COMMAND_NAME} profile uninstall codex [--target AGENTS.md] [--json]`);
+    writeLine(io.stdout, `  ${COMMAND_NAME} profile install <codex|cursor|gemini|antigravity> [--target <path>] [--dry-run|--json]`);
+    writeLine(io.stdout, `  ${COMMAND_NAME} profile status <codex|cursor|gemini|antigravity> [--target <path>] [--json]`);
+    writeLine(io.stdout, `  ${COMMAND_NAME} profile uninstall <codex|cursor|gemini|antigravity> [--target <path>] [--json]`);
     writeLine(io.stdout, '');
     writeLine(io.stdout, 'Profile installs are marker-scoped and never write token values.');
     return 0;
   }
 
-  const clientId = args[1];
-  if (clientId !== 'codex') {
-    throw new UsageError(`Unsupported profile client: ${clientId ?? 'missing'}. Supported clients: codex.`);
+  const clientId = normalizeSetupClientId(args[1]);
+  if (!profileClientConfig(clientId)) {
+    throw new UsageError(`Unsupported profile client: ${args[1] ?? 'missing'}. Supported clients: ${supportedProfileClientIds().join(', ')}.`);
   }
 
   const optionArgs = args.slice(2);
   const outputJson = hasFlag(optionArgs, '--json');
-  const targetPath = optionValue(optionArgs, '--target') ?? defaultCodexProfileTarget();
+  const targetPath = optionValue(optionArgs, '--target') ?? defaultProfileTarget(clientId, io.env);
   let result;
 
   if (subcommand === 'install') {
-    result = await codexProfileInstallResult(targetPath, { write: !hasFlag(optionArgs, '--dry-run') });
+    result = await profileInstallResult(clientId, targetPath, { write: !hasFlag(optionArgs, '--dry-run') });
   } else if (subcommand === 'status') {
-    result = await codexProfileStatusResult(targetPath);
+    result = await profileStatusResult(clientId, targetPath);
   } else if (subcommand === 'uninstall') {
-    result = await codexProfileUninstallResult(targetPath, { write: !hasFlag(optionArgs, '--dry-run') });
+    result = await profileUninstallResult(clientId, targetPath, { write: !hasFlag(optionArgs, '--dry-run') });
   } else {
     throw new UsageError(`Unknown profile command: ${subcommand}`);
   }
@@ -755,6 +780,15 @@ async function mcpCommand(args, io) {
     } else {
       writeLine(io.stdout, JSON.stringify(template.snippet, null, 2));
     }
+    if (template.optionalEnv?.includes(AGENT_INSTANCE_ENV_VAR)) {
+      writeLine(io.stdout, '');
+      writeLine(io.stdout, `${AGENT_INSTANCE_ENV_VAR} must be stable per local client install.`);
+      if (template.agentInstanceGeneration?.automaticCommand) {
+        writeLine(io.stdout, `Use ${template.agentInstanceGeneration.automaticCommand} to generate and persist it, or set it to a unique value such as xmemo-${clientId}-<uuid>.`);
+      } else {
+        writeLine(io.stdout, `Set it to a unique value such as xmemo-${clientId}-<uuid> and persist it outside git.`);
+      }
+    }
     writeLine(io.stdout, 'Review the template before applying it. Token values are not included.');
     return 0;
   }
@@ -805,6 +839,7 @@ async function mcpCommand(args, io) {
       agentId: identity.agentId,
       agentInstanceId: identity.agentInstanceId,
       agentInstanceIdPath: identity.path,
+      agentInstanceGeneration: agentInstanceGenerationPolicy(target),
       writesTokenValue: false
     }, null, 2));
     return 0;
@@ -833,6 +868,7 @@ async function mcpCommand(args, io) {
   } else {
     writeLine(io.stdout, `Set ${TOKEN_ENV_VAR} in your user environment or secret manager. The token value is not included here.`);
   }
+  writeLine(io.stdout, `${AGENT_INSTANCE_ENV_VAR} must be stable per local ${client.label} install; run ${COMMAND_NAME} mcp add ${target} --write to generate it automatically.`);
   return 0;
 }
 
@@ -1365,10 +1401,15 @@ function mcpConfigTemplate(clientId, mcpUrl) {
         agentInstanceEnvVar: AGENT_INSTANCE_ENV_VAR,
         agentInstanceHeader: AGENT_INSTANCE_HEADER
       },
+      agentInstanceGeneration: agentInstanceGenerationPolicy(clientId),
       writesTokenValue: false
     };
   }
 
+  if (clientId === 'cursor') {
+    return bearerJsonMcpTemplate(clientId, mcpUrl, cursorJsonConfig(mcpUrl));
+  }
+
   if (clientId === 'gemini-cli') {
     return oauthJsonMcpTemplate(clientId, mcpUrl, geminiJsonConfig(mcpUrl));
   }
@@ -1377,14 +1418,13 @@ function mcpConfigTemplate(clientId, mcpUrl) {
     return oauthJsonMcpTemplate(clientId, mcpUrl, antigravityJsonConfig(mcpUrl));
   }
 
-  const serverName = clientId === 'cursor' || clientId === 'gemini-cli' || clientId === 'antigravity' ? 'memory_os' : 'memory-os';
   return {
     client: clientId,
-    serverName,
+    serverName: MCP_SERVER_NAME,
     snippetFormat: 'json',
     snippet: {
       mcpServers: {
-        [serverName]: {
+        [MCP_SERVER_NAME]: {
           type: 'http',
           url: mcpUrl,
           headers: {
@@ -1403,6 +1443,28 @@ function mcpConfigTemplate(clientId, mcpUrl) {
       agentInstanceEnvVar: AGENT_INSTANCE_ENV_VAR,
       agentInstanceHeader: AGENT_INSTANCE_HEADER
     },
+    agentInstanceGeneration: agentInstanceGenerationPolicy(clientId),
+    writesTokenValue: false
+  };
+}
+
+function bearerJsonMcpTemplate(clientId, mcpUrl, snippet) {
+  return {
+    client: clientId,
+    serverName: MCP_SERVER_NAME,
+    snippetFormat: 'json',
+    snippet,
+    requiresEnv: [TOKEN_ENV_VAR],
+    optionalEnv: [AGENT_INSTANCE_ENV_VAR],
+    authentication: 'env-bearer',
+    agentIdentity: {
+      agentId: clientId,
+      agentIdHeader: AGENT_ID_HEADER,
+      agentInstanceEnvVar: AGENT_INSTANCE_ENV_VAR,
+      agentInstanceHeader: AGENT_INSTANCE_HEADER
+    },
+    agentInstanceGeneration: agentInstanceGenerationPolicy(clientId),
+    mcpUrl,
     writesTokenValue: false
   };
 }
@@ -1422,20 +1484,20 @@ function oauthJsonMcpTemplate(clientId, mcpUrl, snippet) {
       agentInstanceEnvVar: AGENT_INSTANCE_ENV_VAR,
       agentInstanceHeader: AGENT_INSTANCE_HEADER
     },
+    agentInstanceGeneration: agentInstanceGenerationPolicy(clientId),
     mcpUrl,
     writesTokenValue: false
   };
 }
 
 function mcpLocalProxyTemplate(clientId, proxyUrl) {
-  const serverName = clientId === 'cursor' || clientId === 'gemini-cli' || clientId === 'antigravity' ? 'memory_os' : 'memory-os';
   return {
     client: clientId,
-    serverName,
+    serverName: MCP_SERVER_NAME,
     snippetFormat: 'json',
     snippet: {
       mcpServers: {
-        [serverName]: {
+        [MCP_SERVER_NAME]: {
           type: 'http',
           url: proxyUrl
         }
@@ -1449,10 +1511,27 @@ function mcpLocalProxyTemplate(clientId, proxyUrl) {
       agentInstanceEnvVar: AGENT_INSTANCE_ENV_VAR,
       agentInstanceHeader: AGENT_INSTANCE_HEADER
     },
+    agentInstanceGeneration: agentInstanceGenerationPolicy(clientId),
     writesTokenValue: false
   };
 }
 
+function agentInstanceGenerationPolicy(clientId) {
+  const automaticCommand = MCP_CLIENTS.has(clientId)
+    ? `${COMMAND_NAME} mcp add ${clientId} --write`
+    : clientId === 'copilot-cli'
+      ? `${COMMAND_NAME} setup copilot --write`
+      : null;
+  return {
+    requiredForHeaders: true,
+    stablePerInstall: true,
+    automaticCommand,
+    generatedPattern: `xmemo-${clientId}-<uuid>`,
+    storagePath: `~/.config/xmemo/agent-instances/${clientId}.json`,
+    manualEnvVar: AGENT_INSTANCE_ENV_VAR
+  };
+}
+
 function sameMajorMinor(left, right) {
   const leftParts = left.split('.');
   const rightParts = right.split('.');
@@ -1549,13 +1628,15 @@ function writeSetupSummary(plan, io) {
       }
       return;
     }
-    if (plan.selectedClient.codexProfile) {
-      const profile = plan.selectedClient.codexProfile;
-      writeLine(io.stdout, `  Codex profile target: ${profile.targetPath}`);
-      writeLine(io.stdout, `  Codex profile installed: ${profile.written}`);
-      writeLine(io.stdout, `  Codex profile changed: ${profile.changed}`);
+    if (plan.selectedClient.behaviorProfile) {
+      const profile = plan.selectedClient.behaviorProfile;
+      const profileClient = profileClientConfig(profile.client);
+      writeLine(io.stdout, `  Behavior profile target: ${profile.targetPath}`);
+      writeLine(io.stdout, `  Behavior profile client: ${profileClient?.label ?? profile.client}`);
+      writeLine(io.stdout, `  Behavior profile installed: ${profile.written}`);
+      writeLine(io.stdout, `  Behavior profile changed: ${profile.changed}`);
       if (!profile.written) {
-        writeLine(io.stdout, `  Profile preview: ${COMMAND_NAME} profile install codex --target ${profile.targetPath}`);
+        writeLine(io.stdout, `  Profile preview: ${COMMAND_NAME} profile install ${profile.client} --target ${profile.targetPath}`);
       }
     }
     if (!plan.selectedClient.written) {
@@ -1618,23 +1699,7 @@ bearer_token_env_var = "${TOKEN_ENV_VAR}"
 }
 
 function codexMemoryProfile() {
-  return {
-    client: 'codex',
-    profileVersion: 'codex-mcp-depth-v1',
-    mcpServerName: MCP_SERVER_NAME,
-    requiredTokenEnv: TOKEN_ENV_VAR,
-    objective: 'Use XMemo deliberately through MCP for project context recall and high-signal write-back.',
-    instructions: [
-      'At the start of a non-trivial task, call XMemo recall/search for relevant project decisions, conventions, prior fixes, and active context unless the user explicitly asks not to use memory.',
-      'Use recalled memories as evidence, not as unquestioned truth. Prefer current repository files when memory conflicts with code.',
-      'After meaningful decisions, bug fixes, release steps, or durable conventions, write a concise XMemo memory with scope, source, and no secret values.',
-      'Never store tokens, API keys, cookies, private keys, raw credentials, or sensitive customer data in XMemo.',
-      'For routine or low-signal output, skip durable writes. Prefer summarized procedural or semantic memories over verbose logs.',
-      'Keep XMemo authentication through the XMEMO_KEY environment variable; do not paste token values into prompts, config files, or logs.'
-    ],
-    setupCommand: `${COMMAND_NAME} setup codex --url "$XMEMO_URL"`,
-    smokeCommand: `${COMMAND_NAME} smoke --client codex`
-  };
+  return memoryBehaviorProfile('codex');
 }
 
 function writeCodexMemoryProfile(profile, io) {
@@ -1653,17 +1718,51 @@ function writeCodexMemoryProfile(profile, io) {
 }
 
 function codexProfileInstructionText() {
-  const profile = codexMemoryProfile();
+  return profileInstructionText('codex');
+}
+
+function memoryBehaviorProfile(clientId) {
+  const config = profileClientConfig(clientId);
+  if (!config) {
+    throw new UsageError(`Unsupported profile client: ${clientId}`);
+  }
+  const instructions = [
+    'At the start of a non-trivial task, call XMemo recall/search for relevant project decisions, conventions, prior fixes, and active context unless the user explicitly asks not to use memory.',
+    'Use recalled memories as evidence, not as unquestioned truth. Prefer current repository files when memory conflicts with code.',
+    'After meaningful decisions, bug fixes, release steps, or durable conventions, write a concise XMemo memory with scope, source, and no secret values.',
+    'Never store tokens, API keys, cookies, private keys, raw credentials, or sensitive customer data in XMemo.',
+    'For routine or low-signal output, skip durable writes. Prefer summarized procedural or semantic memories over verbose logs.',
+    config.authInstruction
+  ];
+  return {
+    client: clientId,
+    label: config.label,
+    profileVersion: config.profileVersion,
+    mcpServerName: MCP_SERVER_NAME,
+    requiredTokenEnv: config.requiredTokenEnv ?? null,
+    objective: 'Use XMemo deliberately through MCP for project context recall and high-signal write-back.',
+    instructions,
+    setupCommand: `${COMMAND_NAME} setup ${config.setupAlias} --url "$XMEMO_URL"`,
+    smokeCommand: clientId === 'codex' ? `${COMMAND_NAME} smoke --client codex` : null
+  };
+}
+
+function profileInstructionText(clientId) {
+  const profile = memoryBehaviorProfile(clientId);
   const lines = [
-    '## XMemo Codex profile',
+    `## XMemo ${profile.label} profile`,
     '',
     `MCP server: \`${profile.mcpServerName}\``,
-    `Token env var: \`${profile.requiredTokenEnv}\``,
+  ];
+  if (profile.requiredTokenEnv) {
+    lines.push(`Token env var: \`${profile.requiredTokenEnv}\``);
+  }
+  lines.push(
     '',
     profile.objective,
     '',
-    'Recommended Codex behavior:'
-  ];
+    `Recommended ${profile.label} behavior:`
+  );
   for (const instruction of profile.instructions) {
     lines.push(`- ${instruction}`);
   }
@@ -1671,6 +1770,228 @@ function codexProfileInstructionText() {
   return `${lines.join('\n')}\n`;
 }
 
+function profileClientConfig(clientId) {
+  const profileConfigs = {
+    codex: {
+      label: 'Codex',
+      setupAlias: 'codex',
+      profileVersion: 'codex-mcp-depth-v1',
+      requiredTokenEnv: TOKEN_ENV_VAR,
+      markerStart: CODEX_PROFILE_MARKER_START,
+      markerEnd: CODEX_PROFILE_MARKER_END,
+      defaultTarget: (env) => defaultCodexProfileTarget(env),
+      authInstruction: `Keep XMemo authentication through the ${TOKEN_ENV_VAR} environment variable; do not paste token values into prompts, config files, or logs.`
+    },
+    cursor: {
+      label: 'Cursor',
+      setupAlias: 'cursor',
+      profileVersion: 'cursor-mcp-depth-v1',
+      requiredTokenEnv: TOKEN_ENV_VAR,
+      markerStart: `<!-- ${PROFILE_MARKER_PREFIX}:cursor:start -->`,
+      markerEnd: `<!-- ${PROFILE_MARKER_PREFIX}:cursor:end -->`,
+      defaultTarget: (env) => path.join(userHome(env), '.cursor', 'memory-profile.md'),
+      authInstruction: `Keep XMemo authentication through the ${TOKEN_ENV_VAR} environment variable; do not paste token values into prompts, config files, or logs.`
+    },
+    'gemini-cli': {
+      label: 'Gemini CLI',
+      setupAlias: 'gemini',
+      profileVersion: 'gemini-cli-mcp-depth-v1',
+      markerStart: `<!-- ${PROFILE_MARKER_PREFIX}:gemini-cli:start -->`,
+      markerEnd: `<!-- ${PROFILE_MARKER_PREFIX}:gemini-cli:end -->`,
+      defaultTarget: (env) => path.join(userHome(env), '.gemini', 'GEMINI.md'),
+      authInstruction: 'Use the client-managed MCP OAuth credential; do not paste token values into prompts, config files, or logs.'
+    },
+    antigravity: {
+      label: 'Antigravity',
+      setupAlias: 'antigravity',
+      profileVersion: 'antigravity-mcp-depth-v1',
+      markerStart: `<!-- ${PROFILE_MARKER_PREFIX}:antigravity:start -->`,
+      markerEnd: `<!-- ${PROFILE_MARKER_PREFIX}:antigravity:end -->`,
+      defaultTarget: (env) => path.join(userHome(env), '.gemini', 'antigravity', 'MEMORY.md'),
+      authInstruction: 'Use the client-managed MCP OAuth credential; do not paste token values into prompts, config files, or logs.'
+    }
+  };
+  return profileConfigs[clientId] ?? null;
+}
+
+function supportedProfileClientIds() {
+  return ['codex', 'cursor', 'gemini', 'antigravity'];
+}
+
+function defaultProfileTarget(clientId, env) {
+  const config = profileClientConfig(clientId);
+  if (!config) {
+    throw new UsageError(`Unsupported profile client: ${clientId}`);
+  }
+  return config.defaultTarget(env);
+}
+
+async function confirmProfileInstall(clientId, targetPath, io) {
+  const config = profileClientConfig(clientId);
+  writeLine(io.stdout, '');
+  writeLine(io.stdout, `Write XMemo memory behavior profile to ${targetPath}? [Y/n]`);
+  const answer = (await readLineFromStdin(io.stdin)).trim().toLowerCase();
+  if (answer === '' || answer === 'y' || answer === 'yes') {
+    return true;
+  }
+  if (answer === 'n' || answer === 'no') {
+    return false;
+  }
+  throw new UsageError(`Unsupported response for ${config.label} profile prompt: ${answer}`);
+}
+
+async function readLineFromStdin(stdin) {
+  let input = '';
+  for await (const chunk of stdin) {
+    input += chunk;
+    if (input.includes('\n')) {
+      break;
+    }
+  }
+  return input.split(/\r?\n/, 1)[0] ?? '';
+}
+
+function genericProfileMarkerBlock(clientId) {
+  const config = profileClientConfig(clientId);
+  return `${config.markerStart}\n${profileInstructionText(clientId)}${config.markerEnd}\n`;
+}
+
+async function profileInstallResult(clientId, targetPath, options = {}) {
+  if (clientId === 'codex') {
+    return codexProfileInstallResult(targetPath, options);
+  }
+  const config = profileClientConfig(clientId);
+  const resolvedTarget = path.resolve(targetPath);
+  const existing = await readTextIfExists(resolvedTarget);
+  const marker = profileMarkerBounds(existing, config);
+  const block = genericProfileMarkerBlock(clientId);
+  let nextText;
+
+  if (marker.present) {
+    nextText = `${existing.slice(0, marker.start)}${block}${existing.slice(marker.end)}`;
+  } else if (existing.trim().length === 0) {
+    nextText = block;
+  } else {
+    const separator = existing.endsWith('\n') ? '\n' : '\n\n';
+    nextText = `${existing}${separator}${block}`;
+  }
+
+  const changed = nextText !== existing;
+  const write = Boolean(options.write);
+  if (write && changed) {
+    await fs.mkdir(path.dirname(resolvedTarget), { recursive: true });
+    await fs.writeFile(resolvedTarget, nextText);
+  }
+
+  return {
+    client: clientId,
+    action: 'install',
+    targetPath: resolvedTarget,
+    markerStart: config.markerStart,
+    markerEnd: config.markerEnd,
+    installed: marker.present || (write && changed),
+    written: write,
+    changed,
+    markerPresent: marker.present,
+    writesTokenValue: false
+  };
+}
+
+async function profileStatusResult(clientId, targetPath) {
+  if (clientId === 'codex') {
+    return codexProfileStatusResult(targetPath);
+  }
+  const config = profileClientConfig(clientId);
+  const resolvedTarget = path.resolve(targetPath);
+  const existing = await readTextIfExists(resolvedTarget);
+  const marker = profileMarkerBounds(existing, config);
+  return {
+    client: clientId,
+    action: 'status',
+    targetPath: resolvedTarget,
+    installed: marker.present,
+    markerPresent: marker.present,
+    markerStart: config.markerStart,
+    markerEnd: config.markerEnd,
+    writesTokenValue: false
+  };
+}
+
+async function profileUninstallResult(clientId, targetPath, options = {}) {
+  if (clientId === 'codex') {
+    return codexProfileUninstallResult(targetPath, options);
+  }
+  const config = profileClientConfig(clientId);
+  const resolvedTarget = path.resolve(targetPath);
+  const existing = await readTextIfExists(resolvedTarget);
+  const marker = profileMarkerBounds(existing, config);
+  const write = Boolean(options.write);
+  let changed = false;
+
+  if (marker.present) {
+    let nextText = `${existing.slice(0, marker.start)}${existing.slice(marker.end)}`;
+    nextText = nextText.replace(/\n{3,}/g, '\n\n');
+    if (nextText.trim().length === 0) {
+      nextText = '';
+    } else if (!nextText.endsWith('\n')) {
+      nextText = `${nextText}\n`;
+    }
+    changed = nextText !== existing;
+    if (write && changed) {
+      await fs.writeFile(resolvedTarget, nextText);
+    }
+  }
+
+  return {
+    client: clientId,
+    action: 'uninstall',
+    targetPath: resolvedTarget,
+    installed: marker.present && !(write && changed),
+    written: write,
+    changed,
+    markerPresent: marker.present,
+    markerStart: config.markerStart,
+    markerEnd: config.markerEnd,
+    writesTokenValue: false
+  };
+}
+
+function profileMarkerBounds(content, config) {
+  const start = content.indexOf(config.markerStart);
+  const end = content.indexOf(config.markerEnd);
+  if (start === -1 && end === -1) {
+    return { present: false, start: -1, end: -1 };
+  }
+
+  if (start === -1 || end === -1 || end < start) {
+    throw new UsageError(`${config.label} profile markers are incomplete or out of order; edit the target file manually before retrying.`);
+  }
+
+  if (
+    content.indexOf(config.markerStart, start + config.markerStart.length) !== -1
+    || content.indexOf(config.markerEnd, end + config.markerEnd.length) !== -1
+  ) {
+    throw new UsageError(`${config.label} profile markers appear more than once; edit the target file manually before retrying.`);
+  }
+
+  const afterEnd = end + config.markerEnd.length;
+  const trailingNewlineLength = content.slice(afterEnd, afterEnd + 2) === '\r\n'
+    ? 2
+    : content.slice(afterEnd, afterEnd + 1) === '\n'
+      ? 1
+      : 0;
+
+  return {
+    present: true,
+    start,
+    end: afterEnd + trailingNewlineLength
+  };
+}
+
+function userHome(env) {
+  return env.USERPROFILE || env.HOME || os.homedir();
+}
+
 function codexProfileMarkerBlock() {
   return `${CODEX_PROFILE_MARKER_START}\n${codexProfileInstructionText()}${CODEX_PROFILE_MARKER_END}\n`;
 }
@@ -1800,7 +2121,8 @@ function markerBounds(content) {
 }
 
 function writeProfileResult(action, result, io) {
-  writeLine(io.stdout, `${PRODUCT_NAME} Codex profile ${action}`);
+  const config = profileClientConfig(result.client);
+  writeLine(io.stdout, `${PRODUCT_NAME} ${config?.label ?? result.client} profile ${action}`);
   writeLine(io.stdout, `  Target: ${result.targetPath}`);
   writeLine(io.stdout, `  Installed: ${result.installed}`);
   if ('written' in result) {
@@ -1812,7 +2134,8 @@ function writeProfileResult(action, result, io) {
 
 async function codexSmokeReport(configPath, env) {
   const configText = await readTextIfExists(configPath);
-  const block = tomlServerBlock(configText, MCP_SERVER_NAME);
+  const serverBlock = findTomlServerBlock(configText);
+  const block = serverBlock.block;
   const mcpUrl = block ? tomlStringValue(block, 'url') : null;
   const bearerTokenEnvVar = block ? tomlStringValue(block, 'bearer_token_env_var') : null;
   const tokenValue = env[TOKEN_ENV_VAR] ?? '';
@@ -1829,7 +2152,7 @@ async function codexSmokeReport(configPath, env) {
       name: 'memory_os_server_present',
       ok: Boolean(block),
       required: true,
-      detail: block ? `[mcp_servers.${MCP_SERVER_NAME}]` : `missing [mcp_servers.${MCP_SERVER_NAME}]`
+      detail: block ? `[mcp_servers.${serverBlock.name}]` : `missing [mcp_servers.${MCP_SERVER_NAME}]`
     },
     {
       name: 'mcp_url_present',
@@ -1867,7 +2190,7 @@ async function codexSmokeReport(configPath, env) {
     ok: checks.every((check) => !check.required || check.ok),
     client: 'codex',
     configPath,
-    serverName: MCP_SERVER_NAME,
+    serverName: serverBlock.name ?? MCP_SERVER_NAME,
     mcpUrl,
     tokenEnvVar: TOKEN_ENV_VAR,
     agentInstanceIdPath: identityPath,
@@ -1875,6 +2198,26 @@ async function codexSmokeReport(configPath, env) {
   };
 }
 
+function knownMcpServerNames() {
+  return [MCP_SERVER_NAME, ...LEGACY_MCP_SERVER_NAMES];
+}
+
+function existingJsonMcpServerName(mcpServers) {
+  return knownMcpServerNames().find((name) => mcpServers[name]);
+}
+
+function existingTomlMcpServerName(content) {
+  return knownMcpServerNames().find((name) => content.includes(`[mcp_servers.${name}]`));
+}
+
+function findTomlServerBlock(content) {
+  const name = existingTomlMcpServerName(content);
+  return {
+    name: name ?? null,
+    block: name ? tomlServerBlock(content, name) : ''
+  };
+}
+
 function tomlServerBlock(content, serverName) {
   const header = `[mcp_servers.${serverName}]`;
   const lines = content.split(/\r?\n/);
@@ -1907,8 +2250,9 @@ function cursorJsonSnippet(mcpUrl, identity = envReferenceIdentity('cursor')) {
 async function appendTomlServerConfig(configPath, mcpUrl) {
   const snippet = codexTomlSnippet(mcpUrl);
   const existing = await readTextIfExists(configPath);
-  if (existing.includes(`[mcp_servers.${MCP_SERVER_NAME}]`)) {
-    throw new UsageError(`MCP config already contains [mcp_servers.${MCP_SERVER_NAME}]. Edit ${configPath} manually to avoid duplicate server definitions.`);
+  const existingName = existingTomlMcpServerName(existing);
+  if (existingName) {
+    throw new UsageError(`MCP config already contains [mcp_servers.${existingName}]. Edit ${configPath} manually to avoid duplicate server definitions.`);
   }
 
   await fs.mkdir(path.dirname(configPath), { recursive: true, mode: 0o700 });
@@ -1929,8 +2273,9 @@ async function mergeJsonMcpConfig(configPath, mcpUrl, identity) {
     parsed.mcpServers = {};
   }
 
-  if (parsed.mcpServers[MCP_SERVER_NAME]) {
-    throw new UsageError(`MCP config already contains mcpServers.${MCP_SERVER_NAME}. Edit ${configPath} manually to avoid duplicate server definitions.`);
+  const existingName = existingJsonMcpServerName(parsed.mcpServers);
+  if (existingName) {
+    throw new UsageError(`MCP config already contains mcpServers.${existingName}. Edit ${configPath} manually to avoid duplicate server definitions.`);
   }
 
   parsed.mcpServers[MCP_SERVER_NAME] = cursorJsonServerConfig(mcpUrl, identity);
@@ -1973,8 +2318,9 @@ async function mergeAntigravityMcpConfig(configPath, mcpUrl, identity) {
     parsed.mcpServers = {};
   }
 
-  if (parsed.mcpServers[MCP_SERVER_NAME]) {
-    throw new UsageError(`MCP config already contains mcpServers.${MCP_SERVER_NAME}. Edit ${configPath} manually to avoid duplicate server definitions.`);
+  const existingName = existingJsonMcpServerName(parsed.mcpServers);
+  if (existingName) {
+    throw new UsageError(`MCP config already contains mcpServers.${existingName}. Edit ${configPath} manually to avoid duplicate server definitions.`);
   }
 
   parsed.mcpServers[MCP_SERVER_NAME] = antigravityJsonServerConfig(mcpUrl, identity);
@@ -1996,8 +2342,9 @@ async function mergeGeminiMcpConfig(configPath, mcpUrl, identity) {
     parsed.mcpServers = {};
   }
 
-  if (parsed.mcpServers[MCP_SERVER_NAME]) {
-    throw new UsageError(`MCP config already contains mcpServers.${MCP_SERVER_NAME}. Edit ${configPath} manually to avoid duplicate server definitions.`);
+  const existingName = existingJsonMcpServerName(parsed.mcpServers);
+  if (existingName) {
+    throw new UsageError(`MCP config already contains mcpServers.${existingName}. Edit ${configPath} manually to avoid duplicate server definitions.`);
   }
 
   parsed.mcpServers[MCP_SERVER_NAME] = geminiJsonServerConfig(mcpUrl, identity);
@@ -2018,7 +2365,12 @@ async function mergeCopilotMcpConfig(configPath, proxyUrl) {
     parsed.mcpServers = {};
   }
 
-  parsed.mcpServers['memory-os'] = copilotLocalProxyServerConfig(proxyUrl);
+  const existingName = existingJsonMcpServerName(parsed.mcpServers);
+  if (existingName) {
+    throw new UsageError(`MCP config already contains mcpServers.${existingName}. Edit ${configPath} manually to avoid duplicate server definitions.`);
+  }
+
+  parsed.mcpServers[MCP_SERVER_NAME] = copilotLocalProxyServerConfig(proxyUrl);
   await fs.mkdir(path.dirname(configPath), { recursive: true, mode: 0o700 });
   await fs.writeFile(configPath, `${JSON.stringify(parsed, null, 2)}\n`, { mode: 0o600 });
   await bestEffortChmod(configPath, 0o600);