memorix 1.2.9 → 1.2.10

package/docs/AGENT_OPERATOR_PLAYBOOK.md

@@ -243,7 +243,7 @@ memorix setup --agent omp --global
 What this installs depends on the target agent:
 
 - Claude Code: local `memorix-local` marketplace plugin, best-effort `claude plugin install memorix@memorix-local`, plugin-bundled stdio MCP, hooks, skills, plus `CLAUDE.md` guidance.
-- Codex: local Personal marketplace plugin under `~/.codex/plugins/memorix`, marketplace entry at `~/.agents/plugins/marketplace.json`, best-effort `codex plugin add memorix@personal`, plugin-bundled stdio MCP, skills, and `SessionStart` / `UserPromptSubmit` / `PostToolUse` / `PreCompact` / `Stop` hooks, plus `AGENTS.md` guidance. Codex asks the user to review plugin hooks once in `/hooks` before non-managed hooks run.
+- Codex: local Personal marketplace plugin under `~/plugins/memorix`, marketplace entry at `~/.agents/plugins/marketplace.json`, best-effort `codex plugin add memorix@personal`, plugin-bundled stdio MCP, skills, and `SessionStart` / `UserPromptSubmit` / `PostToolUse` / `PreCompact` / `Stop` hooks. It does not create project `.codex` files or overwrite model, approval, or sandbox settings. Codex asks the user to review plugin hooks once in `/hooks` before non-managed hooks run.
 - GitHub Copilot CLI: local plugin package under `~/.copilot/plugins/local/memorix`, best-effort `copilot plugin install <local-path>`, plugin-bundled stdio MCP, hooks, and skills.
 - Cursor: Cursor MCP config, `.cursor/rules/memorix.mdc`, skills, and hook guidance through Cursor's project config surfaces.
 - Pi: user Pi package with extension-based hook capture and a Memorix skill, registered through `pi install <path> --approve`; project-local setup uses `-l`.
