Substrate Memory for Codex and ChatGPT Work
One package serves ChatGPT Work, Codex in the ChatGPT desktop app, and Codex CLI.
What you get
- Automatic recall: relevant facts from your knowledge base arrive as context each turn. Use them naturally.
- Automatic capture: prompts, tool activity, and answers are saved per turn for future recall.
- Explicit memory: ask the agent to remember or forget a fact.
- Catch-up sync: if some turns were not saved yet, the agent imports them from the local transcript on request.
- Past conversations: right after connecting, the agent offers once to import your earlier Codex sessions on this computer (Import all / Let me pick / Not now).
Install
ChatGPT / Codex app
- Open Plugins and add the marketplace from the GitHub repo
Substrate-memory/Substrate-memory-plugins(workspace admins can import a GitHub marketplace for the team; a personal marketplace file lives at~/.agents/plugins/marketplace.json). - Install Substrate Memory.
- Start a new chat.
Codex CLI
Use the /plugins browser, or run:
codex plugin marketplace add Substrate-memory/Substrate-memory-plugins
codex plugin add substrate-codex@substrate-marketplace
codex mcp add substrate-memory --url <the url in mcp.json>
codex mcp login substrate-memory
login prints the approval link. Choose Approve connection; the command
returns. The agent then installs the hooks. Then approve Substrate's hooks once: in the
Codex app, in its hooks settings [TODO: exact menu label]; in the terminal, /hooks.
Start a new session. Its first reply confirms the connection and offers the import once.
Sign-in flow
Install → Sign in → Review → Approve connection → Connected to Substrate.
The agent starts sign-in (Connect your agent to Substrate). Sign in,
review the connection, choose Approve connection. The agent confirms with
an authenticated memory_search check, reports Connected to Substrate.,
and in the first reply of the new session offers the import once:
I found 42 past conversations on this computer (610 turns, 2 Aug to 7 Oct 2026). Import them into Substrate? Import all / Let me pick / Not now
Import all uploads everything except the current conversation, in the background, straight from the local script to Substrate with a short-lived import-only ticket; your history never passes through the chat. The agent reports progress and a final line: how many conversations were imported, and that Substrate is reading them now. Not now is remembered; ask "import my past conversations" any time.
Hook approval step
Automatic recall and capture run as Codex hooks. Codex 0.154 does not load a
plugin's own hooks from a local install, so $substrate-connect adds the
Substrate hook entries to your Codex hook file, $CODEX_HOME/hooks.json
(default ~/.codex/hooks.json). It backs the file up once and changes only
its own entries. The entries run a stable entry point in $CODEX_HOME/substrate/,
so a plugin update does not change them and needs no new approval.
Approve the Substrate hooks once, with the one step that fits your Codex:
- Codex app: open its hooks settings and approve the Substrate entries [TODO: exact menu label, from Pavel].
- Terminal: run
/hooksand trust the Substrate entries.
Until you approve them, Codex skips automatic capture and recall still works when you ask.
The hooks call the substrate-memory MCP server by name, so connect also registers it
(codex mcp add substrate-memory --url <the url in mcp.json>) when it is
missing.
To disconnect, run $substrate-connect and ask for the disconnect step, or run
python3 <plugin dir>/scripts/codex_user_hooks.py remove yourself. This removes
exactly the Substrate entries, their approval records and the stable entry point.
Run it before codex plugin remove substrate-codex, which does not remove them.
What is captured
Prompts, tool activity, and answers per turn, plus session boundaries (start, resume, clear, compact). Captures are redacted on the way in: passwords, tokens, and keys are replaced before storage.
Privacy
- Memory tools never receive pasted secrets; the agent redacts them first.
memory_forgetsuppresses a fact from normal recall on your explicit request.- History import only runs after you choose it, only from transcripts on your own machine, and is redacted on your machine and again on the server.
Known limits
- There is no session-end hook: Codex cannot call memory tools when a session ends, so the server seals idle sessions after 30 minutes.
- Plugins installed on the web do not deploy scripts, so the sync and import scripts require the desktop app or the CLI.
- The import upload needs network access from Codex's sandbox; Codex asks you to allow it.
- At session launch, the start hook can run before the memory server is connected; the boundary is then picked up on the first turn.
Troubleshooting
- Tools absent after install: start a new session so the plugin loads.
- Sign-in loops: complete Approve connection in the browser, return to
the agent, and ask it to verify with
memory_search. [substrate] ... not saved yet: ask the agent to run$substrate-sync.- Still stuck: ask the agent to run
$substrate-connectand follow its steps.