title: "Project Memory — Codex CLI" tested_with: codex-cli: "0.2.x" last_updated: 2026-03-21 status: proven difficulty: beginner prerequisites: [01-your-first-hour]

Project Memory in Codex CLI

Codex CLI uses AGENTS.md as its primary project memory system. AGENTS.md is an open standard — not proprietary to any single tool — designed to give AI coding agents the context they need about your project.

AGENTS.md: The Open Standard

AGENTS.md emerged as a community-driven convention and is now under Linux Foundation stewardship. Over 60,000 repositories have adopted the format, making it the most widely supported project memory standard in the ecosystem.

The core idea is simple: a Markdown file in your repository that any AI coding agent can read to understand your project's conventions, architecture, and workflows. While Codex CLI has first-class support, the format is intentionally tool-agnostic — other agents and tools can (and do) consume it.

This matters for two reasons. First, your investment in writing AGENTS.md is portable. If you switch tools or add new ones, your project memory travels with you. Second, the standard evolves based on input from a broad community of practitioners, not a single vendor's roadmap.

Where AGENTS.md Lives and How Codex Loads It

AGENTS.md follows the same hierarchical pattern described in the concepts module:

• Project root (./AGENTS.md) — loaded in every session. This is your primary configuration file.
• Subdirectories (./src/api/AGENTS.md) — loaded when the agent works in or references that directory. Use these for module-specific guidance.

When you start a Codex CLI session, the tool automatically:

1. Reads AGENTS.md from your project root
2. Discovers and reads any AGENTS.md files in relevant subdirectories as the agent navigates your codebase
3. Merges instructions, with more specific (deeper) files taking precedence over general (root) ones

No configuration flag or import statement is needed. If the file exists and is named correctly, Codex reads it.

Note: The filename must be exactly AGENTS.md (uppercase). Codex CLI will not recognize agents.md or Agents.md.

Anatomy of a Good AGENTS.md

The structure closely mirrors what works for any project memory file. A solid AGENTS.md covers these sections:

Project Overview

Ground the agent with a brief technical description.

## Project Overview

RecipeBox is a Django 5.0 recipe sharing platform with a React Native mobile app. Monorepo managed with Nx. PostgreSQL database, Redis for caching, Celery for background jobs.

Architecture

Map the territory for the agent.

## Architecture

- `apps/api/` — Django REST Framework application
- `apps/mobile/` — React Native (Expo) mobile app
- `libs/shared/` — Shared TypeScript types and utilities
- `libs/db/` — Database models, migrations, and fixtures
- `tools/` — Nx generators and CI scripts

Conventions

Define the rules that keep generated code consistent with your codebase.

## Conventions

- Python: Black formatter, isort for imports, type hints required on all public functions
- Django: fat models, thin views — business logic lives in model methods and managers
- React Native: functional components only, use React Navigation for routing
- All API endpoints must have OpenAPI docstrings
- Test files live next to the code they test: `foo.py` → `foo_test.py`

Common Tasks

Give the agent the commands it needs to build, test, and verify its work.

## Common Tasks

- **Install all**: `npm install` (Nx handles workspace dependencies)
- **API dev server**: `nx serve api`
- **Mobile dev**: `nx start mobile`
- **Run all tests**: `nx run-many --target=test`
- **Run API tests**: `nx test api`
- **Lint**: `nx run-many --target=lint`
- **DB migrations**: `cd apps/api && python manage.py makemigrations && python manage.py migrate`

What NOT to Do

Prevent the agent from repeating known mistakes.

## What NOT to Do

- Do NOT use Django's `JSONField` — use our typed JSON column wrapper in `libs/db/fields.py`
- Do NOT install packages globally — always scope to the correct Nx project
- Do NOT use `any` in TypeScript shared libraries
- Do NOT write raw SQL — use Django ORM querysets

AGENTS.md vs. CLAUDE.md: Similarities and Differences

If you work with both Codex CLI and Claude Code, you may wonder how these two files relate.

