mex

<div align="center"> <h1 id="mex"> <img src="docs/diagrams/readme/banner.svg" alt="MEX" width="1200"> </h1>

Shared project memory for engineers and their coding agents.

MEX keeps your team's architecture, decisions, requirements, and handoffs alongside the code. Engineers and their agents can build on shared context, review proposed changes, and carry work between sessions and teammates—with Git as the sharing layer.

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

Team memory · A teammate-handoff example · Project Hub · Quick start · How it works · Command map

</div>

---

One engineer knows why a constraint exists. Another has the debugging history. A coding agent found an important edge case in a session nobody else will read. The next teammate has to piece it together again.

What one engineer and their agent learn should become context the next teammate can use. MEX gives that knowledge a durable home in the repository: readable Markdown, code-linked explanations, reviewed knowledge contributions, and structured handoffs. People explore and review it in a local Hub; agents retrieve and help maintain it through project instructions and the CLI.

[!IMPORTANT] MEX 0.8.2 brings setup into the Hub: choose integrations, follow your agent, review and commit setup, then finish with optional global installation and contact details. Terminal setup remains available with mex setup --cli.

💬 Join the MEX community on Discord — discuss ideas, get help, share feedback, and show what you're building.

Join the Discord →

What your team remembers

| What the team needs to retain | Where it lives in MEX | | --- | --- | | How the system works, and why | Wiki architecture, decisions, conventions, and patterns, with Code Graph grounding | | A decision or explanation worth sharing | An Inbox proposal that adds to or corrects existing Wiki knowledge | | Product requirements already captured | Existing Specs, requirements, constraints, and acceptance criteria remain supported | | Where another engineer should continue | Relays with progress, decisions, blockers, evidence, and next actions | | Earlier workflow context | Existing Workstream records remain readable | | Who is involved, and what MEX recorded | Members and Activity history |

Canonical memory travels with ordinary Git commit, push, and pull. Each teammate keeps their own local indexes, drafts, identity selection, and Hub. No hosted MEX service, Docker, proxy, MEX account, or MEX-owned model key is required.

Working solo? The next person using that memory can be you in a new session.

From one engineer to the next

An example: Alex changes webhook retry handling, and Sam will continue the work. Both are active MEX Members in a repository their team has already set up.

1. Start with the team's context. Alex asks Codex to inspect the existing architecture, relevant decisions, and code evidence before making the change and running tests.
2. Keep the useful discoveries. With Alex's direction, Codex updates the relevant Wiki explanation and code references. For a conclusion the team should review, it prepares an Inbox knowledge proposal for explicit approval.
3. Prepare and publish the handoff. Alex asks $mex-relay to draft a Relay for Sam: what changed, which tests ran, what remains, and where to look next. She reviews the draft and publication preview in Hub, explicitly publishes it, then reviews, commits, and pushes the code and canonical MEX files through Git.
4. Continue from shared context. Sam pulls the relevant branch, updates his local indexes as needed, and opens Hub. He reviews and takes the Relay, then asks his coding agent to read its context and continue. His acknowledgement is another canonical change to commit and push.

The Relay carries the explanation and observed repository state—not the uncommitted code. Publishing writes files to Alex's checkout; it does not notify Sam or deliver anything until they share through Git. See Relay boundaries for lifecycle and concurrency details.

Project Hub

The Hub is where people explore and review their team's memory. Open it to explore connected project knowledge and code, review a proposed knowledge change, find an eligible handoff, or see recorded team history.

• Understand the project: Home, Search, Context, and Code bring explanations and implementation evidence together. The Context graph shows knowledge entities and relationships; selecting one reveals its direct code groundings and details.
• Review and carry work forward: Inbox proposes additions and corrections to project knowledge; Relays preserve what the next person needs. Existing Spec proposals and Workstream records remain readable.
• See who and what: Team/Members supports attribution and local identity selection. Activity shows accepted MEX workflow events and recorded project notes—not every code edit or Git action.
• Keep context usable: Health and Jobs expose index status and explicit maintenance.

