mex

<div align="center"> <img src="mascot/mex-mascot.svg" alt="mex mascot" width="80"> <br> <img src="mascot/mex-ascii.svg" alt="MEX ASCII logo" width="520">

A living wiki for your codebase, maintained by your AI coding agents.

English | 简体中文 | Español | Português (Brasil)

</div>

---

mex maps your code, turns what agents learn into structured Markdown, and keeps that knowledge connected to the implementation it describes.

Every coding session starts with relevant architectural context instead of another full-repository scan.

New in v0.7.0: deterministic local code graphs, symbol-grounded knowledge, compact agent retrieval, and Python/Rust support alongside TypeScript and JavaScript.

💬 Join the mex community on Discord — discuss ideas, get help, share feedback, and contribute to the project.

Join the Discord →

npx mex-agent setup

<p align="center"> <img src="screenshots/mex-DashNew.jpg" alt="mex operational memory dashboard" width="640"> </p>

Your codebase knows more than its documentation

Architecture, conventions, edge cases, and past decisions are scattered across source code, pull requests, chat histories, and individual contributors.

AI coding agents rediscover that knowledge every session. A giant instruction file helps at first, but eventually floods the context window, becomes stale, and drifts away from the implementation.

mex creates a living, repo-local wiki that grows as agents work:

• agents document what they learn in readable Markdown
• a deterministic code graph connects that knowledge to exact symbols
• task-aware routing loads only the context needed for the current job
• drift checks identify knowledge affected by code changes
• completed work adds decisions, patterns, and current project state back into the wiki

The code remains the source of truth. The wiki becomes its maintained explanation.

| Ordinary project documentation | The mex living wiki | |---|---| | Written once and gradually forgotten | Grows from real coding work | | Disconnected from the implementation | Claims can point to exact code symbols | | Loaded as one giant instruction file | Context is routed by task | | Refactors silently invalidate docs | Changed, moved, and missing symbols are detected | | Every agent rediscovers the architecture | Agents inherit previous discoveries and decisions | | Knowledge disappears between sessions | Decisions and reusable patterns persist in the repository |

How it works

1. Map the codebase

mex builds a deterministic local code graph using Tree-sitter and SQLite. It indexes symbols and relationships across TypeScript, TSX, JavaScript, JSX, Python, and Rust, including framework-aware Express route-to-handler relationships.

mex graph

2. Build the wiki

During setup, your coding agent uses the graph to understand the project and populate a structured Markdown wiki:

.mex/
├── AGENTS.md
├── ROUTER.md
├── context/
│   ├── architecture.md
│   ├── stack.md
│   ├── setup.md
│   ├── decisions.md
│   └── conventions.md
├── patterns/
│   ├── INDEX.md
│   └── ...
└── events/
    └── decisions.jsonl

These remain ordinary Markdown files: readable, reviewable, version-controlled, and editable by humans or agents.

3. Route the right context

Agents begin with a small anchor file instead of loading the entire wiki. The anchor points to ROUTER.md, which selects the architecture notes, decisions, conventions, and task patterns relevant to the current job.

Agent task
    ↓
Small always-loaded anchor
    ↓
ROUTER.md
    ↓
Relevant wiki pages
    ↓
Compact code-graph neighborhood
    ↓
Targeted source expansion

Editable source: docs/diagrams/context-routing.excalidraw

4. Keep it current

After meaningful work, the agent updates project state, records decisions, and captures reusable patterns. mex checks that the wiki still agrees with the repository:

mex check
mex sync

mex check validates paths, commands, dependencies, links, indexes, staleness, tool configuration, and grounded code symbols without spending AI tokens. When repairs are needed, mex sync gives the agent targeted context instead of asking it to rediscover the whole project.

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

Grounded in the code

Wiki pages can connect important claims to exact graph nodes. A behavioral claim can be grounded through frontmatter:

---
grounds_to:
  - node: "function:a3f8...c21"
    fingerprint: "mh:64:9f2a..."
---

Load-bearing symbol references can also be navigable inline:

