Codex Setup

Auto-config with compaction recovery for Codex AI coding agent

Prerequisite: Install the engram binary first via Homebrew or binary download.

One-Command Setup (Recommended)

engram setup codex

This command does three things:

1. Registers [mcp_servers.engram] in ~/.codex/config.toml (Windows: %APPDATA%\codex\config.toml)
2. Writes ~/.codex/engram-instructions.md with the Engram Memory Protocol
3. Writes ~/.codex/engram-compact-prompt.md for compaction recovery

1. Install engram binary

   brew install gentleman-programming/tap/engram
   
2. Run setup command

   engram setup codex
   

   Output:

   ✓ Registered MCP server in ~/.codex/config.toml
   ✓ Wrote Memory Protocol to ~/.codex/engram-instructions.md
   ✓ Wrote compaction prompt to ~/.codex/engram-compact-prompt.md
   
3. Verify installation

   codex "list memory tools"
   

   The agent should list mem_save, mem_search, etc.

What Gets Configured

MCP Server Registration

Adds to ~/.codex/config.toml:

model_instructions_file = "~/.codex/engram-instructions.md"
experimental_compact_prompt_file = "~/.codex/engram-compact-prompt.md"

[mcp_servers.engram]
command = "engram"
args = ["mcp"]

Memory Protocol Instructions

Writes to ~/.codex/engram-instructions.md:

## Engram Persistent Memory — Protocol

You have access to Engram, a persistent memory system that survives across sessions and compactions.

### WHEN TO SAVE (mandatory — not optional)

Call `mem_save` IMMEDIATELY after any of these:
- Bug fix completed
- Architecture or design decision made
- Non-obvious discovery about the codebase
...

Compaction Recovery Prompt

Writes to ~/.codex/engram-compact-prompt.md:

FIRST ACTION REQUIRED after compaction:

1. Call `mem_session_summary` with the compacted summary content
2. Call `mem_context` to recover previous session context
3. Only then continue working

This preserves what was accomplished before compaction.

Codex injects this into the compaction output, ensuring the new agent persists the summary.

Manual Setup (Alternative)

If you prefer to configure manually:

Add MCP Server

Edit ~/.codex/config.toml (Windows: %APPDATA%\codex\config.toml):

[mcp_servers.engram]
command = "engram"
args = ["mcp"]

Add Memory Protocol

Create ~/.codex/engram-instructions.md and copy the Memory Protocol from DOCS.md.

Then point to it in config.toml:

model_instructions_file = "~/.codex/engram-instructions.md"

Add Compaction Recovery

Create ~/.codex/engram-compact-prompt.md:

FIRST ACTION REQUIRED after compaction:
1. Call `mem_session_summary` with the compacted summary content
2. Call `mem_context` to recover previous session context
3. Only then continue working

Then point to it in config.toml:

experimental_compact_prompt_file = "~/.codex/engram-compact-prompt.md"

Compaction Recovery

Codex uses experimental_compact_prompt_file to inject instructions after compaction.

When Codex compacts (summarizes long conversations), it:

1. Generates a compacted summary
2. Injects the content of engram-compact-prompt.md
3. The new agent reads: “FIRST ACTION REQUIRED: Call mem_session_summary…”
4. The agent saves the summary to engram, preserving work from before compaction

This prevents memory loss across compaction events.

Platform-Specific Notes

Windows

engram setup codex writes to:

• MCP config: %APPDATA%\codex\config.toml
• Instructions: %APPDATA%\codex\engram-instructions.md
• Compaction prompt: %APPDATA%\codex\engram-compact-prompt.md

macOS / Linux

engram setup codex writes to:

• MCP config: ~/.codex/config.toml
• Instructions: ~/.codex/engram-instructions.md
• Compaction prompt: ~/.codex/engram-compact-prompt.md

Memory Protocol Behavior

With the Memory Protocol in engram-instructions.md, the agent:

• Saves proactively after bugfixes, decisions, discoveries, patterns
• Searches reactively when you say “remember” or “what did we do”
• Searches proactively when starting work that might overlap past sessions
• Closes sessions with mem_session_summary before saying “done”
• Recovers state after compaction via experimental_compact_prompt_file

No manual prompting needed — the protocol is always active.

Troubleshooting

MCP tools not available

Check MCP server registration:

# macOS/Linux
cat ~/.codex/config.toml | grep engram

# Windows
type %APPDATA%\codex\config.toml | findstr engram

Agent doesn’t use memory

Check that instruction files exist:

# macOS/Linux
ls ~/.codex/engram-instructions.md
ls ~/.codex/engram-compact-prompt.md

# Windows
dir %APPDATA%\codex\engram-instructions.md
dir %APPDATA%\codex\engram-compact-prompt.md

Server not running

Manually start the server:

engram serve

Codex will connect via stdio, but the HTTP API is useful for debugging.

Next Steps

• Learn about the Memory Protocol
• Explore MCP Tools
• Set up Git Sync for team memory sharing