After setup, run mex hub. Each engineer's Hub reads their own checkout and listens on 127.0.0.1; it is not a shared hosted dashboard. Git brings the team's canonical records into that checkout. Hub protects mutations with a server-side session and CSRF token. Playbook and Catch Up product workflows remain future work.

Quick start

MEX requires Node.js 22.5 or newer, SQLite FTS5 support in that Node build, and a Git repository. See runtime compatibility. The normal npm flow works on macOS, Linux, Windows Command Prompt, PowerShell, and WSL.

Introduce MEX to your repository

Run from the repository root:

npx mex-agent@0.8.2 setup

This opens setup in your local browser Hub. Choose your AI tools, watch the scaffold and indexes build, and let an available selected Claude Code or Codex CLI populate project memory. If the agent is unavailable or fails, copy the population prompt into your agent, then continue. Existing instructions are preserved; any manual integration pointers appear as advisory guidance.

Review the exact setup-file diff in the Hub and choose Commit setup to create a local commit. A manual Git checkpoint remains available. MEX preserves unrelated staged work and never pushes or pulls.

The completion screen explains how to start a fresh agent session and verify that it reads your project memory. It also offers two optional steps: install the mex command globally at the version running setup, and leave an email (plus an optional name) for follow-up about MEX. Contact details are sent through the embedded Web3Forms service and stay out of the repository and usage telemetry. Only a submitted/skipped preference is remembered on this computer. Choose Open Hub when ready; the Hub's introductory tour starts there.

Connected agents have their own installation, account, and network requirements. To print the local browser link without opening it, use npx mex-agent@0.8.2 setup --no-open; add --port <n> to choose a loopback port.

Prefer terminal setup or working over SSH?

npx mex-agent@0.8.2 setup --cli

mex setup --dry-run remains a terminal preview without changes. Once installed, bare mex opens the Hub (or setup for an incomplete project), while mex tui opens the terminal dashboard.

[!NOTE] The full Hub opens when the current .mex/config.json is committed at HEAD. Its setup wizard can commit the reviewed setup files on your explicit request, preserving unrelated staged work. Repositories with unsupported Git hooks or content filters keep the manual checkpoint. MEX never pushes or pulls.

Push the reviewed setup commit through your team's normal Git workflow so teammates receive the same project memory and selected agent instructions. In Hub's Team/Members page, add the people who will participate and choose your local identity. Review and apply those actions explicitly; commit and push new Member records too. Your current-member selection stays local.

Join a repository already using MEX 0.8

Clone or pull the team's repository and branch through Git. For a completed, committed 0.8 setup, build the derived indexes in your own checkout and open Hub:

npx mex-agent@0.8.2 graph rebuild
npx mex-agent@0.8.2 wiki rebuild-index
npx mex-agent@0.8.2 hub

Reuse the shared project memory; do not regenerate it just to join. In Team/Members, check the effective identity and, if needed, choose your existing Member record as a local override. If you do not have a record yet, explicitly create one through the reviewed workflow and share its canonical files. Members are attribution, not a sign-in or permission system.

The committed instruction files and skill directories are reusable by the agents they target. Install the agent separately and start a new session in the repository. If your chosen integration was not included in the shared setup, coordinate adding it with the team; see agent integrations. After later pulls or branch changes, inspect Graph/Wiki health and run the indicated explicit maintenance—reads do not silently update indexes.

Older or incomplete setups should follow upgrade and compatibility first. Keep CLI versions aligned before exchanging new Relays.

<details> <summary><strong>Prefer a global installation?</strong></summary>

npm install -g mex-agent@0.8.2
mex setup

The npm package is named mex-agent; the installed command is mex. Complete the review and commit checkpoint above before running mex hub.

Both the Hub and terminal completion flows offer an optional global installation pinned to the running MEX version. If it fails, setup remains complete an