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.
The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
117,048
developer-tools
documentation
llm
Using mex shorthand: Commands below use mex — run cd .mex && npm link && cd .. once to enable this. Or replace mex with node .mex/dist/cli.js if you prefer not to link globally.
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
The CLI is built automatically during setup.sh. All commands run from your project root (not from inside .mex/).
mex check
If you need to rebuild manually:
cd .mex && npm install && npm run build && cd ..
Commands
| Command | What it does |
|---------|-------------|
| 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
Shell Scripts
The shell scripts are bash scripts and require a bash-compatible shell. On macOS and Linux they work out of the box. On Windows, use WSL, Git Bash, or any bash-compatible terminal.
These run from your project root. They auto-build the CLI if needed. All support --help.
bash .mex/setup.sh # First-time setup — scan, prompt, populate
bash .mex/sync.sh # Interactive menu — check, sync, or export prompt
bash .mex/update.sh # Pull latest mex infrastructure, keep your content
Note: The CLI commands (node .mex/dist/cli.js ...) work on any platform with Node.js, including Windows cmd and PowerShell. Only the shell scripts above require bash.
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
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.
⭐AI-driven public opinion & trend monitor with multi-platform aggregation, RSS, and smart alerts.🎯 告别信息过载，你的 AI 舆情监控助手与热点筛选工具！聚合多平台热点 + RSS 订阅，支持关键词精准筛选。AI 智能筛选新闻 + AI 翻译 + AI 分析简报直推手机，也支持接入 MCP 架构，赋能 AI 自然语言对话分析、情感洞察与趋势预测等。支持 Docker ，数据本地/云端自持。集成微信/飞书/钉钉/Telegram/邮件/ntfy/bark/slack 等渠道智能推送。
