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 — no MCP, no network.

Install in one command 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 all 44 MCP tools via Codex's .mcp.json at http://127.0.0.1:4318/mcp so the agent can also call them 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

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

# Install the Codex CLI connector
remnic connectors install codex-cli

The connector installs the plugin to ~/.codex/plugins/, enables [features] codex_hooks = true in ~/.codex/config.toml, configures MCP, drops the phase-2 extension, and runs a health check. Opt out of the extension with --config installExtension=false.

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.
  • 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.

Install Remnic Codex plugin docs Back home