███╗ ███╗███████╗██╗ ██╗ ████╗ ████║██╔════╝╚██╗██╔╝ ██╔████╔██║█████╗ ╚███╔╝ ██║╚██╔╝██║██╔══╝ ██╔██╗ ██║ ╚═╝ ██║███████╗██╔╝ ██╗ ╚═╝ ╚═╝╚══════╝╚═╝ ╚═╝
AI agents forget everything
between sessions.
mex fixes that.
Persistent, navigable project memory via a structured markdown scaffold. A CLI that detects when docs drift from reality — and fixes them.
The problem is amnesia
Your AI agent is brilliant — for exactly one session. Then it forgets everything and you start over.
Cold starts
Every session starts cold. The agent has no idea what it built yesterday, what conventions you agreed on, or what broke last week.
Context flooding
Developers compensate by stuffing everything into CLAUDE.md — flooding the context window, burning tokens, and degrading attention.
Doc drift
The project changes and nobody updates the docs. The agent's understanding drifts from reality. Silently.
mex is a structured markdown scaffold with a CLI that keeps it honest. The scaffold gives agents persistent project knowledge through navigable files — architecture, conventions, decisions, patterns. The CLI detects when those files drift from the actual codebase, and targets AI to fix only what's broken.
How it works
Navigate, don't dump. The agent loads only the context it needs for the current task.
Session starts
Agent wakes up with zero context.
Agent loads CLAUDE.md
Auto-loaded by the tool. ~120 tokens. Points to .mex/
CLAUDE.md → ROUTER.md
Routing table that maps task types to the right context file.
ROUTER.md → context file
Architecture, stack, conventions, decisions, setup — only what's relevant.
Context → pattern file
Task-specific guides with gotchas, steps, and verify checklists.
Agent executes
Full project context. Minimal token cost. No hallucination.
Drift detection
Seven checkers validate your scaffold against the real codebase. Zero tokens. Zero AI.
Scoring: starts at 100. Deducts −10 per error, −3 per warning, −1 per info.
Scaffold structure
CLI commands
mex checkRun all 7 checkers, output drift score and issuesmex check --quietOne-liner: mex: drift score 92/100 (1 warning)mex initPre-scan codebase, build structured brief for AImex syncDetect drift → build per-file prompts → AI fixes → verifymex sync --dry-runPreview targeted prompts without executingmex watchInstall post-commit hook for automatic drift scoreBefore & after
Real output from running mex init on a production Python/Flask project with Twilio, multi-provider AI pipeline.
## Current Project State
<!-- What is working. What is not yet built.
Known issues.
Update this section whenever significant
work is completed. -->mex init## Current Project State **Working:** - Voice call pipeline (Twilio → STT → LLM → TTS → response) - Multi-provider STT (ElevenLabs, Deepgram) - RAG system with Supabase pgvector - Streaming pipeline with barge-in support **Not yet built:** - Admin dashboard for call monitoring - Automated test suite - Multi-turn conversation memory across calls **Known issues:** - Sarvam AI STT bypass active — routing to ElevenLabs as fallback
Patterns directory generated automatically:
patterns/ ├── add-api-client.md ├── add-language-support.md ├── debug-pipeline.md └── add-rag-documents.md
Get started in
5 minutes
Clone mex into .mex
Clone the repo as a hidden directory in your project root.
Run setup.sh
Auto-builds the CLI, pre-scans your codebase, and populates the scaffold.
Start building
Your AI agent now has persistent project memory. Every session.
Works with any codebase. JavaScript, Python, Go, Rust — if it has files, mex can scaffold it.
Cloning into '.mex'...◌ Building CLI...✔ CLI built◌ Scanning codebase...✔ Detected: Next.js, TypeScript, Tailwind◌ Populating scaffold...✔ context/architecture.md populated✔ context/stack.md populated✔ context/conventions.md populated✔ patterns/INDEX.md created✔ ROUTER.md configuredmex: drift score 100/100Works with your tools
All config files contain identical content. setup.sh asks which tool you use.
Claude Code
CLAUDE.md
Cursor
.cursorrules
Windsurf
.windsurfrules
GitHub Copilot
copilot-instructions.md