atomicmemory · PipDscvr · Apr 21, 2026 · Apr 21, 2026
diff --git a/docs/integrations/coding-agents/codex.md b/docs/integrations/coding-agents/codex.md
@@ -1,40 +1,111 @@
 ---
-title: Codex CLI
+title: Codex
 sidebar_position: 3
 ---
 
-# Codex CLI
+# Codex
 
-:::note[Planned]
-This integration is on the roadmap. The shared `@atomicmemory/mcp-server` already works with any MCP-compatible host — including Codex CLI — but the packaged install experience (one-line register + `AGENTS.md` template) is not yet shipped. See the manual setup below.
-:::
+Give [OpenAI Codex](https://openai.com/index/codex/) persistent, cross-session memory backed by AtomicMemory. Ships as a proper Codex plugin — installable via the Codex plugin marketplace with full interface metadata (category, default prompts, brand color) — not a hand-rolled MCP config.
 
-## Intended shape
+> **Status:** Source available — the Codex plugin manifest and MCP server spec are committed at [`plugins/codex/`](https://github.com/atomicmemory/Atomicmemory-integrations/tree/main/plugins/codex). The `npx -y @atomicmemory/mcp-server` flow below becomes live once `@atomicmemory/atomicmemory-sdk@2.0.0-alpha` publishes to npm ([why](https://github.com/atomicmemory/Atomicmemory-integrations/tree/main/packages/mcp-server#status-pre-release)).
 
-Codex CLI supports MCP servers via its config file. The AtomicMemory install will:
+## What you get
 
-1. Register `@atomicmemory/mcp-server` as an MCP server in `~/.codex/config.toml`.
-2. Ship an `AGENTS.md` snippet teaching Codex when to call `memory_search` / `memory_ingest`.
-3. Support the same config keys (`apiUrl`, `apiKey`, `provider`, `scope`) as the Claude Code plugin.
+- **Durable memory across sessions.** Codex stops forgetting what you told it yesterday.
+- **Memory protocol skill.** The shipped skill teaches Codex to retrieve memories at task start, store learnings on completion, and save session state before context loss — without you having to prompt it each time.
+- **Scope-aware retrieval.** `user` / `agent` / `namespace` / `thread` scopes are threaded through tool calls automatically.
+- **Backend-agnostic.** Point at self-hosted `atomicmemory-core` or a Mem0 service via the SDK's `MemoryProvider` model.
 
-## Manual setup (today)
+## Install
 
-Until the packaged plugin ships, you can wire the MCP server by hand:
+### Option A — Repo marketplace (recommended for teams)
 
-```toml
-# ~/.codex/config.toml
-[mcp_servers.atomicmemory]
-command = "npx"
-args = ["-y", "@atomicmemory/mcp-server"]
+Drop a `.agents/plugins/marketplace.json` at your repo root:
 
-[mcp_servers.atomicmemory.env]
-ATOMICMEMORY_API_URL = "https://memory.yourco.com"
-ATOMICMEMORY_API_KEY = "am_live_…"
+```json
+{
+  "name": "atomicmemory-plugins",
+  "interface": { "displayName": "AtomicMemory Plugins" },
+  "plugins": [
+    {
+      "name": "atomicmemory",
+      "source": { "source": "local", "path": "./plugins/codex" },
+      "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" },
+      "category": "Productivity"
+    }
+  ]
+}
 ```
 
-Then paste the skill body from the [Claude Code integration](/integrations/coding-agents/claude-code#the-skill) into your `AGENTS.md`.
+(Copy-pasteable template: [`plugins/codex/marketplace.example.json`](https://github.com/atomicmemory/Atomicmemory-integrations/blob/main/plugins/codex/marketplace.example.json).)
+
+In Codex, browse the repo's plugin directory and install AtomicMemory.
+
+### Option B — Personal marketplace
+
+Same JSON but at `~/.agents/plugins/marketplace.json`, with `source.path` pointing to wherever you cloned the integrations repo.
+
+### Option C — Manual MCP configuration
+
+Skip the plugin system and register the MCP server directly using the contents of [`.codex-mcp.json`](https://github.com/atomicmemory/Atomicmemory-integrations/blob/main/plugins/codex/.codex-mcp.json). Skips the skill — you'll need to decide when to call memory tools yourself.
+
+## Configure
+
+The MCP server reads scope and credentials from environment variables:
+
+```bash
+export ATOMICMEMORY_API_URL="https://memory.yourco.com"
+export ATOMICMEMORY_API_KEY="am_live_…"
+export ATOMICMEMORY_PROVIDER="atomicmemory"        # or "mem0"
+export ATOMICMEMORY_SCOPE_USER="pip"
+# Optional narrower scopes:
+# export ATOMICMEMORY_SCOPE_AGENT="codex"
+# export ATOMICMEMORY_SCOPE_NAMESPACE="<repo-or-project>"
+# export ATOMICMEMORY_SCOPE_THREAD="<session-id>"
+```
+
+At least one `ATOMICMEMORY_SCOPE_*` must be set — the server rejects scopeless requests.
+
+## Verify
+
+Start a new Codex task and try:
+
+> *"Search my memories for recent project decisions"*
+> *"Remember that we always use pnpm in this repo"*
+
+If the `memory_search` / `memory_ingest` / `memory_package` tools appear and respond, you're set.
+
+## MCP tools exposed
+
+Same three tools as the Claude Code and OpenClaw plugins:
+
+| Tool | Maps to | Purpose |
+|---|---|---|
+| `memory_search` | `MemoryClient.search` | Semantic retrieval with scope filters |
+| `memory_ingest` | `MemoryClient.ingest` | AUDN-mutating ingest (text or messages) |
+| `memory_package` | `MemoryClient.package` | Token-budgeted context package |
+
+See the [SDK reference overview](/sdk/api/overview) for the canonical request / response shapes.
+
+## Memory protocol skill
+
+The shipped skill tells Codex to:
+
+- **On every new task:** call `memory_search` with a task-related query to load relevant prior context.
+- **After significant work:** store key learnings via `memory_ingest` — decisions, strategies that worked, failed approaches, user preferences, conventions.
+- **Before context loss:** ingest a comprehensive session summary (goal, accomplished, decisions, files touched, current state).
+
+View the full skill body: [`plugins/codex/skills/atomicmemory/SKILL.md`](https://github.com/atomicmemory/Atomicmemory-integrations/blob/main/plugins/codex/skills/atomicmemory/SKILL.md).
+
+## View source
+
+- [`plugins/codex/.codex-plugin/plugin.json`](https://github.com/atomicmemory/Atomicmemory-integrations/blob/main/plugins/codex/.codex-plugin/plugin.json) — Codex plugin manifest with interface metadata
+- [`plugins/codex/.codex-mcp.json`](https://github.com/atomicmemory/Atomicmemory-integrations/blob/main/plugins/codex/.codex-mcp.json) — MCP server spec
+- [`plugins/codex/skills/atomicmemory/SKILL.md`](https://github.com/atomicmemory/Atomicmemory-integrations/blob/main/plugins/codex/skills/atomicmemory/SKILL.md) — memory protocol skill
+- [`plugins/codex/marketplace.example.json`](https://github.com/atomicmemory/Atomicmemory-integrations/blob/main/plugins/codex/marketplace.example.json) — marketplace.json template
+- [`packages/mcp-server/`](https://github.com/atomicmemory/Atomicmemory-integrations/tree/main/packages/mcp-server) — the shared MCP server
 
 ## See also
 
-- [Claude Code integration](/integrations/coding-agents/claude-code)
-- [MCP server reference](https://github.com/atomicmemory/Atomicmemory-integrations)
+- [Claude Code integration](/integrations/coding-agents/claude-code) — sibling plugin sharing the same MCP server
+- [Platform scope model](/platform/scope)
diff --git a/docs/integrations/overview.md b/docs/integrations/overview.md
@@ -22,7 +22,7 @@ Agents that edit code, run shells, and drive browsers need memory that survives
 |---|---|---|---|
 | [Claude Code](/integrations/coding-agents/claude-code) | 🔧 Source available¹ | Claude Code plugin (`plugin.json` + `SKILL.md`) | [`plugins/claude-code`](https://github.com/atomicmemory/Atomicmemory-integrations/tree/main/plugins/claude-code) |
 | [OpenClaw](/integrations/coding-agents/openclaw) | 🔧 Source available¹ | ClawHub (`openclaw.plugin.json` + `skill.yaml`) | [`plugins/openclaw`](https://github.com/atomicmemory/Atomicmemory-integrations/tree/main/plugins/openclaw) |
-| [Codex CLI](/integrations/coding-agents/codex) | 🛠️ Planned | MCP server registration + `AGENTS.md` | — |
+| [Codex](/integrations/coding-agents/codex) | 🔧 Source available¹ | Codex plugin (`.codex-plugin/` + `.codex-mcp.json` + marketplace) | [`plugins/codex`](https://github.com/atomicmemory/Atomicmemory-integrations/tree/main/plugins/codex) |
 | [Cursor](/integrations/coding-agents/cursor) | 🛠️ Planned | MCP server + `.cursor/rules` | — |
 
 ¹ Plugin manifest and skill files are committed to the integrations repo. The documented `npx -y @atomicmemory/mcp-server` install path becomes live when `@atomicmemory/atomicmemory-sdk@2.0.0-alpha` publishes to npm — see [the mcp-server status note](https://github.com/atomicmemory/Atomicmemory-integrations/tree/main/packages/mcp-server#status-pre-release).