@@ -668,7 +668,7 @@ If it reports stale MCP command paths, missing `memorix` MCP entries, missing Cl
 memorix repair agents --agent <agent>
 ```
 
-Repair only rewrites Memorix-owned MCP entries, Memorix-owned guidance blocks, and an explicitly targeted Codex Memorix plugin bundle. It does not edit unrelated user config or turn on a user-disabled Codex plugin; enable that one from `/plugins`.
+Repair only rewrites Memorix-owned MCP entries, Memorix-owned guidance blocks, and an explicitly targeted Codex Memorix plugin bundle. It does not edit unrelated user config, grant Codex hook trust, or turn on a user-disabled Codex plugin; review hooks in `/hooks` and enable a disabled plugin in `/plugins`.
 
 ### 1. Is the workspace a Git repo?
 

package/docs/DEVELOPMENT.md

@@ -321,7 +321,13 @@ npm publish --access public
 
 Notes:
 
-- `prepublishOnly` runs build + test, but does not contact live model catalog APIs
+- `prepublishOnly` synchronizes and checks Registry metadata, then runs build + test; it does not contact live model catalog APIs
+- `server.json` is the official MCP Registry record. Keep it synchronized with
+  `package.json` by running `npm run sync:mcp-registry`; verify it with
+  `npm run check:mcp-registry` before a release.
+- The GitHub publish workflow publishes npm first, then uses GitHub OIDC to
+  publish the same verified version to the official MCP Registry. It does not
+  require a Registry token or private key in repository secrets.
 - `@memorix/ai`, `@memorix/agent-core`, `@memorix/tui`, and `@memorix/memcode` are internal workspaces. Their code is bundled into the root `memorix` distribution and they must stay `private` unless the project deliberately establishes an owned npm scope and a separate package-support contract.
 - npm publish is usually manual, especially when 2FA is enabled
 - GitHub release automation should not be treated as a substitute for manual runtime validation

package/docs/INTEGRATIONS.md

@@ -49,7 +49,7 @@ Generated guidance also has scope:
 | Agent | Recommended install | Official entry | What gets installed | Notes |
 | --- | --- | --- | --- | --- |
 | Claude Code | `memorix setup --agent claude --global` | Claude Code plugin marketplace | Local `memorix-local` marketplace, plugin-bundled stdio MCP, skills, hooks, plus `CLAUDE.md` guidance | Setup attempts `claude plugin marketplace add` and `claude plugin install memorix@memorix-local`. |
-| Codex | `memorix setup --agent codex --global` | Codex Personal marketplace plugin | Local plugin under `~/.codex/plugins/memorix`, Personal marketplace entry, plugin-bundled stdio MCP, skills, hooks, plus `AGENTS.md` guidance | Setup attempts `codex plugin add memorix@personal`. Run `memorix doctor agents --agent codex --scope global` to verify the bundle, marketplace, enabled state, and five declared/trusted hooks; start a new thread after setup. |
+| Codex | `memorix setup --agent codex --global` | Codex Personal marketplace plugin | User plugin under `~/plugins/memorix`, Personal marketplace entry, plugin-bundled stdio MCP, skills, and hooks | Setup attempts `codex plugin add memorix@personal`. It leaves project `.codex` files and model/approval/sandbox settings alone. `memorix doctor agents --agent codex --scope global` verifies the bundle, marketplace, and enabled state, then reports any one-time hook review Codex still requires; start a new thread after setup. |
 | GitHub Copilot CLI | `memorix setup --agent copilot --global` | Copilot CLI plugin package | Local plugin under `~/.copilot/plugins/local/memorix` with MCP, skills, and hooks | Setup attempts `copilot plugin install <local-path>` when Copilot CLI is available. |
 | Cursor | `memorix setup --agent cursor --global` | Cursor MCP and rules config | Cursor MCP config, `.cursor/rules/memorix.mdc`, skills, and hook guidance | Reload Cursor after setup so it can pick up project config changes. |
 | Gemini CLI | `memorix setup --agent gemini-cli --global` | Gemini CLI extension | Extension under `~/.gemini/extensions/memorix` with MCP, `GEMINI.md` context, hooks, commands, and skills | Antigravity CLI has an official Gemini CLI migration path, but Gemini CLI remains an active standalone Google CLI target. |

package/docs/SETUP.md

@@ -76,7 +76,7 @@ memorix setup --agent omp --global
 What this does:
 
 - Claude Code: installs a local marketplace plugin, attempts `claude plugin install memorix@memorix-local`, and writes `CLAUDE.md` guidance.
-- Codex: installs a local Personal marketplace plugin, attempts `codex plugin add memorix@personal`, and writes `AGENTS.md` guidance.
+- Codex: installs a user-level Personal marketplace plugin under `~/plugins/memorix`, attempts `codex plugin add memorix@personal`, and keeps project-local `.codex` configuration untouched. The plugin owns its MCP server, skills, and optional hooks without changing your model, approval, or sandbox settings.
 - GitHub Copilot CLI: installs a local plugin package and attempts `copilot plugin install <local-path>`.
 - Cursor: writes Cursor MCP config, rules, skills, and hook guidance.
 - Pi: installs the user-level Memorix Pi package and attempts `pi install <path> --approve`.
@@ -132,9 +132,9 @@ memorix doctor agents --agent <agent>
 memorix repair agents --agent <agent>
 ```
 
-The doctor checks Memorix-owned MCP entries and guidance files for stale command paths, missing `memorix` MCP servers, missing Claude `alwaysLoad`, and outdated Memory Autopilot rules. For `codex --scope global`, it also checks the local plugin bundle, Personal marketplace entry, five declared lifecycle hooks, Codex's trusted hook state, and the installed/enabled state reported by `codex plugin list`.
+The doctor checks Memorix-owned MCP entries and guidance files for stale command paths, missing `memorix` MCP servers, missing Claude `alwaysLoad`, and outdated Memory Autopilot rules. For `codex --scope global`, MCP is owned by the user-level plugin rather than a direct `config.toml` entry. The doctor checks the plugin bundle, Personal marketplace entry, five declared lifecycle hooks, and the installed/enabled state reported by `codex plugin list`; it reports, but never auto-grants, any hook review Codex still requires.
 
