codex-substrate-memory

Public OpenAI Codex CLI plugin for durable Substrate organizational memory. It provides seven MCP tools, completed-turn capture through Codex's global notify hook, and a stale-rollout sweeper that emits content-free session boundaries.

Security requirement: ~/.codex/config.toml is world-readable plaintext. The Substrate API key must come from the Codex process environment. Never put SUBSTRATE_API_KEY in config.toml, an [mcp_servers.substrate.env] table, a command argument, or this repository.

Install

Python 3.11 or newer is required.

python -m pip install codex-substrate-memory

For a source checkout:

python -m pip install -e .

Set the service URL and API key in the environment that launches Codex:

SUBSTRATE_API_URL=https://api.substrate.example
SUBSTRATE_API_KEY=<set-in-process-environment>

Wire Codex

Codex plugins do not declare MCP servers in .codex-plugin/plugin.json. MCP registration lives only in the user's ~/.codex/config.toml.

Codex also has only one global notify setting. If no notify hook exists, use:

notify = ["python", "-m", "codex_memory.notify"]

[mcp_servers.substrate]
command = "python"
args = ["-m", "codex_memory.server"]
startup_timeout_sec = 30

If a notify hook already exists, preserve it with the chainer. Replace the placeholders with the existing command and arguments in the same order:

notify = ["python", "-m", "codex_memory.notify", "--chain", "<original-exe>", "<original-arg-1>"]

[mcp_servers.substrate]
command = "python"
args = ["-m", "codex_memory.server"]
startup_timeout_sec = 30

substrate-codex configure reads the current TOML and prints the appropriate snippet. It is advisory and does not modify the file. substrate-codex configure --write is the explicit opt-in mutation path and creates a backup first.

Tools

Tool	Purpose
substrate_search	Search organizational memory and return cited memory cards.
substrate_read	Read one wiki page by repository-relative path.
substrate_query	Ask a cited question across Substrate memory.
substrate_ingest	Submit intended text for asynchronous ingestion.
substrate_remember	Record a durable fact or decision.
substrate_sync	Sweep stale rollouts and flush the local spool.
substrate_status	Report content-free local configuration and delivery status.

Capture model

Completed turns

Codex appends one JSON argument to the global notify command after an agent-turn-complete event. codex_memory.notify extracts input-messages, last-assistant-message, turn_id, and cwd; applies the shared bounded redaction and event builder; durably queues the turn; and attempts delivery. Capture failures never block Codex. With --chain, the original notify command receives the identical final JSON argument and its exit code is propagated.

Session end

Codex does not emit a session-end notification. codex_memory.rollout therefore scans ~/.codex/sessions/**/rollout-*.jsonl for rollouts older than 15 minutes. It tolerates truncated final lines, unreadable files, and unknown record types. For each stale rollout it queues one deterministic, content-free session_end event containing counts and a message-index boundary only, then persists a one-shot checkpoint marker. The sweeper runs from substrate_sync and substrate-codex sync.

Codex limitations

1. notify is a single global setting. Installing this plugin must not silently replace another hook. Use the documented --chain form to preserve the original executable, arguments, final JSON argument, and exit code.
2. notify has no session-end event. Session closure is inferred only after a rollout file has been inactive past the sweeper threshold. It is not instantaneous.

Privacy boundary

• API credentials are read from process environment variables only.
• Captured messages are normalized, redacted, bounded, and spooled before network delivery.
• The session-end sweeper sends no message text, rollout path, or working directory.
• Local state defaults to ~/.substrate/codex_memory; SUBSTRATE_STATE_HOME overrides the parent directory for isolated environments.
• Redaction cannot recognize every sensitive statement. Use a trusted Substrate server and protect local state.

CLI

substrate-codex serve
substrate-codex status
substrate-codex sync
substrate-codex configure

python -m codex_memory.server is the direct MCP entry point.

Repository map

• .codex-plugin/plugin.json — Codex plugin metadata; intentionally no MCP registration.
• skills/substrate-memory/SKILL.md — agent operating guidance.
• src/codex_memory/ — Codex notify, rollout, configuration, CLI, and MCP integration.
• src/substrate_capture/ — frozen shared capture core; do not edit.
• docs/config-snippet.toml — placeholder-only configuration example.
• tests/ — shared-core and Codex integration tests.
• scripts/ — vendor-manifest and public-plugin safety verification.

Verification scope

The repository test suite exercises the notify shape and chainer, tolerant rollout parsing, one-shot session-end emission, configuration safety, and an in-memory MCP initialize/list/call round trip. It does not claim a live Codex-to-production-Substrate end-to-end run.

License

MIT © 2026 Sightline Technologies Inc.