Setting up a new project scaffold for an AI-assisted codebase (mex-agent setup)
Building a symbol-grounded living wiki tied to exact source locations
Getting a project anchor file (AGENTS.md, CLAUDE.md, .cursorrules, ...) auto-generated so an agent picks up mex context as a standing rule, with no manual wiring
Keeping architectural notes, decisions, and conventions synchronized with code
Running drift detection (mex-agent check) to catch stale documentation
Syncing the wiki back to code after meaningful changes (mex-agent sync)
Retrieving compact, task-scoped context instead of a full-repo grep (mex-agent graph scope "<task>")
Migrating an existing pre-0.7 project into graph grounding (mex-agent graph ground)

When not to use this skill

The project has no meaningful history or architecture worth preserving as living documentation
Documentation is generated purely from source comments (docstrings only, no structured memory needed)
The user only wants an MCP server right now — mex's MCP package (packages/mex-mcp) is not published; do not promise MCP integration (see Compatibility above and Step 5 below)
Real-time code inspection is more urgent than architectural context — mex complements, not replaces, LSP/IDE tools

Instructions

Step 1: One-shot auto-install (recommended)

bash .agent-skills/mex/scripts/install.sh /path/to/project

This is the fully automated path: it registers the skill, resolves an actual mex-agent executable in the order MEX_AGENT_BIN → mex-agent → ~/.local/bin/mex-agent → bare mex only when its version is a mex-agent semantic version, and installs mex-agent plus an unambiguous wrapper when none is available. It then runs mex-agent setup non-interactively (skipped if .mex/ already exists — pass --force to re-run), ensures the default Codex/jeo path has a root AGENTS.md bridge, builds the code graph, runs mex-agent check, and reports the installed anchors. It is idempotent and safe to re-run. See --help for flags (--mode agent-memory, --force, --skip-skill, --tool <claude|cursor|windsurf|copilot|opencode|codex|multiple|none>, GLOBAL=1, AGENTS=<list>).

Known collision: machines with TeX Live installed (common via Homebrew on macOS) already have a mex command — the pdfTeX Multilingual TeX format, unrelated to this tool. mex --version disambiguates them: mex-agent prints a bare semver (e.g. 0.7.1); TeX Live's prints pdfTeX .... install.sh and scripts/mex.sh both resolve the unambiguous mex-agent wrapper first and still report any shadowing bare mex, so detection does not block execution.

Step 2: What auto-install produces

