How to Use NeuralMind with OpenAI Codex
Setup, Token Measurement, and Savings
Verified against the live codebase. DeepSeek v4 Pro QA-corrected.
Abstract
NeuralMind gives any AI coding agent a persistent memory layer — a learned, weighted graph of your codebase that cuts the tokens a code question costs at the retrieval stage: 51–242× fewer than pasting every source file on the public benchmark (v4.12.0), and 12–50× in field reports measured by neuralmind benchmark before v4.5.0 against its fixed 50K-token estimate. This guide walks through using NeuralMind with OpenAI Codex CLI: one-time install, registering the MCP server (works with any MCP-compatible client, including Codex), daily wakeup/query commands, per-layer token measurement, the self-improvement loop, and honest scoping of what's measured vs. modeled. All claims are verified against the live codebase at commit 3fe5a61. A DeepSeek v4 Pro QA sweep corrected several overclaims from the original draft — the corrections are flagged inline.
Architecture
The Two-Brain Model: Codex is the cortex (stateless reasoning over a working-memory window). NeuralMind is the hippocampus + associative cortex (persistent weighted graph of code nodes that learns by Hebbian co-activation, decays unused edges, and runs spreading activation for recall).
Communication channels: MCP tools (19 tools, any agent), lifecycle hooks (SessionStart, UserPromptSubmit, PreCompact, PostToolUse), and the file activity watcher (always-on, per-project).
The Codex relationship: Codex is MCP-compatible. NeuralMind ships an MCP server that exposes neuralmind_wakeup, neuralmind_query, and 17 other tools. Codex gains NeuralMind's retrieval and synapse capabilities by registering that MCP server — no Codex-specific code required.
Procedures
1. One-Time Setup (per repo)
pip install neuralmind
cd /path/to/your-project
neuralmind build . # builds knowledge graph + vector index
neuralmind install-mcp --print # print the MCP config snippet for Codex (or any MCP client)
For Codex specifically: Codex isn't in the auto-detect list (Claude Code, Cursor, Cline, Claude Desktop, VS Code). Use neuralmind install-mcp --print to emit the JSON snippet, then paste it into Codex's MCP server config. Any MCP-compatible client works the same way — the server is the same, only the config file differs.
2. Daily Codex Workflow
Once the MCP server is registered, Codex gains NeuralMind's tools. Start every session with a wakeup, then query as needed:
codex> neuralmind_wakeup(project_path=".") # compact project overview, once per session
codex> neuralmind_query(project_path=".", question="...") # 670–961 mean tokens per question (public benchmark, v4.12.0)
codex> neuralmind_skeleton(project_path=".", file_path="...") # file → skeleton (functions + rationales)
codex> neuralmind_review(project_path=".", changed_files=[...]) # catch co-breaks
codex> neuralmind_next_likely(project_path=".", from_node="...") # predict next file
What Codex sees: Structured project context (identity, architecture, relevant modules, search hits) instead of raw file dumps. The wakeup loads a compact overview once per session (455 tokens in one field report; neuralmind benchmark prints yours); a query averaged 670–961 tokens per repo on the public benchmark at v4.12.0.
3. Registering with Any MCP Client
neuralmind install-mcp --all # auto-detect Claude Code / Cursor / Cline / Claude Desktop / VS Code
neuralmind install-mcp --client cursor # target a specific client
neuralmind install-mcp --print # emit JSON for any MCP client (Codex, Windsurf, custom)
--all non-destructively merges a NeuralMind entry into each detected client's config. --print is the escape hatch: it outputs the {"mcpServers": {"neuralmind": {"command": "neuralmind-mcp", "args": ["."]}}} snippet to paste into any MCP-compatible tool's config file.
Token Measurement (L0-L3 Budgets)
Measurement Stack
| Layer | Content | Budget |
|---|---|---|
| L0 Identity | Project name, description, key facts | ~150 tok |
| L1 Summary | High-level architecture, main components | ~600 tok |
| L2 On-Demand | Specific communities/modules as needed | ~800 tok |
| L3 Search | Semantic search hits | ~1000 tok |
Wakeup: L0 + L1, capped by the budgets above, once per session. Per-query: 670–961 mean tokens per repo on the public benchmark (v4.12.0). Vs pasting every source file: 41,729–232,483 tokens on the same four repos.
Tool-output compression (correction)
Earlier versions of this guide described PostToolUse hooks that compress Read, Bash and Grep output, with reductions of up to ~88% and ~91% that were never measured. When the hooks were finally benchmarked against Claude Code’s documented hook protocol, they turned out not to shrink anything: Claude Code adds a hook’s output next to the tool result instead of replacing it, so they added tokens, and the Read hook never received Claude Code’s payload. The hooks no longer inject anything; the compression benchmark has the measurements.
The hooks are Claude Code-specific, so Codex never ran them. For Codex, token savings come from the MCP retrieval layer (wakeup/query) alone.
Benchmark + Savings Commands
neuralmind benchmark . --json # wakeup, avg query, avg reduction
neuralmind benchmark . --quality # MRR, answerability, recall@k
neuralmind probe . --sample-size 100 # self-probe on YOUR code
neuralmind savings . --cost --model claude-opus-4-8 --queries-per-day 100
neuralmind savings --cost reads your local query event log and prints estimated dollar savings. The "without NeuralMind" cost is modeled from a fixed 50,000-token-per-query baseline; the "with NeuralMind" cost is measured from logged tokens.
Self-Improvement Loop
NeuralMind includes infrastructure for a self-improving / self-evolving product — autonomous signal → diagnose → experiment → promote/rollback loop.
What's wired:
- Synapse learning (always-on): The file activity watcher records co-activations between code nodes. Hebbian reinforcement strengthens edges the agent actually traverses; half-life decay erodes unused edges (personal=30d, shared=60d, ephemeral=1d).
- Fitness function: Multi-objective (MRR, answerability, recall@k) fitness scoring gated by a threshold. Auto-promote fires when fitness exceeds the threshold.
- Tuner: Single-variable in trace fallback mode; live eval is multi-objective. Auto-tune is opt-in and capped at ±1 step per session.
- Learned decay: Wired into
reinforce()— adjusts reinforcement magnitude based on how recently an edge was last traversed.
The gap: The fitness function is effectively single-variable in trace fallback mode. Live eval is multi-objective but unmeasured in production. The "self-evolving product" is aspirational — the infrastructure is built, the tuning signal is weak in production.
Honest Scope — What's Measured vs. Modeled
| Claim | Basis | Confidence |
|---|---|---|
| 51–242× fewer tokens than pasting every source file | Public benchmark, 40 pre-registered queries on 4 repos, v4.12.0 (python -m evals.public.run); retrieval stage only | Measured |
| 12–50× token reduction | Field reports measured by neuralmind benchmark before v4.5.0, against its fixed 50K-token estimate rather than a measured baseline; retrieval stage only | Modeled |
| Wake-up tokens, once per session | L0+L1 in context_selector.py; 455 in one field report, printed by neuralmind benchmark for your repo | Measured |
| 670–961 mean tokens per question | Public benchmark, per repo, v4.12.0; ~830 on the 150-question retrieval eval; varies by graph size | Measured |
| Read/Bash tool-output compression | Benchmarked: as shipped, the hooks added tokens instead of saving them; switched off | Refuted |
| Dollar savings ($/day, $/mo) | With-NM measured from logged tokens; without-NM estimated | Mixed |
| MRR / answerability / recall@k | Benchmark suite (neuralmind benchmark --quality) | Measured |
| End-to-end cost per task | A pre-registered 20-task pilot, Claude Code with and without NeuralMind: no difference | Not supported |
| Self-improving product | Infrastructure built; tuning signal weak in production | Aspirational |
Bottom line: The savings are at the retrieval stage. On the public benchmark NeuralMind's context averaged 670–961 tokens per question, per repo, against 41,729–232,483 to paste every source file (51–242×, v4.12.0); the older 12–50× range comes from field reports measured by neuralmind benchmark before v4.5.0 against its fixed 50K-token estimate. Total end-to-end reduction varies by workflow (how many Read/Bash calls, query volume, codebase shape). Codex and Claude Code users get the same retrieval-stage reduction: the Claude Code hooks add no compression on top (see the correction above). Whether it lowers what a task costs was measured once: a 20-task pilot found no difference.
Tiers
| Tier | Price | Includes |
|---|---|---|
| Free | $0 | Auto-provisioned on first neuralmind wakeup . (v1.7.0) — wakeup, query, search, synapses, build, benchmark, savings, review, all MCP tools, 1 seat |
| Team | $29/user/mo | Governance (per-repo enable/disable, scope, weight threshold), immutable SHA-256 audit log, seat management (5-50 seats), self-hosted deployment, license management |
| Enterprise | Custom | 51+ seats, per-org assurance, custom contracts — contact [email protected] |
Free tier note: v1.7.0 flipped the default tier from "team" to "free" — on first neuralmind wakeup ., a license.json is auto-written with no signup wall.
DeepSeek QA Correction Log
This guide was corrected on 2026-07-26 after DeepSeek v4 Pro verification against the live codebase. The following claims were based on assumptions that didn't hold up:
| Original Claim | Correction | Status |
|---|---|---|
| "install-mcp --all detects Codex" | Codex is not in the auto-detect list (claude-code, cursor, cline, claude-desktop, vscode). Use --print for Codex. | Refuted |
| "PostToolUse hooks fire in Codex" | Hooks are Claude Code-specific. Codex only gets the MCP retrieval layer. | Refuted |
| "12-50× total workflow reduction" | 12–50× is retrieval-stage only, from field reports measured before v4.5.0 against a fixed 50K-token estimate. Total reduction varies by workflow. | Overclaim |
| "88%/91% compression measured" | Never measured. Once benchmarked, the hooks turned out to add tokens instead of saving them, and were switched off. | Refuted |
| "~800-1100 tokens per query" | Modeled estimate using est_nodes * 2 formula. Actual varies by graph size and query. | Modeled |
| "Dollar savings are fully measured" | With-NM is measured; without-NM (and therefore "saved") is estimated from a 50K baseline. | Overclaim |
| "Self-improving product (in production)" | Infrastructure is built; fitness signal is weak in production. Tuning is opt-in, capped. | Aspirational |
Reference Implementation
- Language: Python 3.10+ (stdlib-only)
- Repo: https://github.com/dfrostar/neuralmind
- Commit:
3fe5a61(2026-07-26) - Key files:
- neuralmind/cli.py (3,364 lines — build, wakeup, query, savings, install-mcp)
- neuralmind/mcp_server.py (879 lines — 19 MCP tools)
- neuralmind/mcp_install.py (245 lines — client detection + registration)
- neuralmind/context_selector.py (993 lines — L0/L1/L2/L3 progressive disclosure)
- neuralmind/synapses.py (1,593 lines — Hebbian synapse store)
- neuralmind/hooks.py (544 lines — Claude Code hook integration)
- neuralmind/compressors.py (310 lines — Read/Bash/Grep compression)
- neuralmind/fitness.py (multi-objective fitness)
- neuralmind/tuner.py (denominator-safe, incumbent-guarded)