Codex CLI integration

Codex CLI, now with real memory.

@remnic/plugin-codex is the native Remnic plugin for OpenAI's Codex CLI. Three lifecycle hooks handle recall and observation; a drop-in memories_extensions/remnic/instructions.md file teaches Codex's phase-2 consolidation sub-agent how to read Remnic memory files directly from disk, with no MCP and no network.

Install Package on npm Full docs

How it plugs in

Hooks, not tools

Three hooks (SessionStart, UserPromptSubmit, and Stop) handle recall and observation without consuming Codex's tool-call budget.

MCP over HTTP

Remnic registers its full MCP tool surface via Codex's .mcp.json at http://127.0.0.1:4318/mcp so the agent can also call the tools explicitly.

Phase-2 extension

The connector drops <codex_home>/memories_extensions/remnic/instructions.md so Codex's sandboxed consolidation sub-agent auto-discovers Remnic on disk.

Skills

Six skill folders ship with the plugin: remnic-memory-workflow, remnic-recall, remnic-remember, remnic-search, remnic-entities, remnic-status.

Install

Three steps. Start the daemon, mint the connector, then load the plugin.

# 1. Install Remnic and start the daemon
npm install -g @remnic/cli && remnic daemon install

# 2. Mint a token and materialize the phase-2 extension
remnic connectors install codex-cli

# 3. Install the plugin, then load it through Codex
npm install -g @remnic/plugin-codex

Step 2 writes Remnic connector state and a bearer token, and materializes ~/.codex/memories_extensions/remnic/instructions.md for Codex's phase-2 consolidation sub-agent. It does not edit ~/.codex/config.toml or load the plugin. Add the MCP block below, set REMNIC_AUTH_TOKEN, then load the plugin through Codex's plugin loader and approve the hooks with /hooks on first use. Skip the extension with the codex.installExtension config flag.

Codex Marketplace

Remnic is available in the Codex marketplace. If you prefer a one-liner that bundles plugin install with marketplace metadata: 

codex marketplace add joshuaswarren/remnic

The marketplace manifest lives at marketplace.json in the repo root.

MCP alternative (manual)

If you'd rather wire Codex to Remnic manually, start the server and add an MCP entry to ~/.codex/config.toml: 

export REMNIC_AUTH_TOKEN="$(openssl rand -base64 32)"
npx remnic-server --host 127.0.0.1 --port 4318 \
  --auth-token "$REMNIC_AUTH_TOKEN"
[mcp_servers.remnic]
url = "http://127.0.0.1:4318/mcp"
bearer_token_env_var = "REMNIC_AUTH_TOKEN"

That gives Codex access to every Remnic MCP tool (recall, store, entity lookup, and the rest), but without the automatic hooks. See the Codex CLI guide for session-start hooks, cross-machine setup, and Tailscale-based deployments.

What happens on each turn

  • SessionStart: query Remnic with project context, inject as additionalContext.
  • UserPromptSubmit: recall with the prompt text (minimal mode, 20s timeout), inject top matches.
  • PostToolUse: observe bash executions and file changes in the background.
  • PreCompact: before Codex compacts the conversation, flush the observe buffer so nothing is lost.
  • Stop: on final turn, flush remaining messages and clean up the cursor file.

Codex has no SessionEnd event. The Stop hook detects stop_hook_active: false to identify the final turn.

Project-scoped and procedural memory

Codex's session-start hook detects your git repository and scopes memory to that project, so context from one repo does not bleed into another. Global facts still surface across projects. Remnic also captures procedural memory, multi-step runbooks distilled from your work, on by default outside the conservative preset. See the coding agents page for the full model.

Install in 60 seconds Star on GitHub All integrations