From 04c456a38450115d9b42e96aa23aee2b507d5964 Mon Sep 17 00:00:00 2001 From: Philippe Mortelette Date: Tue, 21 Apr 2026 14:00:16 -0400 Subject: [PATCH] docs(codex): flip from Planned to Source available Codex CLI plugin shipped in Atomicmemory-integrations#4 as plugins/codex/ (config.toml.example + AGENTS.md + README). Update the integration page and the overview table accordingly: - Full install flow: register MCP server, paste AGENTS.md skill, verify - Status callout with pre-release footnote (SDK npm publish gate) - MCP tools table pointing at SDK reference - View source section with direct links to config.toml.example, AGENTS.md, and the shared mcp-server package - Overview table row updated to "Source available" with the Source column linking to plugins/codex --- docs/integrations/coding-agents/codex.md | 66 ++++++++++++++++++------ docs/integrations/overview.md | 2 +- 2 files changed, 51 insertions(+), 17 deletions(-) diff --git a/docs/integrations/coding-agents/codex.md b/docs/integrations/coding-agents/codex.md index c1a954e..2c3e611 100644 --- 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 = "" +``` + +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 index 8f9f266..a3cfa52 100644 --- 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).