███╗   ███╗███████╗██╗  ██╗
  ████╗ ████║██╔════╝╚██╗██╔╝
  ██╔████╔██║█████╗   ╚███╔╝
  ██║╚██╔╝██║██╔══╝   ██╔██╗
  ██║ ╚═╝ ██║███████╗██╔╝ ██╗
  ╚═╝     ╚═╝╚══════╝╚═╝  ╚═╝

mex

AI agents forget everything between sessions. mex gives them permanent, navigable project memory.

Every session starts cold:

• The agent has no idea what it built yesterday
• It forgets the conventions you agreed on
• It doesn't know what broke last week

Developers compensate by stuffing everything into CLAUDE.md — but that floods the context window, burns tokens, and degrades attention. Meanwhile, the project changes and nobody updates the docs. The agent's understanding drifts from reality.

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. The scaffold grows automatically — after every task, the agent updates project state and creates patterns from real work.

Works with any stack — JavaScript, Python, Go, Rust, and more.

Star History

Install

The npm package is named promexeus (our social handle — mex was taken on npm). The CLI command is mex.

npx promexeus setup

That's it. The setup command creates the .mex/ scaffold, asks which AI tool you use, pre-scans your codebase, and generates a targeted prompt to populate everything. Takes about 5 minutes.

At the end of setup, you'll be asked to install mex globally. If you accept:

mex check        # drift score
mex sync         # fix drift

If you skip global install, everything still works via npx:

npx promexeus check        # drift score
npx promexeus sync         # fix drift

You can install globally later at any time:

npm install -g promexeus

Drift Detection

Eight checkers validate your scaffold against the real codebase. Zero tokens, zero AI.

| Checker | What it catches | |---------|----------------| | path | Referenced file paths that don't exist on disk | | edges | YAML frontmatter edge targets pointing to missing files | | index-sync | patterns/INDEX.md out of sync with actual pattern files | | staleness | Scaffold files not updated in 30+ days or 50+ commits | | command | npm run X / make X referencing scripts that don't exist | | dependency | Claimed dependencies missing from package.json | | cross-file | Same dependency with different versions across files | | script-coverage | package.json scripts not mentioned in any scaffold file |

Scoring: starts at 100. Deducts -10 per error, -3 per warning, -1 per info.

CLI

All commands run from your project root. If you didn't install globally, replace mex with npx promexeus.

Commands

| Command | What it does | |---------|-------------| | mex setup | First-time setup — create .mex/ scaffold and populate with AI | | mex setup --dry-run | Preview what setup would do without making changes | | mex check | Run all 8 checkers, output drift score and issues | | mex check --quiet | One-liner: mex: drift score 92/100 (1 warning) | | mex check --json | Full report as JSON for programmatic use | | mex check --fix | Check and jump straight to sync if errors found | | mex sync | Detect drift → choose mode → AI fixes → verify → repeat | | mex sync --dry-run | Preview targeted prompts without executing | | mex sync --warnings | Include warning-only files in sync | | mex init | Pre-scan codebase, build structured brief for AI | | mex init --json | Raw scanner brief as JSON | | mex watch | Install post-commit hook (silent on perfect score) | | mex watch --uninstall | Remove the hook | | mex commands | List all commands and scripts with descriptions |

Running check after drift is fixed by sync

Before / After

Real output from testing mex on Agrow, an AI-powered agricultural voice helpline (Python/Flask, Twilio, multi-provider pipeline).

Scaffold before setup:

## Current Project State
<!-- What is working. What is not yet built. Known issues.
     Update this section whenever significant work is completed. -->

Scaffold after setup:

## Current Project State

**Working:**
- Voice call pipeline (Twilio → STT → LLM → TTS → response)
- Multi-provider STT (ElevenLabs, Deepgram) with configurable selection
- RAG system with Supabase pgvector for agricultural knowledge retrieval
- 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 after setup:

patterns/
├── add-api-client.md       # Steps, gotchas, verify checklist for new service clients
├── add-language-support.md  # How to extend the 8-language voice pipeline
├── debug-pipeline.md        # Where to look when a call fails at each stage
└── add-rag-documents.md     # How to ingest new agricultural knowledge

Real World Results

Independently tested by a community member on OpenClaw across 10 structured scenarios on a homelab setup (Ubuntu 24.04, Kubernetes, Docker, Ansible, Terraform, networking, monitoring). 10/10 tests passed. Drift score: 100/100.

Token usage before vs after mex:

| Scenario | Without mex | With mex | Saved | |----------|------------|---------|-------| | "How does K8s work?" | ~3,300 tokens | ~1,450 tokens | 56% | | "Open UFW port" | ~3,300 tokens | ~1,050 tokens | 68% | | "Explain Docker" | ~3,300 tokens | ~1,100 tokens | 67% | | Multi-context query | ~3,300 tokens | ~1,650 tokens | 50% |

~60% average token reduction per session.

Context is no longer all-or-nothing — loaded on demand, only what's relevant.

How It Works

Session starts
    ↓
Agent loads CLAUDE.md (auto-loaded, lives at project root)
    ↓
CLAUDE.md says "Read .mex/ROUTER.md before doing anything"
    ↓
ROUTER.md routing table → loads relevant context file for this task
    ↓
context file → points to pattern file if task-specific guidance exists
    ↓
Agent executes with full project context, minimal token cost
    ↓
After task: agent updates scaffold (GROW step)
    ↓
New patterns, updated project state — scaffold grows from real work

CLAUDE.md stays at ~120 tokens. The agent navigates to only what it needs. After every task, the agent updates the scaffold — creating patterns from new task types, updating project state, fixing stale context. The scaffold compounds over time.

File Structure

your-project/
├── CLAUDE.md              ← auto-loaded by tool, points to .mex/
├── .mex/
│   ├── ROUTER.md          ← routing table, session bootstrap
│   ├── AGENTS.md          ← always-loaded anchor (~150 tokens)
│   ├── context/
│   │   ├── architecture.md   # how components connect
│   │   ├── stack.md           # technology choices and reasoning
│   │   ├── conventions.md     # naming, structure, patterns
│   │   ├── decisions.md       # append-only decision log
│   │   └── setup.md           # how to run locally
│   └── patterns/
│       ├── INDEX.md           # pattern registry
│       └── *.md               # task-specific guides with gotchas + verify checklists
└── src/

Multi-Tool Compatibility

| Tool | Config file | |------|------------| | Claude Code | CLAUDE.md | | Cursor | .cursorrules | | Windsurf | .windsurfrules | | GitHub Copilot | .github/copilot-instructions.md | | OpenCode | .opencode/opencode.json | | Codex (OpenAI) | AGENTS.md |

Most config files embed the same instructions directly. OpenCode is the exception — .opencode/opencode.json references .mex/AGENTS.md instead of embedding content. mex setup asks which tool you use and creates the appropriate config.

Contributing

Contributions welcome! See CONTRIBUTING.md for setup and guidelines.

Changelog

See CHANGELOG.md for release history.

License

MIT