-After Codex setup, start a new thread so enabled plugins can load. Codex does not expose a command that proves hooks are already active inside the current thread. If doctor reports `codex-plugin-disabled`, open `/plugins` and turn Memorix on there; repair does not toggle a user-disabled plugin.
+After Codex setup, start a new thread so enabled plugins can load. If Codex asks to review plugin hooks, approve or decline them in `/hooks`; this is user-level plugin consent, not project trust. If doctor reports `codex-plugin-disabled`, open `/plugins` and turn Memorix on there; repair does not toggle a user-disabled plugin.
 
 ### Option B: manual stdio MCP
 
@@ -330,7 +330,9 @@ HTTP variants in Windsurf-like clients may use `serverUrl`:
 }
 ```
 
-### Codex fallback
+### Codex manual MCP compatibility
+
+The user-level plugin is the default and should be the only Memorix route for Codex. Use this compatibility fallback only when the Codex plugin system is unavailable; do not add it alongside `memorix@personal`, because that creates duplicate MCP ownership.
 
 Config file: `~/.codex/config.toml`
 

package/docs/hooks-architecture.md

@@ -27,7 +27,7 @@
 |-------|---------|------|
 | VS Code Copilot | `.github/hooks/*.json` | Claude Code 兼容 |
 | Claude Code | `.claude/settings.json` | 原生 |
-| Codex | Memorix 插件内 `hooks/hooks.json` | Codex plugin hooks；通过 `memorix setup --agent codex` 安装 |
+| Codex | 用户级 Memorix 插件内 `hooks/hooks.json` | Codex plugin hooks；通过 `memorix setup --agent codex --global` 安装，不写项目 `.codex/hooks.json` |
 | Windsurf | `.windsurf/cascade.json` | Windsurf 格式 |
 | Cursor | `.cursor/hooks.json` | Cursor 格式 |
 | Kiro | `.kiro/hooks/*.hook.md` | Markdown + YAML |

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "memorix",
-  "version": "1.2.9",
+  "mcpName": "io.github.AVIDS2/memorix",
+  "version": "1.2.10",
   "description": "Local-first shared memory layer for AI coding agents across MCP clients, Git history, reasoning context, and project sessions.",
   "type": "module",
   "sideEffects": false,
@@ -33,6 +34,7 @@
   "files": [
     "dist",
     "src",
+    "server.json",
     "!src/**/*.js",
     "!src/**/*.js.map",
     "!src/**/*.d.ts",
@@ -63,9 +65,11 @@
     "test:e2e": "vitest run tests/e2e/",
     "benchmark:codegraph": "node scripts/benchmark-codegraph-provider.cjs",
     "benchmark:retrieval": "npm run build && node scripts/benchmark-retrieval.mjs",
+    "sync:mcp-registry": "node scripts/sync-mcp-registry-manifest.mjs",
+    "check:mcp-registry": "node scripts/check-mcp-registry-manifest.mjs",
     "audit:pi-upstream": "node scripts/pi-upstream-audit.mjs",
     "lint": "tsc --noEmit",
