mex

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

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

=22.5">

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

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.

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:

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.