v8.9.6 — Codex MCP integration + stdio banner fix

MATHIR v8.9.6 — Release Notes

Date: 2026-07-31
Type: Patch release (Codex integration + stdio banner fix)
Compatibility: Fully backward-compatible with v8.9.5. No breaking API changes. Existing projects, memories, and configurations continue to work.

---

TL;DR

Codex Desktop / CLI is now a fully supported MATHIR client (third inference host after Claude Code and OpenCode/MiMoCode). A stdio banner bug that crashed Codex MCP discovery was discovered and fixed mid-session. Both targeted installers and a portable cross-user configuration template are now shipped.

---

What's New

Highlight: Codex Desktop / CLI support

Three independent layers of integration, each fixed end-to-end with portable templates:

1. Layer A — MCP server. Codex auto-discovers MCP servers from ~/.codex/config.toml. We now ship a working [mcp_servers.mathir] block plus a portable template at mathir_mcp/codex_templates/config.toml.snippet.
2. Layer B — Auto-inject hook. Codex supports UserPromptSubmit hooks (file-based). We reuse the existing claude_code_hook.py (works for Claude Code, Codex, and any other host that fires the same hook event).
3. Layer C — Transparent OpenAI proxy. Codex can forward OPENAI_BASE_URL to its subprocesses via [shell_environment_policy.set]. Pointing this at http://127.0.0.1:7339/v1 routes Codex's LLM calls through mathir_proxy.py for prompt-time MATHIR context augmentation.

After this release, Codex Desktop exposes the same 27 mcp__mathir__* tools that Claude Code does, and every Codex prompt gets MATHIR context auto-injected before the model sees it.

Critical fix: FastMCP stdio banner crash

mcp.run() in FastMCP 3.4.4 prints a 15-line colored ASCII banner on stdout at startup. For MCP-over-stdio, stdout is the JSON-RPC channel — the banner silently corrupted the framing and every MCP host reading JSON-RPC straight off stdout registered zero tools. Diagnosis was made by Codex itself when it discovered the live MCP server "existed but no tools showed up" and traced the cause via its own config audit.

Fix (mathir_mcp/mathir_lib/mathir_mcp_server.py:1490):

mcp.run(show_banner=False)

stderr logging is unaffected. Daemon logging output and 3-layer cache logs still appear on stderr.

---

Installation & Upgrade

Fresh install

1. Download mathir-v8.9.6-slim.zip (37 MiB, no benchmark data) or mathir-v8.9.6-source.zip (172 MiB, full git-tracked tree).
2. Extract anywhere.
3. Windows: open install.bat. Linux/macOS: ./install.sh. Both delegate to mathir_mcp/bin/install.{bat,sh} which handles Python detection, dependency install, and (optionally) auto-start.
4. To also install Codex integration, follow docs/CODEX_INTEGRATION.md.

Upgrade from 8.9.x (in-place)

git pull origin main
git checkout v8.9.6
pip install -e .[cpu]    # or [torch] for GPU
# Daemon picks up new code automatically — next /health call will report 8.9.6.
# Restart Codex fully (not just new task) to pick up MCP config changes.

---

Documentation

Doc	Purpose
docs/CODEX_INTEGRATION.md (16 KB, new)	Full Codex setup guide — config + autostart + 3-layer troubleshooting + cheat sheet
mathir_mcp/docs/troubleshooting/codex-mcp-tools-invisible-three-layers.md	The three-layer failure narrative (~/PATH/banner)
mathir_mcp/docs/troubleshooting/codex-mcp-path-expansion.md	Detailed walk-through of the ~ non-expansion bug
mathir_mcp/codex_templates/README.md	How to use the portable Codex config templates

---

Portable Templates (no hardcoded usernames)

mathir_mcp/codex_templates/ ships three files that any user can drop in without touching the rest of the repo:

• hooks.json — drop-in for ~/.codex/hooks.json. Replace <YOU> (Windows) or <USER> (macOS/Linux) with your username.
• config.toml.snippet — TOML blocks for ~/.codex/config.toml. Replace <ABS_PYTHON> with the absolute path of your Python interpreter (where.exe python on Windows), and <HOME> with C:\Users\<YOU> (Windows) or /Users/<USER> (macOS) / /home/<USER> (Linux).
• README.md — explains the placeholders + links to the integration guide.

The templates do not hardcode any user's path. They are designed to be safe to commit to a public repo and never break when someone else clones it.

