Codex CLI

Switch between Codex, Claude Code, Gemini, and Cursor without losing context. The Codex package gives you a reliable Working Memory bootstrap, a bundled local MCP server, search and distill skills, and automatic thread capture. Codex still decides when to use memory, but modern Codex tends to follow MCP tools more proactively than skill-only guidance. That is why the recommended setup is hybrid: plugin + MCP + hook.

Before You Start

• Nowledge Mem running locally (installation) or a reachable remote Mem server
• Codex CLI installed
• nmem CLI in your PATH

Setup

# Option 1: uvx
curl -LsSf https://astral.sh/uv/install.sh | sh
uvx --from nmem-cli nmem --version

# Option 2: pip
pip install nmem-cli

codex plugin marketplace add nowledge-co/community

codex marketplace add nowledge-co/community

[features]
plugins = true
codex_hooks = true

[plugins."nowledge-mem@nowledge-community"]
enabled = true

HOOK_SETUP="$(find ~/.codex/plugins/cache -path '*/nowledge-mem/*/scripts/install_hooks.py' -print 2>/dev/null | sort | tail -1)"
test -n "$HOOK_SETUP" && python3 "$HOOK_SETUP"

git clone https://github.com/nowledge-co/community.git /tmp/nowledge-community
cp /tmp/nowledge-community/nowledge-mem-codex-plugin/AGENTS.md ./AGENTS.md
rm -rf /tmp/nowledge-community

nmem config client set url https://mem.example.com
nmem config client set api-key nmem_your_key

nmem config mcp show --host codex

Repo-level install (alternative)

Instead of a shared marketplace source, you can bundle the plugin in a project repo using a local Codex marketplace file. This makes the plugin available to anyone who clones the repo.

git clone https://github.com/nowledge-co/community.git /tmp/nowledge-community
mkdir -p .agents
cp -r /tmp/nowledge-community/nowledge-mem-codex-plugin ./.agents/nowledge-mem
rm -rf /tmp/nowledge-community
mkdir -p .agents/plugins

Create .agents/plugins/marketplace.json:

{
  "name": "local",
  "plugins": [
    {
      "name": "nowledge-mem",
      "source": {
        "source": "local",
        "path": "./.agents/nowledge-mem"
      },
      "policy": {
        "installation": "INSTALLED_BY_DEFAULT",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

The path is relative to the repo root, not to the marketplace file. For this local setup, use:

[plugins."nowledge-mem@local"]
enabled = true

Then run the hook setup from the repo-local plugin:

python3 ./.agents/nowledge-mem/scripts/install_hooks.py

Update

If you installed the Codex package before 0.1.10, marketplace update alone refreshes the plugin files but does not reliably refresh the host-level Stop hook. Run the hook setup below after updating; it replaces older async hook entries that current Codex stable skips.

codex plugin marketplace upgrade nowledge-community

Then refresh the hook runtime:

HOOK_SETUP="$(find ~/.codex/plugins/cache -path '*/nowledge-mem/*/scripts/install_hooks.py' -print 2>/dev/null | sort | tail -1)"
test -n "$HOOK_SETUP" && python3 "$HOOK_SETUP"

If the marketplace is not registered yet, run:

codex plugin marketplace add nowledge-co/community || codex marketplace add nowledge-co/community

Then restart Codex. If you are using a repo-local @local source, update that local source path instead.

Skills

The plugin skills still matter in the hybrid setup. They teach Codex when to use memory at all, while MCP gives Codex a lower-friction execution path once it decides to act.

Direct nmem Use

nmem remains the universal fallback and the real Codex thread-import path. The Stop hook uses the same command automatically:

nmem --json wm read
nmem --json m search "auth token rotation" --mode deep
nmem --json t save --from codex -p . -s "Finished the auth refactor."
nmem --json m add "JWT refresh failures came from clock skew." --title "JWT refresh failures traced to clock skew" --importance 0.9 --unit-type learning -l auth -s codex

By default, nmem t save --from codex reads sessions from ~/.codex. If your Codex home lives somewhere else, set CODEX_HOME and the save path follows automatically.

Migrating from Custom Prompts

If you previously used nowledge-mem-codex-prompts, the plugin covers everything the prompts did:

1. Install the plugin (see Setup above).
2. Remove old prompts: rm ~/.codex/prompts/{read_working_memory,search_memory,save_session,distill}.md
3. The plugin skills replace the prompts one-to-one.

Troubleshooting

"Command not found: nmem"

Install with pip install nmem-cli or use uvx --from nmem-cli nmem. See Getting Started.

"Cannot connect to server"

Run nmem status and nmem config client show for remote setups. See Remote Access.

Skills not appearing

Restart Codex after installing the plugin. Verify three things: the marketplace was added, nowledge-mem@nowledge-community was installed from /plugins, and ~/.codex/config.toml has both [features] plugins = true and [plugins."nowledge-mem@nowledge-community"] enabled = true. If you intentionally use a repo-local source, use [plugins."nowledge-mem@local"].

Codex threads are not appearing automatically

Run the hook setup again, then restart Codex:

HOOK_SETUP="$(find ~/.codex/plugins/cache -path '*/nowledge-mem/*/scripts/install_hooks.py' -print 2>/dev/null | sort | tail -1)"
test -n "$HOOK_SETUP" && python3 "$HOOK_SETUP"

The setup writes ~/.codex/hooks.json and ensures codex_hooks = true in ~/.codex/config.toml.

"plugin is not installed"

Run codex plugin marketplace add nowledge-co/community (or codex marketplace add nowledge-co/community on legacy Codex), install nowledge-mem@nowledge-community from /plugins, then verify the plugin key in ~/.codex/config.toml.

It only reads Working Memory, but never searches or distills

That usually means Codex is only seeing the plugin bootstrap path. Confirm the bundled nowledge-mem MCP server is visible in Codex, then merge the package AGENTS.md into your project root. If Mem is remote or not on the default local port, add mcp_servers.nowledge-mem in ~/.codex/config.toml to override the bundled endpoint.

Related

• Integrations overview
• Gemini CLI
• Claude Code
• Remote access