-    "prepublishOnly": "npm run build && npm test"
+    "prepublishOnly": "npm run sync:mcp-registry && npm run check:mcp-registry && npm run build && npm test"
   },
   "keywords": [
     "mcp",

package/plugins/claude/memorix/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "memorix",
-  "version": "1.2.9",
+  "version": "1.2.10",
   "description": "Shared workspace memory for Claude Code and other AI coding agents.",
   "author": {
     "name": "AVIDS2",

package/plugins/codex/memorix/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.2.9",
+  "version": "1.2.10",
   "description": "Shared workspace memory for Codex and other AI coding agents.",
   "author": {
     "name": "AVIDS2",

package/plugins/copilot/memorix/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.2.9",
+  "version": "1.2.10",
   "description": "Shared local workspace memory for GitHub Copilot CLI and other AI coding agents.",
   "author": {
     "name": "AVIDS2",

package/plugins/gemini/memorix/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.2.9",
+  "version": "1.2.10",
   "mcpServers": {
     "memorix": {
       "command": "memorix",

package/plugins/omp/memorix/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix-omp-package",
-  "version": "1.2.9",
+  "version": "1.2.10",
   "description": "Memorix shared workspace memory package for Oh-my-Pi.",
   "license": "Apache-2.0",
   "keywords": [

package/plugins/openclaw/memorix/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.2.9",
+  "version": "1.2.10",
   "description": "Shared workspace memory for OpenClaw and other AI coding agents.",
   "author": {
     "name": "AVIDS2",

package/plugins/pi/memorix/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix-pi-package",
-  "version": "1.2.9",
+  "version": "1.2.10",
   "description": "Memorix shared workspace memory package for Pi coding agent.",
   "license": "Apache-2.0",
   "keywords": [

package/server.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.AVIDS2/memorix",
+  "title": "Memorix",
+  "description": "Local-first persistent project memory for AI coding agents across MCP clients and sessions.",
+  "repository": {
+    "url": "https://github.com/AVIDS2/memorix",
+    "source": "github"
+  },
+  "version": "1.2.10",
+  "websiteUrl": "https://github.com/AVIDS2/memorix#readme",
+  "icons": [
+    {
+      "src": "https://raw.githubusercontent.com/AVIDS2/memorix/main/assets/logo.png",
+      "mimeType": "image/png",
+      "sizes": [
+        "1024x1024"
+      ]
+    }
+  ],
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "memorix",
+      "version": "1.2.10",
+      "runtimeHint": "npx",
+      "packageArguments": [
+        {
+          "type": "positional",
+          "value": "serve"
+        }
+      ],
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}

package/src/cli/commands/agent-integrations.ts

@@ -12,6 +12,7 @@ import {
   getSetupAgentTargets,
   installPluginPackage,
   installMcpConfig,
+  migrateLegacyCodexIntegration,
   tryInstallCodexPlugin,
   type McpConfigAgent,
 } from './setup.js';
@@ -228,7 +229,7 @@ function asRecordArray(value: unknown): JsonRecord[] {
 }
 
 function codexPluginPath(): string {
-  return `${homedir()}/.codex/plugins/${CODEX_PLUGIN_NAME}`;
+  return `${homedir()}/plugins/${CODEX_PLUGIN_NAME}`;
 }
 
 function codexPluginMcpPath(): string {
@@ -254,7 +255,10 @@ function isMemorixCodexPlugin(value: JsonRecord): boolean {
 
 export function parseCodexPluginList(output: string): AgentPluginCheck['runtime'] | null {
   try {
-    const parsed = asRecord(JSON.parse(output));
+    const start = output.indexOf('{');
+    const end = output.lastIndexOf('}');
+    if (start < 0 || end < start) return null;
+    const parsed = asRecord(JSON.parse(output.slice(start, end + 1)));
     if (!parsed) return null;
     const entries = [...asRecordArray(parsed.installed), ...asRecordArray(parsed.available)];
     const plugin = entries.find(isMemorixCodexPlugin);
@@ -407,7 +411,7 @@ async function inspectCodexMarketplace(): Promise<AgentPluginCheck> {
 
   const source = asRecord(entry.source);
   const sourcePath = typeof source?.path === 'string' ? source.path : '';
-  const issues = source?.source === 'local' && normalizeMarketplacePath(sourcePath) === '.codex/plugins/memorix'
+  const issues = source?.source === 'local' && normalizeMarketplacePath(sourcePath) === 'plugins/memorix'
     ? []
     : ['codex-marketplace-entry-stale'];
   return {
@@ -1060,9 +1064,11 @@ export async function repairAgentIntegrations(options: {
         } else {
           if (!options.dry) {
             await installPluginPackage({ agent: 'codex' });
-            if (needsInstall) {
-              const install = tryInstallCodexPlugin();
-              if (!install.ok) skipped.push('codex:plugin:global:install-pending');
+            const install = tryInstallCodexPlugin();
+            if (install.ok) {
+              await migrateLegacyCodexIntegration({ projectRoot });
+            } else {
+              skipped.push('codex:plugin:global:install-pending');
             }
           }
           changed.push('codex:plugin:global');

package/src/cli/commands/setup.ts

@@ -162,7 +162,9 @@ const OPENCLAW_BUNDLE_AGENTS = new Set<AgentName>(['openclaw']);
 const ANTIGRAVITY_PLUGIN_AGENTS = new Set<AgentName>(['antigravity']);
 const HERMES_PLUGIN_AGENTS = new Set<AgentName>(['hermes']);
 const OMP_PACKAGE_AGENTS = new Set<AgentName>(['omp']);
-const PACKAGE_OWNED_INTEGRATION_AGENTS = new Set<AgentName>(['antigravity', 'openclaw', 'hermes', 'omp']);
+// These hosts have a native package/plugin surface. Their default setup must not
+// create project-local fallback files beside the user's own agent configuration.
+const PACKAGE_OWNED_INTEGRATION_AGENTS = new Set<AgentName>(['codex', 'antigravity', 'openclaw', 'hermes', 'omp']);
 const SUPPORTED_SETUP_AGENTS: AgentName[] = [
   'claude',
   'codex',
@@ -484,6 +486,32 @@ function mergeTomlMcpConfig(existingContent: string | null, generatedContent: st
   return `${parts.join('\n\n')}\n`;
 }
 
+type LegacyArtifactStatus = 'removed' | 'preserved' | 'missing';
+
+export interface CodexLegacyMigrationResult {
+  mcp: LegacyArtifactStatus;
+  projectHooks: LegacyArtifactStatus;
+  pluginFolder: LegacyArtifactStatus;
+}
+
+function getTomlSection(content: string, section: string): string | null {
+  const lines = content.split(/\r?\n/);
+  const header = `[${section}]`;
+  const start = lines.findIndex((line) => line.trim() === header);
+  if (start < 0) return null;
+
+  let end = lines.length;
+  for (let index = start + 1; index < lines.length; index += 1) {
+    const trimmed = lines[index].trim();
+    if (trimmed.startsWith('[') && trimmed.endsWith(']')) {
+      end = index;
+      break;
+    }
+  }
+
+  return lines.slice(start + 1, end).join('\n');
+}
+
 function isLegacyCodexMemorixNodeServer(server: MCPServerEntry): boolean {
   if (server.name !== 'memorix' || server.command.trim().toLowerCase() !== 'node') return false;
   const startsMemorixStdio = server.args.some((arg) => arg.trim().toLowerCase() === 'serve');
@@ -494,6 +522,22 @@ function isLegacyCodexMemorixNodeServer(server: MCPServerEntry): boolean {
   return startsMemorixStdio && sourceEntry;
 }
 
+function isOwnedLegacyCodexMcp(content: string): boolean {
+  const section = getTomlSection(content, 'mcp_servers.memorix');
+  if (section === null || getTomlSection(content, 'mcp_servers.memorix.env') !== null) return false;
+
+  const allowedKeys = new Set(['command', 'args', 'type', 'startup_timeout_sec', 'tool_timeout_sec', 'enabled']);
+  for (const rawLine of section.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) continue;
+    const key = line.match(/^([A-Za-z0-9_]+)\s*=/)?.[1];
+    if (!key || !allowedKeys.has(key)) return false;
+  }
+
+  const server = new CodexMCPAdapter().parse(content).find((entry) => entry.name === 'memorix');
+  return Boolean(server && isLegacyCodexMemorixNodeServer(server));
+}
+
 /**
  * Codex plugins now own Memorix stdio MCP registration. Remove only the old
  * source-path form emitted by pre-plugin setup, never a user's custom server.
@@ -508,9 +552,7 @@ export async function removeLegacyCodexMemorixMcpConfig(
     return { configPath, removed: false };
   }
 
-  const adapter = new CodexMCPAdapter();
-  const legacyServer = adapter.parse(existingContent).find(isLegacyCodexMemorixNodeServer);
-  if (!legacyServer) return { configPath, removed: false };
+  if (!isOwnedLegacyCodexMcp(existingContent)) return { configPath, removed: false };
 
   let nextContent = removeTomlSection(existingContent, 'mcp_servers.memorix.env');
   nextContent = removeTomlSection(nextContent, 'mcp_servers.memorix');
@@ -518,6 +560,88 @@ export async function removeLegacyCodexMemorixMcpConfig(
   return { configPath, removed: true };
 }
 
+function collectHookCommands(value: unknown, commands: string[]): void {
+  if (Array.isArray(value)) {
+    for (const item of value) collectHookCommands(item, commands);
+    return;
+  }
+  if (!value || typeof value !== 'object') return;
+
+  for (const [key, child] of Object.entries(value as Record<string, unknown>)) {
+    if ((key === 'command' || key === 'commandWindows') && typeof child === 'string') {
+      commands.push(child);
+    } else {
+      collectHookCommands(child, commands);
+    }
+  }
+}
+
+function isOwnedLegacyCodexHooks(content: string): boolean {
+  try {
+    const parsed = JSON.parse(content) as { hooks?: unknown };
+    if (!parsed.hooks || typeof parsed.hooks !== 'object') return false;
+    const commands: string[] = [];
+    collectHookCommands(parsed.hooks, commands);
+    return commands.length > 0
+      && commands.every((command) => /^memorix(?:\.cmd)?\s+hook(?:\s|$)/i.test(command.trim()));
+  } catch {
+    return false;
+  }
+}
+
+async function removeOwnedLegacyCodexPluginFolder(homeDir: string): Promise<LegacyArtifactStatus> {
+  const canonicalPath = path.join(homeDir, 'plugins', 'memorix');
+  const legacyPath = path.join(homeDir, '.codex', 'plugins', 'memorix');
+  if (!existsSync(legacyPath)) return 'missing';
+  if (!existsSync(canonicalPath)) return 'preserved';
+
+  try {
+    const manifest = JSON.parse(await readFile(path.join(legacyPath, '.codex-plugin', 'plugin.json'), 'utf-8')) as Record<string, unknown>;
+    const repository = String(manifest.repository ?? '');
+    if (manifest.name !== 'memorix' || !repository.includes('github.com/AVIDS2/memorix')) return 'preserved';
+    await rm(legacyPath, { recursive: true, force: true });
+    return 'removed';
+  } catch {
+    return 'preserved';
+  }
+}
+
+export async function migrateLegacyCodexIntegration(options: {
+  homeDir?: string;
+  projectRoot?: string;
+} = {}): Promise<CodexLegacyMigrationResult> {
+  const homeDir = options.homeDir ?? homedir();
+  const projectRoot = options.projectRoot ?? process.cwd();
+  const configPath = path.join(homeDir, '.codex', 'config.toml');
+  let mcp: LegacyArtifactStatus = 'missing';
+
+  try {
+    const content = await readFile(configPath, 'utf-8');
+    if (getTomlSection(content, 'mcp_servers.memorix') !== null) {
+      mcp = (await removeLegacyCodexMemorixMcpConfig(configPath)).removed ? 'removed' : 'preserved';
+    }
+  } catch {
+    mcp = 'missing';
+  }
+
+  const hooksPath = path.join(projectRoot, '.codex', 'hooks.json');
+  let projectHooks: LegacyArtifactStatus = 'missing';
+  try {
+    const content = await readFile(hooksPath, 'utf-8');
+    if (isOwnedLegacyCodexHooks(content)) {
+      await rm(hooksPath, { force: true });
+      projectHooks = 'removed';
+    } else {
+      projectHooks = 'preserved';
+    }
+  } catch {
+    projectHooks = 'missing';
+  }
+
+  const pluginFolder = await removeOwnedLegacyCodexPluginFolder(homeDir);
+  return { mcp, projectHooks, pluginFolder };
+}
+
 function mergeYamlMcpConfig(existingContent: string | null, generatedContent: string): string {
   let existing: Record<string, unknown> = {};
   try {
@@ -678,7 +802,9 @@ export async function installPluginPackage(options: PluginInstallOptions): Promi
   }
 
   if (options.agent === 'codex') {
-    const pluginPath = path.join(home, '.codex', 'plugins', 'memorix');
+    // Codex discovers personal plugins from the user marketplace. Keep the
+    // package outside ~/.codex so setup does not look like project/config state.
+    const pluginPath = path.join(home, 'plugins', 'memorix');
     const marketplacePath = path.join(home, '.agents', 'plugins', 'marketplace.json');
     await copyDir(source, pluginPath);
     await stampCodexPluginVersion(pluginPath);
@@ -908,6 +1034,39 @@ function tryInstallClaudePlugin(marketplaceRoot: string): { ok: boolean; message
   };
 }
 
+export type CodexPluginState = 'ready' | 'disabled' | 'missing' | 'unknown';
+
+export function parseCodexPluginState(content: string): CodexPluginState {
+  try {
+    // Some Windows builds emit a one-line diagnostic before the requested JSON.
+    const start = content.indexOf('{');
+    const end = content.lastIndexOf('}');
+    if (start < 0 || end < start) return 'unknown';
+    const parsed = JSON.parse(content.slice(start, end + 1)) as { installed?: unknown };
+    if (!Array.isArray(parsed.installed)) return 'unknown';
+
+    const plugin = parsed.installed.find((entry): entry is Record<string, unknown> => (
+      Boolean(entry)
+      && typeof entry === 'object'
+      && (entry as Record<string, unknown>).pluginId === 'memorix@personal'
+    ));
+    if (!plugin || plugin.installed !== true) return 'missing';
+    return plugin.enabled === true ? 'ready' : 'disabled';
+  } catch {
+    return 'unknown';
+  }
+}
+
+function getCodexPluginState(): CodexPluginState {
+  const result = spawnSync('codex', ['plugin', 'list', '--json'], {
+    encoding: 'utf-8',
+    stdio: 'pipe',
+    shell: process.platform === 'win32',
+  });
+  if (result.status !== 0) return 'unknown';
+  return parseCodexPluginState(result.stdout || '');
+}
+
 export function tryInstallCodexPlugin(): { ok: boolean; message: string } {
   const result = spawnSync('codex', ['plugin', 'add', 'memorix@personal', '--json'], {
     encoding: 'utf-8',
@@ -915,13 +1074,28 @@ export function tryInstallCodexPlugin(): { ok: boolean; message: string } {
     shell: process.platform === 'win32',
   });
 
-  if (result.status === 0) {
-    return { ok: true, message: 'codex: plugin installed from Personal marketplace' };
-  }
-
   const output = `${result.stderr || ''}\n${result.stdout || ''}`.toLowerCase();
-  if (output.includes('already')) {
-    return { ok: true, message: 'codex: plugin already installed from Personal marketplace' };
+  const addFinished = result.status === 0 || output.includes('already');
+  if (addFinished) {
+    const pluginState = getCodexPluginState();
+    if (pluginState === 'ready') {
+      return {
+        ok: true,
+        message: result.status === 0
+          ? 'codex: plugin installed and enabled from Personal marketplace'
+          : 'codex: plugin already installed and enabled from Personal marketplace',
+      };
+    }
+    if (pluginState === 'disabled') {
+      return {
+        ok: false,
+        message: 'codex: Memorix plugin is installed but disabled. Enable it in Codex Plugins before any legacy MCP or project hooks are removed.',
+      };
+    }
+    return {
+      ok: false,
+      message: 'codex: plugin registration finished, but Codex did not confirm an enabled Memorix plugin. Legacy MCP and project hooks were kept unchanged.',
+    };
   }
 
   const detail = (result.stderr || result.stdout || result.error?.message || '').trim();
@@ -1106,7 +1280,9 @@ export async function installAgentSetup(agent: AgentName, plan: SetupPlan, globa
   const hasAntigravityPlugin = plan.actions.includes('antigravity-plugin') && agent === 'antigravity';
   const hasHermesPlugin = plan.actions.includes('hermes-plugin') && agent === 'hermes';
   const hasOmpPackage = plan.actions.includes('omp-package') && agent === 'omp';
-  const wantsMcpConfig = plan.mcp !== 'none' && agent !== 'pi';
+  // Codex's supported default is the user-level plugin. Never create a
+  // project-local .codex/config.toml as an implicit fallback.
+  const wantsMcpConfig = plan.mcp !== 'none' && agent !== 'pi' && !(agent === 'codex' && !global);
 
   if (PLUGIN_PACKAGE_AGENTS.has(agent) && plan.includePlugin && !global) {
     p.log.info(`${agent}: project setup leaves user-level plugins untouched. Run \`memorix setup --agent ${agent} --global\` to install its plugin, skills, and lifecycle hooks.`);
@@ -1115,7 +1291,7 @@ export async function installAgentSetup(agent: AgentName, plan: SetupPlan, globa
   if (hasPluginPackage) {
     const result = await installPluginPackage({
       agent: agent as PluginInstallOptions['agent'],
-      includeHooks: plan.actions.includes('hooks'),
+      includeHooks: plan.includeHooks,
     });
     p.log.success(`${agent}: plugin package -> ${result.pluginPath}`);
     if (result.marketplacePath) {
@@ -1123,17 +1299,16 @@ export async function installAgentSetup(agent: AgentName, plan: SetupPlan, globa
     }
     if (agent === 'codex') {
       const install = tryInstallCodexPlugin();
-      if (install.ok) p.log.success(install.message);
-      else p.log.warn(install.message);
       if (install.ok) {
-        try {
-          const migration = await removeLegacyCodexMemorixMcpConfig();
-          if (migration.removed) {
-            p.log.info(`codex: removed legacy source-path MCP config from ${migration.configPath}`);
-          }
-        } catch {
-          p.log.warn('codex: plugin installed, but the legacy MCP config could not be checked');
-        }
+        p.log.success(install.message);
+        const migration = await migrateLegacyCodexIntegration({ projectRoot: process.cwd() });
+        if (migration.mcp === 'removed') p.log.info('codex: removed the legacy source-path MCP block; the enabled plugin now owns MCP.');
+        if (migration.mcp === 'preserved') p.log.warn('codex: kept a customized legacy Memorix MCP block; remove it manually only after confirming plugin MCP works.');
+        if (migration.projectHooks === 'removed') p.log.info('codex: removed a legacy project-local Memorix hooks.json; plugin hooks now own lifecycle capture.');
+        if (migration.projectHooks === 'preserved') p.log.warn('codex: kept a project .codex/hooks.json because it contains non-Memorix commands.');
+        if (migration.pluginFolder === 'removed') p.log.info('codex: removed the migrated legacy plugin folder under ~/.codex/plugins.');
+      } else {
+        p.log.warn(install.message);
       }
     } else if (agent === 'claude' && result.marketplaceRoot) {
       const install = tryInstallClaudePlugin(result.marketplaceRoot);
@@ -1224,6 +1399,8 @@ export async function installAgentSetup(agent: AgentName, plan: SetupPlan, globa
       const result = await installMcpConfig({ agent: agent as McpConfigAgent, projectRoot: targetRoot, global, mcp });
       p.log.success(`${agent}: MCP config -> ${result.configPath}`);
     }
+  } else if (agent === 'codex' && !global && plan.mcp !== 'none') {
+    p.log.info('codex: project-local .codex config is intentionally untouched. Run `memorix setup --agent codex --global` to install the user-level plugin.');
   }
 
   if (hasPluginPackage) {