Skip to main content
Prerequisite: Install the engram binary first via Homebrew or binary download.
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

Build docs developers (and LLMs) love

Get started for freeTalk to us