atomicmemory · PipDscvr · Apr 21, 2026
diff --git a/docs/integrations/coding-agents/codex.md b/docs/integrations/coding-agents/codex.md
@@ -5,36 +5,70 @@ sidebar_position: 3
 
 # Codex CLI
 
-:::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 CLI](https://github.com/openai/codex) persistent, cross-session memory backed by AtomicMemory. Codex registers MCP servers through `~/.codex/config.toml`, so the integration ships two small pieces: a config block that spawns the shared `@atomicmemory/mcp-server`, and an `AGENTS.md` skill body that teaches Codex when to call memory tools.
 
-## Intended shape
+> **Status:** Source available — the config snippet and AGENTS.md skill body 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.
+- **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:
+### 1. Register the MCP server
+
+Append the block below to `~/.codex/config.toml` (or copy from [`plugins/codex/config.toml.example`](https://github.com/atomicmemory/Atomicmemory-integrations/blob/main/plugins/codex/config.toml.example)):
 
 ```toml
-# ~/.codex/config.toml
 [mcp_servers.atomicmemory]
 command = "npx"
 args = ["-y", "@atomicmemory/mcp-server"]
 
 [mcp_servers.atomicmemory.env]
-ATOMICMEMORY_API_URL = "https://memory.yourco.com"
-ATOMICMEMORY_API_KEY = "am_live_…"
+ATOMICMEMORY_API_URL        = "https://memory.yourco.com"
+ATOMICMEMORY_API_KEY        = "am_live_…"
+ATOMICMEMORY_PROVIDER       = "atomicmemory"
+ATOMICMEMORY_SCOPE_USER     = "pip"
+# ATOMICMEMORY_SCOPE_NAMESPACE = "<repo-or-project>"
+```
+
+At least one scope field (`user` / `agent` / `namespace` / `thread`) must be set — the server rejects scopeless requests.
+
+### 2. Add the skill to AGENTS.md
+
+Paste [`plugins/codex/AGENTS.md`](https://github.com/atomicmemory/Atomicmemory-integrations/blob/main/plugins/codex/AGENTS.md) into your project's `AGENTS.md` (or user-level `~/.codex/AGENTS.md`). This teaches Codex when to call `memory_search`, `memory_ingest`, and `memory_package`, and what to skip.
+
+### 3. Verify
+
+Start `codex` — it should list `atomicmemory` as an available MCP server. Ask something that exercises memory:
+
+```
+you> remember that we always use pnpm in this repo
+codex> [calls memory_ingest]
+       Saved.
 ```
 
-Then paste the skill body from the [Claude Code integration](/integrations/coding-agents/claude-code#the-skill) into your `AGENTS.md`.
+## MCP tools exposed
+
+Same three tools as the Claude Code plugin:
+
+| 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.
+
+## View source
+
+- [`plugins/codex/config.toml.example`](https://github.com/atomicmemory/Atomicmemory-integrations/blob/main/plugins/codex/config.toml.example) — the MCP server block
+- [`plugins/codex/AGENTS.md`](https://github.com/atomicmemory/Atomicmemory-integrations/blob/main/plugins/codex/AGENTS.md) — the agent-facing skill body
+- [`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 CLI](/integrations/coding-agents/codex) | 🔧 Source available¹ | MCP server registration + `AGENTS.md` | [`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).