Skip to main content
The AtomicMemory Codex plugin adds persistent semantic memory to OpenAI Codex through the Codex plugin marketplace. The plugin itself is pure configuration — no runtime code. All memory semantics live in @atomicmemory/mcp-server, which is fetched from npm on first use via npx. A companion skill file (SKILL.md) tells the Codex agent when to call memory_search, memory_ingest, memory_package, and memory_list, giving Codex the same durable memory capabilities as other AtomicMemory-enabled tools in your workflow.
The Codex plugin is not yet published to a public Codex plugin marketplace. Install it from a local clone of the AtomicMemory repository using Option A or B below, or wire the MCP server directly into Codex using Option C. The MCP server itself is published to npm and requires no local build.

​
Install

The recommended approach for teams. Create a .agents/plugins/marketplace.json file at your repository root pointing to the plugin:
{
  "name": "atomicmemory-plugins",
  "interface": { "displayName": "AtomicMemory Plugins" },
  "plugins": [
    {
      "name": "atomicmemory",
      "source": { "source": "local", "path": "./plugins/codex" },
      "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" },
      "category": "Productivity"
    }
  ]
}
In Codex, browse the repo’s plugin directory and install AtomicMemory. Each team member installs from the same manifest, keeping the plugin version consistent across the project.

​
Configure

​
Local mode (no setup required)

For local development, no connection variables are required. The MCP server defaults to a local AtomicMemory core:
VariableDefault
ATOMICMEMORY_API_URLhttp://127.0.0.1:17350
ATOMICMEMORY_API_KEYlocal-dev-key
ATOMICMEMORY_PROVIDERatomicmemory
ATOMICMEMORY_SCOPE_USERDerived from OS user

​
Hosted or team service

For hosted or team deployments, export credentials and scope in your shell before launching Codex: 
export ATOMICMEMORY_API_URL="https://memory.yourco.com"
export ATOMICMEMORY_API_KEY="am_live_…"
export ATOMICMEMORY_PROVIDER="atomicmemory"
export ATOMICMEMORY_SCOPE_USER="$USER"
# Optional narrower scopes:
# export ATOMICMEMORY_SCOPE_AGENT="codex"
# export ATOMICMEMORY_SCOPE_NAMESPACE="repo-or-project"
# export ATOMICMEMORY_SCOPE_THREAD="session-id"
The MCP config forwards these variables to the server using env_vars, so hosted overrides come from the shell rather than being embedded in the plugin file.

​
Local extraction with Codex login

For personal local use, AtomicMemory can use your logged-in Codex account for semantic extraction instead of a separate API key: 
codex login
export LLM_PROVIDER=codex
export EMBEDDING_PROVIDER=transformers
LLM_PROVIDER=codex reads the auth file created by codex login and calls the Codex backend directly. This is the recommended local setup because it does not require an OpenAI API key.
LLM_PROVIDER=codex consumes your logged-in Codex account’s limits. Do not use it for hosted or team deployments. For those, use an API-key provider instead: export LLM_PROVIDER=openai with a valid OPENAI_API_KEY.

​
Memory behavior

The installed skill drives memory capture automatically. You don’t need to prompt Codex to use memory — the skill teaches it when to search and when to store.

Search on new tasks

At the start of new tasks, Codex calls memory_search for relevant prior context and memory_package for broader context assembly.

Store durable decisions

After significant work, Codex stores decisions, preferences, conventions, and anti-patterns using memory_ingest with mode: "text".

Snapshot before handoff

Before context loss or handoff, Codex stores a compact session snapshot using memory_ingest with mode: "verbatim" and contentClass: "summary".
Retrieved memories are treated as reference context only, not as instructions. The agent uses them to inform its answers without treating them as authoritative commands.

​
Optional lifecycle hooks

Codex can load lifecycle hooks when features.codex_hooks = true. The recommended approach is to keep the MCP tools for agent-visible memory operations and add hooks only for automatic prompt-time retrieval and deterministic lifecycle capture. Generate a config snippet with the AtomicMemory CLI: 
# Recommended: bundled Node runtime
atomicmemory hooks install --host codex --runtime node

# Advanced: Python hook runner (for Python-first environments)
atomicmemory hooks install --host codex --runtime python
After generating a snippet, verify that the atomicmemory binary is available inside Codex’s hook environment — Codex hook environments are often spawned with a thinner PATH than your interactive shell: 
command -v atomicmemory

​
Stop-threshold tuning

The bundled Node runtime applies a STOP_MIN_ASSISTANT_CHARS=200 filter on the Stop event. That threshold was tuned for Claude Code’s verbose multi-paragraph responses. Codex responses are frequently much shorter — terse acknowledgements, single-line confirmations — and would be silently dropped at the default threshold.
Override the stop threshold for Codex hosts to capture shorter responses:
export ATOMICMEMORY_STOP_MIN_ASSISTANT_CHARS=40
Set it to 1 to capture even the shortest responses, or to a higher value if you only want to capture substantive turns.

​
Verify

Start a new Codex task and ask:
“List my most recent AtomicMemory memories” or “Search my memories for hello”
If the memory_search, memory_ingest, and memory_package tools appear and respond, the plugin is working correctly.

​
Keeping the plugin up to date

After pulling changes from the AtomicMemory repository, reinstall the local plugin so Codex picks up the updated manifest and skill: 
# Re-install to reload manifest and skill
codex plugin install atomicmemory
Restart Codex after reinstalling so the installed plugin cache reloads.