Codex CLI
Your Codex agent remembers past decisions, finds relevant context, and learns from every session, across all your AI tools.
Packaged Codex skills
Codex gets one reusable memory package: Working Memory at session start, search when prior work matters, real thread save when you ask for it, and distillation for durable learnings.
Switch between Codex, Claude Code, Gemini, and Cursor without losing context. The Codex package gives you a reliable Working Memory bootstrap plus search, distill, and save skills. Codex still decides when to invoke those skills, so project AGENTS.md guidance matters more here than in hook-driven hosts like Claude Code or OpenClaw.
How you'll know it's working
Start a session and ask "What was I working on?" You should see your recent focus areas and priorities. You can also run $nowledge-mem:working-memory to verify that the explicit Working Memory command is available in the session. If you're setting up for the first time, run $nowledge-mem:status to check connectivity.
Before You Start
- Nowledge Mem running locally (installation) or a reachable remote Mem server
- Codex CLI installed
nmemCLI in yourPATH
Setup
Install nmem
# Option 1: uvx
curl -LsSf https://astral.sh/uv/install.sh | sh
uvx --from nmem-cli nmem --version
# Option 2: pip
pip install nmem-cliIf Nowledge Mem is already running on the same machine through the desktop app, the cleanest setup is Settings → Preferences → Developer Tools → Install CLI.
Install the plugin
Use the cache path, not the old plugin path
If you run into older instructions that copy the plugin to ~/.codex/plugins/nowledge-mem, ignore them. Current Codex builds look for the local plugin at ~/.codex/plugins/cache/local/nowledge-mem/local/.
# Clone the community repo
git clone https://github.com/nowledge-co/community.git /tmp/nowledge-community
# Copy into the Codex plugin cache
mkdir -p ~/.codex/plugins/cache/local/nowledge-mem/local
cp -R /tmp/nowledge-community/nowledge-mem-codex-plugin/. \
~/.codex/plugins/cache/local/nowledge-mem/local/
rm -rf /tmp/nowledge-communityThen add both entries to ~/.codex/config.toml:
[features]
plugins = true
[plugins."nowledge-mem@local"]
enabled = trueRestart Codex after installation.
Optionally add project-level guidance
Copy or merge the plugin's AGENTS.md into your project root for stronger default memory behavior:
cp ~/.codex/plugins/cache/local/nowledge-mem/local/AGENTS.md ./AGENTS.mdIf your project already has an AGENTS.md, merge the Nowledge section instead of overwriting. This is the clean way to make Codex do more than the basic Working Memory bootstrap on continuation-heavy repos.
Configure remote Mem when needed
nmem config client set url https://mem.example.com
nmem config client set api-key nmem_your_keynmem resolves connection settings in this order:
--api-url/--api-keyflagsNMEM_API_URL/NMEM_API_KEY~/.nowledge-mem/config.json- defaults
Repo-level install (alternative)
Instead of installing globally, you can bundle the plugin in a project repo using a 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/pluginsCreate .agents/plugins/marketplace.json:
{
"name": "local",
"plugins": [
{
"name": "nowledge-mem",
"source": {
"source": "local",
"path": "./.agents/nowledge-mem"
},
"policy": {
"installation": "INSTALLED_BY_DEFAULT"
}
}
]
}The path is relative to the repo root, not to the marketplace file. You still need the config entries in ~/.codex/config.toml (see Install step above).
Update
Replace the plugin files with the latest version:
git clone https://github.com/nowledge-co/community.git /tmp/nowledge-community-update
cp -R /tmp/nowledge-community-update/nowledge-mem-codex-plugin/. \
~/.codex/plugins/cache/local/nowledge-mem/local/
rm -rf /tmp/nowledge-community-updateThen restart Codex.
Skills
| Skill | Trigger | What it does |
|---|---|---|
$nowledge-mem:working-memory | Session start, "what am I working on" | Loads your daily Working Memory briefing |
$nowledge-mem:search-memory | Prior work, past decisions, "why did we..." | Searches memories and threads with progressive inspection |
$nowledge-mem:save-thread | "Save this session" | Real Codex transcript import via nmem t save --from codex |
$nowledge-mem:distill-memory | Decisions, learnings, procedures emerge | Proactively saves durable insights to memory |
$nowledge-mem:status | "Is Mem working?", errors | Checks server connectivity and configuration |
Direct nmem Use
The agent can also compose nmem commands directly, beyond what the skills cover:
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 codexBy 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:
- Install the plugin (see Setup above).
- Remove old prompts:
rm ~/.codex/prompts/{read_working_memory,search_memory,save_session,distill}.md - The plugin skills replace the prompts one-to-one.
| Old prompt | New skill |
|---|---|
/prompts:read_working_memory | $nowledge-mem:working-memory |
/prompts:search_memory | $nowledge-mem:search-memory |
/prompts:save_session | $nowledge-mem:save-thread |
/prompts:distill | $nowledge-mem:distill-memory |
| (none) | $nowledge-mem:status |
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 that ~/.codex/config.toml has both [features] plugins = true and [plugins."nowledge-mem@local"] enabled = true.
"plugin is not installed"
Check that the plugin files are at ~/.codex/plugins/cache/local/nowledge-mem/local/ and that .codex-plugin/plugin.json exists inside that directory.
It only reads Working Memory, but never searches or distills
That usually means Codex is following the reliable bootstrap but does not yet have strong enough repo guidance for proactive follow-through. Merge the package AGENTS.md into your project root, then retry with a continuation-style prompt such as "What did we decide before about this release?" or "Search prior work on this regression."