The content you put in both files is effectively the same: project overview, architecture, conventions, tasks, anti-patterns. The difference is which tool reads which file.

Note: Both files can coexist in the same repository. If your team uses both Codex CLI and Claude Code, maintain both files. See the section on coexistence below.

The .codex/ Directory

Codex CLI uses a .codex/ directory for project-level configuration:

• .codex/config.yaml — project-wide settings including default model, approval mode, and environment variables the agent can access.
• .codex/config.local.yaml — personal overrides (add to .gitignore).

A typical .codex/config.yaml:

# Adapt this by: setting your preferred model and approval mode.
model: o4-mini
approval_mode: suggest

Available approval modes control how much autonomy the agent gets:

Warning: full-auto mode runs commands in a sandboxed environment, but you should still understand what the agent is doing. Start with suggest or auto-edit until you are comfortable with the agent's behavior on your project.

Codex-Specific Configuration

Beyond AGENTS.md, Codex CLI supports additional configuration that shapes agent behavior:

Environment Variables

You can specify which environment variables the agent can access in .codex/config.yaml:

# Adapt this by: listing only the variables your agent needs. Never expose secrets unnecessarily.
env:
  NODE_ENV: development
  DATABASE_URL: postgresql://localhost:5432/myapp_dev

Project-Level Instructions in Config

For short instructions that do not warrant a full AGENTS.md file, you can embed them directly in the config:

# Adapt this by: using this for brief, project-wide instructions only.
instructions: "Always run tests after making changes. Use conventional commit messages."

For anything longer than a sentence or two, use AGENTS.md instead — it is easier to read, review, and version.

Starter AGENTS.md Template

Copy this into your project root and fill in the details. Five minutes of effort, sessions of payoff.

# AGENTS.md

## Project Overview

<!-- One to two sentences: what is this project, what tech stack, any key context. -->

## Architecture

<!-- List 4-6 key directories and their purpose. -->

## Conventions

<!-- List 3-5 coding conventions that matter most in this project. -->

## Common Tasks

- **Install**: `<!-- your install command -->`
- **Dev server**: `<!-- your dev command -->`
- **Run tests**: `<!-- your test command -->`
- **Lint**: `<!-- your lint command -->`

## What NOT to Do

<!-- List 2-3 project-specific anti-patterns. -->

Coexisting: AGENTS.md and CLAUDE.md in the Same Repo

If your team uses both Codex CLI and Claude Code, you have three options:

Option 1: Maintain Both Files Separately

Keep AGENTS.md and CLAUDE.md at your project root, each with the same content. This is the simplest approach but creates a maintenance burden — you must update both files when conventions change.

Option 2: One Primary, One Minimal

Choose one file as your source of truth (whichever tool your team uses more) and make the other a brief pointer:

<!-- AGENTS.md (if CLAUDE.md is primary) -->
# AGENTS.md

See CLAUDE.md in this directory for full project conventions. This file exists for Codex CLI compatibility.

## Quick Reference

- **Run tests**: `pnpm test`
- **Dev server**: `pnpm dev`

Option 3: Shared Content via Symlink

On Unix-like systems, you can symlink one to the other:

# Adapt this by: choosing which filename to keep as the real file.
ln -s CLAUDE.md AGENTS.md

This ensures both files always have identical content. The trade-off is that you cannot include tool-specific instructions in either file, since both tools will read the same content.

Note: For most teams, Option 1 or Option 2 works best. The small duplication cost is usually worth the clarity of having each tool read its own file.

Testing Your AGENTS.md

After creating or updating your AGENTS.md, verify it works:

1. Start a new Codex CLI session (previous sessions will not pick up changes mid-conversation).
2. Ask the agent to describe your project conventions:

   What are the coding conventions for this project?
   

3. Verify the response matches your AGENTS.md. If the agent gives generic advice, check your filename and file location.
4. Run a small coding task and inspect whether the output follows your conventions without you needing to mention them.

Quick Reference