mex-agent setup scaffolds (verified against mex-agent 0.7.1; the README's own diagram is slightly aspirational — it shows an events/decisions.jsonl that does not exist until you actually run mex-agent log):

.mex/
|-- AGENTS.md          # small, always-loaded anchor (mirrors the root anchor)
|-- ROUTER.md          # maps task types to relevant wiki pages
|-- SETUP.md           # the "copy this into your agent" population prompt
|-- SYNC.md            # the drift-repair prompt used by `mex-agent sync`
|-- config.json        # scaffold id, detected AI tool(s)
|-- graph.db           # the deterministic code graph (SQLite)
|-- context/
|   |-- architecture.md
|   |-- stack.md
|   |-- setup.md
|   |-- decisions.md
|   `-- conventions.md
`-- patterns/
    |-- INDEX.md
    `-- README.md

Every context/*.md and patterns/* file is an empty template at this point — mex-agent setup does not read your codebase and fill them in. It prints a long prompt (bounded by "COPY ABOVE THIS LINE" banners) that you must paste into your coding agent's chat; that agent session is what actually writes project-specific content into the scaffold. scripts/install.sh detects the banner and prints a warning so this step is never silently skipped.

One consequence of automating that prompt: mex's follow-up "Has population finished?" grounding step is TTY-only (confirmAndCaptureGrounding bails when stdin is not a TTY, verified in mex-agent 0.7.1), so driving mex-agent setup non-interactively skips grounding capture. Run mex-agent graph ground once the agent has populated the scaffold; install.sh prints this reminder.

It also writes a project anchor file at the repository root, chosen interactively (mex asks "Which AI tool do you use?") — this is the "rule document" the skill turns on automatically once you've answered that one prompt (install.sh answers it for you via --tool, default codex):

Tool	Project anchor mex writes
Claude Code	`CLAUDE.md`
Codex	`AGENTS.md`
Cursor	`.cursorrules`
Windsurf	`.windsurfrules`
GitHub Copilot	`.github/copilot-instructions.md`
OpenCode	`.opencode/opencode.json`

jeo, gjc, and jeopi do not have a dedicated row in mex's own detection table, but all three read a project's root AGENTS.md the same way Codex does — this very repository's own AGENTS.md-driven skill instructions are loaded that way. So install.sh's default --tool codex gives jeo/gjc/jeopi their rule document automatically. That covers the anchor file only; the wiki content it points to (.mex/context/*.md, .mex/patterns/*) still needs the paste-into-agent step from Step 2 above — there is no way to skip that and still get real, project-specific content. Verify what actually exists with bash .agent-skills/mex/scripts/mex.sh doctor (Step 6).

Step 3: Populate ROUTER.md

Edit .mex/ROUTER.md to map common agent tasks to relevant wiki pages:

# ROUTER.md

## Task: add a new API endpoint

Load:
- context/architecture.md
- context/conventions.md
- patterns/http-handlers.md

Don't load:
- context/decisions.md (unless the endpoint changes a prior decision)

Step 4: Keep the graph and wiki current

mex-agent graph          # rebuild the deterministic code graph after code changes
mex-agent check          # validate paths, links, staleness, and grounded symbols
mex-agent sync           # repair drift with targeted agent prompts
mex-agent graph scope "<task description>"   # compact, task-relevant context

mex-agent check never spends AI tokens — it is a mechanical validator. When it finds drift, mex-agent sync hands the agent a targeted diff instead of asking it to rediscover the whole project.

Step 5: MCP server — not published, do not promise it

packages/mex-mcp in the upstream monorepo exposes the wiki and event log as MCP tools, but as of this writing it is not published to npm and ships no mex mcp CLI subcommand in the released mex-agent package. The only way to run it today is building from source inside a mex checkout:

git clone https://github.com/mex-memory/mex
cd mex && npm run build --workspace mex-mcp

Do not tell a user mex is "installed as an MCP server" for Claude Code, Cursor, jeo, gjc, jeopi, or OpenCode — there is no supported registration command yet. Check the MCP server section of the README (https://github.com/mex-memory/mex#mcp-server) to track publication status instead of fabricating a mcp add invocation.

Step 6: Read-only environment check

bash .agent-skills/mex/scripts/mex.sh doctor [project_path]
bash .agent-skills/mex/scripts/mex.sh check <project_path> [extra mex check args...]
bash .agent-skills/mex/scripts/mex.sh graph <project_path> [extra mex graph args...]

doctor only inspects the environment (Node.js version, mex-agent resolution, Git repo, .mex/ scaffold, and project anchors) — it never installs packages or modifies project memory. check/graph are thin pass-throughs to the real mex-agent CLI. Verified behavior in mex-agent 0.7.1: mex-agent check may refresh .mex/graph.db, so run it on a scratch copy when a shared or dirty worktree must remain byte-identical.

Best practices

Use install.sh, not manual steps — it is idempotent (skips mex-agent setup when .mex/ already exists) and reports the anchor file mex chose, removing the copy/paste error surface of doing this by hand.
ROUTER.md is the anchor — an intelligent router prevents agents from loading the entire wiki. Keep task-to-context mappings short and specific.
Ground claims to code — use frontmatter grounds_to for architectural decisions so they stay tethered to exact symbol fingerprints.
Check before sessions, sync after — mex-agent check detects staleness; mex-agent sync gives agents compact context for repairs. Because 0.7.1 may refresh graph.db during check, use a scratch copy for read-only audits.
Version the wiki — .mex/ is Markdown/JSONL; commit it to Git so you can track how memory evolved.
Multi-language support — mex handles TypeScript, JavaScript, Python, and Rust. If your project mixes languages, its code graph will too.
Never claim MCP is wired up — the MCP package is unpublished upstream; only document the build-from-source path in Step 5, and re-check the README before telling a user otherwise.
Telemetry is opt-out, not opt-in — mex sends anonymous command name/version/OS by default. Mention DO_NOT_TRACK=1, MEX_TELEMETRY=0, or mex-agent config set telemetry off if the user cares.

References

references/commands.md — curated command reference by workflow stage
scripts/install.sh — one-shot auto-installer (skill registration + mex-agent install + setup/graph/check)
scripts/mex.sh — read-only doctor + thin check/graph wrappers
Mex GitHub Repository
Mex Docs
Mex MCP server status — confirm publication status before promising MCP integration
Project standards: .agent-skills/skill-standardization/SKILL.md

Examples

Example 1: Auto-install and route agent context

bash .agent-skills/mex/scripts/install.sh ~/code/my-project
# Edit .mex/ROUTER.md to map your task types

The install prints which root anchor file was created (e.g. AGENTS.md), so jeo/gjc/jeopi/Codex-style agents pick it up on their very next session in that project, with no further setup.

Example 2: Detect drift after an agent session

cd ~/code/my-project
mex-agent check
# Reports stale paths, broken links, symbol changes
mex-agent sync
# Generates a compact diff for the agent to review

Example 3: Environment check before recommending mex to a project

bash .agent-skills/mex/scripts/mex.sh doctor /path/to/project
# Reports: Node.js version, resolved mex-agent status, Git repo status,
# .mex/ scaffold presence, and which project anchor file exists

Example 4: Re-run setup after moving to agent-memory mode

bash .agent-skills/mex/scripts/install.sh ~/code/my-homelab --mode agent-memory --force
# Adds HEARTBEAT.md conventions for long-running operational agents

mex

Mex — persistent project memory for AI coding agents

When to use this skill