A living wiki for your codebase, maintained by your AI coding agents.
English | 简体中文 | Español | Português (Brasil)
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.8.0:mex setup
now prepares the Graph and Wiki end to end, installs the official Claude Code and Codex skills, protects local stores from Git, and automatically launches the first available agent you selected.
💬 Join the mex community on Discord — discuss ideas, get help, share feedback, and contribute to the project.
npx mex-agent setup
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 |
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 rebuild
Graph reads never rebuild implicitly. Use mex graph status
for a read-only
freshness check, mex graph refresh
to explicitly republish a compatible index,
and mex graph rebuild
for an isolated full rebuild. The legacy bare
mex graph
command remains a safe rebuild alias.
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.
Agents begin with a small anchor file instead of 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
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
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.
The graph is also a compact agent-retrieval layer:
mex graph scope "trace the authentication flow"
Instead of returning a repository-sized source dump, mex prioritizes the declarations and real execution flows most likely to answer the task under a hard estimated-token budget. The default response is source-backed and uses deterministic meta
, source
, flow
, and summary
JSONL records.
Returned source is already read. When the summary is ok
, an agent can answer directly even if lower-priority optional context was truncated. Exact expansion remains available when a declaration is missing or the summary recommends a follow-up:
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.
Targeted get
, query
, and impact
reads abstain when freshness cannot be proved; they never combine an older node identity with newer source text.
A 24-session pilot compared the 0.7.2 candidate with files-only search across 12 Hono and MEX tasks:
| Measurement | Result |
|---|---|
| Blind-correct answers | 7/12 candidate vs 6/12 files |
| New-token change | -54.5% |
| Processed-token change | -72.5% |
| Estimated-cost change | -56.6% |
| Mean-latency change | -22.9% |
| Required source spans returned | 22/23 (95.7%) |
| Required Hono flows returned | 6/6 (100%) |
Each task ran once per arm with Claude Sonnet. These are descriptive small-N results against a files-only baseline, not a released-main
comparison or a universal token-savings claim. See the benchmark report for methodology and limitations.
See the benchmark results and evaluation harness for the methodology, raw results, caveats, and reproduction commands.
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 protects checkout-local databases from Git, builds the code graph, asks your selected Claude Code or Codex CLI to populate the Markdown scaffold, migrates and indexes the Wiki, installs the project anchor and official MEX skills, and validates the result. It then prints the commit checkpoint required before Hub can start.
The mex-agent
npm package ships two official project skills from one canonical source:
mex-inbox
prepares governed Spec, requirement, constraint, and acceptance-criterion proposals.mex-relay
prepares durable team handoffs.
The normal mex setup
flow installs copies for every selected supported agent; no separate plugin or skill installer is required. Claude Code receives .claude/skills/mex-inbox
and .claude/skills/mex-relay
, while Codex receives .agents/skills/mex-inbox
and .agents/skills/mex-relay
. Selecting both agents installs both sets and updates only the marker-delimited MEX block in CLAUDE.md
and AGENTS.md
. That managed block also directs every new agent session to read .mex/AGENTS.md
and .mex/ROUTER.md
before project work.
Invoke the skills explicitly as /mex-inbox
and /mex-relay
in Claude Code, or $mex-inbox
and $mex-relay
in Codex. Clear natural-language requests for governed Spec proposals or durable handoffs invoke them automatically as well.
A plain npm package install only delivers the payload; it never mutates the current repository. After upgrading mex-agent
, receive newer packaged skill copies with:
mex skills sync
mex skills sync --dry-run
Start a new Claude Code or Codex session after setup or sync so the skills and project instructions are guaranteed to load. Project skill files should normally be committed so teammates receive the same behavior. MEX never stages or commits them automatically. If a project ignores one of the narrow skill paths, sync warns with the exact path and suggested ignore rule instead of exposing other .claude
or .agents
files.
A standalone Codex plugin or marketplace package may be added later, but it is not required for this release.
After setup:
git status --short # Review the canonical MEX files
git add .mex # Local Graph/Wiki databases stay ignored
git commit -m "chore: initialize MEX"
mex check # Check wiki health and code grounding
mex sync # Repair drift with targeted agent prompts
mex graph scope "<task>" # Retrieve compact task context
mex hub # Opens after .mex/config.json is committed at HEAD
If you skipped global installation, use npx mex-agent
in place of mex
. Install globally at any time with:
npm install -g mex-agent
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.
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 hub [--port <n>] [--no-open] |
|
| Open the secure local Project Hub | |
mex capabilities --json |
|
| Discover bounded structured reads, previews, and apply commands | |
| `mex member list | show |
| Read canonical members and the effective actor | |
| `mex member add | update |
| Preview a member/selection request; apply only an approved preview envelope | |
| `mex activity list | show --json` |
| Read bounded canonical Activity | |
mex activity record |
|
| Preview an append-only canonical Activity record | |
| `mex workstream list | show --json` |
| Read bounded canonical Workstreams | |
| `mex workstream create | update |
| Preview a Workstream change; apply only an approved preview envelope | |
mex inbox contract --action <command-id> --json |
|
| Resolve only the exact Inbox mutation schema needed by an agent | |
mex relay contract --action <command-id> --json |
|
| Resolve only the exact Relay mutation schema needed by an agent | |
| `mex inbox | relay contract --json` |
| Resolve the backward-compatible complete static contract catalog for diagnosis | |
| `mex relay draft list | show |
| Read or preview changes to checkout-local handoff drafts | |
| `mex relay list | show --json` |
| Read bounded canonical handoffs; the Workstream filter matches legacy Relays only | |
| `mex relay publish | acknowledge |
| Preview a standalone handoff lifecycle action; apply only its exact approved envelope | |
| `mex spec list | show --json` |
| Read root Specs and their explicit Wiki hierarchy without maintaining indexes | |
mex setup |
|
| Create and populate the living wiki | |
mex skills sync [--dry-run] [--json] |
|
| Install or safely update official skills for configured Claude Code/Codex clients | |
mex check |
|
| Check wiki health and calculate a drift score | |
mex sync |
|
| Repair stale or inconsistent knowledge | |
mex graph |
|
| Backward-compatible alias for a safe isolated rebuild | |
mex graph status |
|
| Inspect graph freshness without writing | |
mex graph refresh |
|
| Explicitly refresh a compatible graph index | |
mex graph rebuild |
|
| Build and validate an isolated candidate, then publish it atomically | |
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 graph repair |
|
| Recover an interrupted graph store without a rebuild | |
| `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 |
mex hub
starts a desktop-oriented control room on 127.0.0.1
and opens it in
your browser. The bootstrap link is one-use, ordinary API requests require an
in-memory session, and mutating requests also require same-origin CSRF proof.
Use --no-open
to print the launch URL without opening a browser, or --port
to request a specific loopback port.
The Hub displays repository context, locally persisted job history, canonical members and Workstreams, read-only Specs, the effective checkout actor, and the read-only Activity timeline. The Members workbench uses explicit preview/review/apply for canonical identity changes and keeps member selection local. Activity presents immutable MEX records alongside Project notes without exposing a manual recorder in the browser. New records retain a service-owned workflow/custom origin and an optional human label; older records remain byte-preserving and display an unknown origin. The Workstreams workbench uses the same exact preview/apply boundary for create, update, and one-way archive operations; every successful canonical change emits one Activity event. Specs are a fresh-index, read-only view of canonical Wiki Spec roots and explicit requirement, constraint, acceptance-criterion, and refinement relations. The real Code workspace searches symbols and source, inspects callers/callees/impact, reports graph Health, and lets you explicitly refresh or rebuild the local graph. Its read-only Knowledge workspace browses and searches canonical Wiki entries, shows bounded evidence, provenance, relations, backlinks, and current grounding, and links Code to Knowledge only through explicit groundings. Wiki Health offers explicit refresh/rebuild jobs only when a stable status makes them safe. Reads never maintain either index automatically, rankings remain domain-local, and the packaged UI never substitutes development fixtures for project data.
Relays are standalone repository-native handoffs. A new handoff needs recipients and a summary, not a Workstream. Publication records the observed branch, exact HEAD, clean/dirty flag, and observation time without staging, committing, pushing, pulling, or capturing dirty source contents. Existing schema-v1/v2 Relays keep their recorded Workstream and remain actionable. Before a repository starts publishing strict schema-v3 Relays, every teammate must update MEX; older binaries cannot parse the new format.
Projects created before mex 0.7 can add graph grounding without regenerating or rewriting their existing documentation:
mex graph rebuild
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.
mex setup
installs the appropriate project anchor and, for Claude Code or Codex, the official project skills:
| Tool | Project anchor | Official skill directory |
|---|---|---|
| Claude Code | CLAUDE.md |
|
.claude/skills/mex-inbox , .claude/skills/mex-relay |
||
| Codex | AGENTS.md |
|
.agents/skills/mex-inbox , .agents/skills/mex-relay |
||
| 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.
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. For local development, build it with:
npm run build --workspace mex-mcp
The primary v0.8.0 release remains the mex-agent
CLI.
The primary mex experience is the living codebase wiki. The same routing and maintenance model can also support persistent agents whose project is an operational environment:
mex setup --mode agent-memory
Agent-memory mode adds a HEARTBEAT.md
contract and cleanup conventions for homelabs, infrastructure workspaces, and long-running operational agents.
In an independent community test on OpenClaw, mex passed 10/10 structured homelab scenarios and reduced loaded context by approximately 60% on average. These results describe agent-memory mode and are separate from the code-graph benchmark above.
Markdown is the durable interface. Humans and agents can both read and edit it.Code is the source of truth. Important claims stay connected to implementation.Context should be routed, not dumped. Agents load what the task requires.Knowledge should grow from real work. Useful patterns emerge from completed tasks.Maintenance should be continuous. Documentation evolves with the repository.Retrieval should be deterministic. Mechanical work should not consume AI tokens.
mex collects anonymous, opt-out usage data—command name, version, and OS—to understand how the tool is used. It never collects paths, arguments, file contents, IP addresses, or personal data.
Audit the exact payload with mex telemetry inspect
. Opt out with DO_NOT_TRACK=1
, MEX_TELEMETRY=0
, or mex config set telemetry off
. See TELEMETRY.md for full details.
mex is provider-neutral. Integration guides, sponsored examples, and community recipes should be useful on their own, clearly labeled, and live in documentation rather than silently changing the default experience.
Contributions are welcome. See CONTRIBUTING.md for development setup and guidelines.
See CHANGELOG.md for release history.