mex

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

Why mex?

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.

What It Does

mex creates a structured markdown scaffold for agent memory:

• AGENTS.md / CLAUDE.md — tiny tool-loaded anchor
• ROUTER.md — routing table for task-specific context
• context/ — architecture, stack, setup, decisions, conventions
• patterns/ — reusable task guides with gotchas and verification steps
• .mex/events/decisions.jsonl — append-only notes through mex log

The 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.

Quick Start

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

Windows

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.sh flow): 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.

How It Works

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

Drift Detection

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

Scoring starts at 100. mex deducts 10 per error, 3 per warning, and 1 per info.

Editable source: docs/diagrams/drift-sync.excalidraw

Commands

All commands run from your project root. If you did not install globally, replace mex with npx mex-agent.

Supported Tools

mex setup asks which tool you use and creates the right config file.

Neovim users can use docs/vim-neovim.md for Claude Code, Avante.nvim, Copilot.vim, and generic plugin setups.

MCP Server

packages/mex-mcp exposes mex to AI agents over the Model Context Protocol as native tool calls — no shelling out, structured JSON back. It imports mex-agent directly, so the tools run the same code as the CLI and never drift from it.

Every tool takes an optional projectRoot (defaults to the current directory), so one server can target any project. Run mex setup first — the tools need a .mex/ scaffold.

Configure your client (Claude Code / Cursor .mcp.json):

{
  "mcpServers": {
    "mex": {
      "command": "node",
      "args": ["packages/mex-mcp/dist/index.js"]
    }
  }
}

Build it with npm run build --workspace mex-mcp first. Once published, this becomes "command": "npx", "args": ["mex-mcp"].

At session start an agent orients with two calls:

mex_check()                   # is the scaffold drifting?
mex_read_file("ROUTER.md")    # load the router, then pull only the context it needs

Before / After

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

Real World Results

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.

~60% average token reduction per session.

Agent Memory Mode

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 right memory files.
• context/ stores architecture, stack, conventions, setup, and decisions.
• patterns/ stores recurring runbooks.
• .mex/events/decisions.jsonl stores append-only notes and rationale through mex log.

mex heartbeat is intentionally lighter than mex check: it reads last_updated frontmatter and memory cleanup metadata, prints HEARTBEAT_OK when clean, and reports only when the agent needs to review stale context or memory files. Use mex watch --interval to run heartbeat repeatedly in a persistent-agent workspace.

Configuration

Optional settings live in .mex/config.json. Missing values fall back to defaults.

{
  "staleness": {
    "warnDays": 30,
    "errorDays": 90,
    "warnCommits": 50,
    "errorCommits": 200
  },
  "heartbeat": {
    "staleDays": 7,
    "memoryCleanupDays": 7,
    "dailyMemoryRetentionDays": 14
  },
  "watch": {
    "intervalMinutes": 30
  }
}

Telemetry

mex collects anonymous, opt-out usage data (command name, version, OS — never paths, args, file contents, IP, or personal data) to understand how the tool is used. Audit the exact payload with mex telemetry inspect, and opt out any time with DO_NOT_TRACK=1, MEX_TELEMETRY=0, or mex config set telemetry off. Full details: TELEMETRY.md.

Ecosystem

mex is provider-neutral. Integration guides, sponsored examples, and community recipes should be useful on their own, clearly labeled, and live in docs rather than silently changing the default experience.

Contributing

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

Changelog

See CHANGELOG.md for release history.

License

MIT