by mex-memory
Persistent project memory for AI coding agents. Structured scaffold + drift detection CLI.
# Add to your Claude Code skills
git clone https://github.com/mex-memory/mexLast scanned: 6/22/2026
{
"issues": [
{
"type": "npm-audit",
"message": "brace-expansion: brace-expansion: Large numeric range defeats documented `max` DoS protection",
"severity": "medium"
},
{
"type": "npm-audit",
"message": "esbuild: esbuild allows arbitrary file read when running the development server on Windows",
"severity": "low"
},
{
"type": "npm-audit",
"message": "postcss: PostCSS has XSS via Unescaped </style> in its CSS Stringify Output",
"severity": "medium"
},
{
"type": "npm-audit",
"message": "simple-git: simple-git is vulnerable to Remote Code Execution",
"severity": "high"
},
{
"type": "npm-audit",
"message": "vite: launch-editor: NTLMv2 hash disclosure via UNC path handling on Windows",
"severity": "high"
},
{
"type": "npm-audit",
"message": "vitest: When Vitest UI server is listening, arbitrary file can be read and executed",
"severity": "critical"
},
{
"type": "npm-audit",
"message": "ws: ws: Memory exhaustion DoS from tiny fragments and data chunks",
"severity": "high"
}
],
"status": "FAILED",
"scannedAt": "2026-06-22T09:48:30.396Z",
"npmAuditRan": true,
"pipAuditRan": true,
"promptInjectionRan": true
}mex is an open-source ai agents skill for AI coding assistants such as Claude Code, Codex CLI, and ChatGPT, built by mex-memory. Persistent project memory for AI coding agents. Structured scaffold + drift detection CLI. It has 985 GitHub stars.
mex failed SkillsLLM's automated security scan, which flagged one or more high-severity issues. Review the Security Report section carefully before using it.
Clone the repository with "git clone https://github.com/mex-memory/mex" and add it to your Claude Code skills directory (see the Installation section above).
mex is primarily written in TypeScript. It is open-source under mex-memory on GitHub, so you can review or fork the full source.
Yes. SkillsLLM lists many other AI Agents skills you can browse and compare side by side. Open the AI Agents category from the badge at the top of this page, or use the Related Skills and comparison links further down to weigh mex against similar tools.
No comments yet. Be the first to share your thoughts!
Requires a passing catalog security scan. Resolve the flagged issues and resubmit to enable featuring.
Persistent project memory for AI coding agents.
AI agents forget everything between sessions. mex gives them permanent, navigable project memory so every session starts with the right context instead of a cold prompt dump.
npx mex-agent setup
Most agent memory setups become one giant instruction file. That works for a while, then it floods the context window, burns tokens, and drifts away from the real codebase.
| Without mex | With mex |
|---|---|
Giant CLAUDE.md / rules files |
Small anchor file plus routed context |
| Agents forget decisions and conventions | Decisions, patterns, and project state persist |
| Docs silently drift from code | mex check catches stale or broken scaffold claims |
| Every session starts cold | Agents load only the files relevant to the task |
| Repeated work stays tribal | New patterns grow from real tasks |
mex creates a structured markdown scaffold for agent memory:
AGENTS.md / CLAUDE.md — tiny tool-loaded anchorROUTER.md — routing table for task-specific contextcontext/ — architecture, stack, setup, decisions, conventionspatterns/ — reusable task guides with gotchas and verification steps.mex/events/decisions.jsonl — append-only notes through mex logThe CLI keeps that scaffold honest. It checks paths, commands, dependencies, pattern indexes, staleness, and script coverage without spending AI tokens. When drift appears, mex sync builds targeted prompts so the agent fixes only the stale pieces.
The npm package is named mex-agent because mex was already taken. The CLI command is still mex.
npx mex-agent setup
Setup creates the .mex/ scaffold, asks which AI tool you use, pre-scans your codebase, and generates a targeted prompt to populate the memory files. It takes about five minutes.
At the end of setup, you can install mex globally:
mex check # drift score
mex sync # fix drift
If you skip global install, use npx:
npx mex-agent check
npx mex-agent sync
Install globally later at any time:
npm install -g mex-agent
The recommended npx mex-agent setup flow runs in any terminal (Command Prompt, PowerShell, or WSL) and does not need bash, so most Windows users do not have to think about this section.
Windows users (legacy
setup.shflow): Run all commands inside WSL or Git Bash. Do not mix environments.
If you previously installed via the legacy setup.sh script, building inside WSL and then running the CLI from a native Windows terminal causes "module not found" errors because node_modules and path resolution differ between the two filesystems. Run install, build, and CLI commands inside the same environment: either entirely in WSL / Git Bash, or entirely in native Windows via npx mex-agent.
See issue #10 for context.
The agent starts with a tiny auto-loaded file. That file points to ROUTER.md, and the router loads only the context needed for the current task. After meaningful work, the GROW step updates project state, decisions, and task patterns so the scaffold becomes more useful over time.
Editable source: docs/diagrams/context-routing.excalidraw
Eleven checkers validate your scaffold against the real codebase. Zero tokens, zero AI.
| Checker | What it catches |
|---|---|
| path | Referenced file paths that do not 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 references scripts that do not 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 |
| tool-config-sync | Installed AI tool config files (e.g. CLAUDE.md, .cursorrules) out of sync with each other |
| todo-fixme | Unresolved TODO / FIXME markers left in scaffold markdown |
| broken-link | Markdown links to local files that do not exist on disk |
Scoring starts at 100. mex deducts 10 per error, 3 per warning, and 1 per info.
Editable source: docs/diagrams/drift-sync.excalidraw
All commands run from your project root. If you did not install globally, replace mex with npx mex-agent.
| Command | What it does |
|---|---|
mex |
Open the interactive terminal dashboard |
mex tui |
Open the interactive terminal dashboard explicitly |
mex setup |
First-time setup: create .mex/ scaffold and populate with AI |
mex setup --mode agent-memory |
Create templates for persistent-agent / homelab memory workspaces |
mex setup --dry-run |
Preview what setup would do without making changes |
mex check |
Run drift checkers and output a scored report |
mex check --quiet |
One-liner: mex: drift score 92/100 (1 warning) |
mex check --json |
Full report as JSON |
mex check --fix |
Check and jump straight to sync if errors are found |
mex sync |
Detect drift, choose mode, let AI fix, 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 and build a structured brief for AI |
mex init --json |
Raw scanner brief as JSON |
mex log <message> |
Append a note, decision, risk, or todo |
mex timeline |
View recent event log entries |
mex heartbeat |
Run lightweight persistent-agent health checks once |
mex doctor |
Friendly scaffold health summary |
mex watch |
Install post-commit hook |
mex watch --interval |
Run heartbeat repeatedly in the foreground |
mex watch --uninstall |
Remove the hook |
mex completion <shell> |
Print shell completions |
mex commands |
List commands and scripts with descriptions |
mex setup asks which tool you use and creates the right config file.
| Tool | Config file |
|---|---|
| Claude Code | CLAUDE.md |
| Cursor | .cursorrules |
| Windsurf | .windsurfrules |
| GitHub Copilot | .github/copilot-instructions.md |
| OpenCode | .opencode/opencode.json |
| Codex | AGENTS.md |
Neovim users can use docs/vim-neovim.md for Claude Code, Avante.nvim, Copilot.vim, and generic plugin setups.
Real output from testing mex on Agrow, an AI-powered agricultural voice helpline.
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 with configurable selection
- 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; ElevenLabs fallback in use
Patterns directory after setup:
patterns/
├── add-api-client.md
├── add-language-support.md
├── debug-pipeline.md
└── add-rag-documents.md
Independently tested by a community member on OpenClaw across 10 structured homelab scenarios covering Ubuntu 24.04, Kubernetes, Docker, Ansible, Terraform, networking, and monitoring. 10/10 tests passed. Drift score: 100/100.
| 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.
mex setup --mode agent-memory creates a scaffold for persistent agents whose "project" is an operational environment rather than a code repo. It adds a HEARTBEAT.md contract and templates that frame mex as structured, task-routed memory:
ROUTER.md tracks current operational state and routes the agent to the righ