---

Files Changed

.gitignore                                    | 12 ++++++++++++
CHANGELOG.md                                  | 10 ++++++++++
docs/CODEX_INTEGRATION.md                     | (new, 16 KB)
mathir_mcp/CHANGELOG.md                       | 11 +++++++++++
mathir_mcp/__init__.py                        |  2 +-
mathir_mcp/bin/auto_start.bat                 |  4 ++-- (proxy target: anthropic.com → openai.com)
mathir_mcp/codex_templates/                   | (new)
mathir_mcp/codex_templates/README.md          | (new, 2.3 KB)
mathir_mcp/codex_templates/config.toml.snippet| (new, 3.1 KB, portable placeholders)
mathir_mcp/codex_templates/hooks.json         | (new, 261 B, portable placeholder)
mathir_mcp/docs/troubleshooting/              | (new)
mathir_mcp/docs/troubleshooting/codex-mcp-path-expansion.md                  | (new)
mathir_mcp/docs/troubleshooting/codex-mcp-tools-invisible-three-layers.md   | (new)
mathir_mcp/mathir_lib/__init__.py             |  2 +- (8.9.5 → 8.9.6)
mathir_mcp/mathir_lib/mathir_mcp_server.py    |  2 +- (mcp.run → mcp.run(show_banner=False))
mathir_mcp/pyproject.toml                     |  2 +- (8.9.5 → 8.9.6)

14 files changed, 687 insertions(+), 6 deletions(-).

---

Verification

Check	Command	Expected
Daemon /health version	curl http://127.0.0.1:7338/health	"version":"8.9.6"
python -m mathir_mcp --version	__version__ == "8.9.6"
Codex MCP tools listed	ask Codex "liste tes outils MCP"	mcp__mathir__* appears (27 tools total)
MCP server tools/list	probe via stdio JSON-RPC	27 tools, no stdout banner
pip show mathir-mcp	version field	8.9.6

---

Known Issues & Mitigations

• ~ in MCP env vars: Codex (and Electron hosts in general) does not shell-expand ~. Mitigation documented in the integration guide + templates use absolute paths. Helper GUID-NEVER copy a Codex MCP env block from a Claude Code tutorial without un-tilding it.
• python not on PATH in Codex subprocesses: Mitigation uses <ABS_PYTHON> placeholder, defaulted via where.exe python.
• FastMCP stdout banner: Fixed in this release. Future FastMCP versions may regress — if you upgrade FastMCP, re-test tools/list via stdio probe and pin show_banner=False.

---

Acknowledgements

This release was developed live across multiple AI agents (Claude Code, OpenCode, Codex itself) plus a human-in-the-loop. Codex found the show_banner=False root cause from inside the failing config. That alone is a good demonstration of the system in production.

---

Checksums

mathir-v8.9.6-source.zip   180,327,447 bytes
mathir-v8.9.6-slim.zip      38,363,525 bytes

(Computed via 7-Zip LZMA / zip64; sha256 available on request via Get-FileHash.)

8.9.6

MATHIR 8.9.6

• release(v8.9.6): Codex MCP integration + stdio banner fix (8ace6d3)

8.9.5

Autonomous maintenance + headless god-mode workers

Added

