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 reduces token spend on code questions by 40-70x at the retrieval stage. 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=".") # ~400-600 tokens instead of 50K
codex> neuralmind_query(project_path=".", question="...") # ~800-1100 tokens
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 ~400-600 tokens; a follow-up queries ~800-1100 tokens.
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 |
Total wakeup: ~400-600 tok. Per-query: ~800-1100 tok. Vs full codebase: 50K+ tok loaded naively.
PostToolUse Hook Compression
When installed via neuralmind install-hooks, PostToolUse hooks compress three output types automatically:
| Tool | Typical reduction | Mechanism |
|---|---|---|
| Read | Up to ~88% | File → skeleton (functions + rationales + call graph) |
| Bash | Up to ~91% | Keep errors + tail, drop middle |
| Grep | Capped | Max 25 matches, "N more hidden" pointer |
Note: The 88%/91% figures are documentation claims, not measured benchmarks. Actual compression depends on file size and content type. The Hooks are Claude Code-specific; Codex does not fire 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 |
|---|---|---|
| 40-70x token reduction | Retrieval-stage only (50K baseline → ~800 tok) | Modeled |
| ~400-600 tok wakeup | L0+L1 in context_selector.py | Measured |
| ~800-1100 tok query | L2+L3 per typical query; varies by graph size | Modeled |
| 88%/91% Read/Bash compression | Documentation claims, not benchmarked | Aspirational |
| Dollar savings ($/day, $/mo) | With-NM measured from logged tokens; without-NM estimated | Mixed |
| MRR / answerability / recall@k | Benchmark suite (neuralmind benchmark --quality) | Measured |
| Self-improving product | Infrastructure built; tuning signal weak in production | Aspirational |
Bottom line: The 40-70x figure is real at the retrieval stage — NeuralMind replaces a 50K-token file dump with ~800 tokens of targeted context. Total end-to-end reduction varies by workflow (how many Read/Bash calls, query volume, codebase shape). Codex users get the retrieval-stage savings; Claude Code users add PostToolUse hook compression on top.
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 | $79/user/mo | 51+ seats, per-org assurance, custom contracts (future) |
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 |
| "40-70x total workflow reduction" | 40-70x is retrieval-stage only. Total reduction varies by workflow. | Overclaim |
| "88%/91% compression measured" | Documentation claims only, not benchmarked. | Aspirational |
| "~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)