Native integration · Shipped and tested

Mneme HQ + Codex CLI

Q: Which Codex CLI mutations are blocked before execution?

Native apply_patch Add File and Update File operations, including bundled multi-operation patches: all operations in a bundle are evaluated, and any deterministic violation denies the entire call before execution.

Q: Are shell and script-driven writes governed?

Not pre-execution. Shell and script-driven writes are a known coverage gap before execution because their path and content exist only inside command text. The Stop hook audits every artifact the session changed as a complete file, which is the backstop.

Q: Does Mneme protect file deletions in Codex CLI?

No. apply_patch Delete File is recognized but SKIP by design under ADR-018: a pure deletion introduces no content, so no delete-protection is claimed or provided. Deletions are recorded in the Stop audit.

A trusted hook bundle enforces Mneme’s decision corpus in OpenAI Codex CLI sessions: native apply_patch mutations are checked before execution, and a Stop audit reviews every artifact the session changed as a complete file. Validated 10/10 against Codex CLI 0.149.1 (Windows via codex exec, binary pinned by SHA-256).

GitHub Evidence: PR #321

Status: shipped, merged, validated

The integration merged on August 24, 2026 (PR #321) and lives at mneme/integrations/codex_cli/: a PreToolUse gate, a Stop audit, and an apply_patch parser. Validation ran 10/10 against Codex CLI 0.149.1, with per-run raw payloads, transcripts, and manifests archived under validation/codex-cli/ in the repository.

The claim, precisely: Mneme preflights supported native Codex mutation paths — apply_patch Add and Update operations — and can deny deterministic architectural violations before execution. Shell-based mutations are not reconstructed pre-execution; Mneme detects changed artifacts at Stop and audits their whole-file state as a backstop.

Architecture: three hook events, one script

SessionStart
   ↓
captures the session baseline (repository snapshot)
   ↓
PreToolUse  (^apply_patch$)
   ↓
parses the proposal, checks introduced content only
(ADR-018) via mneme check --json, denies violations
BEFORE execution
   ↓
Stop
   ↓
diffs the repo against the baseline, runs one
whole-file check per changed surviving artifact

Gate results map onto Codex’s native response shapes: PASS/SKIP emits no opinion; DENY returns permissionDecision: "deny" at PreToolUse and decision: "block" at Stop; WARN and unevaluated outcomes surface as visible non-blocking context (“[mneme] WARN …”, “[mneme] UNEVALUATED … NOT evaluated”) — never silently reported as governed.

Mutation-surface boundaries

This integration is precise about what it does and does not govern:

Surface	Enforcement
apply_patch Add / Update, incl. multi-file bundles	Pre-execution enforcement. Every operation in a bundle is evaluated; any definite violation denies the entire call.
Shell and script-driven writes	Stop-only audit — not pre-execution blocking. Path and content exist only inside command text; Mneme does not parse shells.
apply_patch Delete File	Recognized but SKIP by design under ADR-018: a pure deletion introduces no content. No delete-protection is claimed or provided; deletions are recorded in the Stop audit.
Dirty untouched files	Ignored — files already dirty before the session are out of scope unless Codex touches them.
Dirty touched files	Once Codex modifies a pre-dirty file, it enters the session audit set and must satisfy whole-file policy at Stop — including violations that predate the session.
Corrupt / unevaluable state	Visible fail-open. Unparseable output, launch failure, timeout, or an unreadable target produces an explicit UNEVALUATED diagnostic — never silently claimed as governed.

Loop bounds and trust model

Remediation loops terminate. A Stop block that triggers a real repair passes on the next Stop; a consecutive-block cap (8) releases the loop with a visible warning rather than retrying forever.
Hook trust is explicit. SessionStart, PreToolUse, and Stop definitions must be reviewed and trusted via Codex’s /hooks. Codex stores one trusted hash per (hooks.json path, event, index) slot — re-trusting a different command in the same slot evicts the previous definition’s trust until re-reviewed.
Scope qualification. Validated on Windows via codex exec against 0.149.1. Interactive TUI modes, other platforms, and other Codex versions are not separately proven.

Evidence

PR #321 — implementation, tests, and validation record
docs/integrations/codex-cli.md — architecture and policy reference
validation/codex-cli/capability-matrix.md — mutation-surface matrix, evidence-cited per cell
Raw validation runs — transcripts, worktree snapshots, manifests

FAQ

Which Codex CLI mutations are blocked before execution?

Native apply_patch Add File and Update File operations, including bundled multi-operation patches: all operations are evaluated, and any deterministic violation denies the entire call before execution.

Are shell and script-driven writes governed?

Not pre-execution. Their path and content exist only inside command text, so Mneme does not reconstruct them. The Stop hook audits every artifact the session changed as a complete file — that is the backstop, and it is the honest boundary of this integration.

Does Mneme protect file deletions in Codex CLI?

No. apply_patch Delete File is recognized but SKIP by design under ADR-018 — a pure deletion introduces no content. Deletions are recorded in the Stop audit; no delete-protection is claimed or provided.

What happens when the checker itself fails?

Every degraded outcome is visible and never reported as governed: an explicit UNEVALUATED diagnostic states what was not evaluated. For multi-operation bundles, a definite violation denies the whole call even when a sibling operation could not be evaluated, and the denial discloses which operations were never checked.

Deterministic guardrails inside Codex CLI sessions

Open-source. Repo-native. The same decision corpus enforced at Codex’s pre-tool boundary and audited at Stop — with published evidence for every claim on this page.

GitHub All integrations