Skip to content

substrate-memory/substrate-codex

v0.11.4MIT

Substrate long-term memory for ChatGPT Work, Codex in the ChatGPT desktop app, and Codex CLI.

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

  1. 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).
  2. Install Substrate Memory.
  3. 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 /hooks and 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_forget suppresses 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-connect and follow its steps.