Codex CLI

Read https://mem.nowledge.co/docs/integrations/codex-cli.mdx, then help me install or update Nowledge Mem for Codex CLI. Use the recommended path first, verify the setup with the success check in the guide, and summarize what changed.

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
hooks = true
plugin_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)"
if [ -z "$HOOK_SETUP" ]; then
  echo "Hook setup was not found. Open Codex, run /plugins, install nowledge-mem@nowledge-community, then retry."
else
  python3 "$HOOK_SETUP"
fi

$HookSetup = Get-ChildItem "$env:USERPROFILE\.codex\plugins\cache" -Recurse -Filter install_hooks.py |
  Where-Object { $_.FullName -like "*nowledge-mem*" } |
  Sort-Object FullName |
  Select-Object -Last 1
if ($null -eq $HookSetup) {
  Write-Host "Hook setup was not found. Open Codex, run /plugins, install nowledge-mem@nowledge-community, then retry."
} else {
  py -3 $HookSetup.FullName
}

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.13, refresh the marketplace first. Current Codex builds may refresh the marketplace checkout without reinstalling the already-installed package cache, so the hook setup file or bundled hook changes may still be missing until the package itself is updated from /plugins.

codex plugin marketplace upgrade nowledge-community

Open Codex, run /plugins, update or reinstall nowledge-mem@nowledge-community, then restart Codex.

After the package itself is updated, refresh the hook runtime:

HOOK_SETUP="$(find ~/.codex/plugins/cache -path '*/nowledge-mem/*/scripts/install_hooks.py' -print 2>/dev/null | sort | tail -1)"
if [ -z "$HOOK_SETUP" ]; then
  echo "Hook setup is still missing. Reinstall nowledge-mem@nowledge-community from Codex /plugins, then retry."
else
  python3 "$HOOK_SETUP"
fi

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.

Nowledge FS for Codex

Nowledge FS is the shared path-first layer behind Knowledge Tree. It is not a Codex-only feature. Codex can use the same layer through the MCP server with mem_fs, a path-first view across memories, threads, wiki pages, working memory, activities, sources, and artifacts.

mem_fs: recall "why did we change token refresh?" --in /memories -k 5
mem_fs: cat /memories/by-id/<id>.memory.md
mem_fs: ls /memories/by-label/auth

If MCP is not available, use the CLI:

nmem fs recall "session token strategy" --in /memories -k 5
nmem fs grep "JWT rotation" /memories
nmem fs cat /memories/by-id/<id>.memory.md

Use recall for fuzzy intent, find for metadata constraints, grep for exact strings, stat before loading large bodies, and cat after a useful path has been found. This preview release is API-backed and works in desktop, web, and remote setups; mounting it as a real folder is planned for a later phase.

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 [features] plugins = true, hooks = true, plugin_hooks = 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 enables both hook gates in ~/.codex/config.toml and keeps a host-level fallback for Codex builds that still need ~/.codex/hooks.json. If Codex shows /hooks, make sure the Nowledge Mem Stop hook is enabled there.

codex mcp list shows Not logged in

Update nmem so it matches your Mem app/server, install the CLI config from the desktop app if you use local desktop Mem, then rerun the hook setup:

pip install -U nmem-cli
nmem status
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"

Do not run codex mcp login nowledge-mem. That command is for OAuth MCP servers. Nowledge Mem uses the URL and headers generated by nmem config mcp show --host codex.

"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
• Nowledge FS
• Gemini CLI
• Claude Code
• Remote access