• Autonomous background maintenance thread — memory decay/promotion/dedup/link-building now runs on its own timer (config-driven via mathir.json's new "maintenance" block), no manual trigger needed.
• Headless, on-demand god-mode workers (god_mode_start.py/god_mode_stop.py/god_worker_daemon.py) — an orchestrator can launch a real coding-agent CLI in the background that polls, claims, executes, and reports on a task unattended.
• Deterministic (non-LLM) god-mode report tool (god_mode_report.py) reads results straight from the SQLite DB.
• Atomic task claiming + new /api/god/ack route close a race/staleness bug in god-mode's polling protocol.

Fixed

• Memory decay-eligibility bug that permanently excluded never-recalled memories from decaying.
• Guardrail memories no longer get silently reclassified away by the anomaly detector.

Changed

• Memory-link-graph similarity threshold raised 0.7 → 0.88 (previous value produced an unusable, almost-complete link graph).
• Renamed leftover MYCERISE_STATE_DIR/MYCERISE_LOG_FILE env vars to MATHIR_STATE_DIR/MATHIR_LOG_FILE.

Full detail: CHANGELOG.md

8.9.4

MATHIR 8.9.4

• fix(server): every guardrail memory_save was failing with ImportError (2965dfd)
• docs: rewrite 5-tier to 6-tier content in 03_MASTER_QA_GUIDE.md's memory-tiers section (b868503)
• fix(brain): mathir-brain console script was launching a broken proxy (ccf0912)
• fix(config): sync stale version default in config_template.json (72b57eb)
• chore: trivial commit to trigger GitHub contributor-graph reindex (e6e9c23)
• docs(readme): fix stale duplicate proxy blurb, drop leaked project name (a95738f)
• docs(readme): fix the pitch -- MATHIR is a request-path layer, not an API you call (59c9bd2)
• docs(readme): front-load "what is MATHIR" + honest Mem0 comparison, collapse narrative padding (74284eb)
• docs: fix stale 26-tool-count and outdated version tables in research docs (b3c4443)
• docs(global): sync top-level README + CHANGELOG to v8.9.4, fix base_url inconsistency (a904fe8)
• docs: sweep docs/, INSTALL_FOR_AGENT/, INSTALL_FOR_DEV/, config/ for v8.9.4 + stale-protocol drift (47515f3)
• docs(proxy): demote static instruction-injection templates to fallback status (8660739)
• chore(release): v8.9.4 -- fix version drift across source-of-truth files, changelog this session (5f0a36f)
• chore(cleanup): remove legacy brain/ duplicate subsystem (59065d6)
• refactor(security): unify the two independent prompt-injection sanitizers (64105f5)
• fix(security): daemon-side prompt-injection sanitizer was a no-op (52cc317)
• feat(proxy): expand upstream allowlist to ~30 providers + dynamic-subdomain support (287a6c1)
• feat(proxy): multi-upstream routing + fix double /v1 path bug (f67c606)
• feat(proxy): universal Anthropic Messages API route + cross-platform supervision (8cc9a47)
• feat(inject): wire the push-based auto-injection hook, was dead code (323edca)
• fix(autostart): healthcheck watchdog no longer requires admin rights (b0e847f)
• Fix 500 on memory endpoints: tqdm crashes on stderr.flush() in detached process (10bcc95)

v8.9.3 — Honest repositioning + cross-platform autostart fix

Docs: repositioning, not competing

MATHIR no longer frames itself as beating Mem0/Zep/Letta/FAISS head-to-head. The 2026 landscape has native memory in Claude/ChatGPT/Gemini and a funded agent-memory ecosystem — this release repositions around what MATHIR actually validates: self-maintaining tiered memory (6 tiers, decay/promotion/consolidation) and cross-process, cross-provider, local-first multi-agent sharing (God Mode).

• Dropped the "vs Alternatives" scorecard from the README; replaced with an honest "Positioning (2026)" section.
• docs/03_MASTER_QA_GUIDE.md and docs/07_MATHIR_VS_VECTORDB_USE_CASES.md reworded away from "beats X" claims.
• Removed inflated "doctoral-level" language — this is a master's research project.
• New: docs/MATHIR_FOR_ROBOTICS.md — seed doc for a planned separate MATHIR FOR ROBOTICS track (Isaac Sim simulation, then RC car), testing whether place-based episodic memory complements sensor-fusion robustness when sensors degrade. Honestly grounded against the existing literature (Grace-BEV/MetaBEV/UniBEV, Mobileye REM/Tesla fleet learning, LLM4AD latency), with explicit unvalidated-hypothesis framing.

Fix: cross-platform daemon auto-start

auto_start.bat hardcoded a Python 3.11 path that doesn't exist on Miniconda/Anaconda setups, silently breaking daemon auto-start. Same class of bug existed in the Linux systemd unit and macOS launchd plist.

• Windows (auto_start.bat): resolves Python via where python → py launcher → common install dirs.
• Linux (mathir-daemon.service): ExecStart resolves python3/python via PATH at start time.
• macOS (com.mathir.daemon.plist + install_smart.py): prefers venv python → python3 on installer PATH → env python3 fallback, instead of a hardcoded /usr/bin/python3.

Full diff: v8.9.2...v8.9.3

8.9.3

MATHIR 8.9.3

• release: v8.9.3 — doc repositioning + cross-platform autostart fix (f3abe07)
• fix(autostart): resolve Python dynamically on Windows/Linux/macOS (c3e55f6)
• docs: reposition away from competitor comparisons, spin off robotics research (57e72e8)

v8.9.2 - God-mode Client Bridge (tests passing)

God-mode Client Bridge + Cross-Platform Tooling

This release ships the missing client-side layer of MATHIR's god-mode multi-agent orchestration, plus a docs sweep and version sync to v8.9.2.

Note — All 162 tests pass on Python 3.10 / 3.11 / 3.12 (commit 98b3b7f). One follow-up commit on this release fixes a stale assert == 24 tool-count test that was carried from v8.4.x — the canonical tool count is now 27.

What's New

God-mode client bridge (mathir_mcp/bin/god/)

• god_bridge.py — cross-platform polling daemon, 3 modes:
  • worker — polls /api/god/poll for tasks assigned to your worker name
  • orchestrator — watches /api/memories for new god:result:* entries
  • observer — logs every god:* event (debug / monitoring)
• Stdlib-only, no new dependencies
• Cross-platform beep + log notification (Windows: winsound + [Console]::Beep; POSIX: paplay + bell)
• Full label taxonomy (god:task, god:result, god:reply, god:reg, god:shutdown) in PROTOCOL.md

Lightweight cross-platform pollers

• god_poll.ps1 — PowerShell one-shot poller (Windows, faster boot)
• god_poll.sh — POSIX bash one-shot poller (Linux / macOS / Git-Bash / WSL)

Cross-platform path discipline

• Zero hardcoded paths in any bin/god/* file
• All paths env-var resolved (MATHIR_DAEMON_URL, MYCERISE_STATE_DIR, MYCERISE_LOG_FILE, XDG_CONFIG_HOME)
• Compatible Windows + Linux + macOS without modification

Server-side (already shipping, now documented alongside)

• mathir_lib/mathir_god.py (v8.8.0) — GodProtocol, TaskGraph, WorkerRegistry, WorktreeManager
• Daemon routes /api/god/poll + /api/god/agents (mathir_server.py:1422)
• MCP tools: mathir_god_agent, mathir_god_orchestre

Version sync

• __version__ (__init__.py): 8.5.1 → 8.9.2
• pyproject.toml: version 8.5.1 → 8.9.2
• All docs bumped to v8.9.2 (previously stale at v8.9.0 or V8.4.1)

Tool count correction

26 → 27 MCP tools — audit confirmed audit_immunological was missing in earlier counts.
Canonical breakdown:

• 2 auto-injection (session_start, context)
• 10 basic (save/recall/smart_search/hybrid_search/decay/promote/...)
• 7 lifecycle (link/get_links/build_links/incoming_links/consolidate/...)
• 3 advanced (advanced tools)
• 1 guardrail (list_guardrails)
• 1 immunological (audit_immunological)
• 1 health (health/ping)
• 2 god mode (mathir_god_agent, mathir_god_orchestre)

Docs sweep

Doc	Change
33_QUICK_START.md	v8.9.0 → v8.9.2, 26→27 tools, new section "5b. Long-running polling (god bridge)"
BRAIN_ARCHITECTURE.md	5-phase → 6-phase, new "Phase 6 — Multi-Agent Orchestration Bridge", Files section extended
05_SHIPPING_GUIDE.md	v8.9.0 → v8.9.2, new "Option D: God Bridge (multi-agent orchestration)"
06_MULTIMODAL_MEMORY_GUIDE.md	V8.4.1 → V8.9.2, god-mode bridge mentioned
07_MATHIR_VS_VECTORDB_USE_CASES.md	"seven memory tiers" → six, V8.4.1 → V8.9.2, version note
08_WHY_SAME_RESULTS.md	"valid for v8.9.2" version note
GOD_MODE.md	new "Client-side tooling (bin/god/)" section
OUTREACH.md	v8.9.0 → v8.9.2, client bridge mention across emails
SOTA_RESEARCH_2024_2026.md	"last reviewed v8.9.2" note
mathir_mcp/CHANGELOG.md	new "v8.9.2 — GOD-MODE CLIENT BRIDGE" section
mathir_mcp/README.md	new "God-mode orchestration (bin/god/)" section, index updated
mathir_mcp/bin/README.md	new "## God-mode orchestration (multi-agent coordination)" section

Cross-links verified

• 22 markdown links audited across 4 main docs
• 0 broken links found

Quick Start

# Worker terminal
python mathir_mcp/bin/god/god_bridge.py --mode worker --name <my-worker> --interval 5

# Orchestrator terminal (separate)
python mathir_mcp/bin/god/god_bridge.py --mode orchestrator --interval 5 --project <name>

Compatibility Notes

• No new runtime dependencies for the bridge — uses only Python stdlib (urllib, json)
• Existing daemon versions are still backward-compatible — the bridge only uses the /api/god/poll, /api/god/agents, /api/memory/audit, and /api/memories routes, all of which ship in v8.8.0+
• Daemon runtime upgrade is optional but recommended — see bin/install_mathir.bat / .sh for cross-platform upgrade scripts

Stats

• 21 files changed across 2 commits (0d8a05e + 98b3b7f)
• 5 new files in mathir_mcp/bin/god/ (god_bridge.py, god_poll.ps1, god_poll.sh, PROTOCOL.md, README.md)
• 16 modified files (docs + version labels + test assertion)
• 0 hardcoded machine paths in any deliverable
• 162/162 tests pass on Python 3.10 / 3.11 / 3.12

8.9.2

MATHIR 8.9.2

• fix(tests): update stale tool count assertion 24 -> 27 (matches v8.9.2 reality) (98b3b7f)
• release: v8.9.2 — God-mode client bridge + cross-platform tooling + docs sweep (0d8a05e)

v8.9.1 — Canonical 27 tools doc fix

Doc correction release

The v8.9.0 release miscounted MCP tools as 26 — the audit_immunological tool was missing from the tally. Verified against the live MCP tool list: 27 tools.

Canonical breakdown (27 tools)

Category	Count	Tools
Auto-injection	2	session_start, context
Basic	10	save, recall, smart_search, hybrid_search, audit, export, delete, sessions, stats, dashboard
Lifecycle	7	promote, auto_promote, decay, consolidate, link, get_links, build_links
Advanced	3	by_path, recall_quality, incoming_links
Guardrail	1	list_guardrails
Immunological	1	audit_immunological
Health	1	mathir_health
God Mode	2	god_agent, god_orchestre

What changed

• All docs/templates/READMEs/architecture diagrams: 26 → 27 tools everywhere
• 150+ agent/skill files: LIVING MEMORY (5 TIERS) → (6 TIERS)
• Guardrail row added to all memory-tier tables
• block_type declarations: added missing immunological tier
• Version titles: stale v8.5/v8.6/v8.7 → v8.9.0
• opencode_templates/README: 19 → 27 tools, 5-tier → 6-tier model

No code changes

This is a documentation-only release. No Python files were modified. The MCP server, daemon, and all tool implementations are unchanged from v8.9.0.

Full changelog: see CHANGELOG.md [8.9.1] section.

v8.6.1 — Portable Paths + Cross-Platform Install Fix

v8.6.1 — Portable Paths + Cross-Platform Install Fix

What changed

Zero hardcoded paths. Eliminated ~90 machine-specific paths (C:\Users\..., D:\SECRET_PROJECT\...) and ~50 legacy ~/.config/opencode/bin/ references across 24 files. Every script, install guide, template, and Python module now uses portable resolution (%USERPROFILE%, $HOME, ~, Path.home(), os.path.expanduser).

New canonical install location: ~/.config/MATHIR/mathir_mcp/ (replaces ~/.config/opencode/bin/).

DB routing fixed: Memory databases are now created inside the project directory (.mathir/mathir.db) for new projects, while existing 417 databases in the global config are still found and used. No data loss.

Daemon launch bug fixed: auto_start.bat was launching the legacy TCP socket server instead of the HTTP/Flask server. All auto-start scripts now correctly start mathir_server.py.

Breaking changes

• Install path changed from ~/.config/opencode/bin/ to ~/.config/MATHIR/mathir_mcp/. If you had the old path in your MCP config, update it.
• mathir_paths.py no longer falls back to ~/.config/opencode. Set $MATHIR_HOME if you need a custom location.

Cross-platform

Platform	Auto-start	Config path
Windows	bin/auto_start.bat or Task Scheduler	%USERPROFILE%\.config\MATHIR\
Linux	bin/auto_start.sh or systemd	~/.config/MATHIR/
macOS	bin/auto_start.sh or launchd	~/.config/MATHIR/

Install

git clone https://github.com/sil3d/MATHIR.git
cd MATHIR/mathir_mcp
pip install -e .

Full guides: Windows · Linux · macOS

98/98 tests passing (Python 3.10, 3.11, 3.12)

Full changelog: CHANGELOG.md