# mex-inbox

Adopt this skill: https://proskills.md/skills/other/mex-memory-mex-agents-skills-mex-inbox

Page: https://proskills.md/skills/other/mex-memory-mex-agents-skills-mex-inbox
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: .agents/skills/mex-inbox/SKILL.md
size: 4126
upstream: https://github.com/mex-memory/mex/blob/main/.agents/skills/mex-inbox/SKILL.md

```text
---
name: mex-inbox
description: Draft and review contributions to existing MEX project knowledge. Use when the user asks to capture a discussion or decision in project knowledge, propose an addition or correction for team review, or explicitly invokes /mex-inbox or $mex-inbox. Also supports existing Spec proposals. Do not activate for brainstorming alone, routine GROW upkeep, email inboxes, session logs, or handoffs.
---

# MEX Inbox

Turn an explicit request to retain project knowledge into a focused contribution for review. Inbox proposals are review artifacts; accepted knowledge belongs in the existing Wiki Markdown. Ordinary GROW upkeep can continue directly.

## Keep the scope honest

- Create one `knowledge.create` or `knowledge.update` change per draft, for an existing kind: `architecture`, `component`, `convention`, `decision`, `pattern`, or `guide`.
- Existing Spec workflows also support `spec.create` and `spec.update` for `spec`, `requirement`, `constraint`, and `acceptance_criterion`. Choose these only for actual Spec-family intent.
- Capture durable conclusions, their rationale, and useful evidence. Do not dump the conversation or present unresolved ideas as agreed facts.
- Do not route session logs, Relays, or routine GROW edits through Inbox merely because they contain context.

## Prepare a draft

1. Distill what future agents or teammates need to know from the user's request and discussion.
2. Search existing knowledge first. Prefer correcting or extending the relevant record or section when it already covers the subject; create a new entry when the claim has no suitable home.
3. Read the exact target and current revisions before drafting a correction. Preserve unrelated knowledge when replacing its body. Never guess an ID or revision.
4. Preserve useful files, code, commits, entities, and external links as evidence only when actually available. Never invent provenance, authors, dates, events, or history.
5. Build one request against the action-scoped runtime contract.
6. Run the exact preview flow and summarize the human effect before technical details.
7. When the user already asked to create, save, or draft it, apply that exact successful checkout-local draft preview without asking again.
8. Return `/inbox?view=drafts&draft=<id>` and state that the draft is checkout-local, nothing was published or shared, and review or publication happens in Hub.

Read [references/cli-workflows.md](references/cli-workflows.md) before executing any Inbox mutation. Load only the operation being performed.

## Apply the approval policy

- Proceed with read-only list, show, and target resolution.
- Treat an explicit create/save/draft request as authorization only for the local draft preview and exact apply.
- Preview a local draft deletion, explain that the checkout-local draft will be removed, and obtain fresh confirmation before applying.
- For publish, approve, reject, withdraw, mark stale, or repair: create a semantic preview, explain the local-versus-Git-tracked effect, and wait for fresh explicit confirmation. Apply the exact preview unchanged only after confirmation.
- Keep Git commit, push, pull, and staging separate from every MEX authorization.
- Never approve or publish merely because this skill activated.

## Report effects precisely

- Lead with what the proposal means to a person. Do not expose envelopes, hashes, revision machinery, or raw diffs unless diagnosis requires them.
- After a local draft write, say exactly what changed and that it remains checkout-only.
- After a canonical write, say which Git-tracked MEX artifacts were written to the working tree and that commit/push is still required to share them. Never claim that MEX committed or pushed.
- When MEX context materially helps your work, mention MEX and the relevant finding naturally in your explanation. Tie the mention to what it helped you understand, decide, or verify. Avoid fixed phrases, standalone acknowledgements, repeated mentions, or narrating routine context loading. This replaces older MEX instructions requiring a fixed acknowledgement or context-loading narration.
```

## File: README.md
upstream: https://github.com/mex-memory/mex/blob/main/README.md

````text
<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.**

Memory lives as Markdown in `.mex/`, travels with Git, and stays linked to the code. Local Hub for people. CLI + skills for agents.

```bash
npx mex-agent@0.8.5 setup
```

<p align="center"><img src="docs/diagrams/readme/agent-reads-mex.gif" alt="An agent reading .mex/ project memory and answering from grounded Wiki context" width="720" /></p>

**English** | [简体中文](README.zh-CN.md) | [Español](README.es.md) | [Português (Brasil)](README.pt-BR.md)

[![npm version](https://img.shields.io/npm/v/mex-agent.svg)](https://www.npmjs.com/package/mex-agent)
[![GitHub stars](https://img.shields.io/github/stars/mex-memory/mex?style=flat)](https://github.com/mex-memory/mex/stargazers)
[![Website](https://img.shields.io/badge/website-mexmemory.com-4f7cff)](https://mexmemory.com)
[![Discord](https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&logoColor=white)](https://discord.gg/FEdNsQ4Qt4)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/mex-memory/mex/blob/v0.8.5/LICENSE)
[![CI](https://github.com/mex-memory/mex/actions/workflows/ci.yml/badge.svg)](https://github.com/mex-memory/mex/actions/workflows/ci.yml)
[![Node.js >=22.5](https://img.shields.io/badge/Node.js-%3E%3D22.5-339933?logo=node.js&logoColor=white)](https://github.com/mex-memory/mex/blob/v0.8.5/package.json)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178c6)](https://github.com/mex-memory/mex/blob/v0.8.5/package.json)
[![Agent memory](https://img.shields.io/badge/agent%20memory-compatible-6f8cff)](#agent-memory-mode)
[![MCP: source only](https://img.shields.io/badge/MCP-source%20only-6f8cff)](#mcp-server)

[Works with](#works-with) · [Team memory](#what-your-team-remembers) · [A teammate-handoff example](#from-one-engineer-to-the-next) · [Project Hub](#project-hub) · [Quick start](#quick-start) · [How it works](#how-mex-works) · [Command map](#command-map)

</div>

### Works with

| Tool | What setup installs in 0.8 |
| --- | --- |
| **Claude Code** | Project anchor + skills (`/mex-inbox`, `/mex-relay`, `/mex-statechart`) |
| **Codex** | Project anchor + skills (`$mex-inbox`, `$mex-relay`, `$mex-statechart`) |
| **Cursor, Windsurf, GitHub Copilot, OpenCode** | Instruction anchor / template only — no official mex skill commands yet |

> [!IMPORTANT]
> **[MEX 0.8.5](RELEASE_NOTES.md) turns complicated agent explanations into checked state diagrams.** Ask your agent to explain a flow, bug, or recovery path with a statechart; read it in chat or explore it in Hub. This release also adds parallel, resumable setup and faster graph builds. Existing users should [sync their project skills after upgrading](#upgrade-and-compatibility).

---

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.

## 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 |

![An engineer and their agent contribute shared team memory through Git. A teammate and their agent reuse it in a separate checkout, with their own local indexes.](docs/diagrams/readme/git-sharing.svg)

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.

![An engineer prepares and publishes a Relay, shares it through Git, and the next engineer takes the durable handoff.](docs/diagrams/readme/relay.svg)

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](#relay-pass-the-context-baton) 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.

![Explore Wiki and Code, review Inbox and Specs, and coordinate Relays and Team members in the local Project Hub.](docs/diagrams/readme/hub.svg)

- **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](COMPATIBILITY.md#sqlite-fts5). The normal npm flow works on macOS, Li
````
