From b8a4e8f6ebff0c5522cb7d8c99dc62950236e17e Mon Sep 17 00:00:00 2001 From: Philippe Mortelette Date: Tue, 21 Apr 2026 17:57:34 -0400 Subject: [PATCH] docs(codex): flip from Planned to Source available (proper plugin format) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Follow-up to the redone Codex plugin in Atomicmemory-integrations#5. The earlier Codex plugin used ~/.codex/config.toml; the real plugin format is .codex-plugin/plugin.json + .codex-mcp.json + a marketplace.json manifest (matching how mem0-plugin ships). Rewrite the doc page around that: - Three install options: repo marketplace (recommended), personal marketplace, manual MCP config - Configure section with the env-var surface mirroring packages/mcp-server/src/config.ts - Memory protocol skill section summarizing the shipped SKILL.md (on new task / after significant work / before context loss) - MCP tools table pointing at SDK reference - View source section with direct links to plugin.json, .codex-mcp.json, SKILL.md, and marketplace.example.json - Overview table: Codex row flipped to "🔧 Source available" with the correct install surface label and source link --- docs/integrations/coding-agents/codex.md | 117 ++++++++++++++++++----- docs/integrations/overview.md | 2 +- 2 files changed, 95 insertions(+), 24 deletions(-) diff --git a/docs/integrations/coding-agents/codex.md b/docs/integrations/coding-agents/codex.md index c1a954e..83e7c9d 100644 --- 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="" +# export ATOMICMEMORY_SCOPE_THREAD="" +``` + +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 index 8f9f266..20444b4 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](/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).