Authentication is enforced by
[`requireSession()`](mex://function:a3f8...c21).

When that function changes, moves, or disappears, mex can identify the affected knowledge. Confident renames and moves are durably rebound during sync; ambiguous changes are surfaced for the agent to resolve.

This lets agents read broadly to understand a behavior while grounding only the few symbols that actually support what they write.

Compact retrieval for coding agents

The graph is also a compact agent-retrieval layer:

mex graph scope "trace the authentication flow"

Instead of returning a large source dump, mex produces a scored neighborhood of relevant symbols under a hard estimated-token budget. The default response contains compact signatures, relationships, node IDs, and selection reasons.

Agents can then expand only the symbols they need:

mex graph get <node-id>

Structural queries and impact analysis are available directly:

mex graph query where-defined authenticate
mex graph query who-calls requireSession
mex graph query what-calls createServer
mex impact requireSession

Agent-facing graph commands use deterministic JSONL envelopes so tools can reliably distinguish metadata, results, and summaries.

Results

On the mex repository benchmark:

| Measurement | Result | |---|---:| | Full repository corpus ÷ graph scope | 916.38× | | Grep top-3 output ÷ graph scope | 10.74× | | Expected-symbol recall | 100% | | Minimal-context agent tasks completed | 5/5 | | Minimal-context tasks requiring fallback Read/Grep | 0/5 | | Inline-source tasks requiring fallback Read/Grep | 4/5 |

The measured repository contained:

• 252 corpus files
• approximately 733,605 estimated tokens
• 154 graph-indexed source files
• 1,867 code nodes
• 2,892 relationships
• approximately 7.2 seconds to build the graph

These are directional results from one repository, six scripted retrieval tasks, and five real-agent tasks. They demonstrate compact retrieval behavior, not a universal end-to-end graph-versus-no-graph token-savings claim.

See the benchmark results and evaluation harness for the methodology, raw results, caveats, and reproduction commands.

Quick start

mex requires Node.js 22.5 or newer. The npm package is named mex-agent because mex was already taken; the CLI command is still mex.

npx mex-agent setup

Setup inspects the repository, builds the local code graph, creates the Markdown wiki, asks your coding agent to populate it from graph evidence, installs the right project anchor, and validates the result.

After setup:

mex check                    # Check wiki health and code grounding
mex sync                     # Repair drift with targeted agent prompts
mex graph scope "<task>"     # Retrieve compact task context

If you skipped global installation, use npx mex-agent in place of mex. Install globally at any time with:

npm install -g mex-agent

Windows

The recommended npx mex-agent setup flow runs in Command Prompt, PowerShell, or WSL and does not require bash.

If you use the legacy setup.sh flow, run install, build, and CLI commands in the same environment. Do not build in WSL and then run the CLI from a native Windows terminal. See issue #10 for context.

Core commands

All commands run from the project root. Replace mex with npx mex-agent if it is not installed globally.

| Command | What it does | |---|---| | mex / mex tui | Open the interactive terminal dashboard | | mex setup | Create and populate the living wiki | | mex check | Check wiki health and calculate a drift score | | mex sync | Repair stale or inconsistent knowledge | | mex graph | Build or refresh the local code graph | | mex graph scope <task> | Retrieve compact, task-relevant context | | mex graph get <node-id...> | Expand exact symbols from a retrieval result | | mex graph query <relation> <symbol> | Query structural code relationships | | mex graph ground | Connect an existing pre-0.7 wiki to the graph | | mex impact <symbol\|file> | Find code and wiki content affected by a change | | mex log <message> | Record a decision, note, risk, or todo | | mex timeline | Read recent project events | | mex heartbeat | Run persistent-agent health checks | | mex completion <shell> | Print shell completions | | mex commands | List every command and script |

Existing mex projects

Projects created before mex 0.7 can add graph grounding without regenerating or rewriting their existing documentation:

mex graph
mex graph ground

The migration agent preserves existing prose while adding tight grounds_to entries and navigable mex:// references. It is safe to rerun.

Existing installations remain compatible. If no graph exists, the filesystem and lexical checkers continue to run. If SQLite or an individual grammar cannot load, graph checks are skipped with a warning while the rest of the CLI remains available.

See Code graph support for the tested language and relationship matrix, graceful-degradation behavior, and current limitations.

Supported tools

mex setup installs the appropriate project anchor for your coding agent:

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

Neovim users can follow the Neovim integration guide for Claude Code, Avante.nvim, Copilot.vim, and generic plugin setups.

MCP server

packages/mex-mcp exposes the existing wiki and event-log functionality as Model Context Protocol tools while importing the same implementation as the CLI.

The MCP package is not published yet. F