Rework the Codex install flow around `codex plugin marketplace add
<clone>` so users can lean on the repo's bundled
`.agents/plugins/marketplace.json` instead of hand-authoring one.
This removes the "path must be under ~/" constraint that was tripping
people up.
Also:
- Call out that sideloading auto-registers `mem0` via .codex-mcp.json,
so Option A (Direct MCP) and Option B (sideload) must not be combined.
- Rename the Direct MCP snippet on the platform page from `mem0-mcp`
to `mem0` to match the bundled plugin — prevents silent duplicate
servers for users who follow one path then try the other.
- Drop the trailing slash in .codex-mcp.json's URL to match the rest
of the docs.
- Add `codex plugin marketplace upgrade` / `remove` and the plugin
cache path (~/.codex/plugins/cache/...).
- New troubleshooting entries for duplicate MCP registration and for
hooks breaking after a clone is moved (the installer bakes absolute
paths, so moving the clone requires re-running it).
Re-checked the docs PR against developers.openai.com/codex/plugins/build,
which states: "Keep source.path relative to the marketplace root, start
it with ./, and keep it inside that root."
The earlier sideload instructions used an absolute path
(/Users/YOU/src/mem0/mem0-plugin) which violates that rule. Updated:
- docs/integrations/codex.mdx Option B — clone under ~/codex-plugins/,
use "./codex-plugins/mem0-source/mem0-plugin", restart Codex made an
explicit step.
- mem0-plugin/README.md Option B — same fix.
- Updated the "plugin/read failed in TUI" troubleshooting entry to
point at the relative-path requirement.
The support ticket that surfaced this found three overlapping issues:
1. docs/integrations/codex.mdx shipped a marketplace.json snippet with
path "./plugins/mem0" — a directory that does not exist, with no clone
prerequisite documented, and using a folder name that does not match
the actual mem0-plugin/ directory. Users copy-pasted it verbatim and
hit "plugin/read failed in TUI".
2. The "Manual MCP Configuration" option used a JSON mcpServers block.
Codex reads MCP servers as TOML in ~/.codex/config.toml, not JSON.
Same bug in docs/platform/mem0-mcp.mdx (no Codex accordion at all on
main) and mem0-plugin/README.md Option C.
3. The page claimed "Codex uses a skill-based approach instead of
lifecycle hooks" — stale; hooks are now available via opt-in
installer (mem0-plugin/scripts/install_codex_hooks.py).
Lead with the working TOML MCP config (zero dependencies, works today),
demote the marketplace.json to a "Sideload (Advanced)" section with the
required git clone step and the correct mem0-plugin path, and point
sideloaders at the hooks installer + codex_hooks feature flag. Added
troubleshooting entries for the TUI read error and hooks-not-firing.
gabrielstein-mem0