Where Codex stores AGENTS.md, prompts, memories, and MCP servers

Codex (OpenAI’s coding CLI) keeps almost everything under one global ~/.codex/ folder plus AGENTS.md files in your repos. The main difference from other tools: its config — including MCP servers — is TOML, not JSON. ~ is your home directory.

At a glance

Artifact	Global	Per-project	Format
Instructions	~/.codex/AGENTS.md	AGENTS.md (project root and nested)	Markdown
Config + MCP servers	~/.codex/config.toml → [mcp_servers.<name>]	—	TOML
Custom prompts	~/.codex/prompts/*.md	—	Markdown
Memories	~/.codex/memories/*.md	—	Markdown
Rules	~/.codex/rules/*.rules	.codex/rules/*.rules	plain text
Agent definitions	~/.codex/agents/*.toml	.codex/agents/*.toml	TOML
Credentials	~/.codex/auth.json — never share or index this	—	JSON

AGENTS.md

Codex reads instructions from AGENTS.md in a documented cascade: the global ~/.codex/AGENTS.md first, then the one at the repo root, then any in subdirectories of the code it’s touching — closer files win. It’s the same cross-tool convention Cursor and Claude Code also read, so one well-written AGENTS.md can serve every tool on the team.

config.toml and MCP servers

All of Codex’s configuration lives in ~/.codex/config.toml — model, approval policy, profiles, and MCP servers as TOML tables:

[mcp_servers.quartermaster]
url = "http://localhost:8765/mcp"

[mcp_servers.some-stdio-server]
command = "npx"
args = ["-y", "some-mcp-package"]
env = { API_KEY = "..." }

TOML, not JSON

Pasting a JSON mcpServers block from another tool into config.toml silently fails. The shape is the same idea (name → command/args/env or url), but the syntax is TOML tables — this is the most common porting mistake when moving MCP configs between Codex and JSON-config tools.

The env values in server tables are where API keys end up — config.toml is secret-adjacent even though most of it is harmless.

Custom prompts

Markdown files in ~/.codex/prompts/ become reusable slash-style prompts — the filename is the prompt name, subfolders namespace it. These are the Codex equivalent of Claude Code’s commands/ directory.

Memories

Curated long-term memory lives as Markdown files in ~/.codex/memories/ — plain files you (or the agent) write and edit, loaded across sessions.

Rules

.rules files under a rules/ folder (~/.codex/rules/ globally, .codex/rules/ per project) hold always-on constraints in plain text — narrower and blunter than AGENTS.md, applied without the cascade.

auth.json

~/.codex/auth.json holds your OAuth credentials. It belongs in no backup you share, no repo, and no index — Quartermaster’s scanner hard-skips it by name, along with every other credential store it recognizes.

Seeing all of it at once

Quartermaster’s scanner indexes every location on this page into one searchable registry alongside Claude Code, Cursor, and 8 more tools — one record per MCP server parsed out of config.toml, with env values dropped and key names kept. It can convert a JSON MCP config to the TOML shape (and back), so the porting mistake above stops being manual work. See the full discovery map or the quickstart.