mex

Mex — AI コーディングエージェントのための永続的なプロジェクトメモリ

Mex はコードをマッピングし、エージェントが学んだことを構造化された Markdown に変換し、その知識を説明対象の実装と結び付けた状態に保ちます。コーディングセッションを始めるたびに、リポジトリ全体を再スキャンするのではなく、関連するアーキテクチャのコンテキストから開始できます。

このスキルを使う場面

• AI 支援を前提としたコードベースで、新しいプロジェクトのひな形を設定する（mex-agent setup）
• 正確なソースコードの位置にひも付いた、シンボルを根拠とする更新され続ける Wiki を構築する
• プロジェクトのアンカーファイル（AGENTS.md、CLAUDE.md、.cursorrules、...）を自動生成し、手動で設定しなくてもエージェントが mex のコンテキストを常時ルールとして取り込めるようにする
• アーキテクチャに関するメモ、決定事項、規約をコードと同期した状態に保つ
• ドリフト検出（mex-agent check）を実行し、古くなったドキュメントを見つける
• 重要な変更後に Wiki をコードへ同期する（mex-agent sync）
• リポジトリ全体を grep する代わりに、タスクに即したコンパクトなコンテキストを取得する（mex-agent graph scope "<task>"）
• 既存の 0.7 未満のプロジェクトをグラフの根拠付けに移行する（mex-agent graph ground）

このスキルを使わない場面

• プロジェクトに、更新され続けるドキュメントとして残す価値のある履歴やアーキテクチャがない
• ドキュメントがソースコードのコメントだけから生成されており（docstring のみ）、構造化されたメモリが必要ない
• ユーザーが今すぐ必要としているのは MCP サーバーだけ — mex の MCP パッケージ（packages/mex-mcp）は公開されていません。MCP 連携を約束しないでください（上記の「互換性」と下記のステップ 5 を参照）
• アーキテクチャのコンテキストよりリアルタイムのコード検査を優先する必要がある — mex は LSP／IDE ツールを補完するものであり、置き換えるものではありません

手順

ステップ 1：ワンショットの自動インストール（推奨）

bash .agent-skills/mex/scripts/install.sh /path/to/project

これは完全自動化された方法です。スキルを登録し、MEX_AGENT_BIN → mex-agent → ~/.local/bin/mex-agent の順に実際の mex-agent 実行ファイルを探します。いずれも見つからない場合は、バージョンが mex-agent のセマンティックバージョンである場合に限り、最後に単独の mex を確認し、mex-agent と曖昧さのないラッパーをインストールします。続いて、非対話モードで mex-agent setup を実行します（.mex/ がすでに存在する場合はスキップされます。再実行するには --force を渡してください）。さらに、デフォルトの Codex／jeo パスにルートの AGENTS.md ブリッジがあることを確認し、コードグラフを構築して mex-agent check を実行し、インストールされたアンカーを報告します。冪等で、安全に再実行できます。フラグについては --help を参照してください（--mode agent-memory、--force、--skip-skill、--tool <claude|cursor|windsurf|copilot|opencode|codex|multiple|none>、GLOBAL=1、AGENTS=<list>）。

既知の競合： TeX Live がインストールされたマシン（macOS では Homebrew 経由でインストールされていることがよくあります）には、すでに mex コマンドがあります。これはこのツールとは無関係の pdfTeX Multilingual TeX 形式です。mex --version で区別できます。mex-agent はセマンティックバージョンをそのまま出力します（例：0.7.1）。一方、TeX Live は pdfTeX ... と出力します。install.sh と scripts/mex.sh はどちらも、曖昧さのない mex-agent ラッパーを最初に解決し、既存の mex コマンドとの競合も報告するため、検出によって実行が妨げられることはありません。

Step 2: 自動インストールで生成されるもの

mex-agent setup は次の構成を作成します（mex-agent 0.7.1 で検証済みです。README の図はやや理想的な状態を示しており、events/decisions.jsonl は実際に mex-agent log を実行するまで存在しません）。

.mex/
|-- AGENTS.md          # small, always-loaded anchor (mirrors the root anchor)
|-- ROUTER.md          # maps task types to relevant wiki pages
|-- SETUP.md           # the "copy this into your agent" population prompt
|-- SYNC.md            # the drift-repair prompt used by `mex-agent sync`
|-- config.json        # scaffold id, detected AI tool(s)
|-- graph.db           # the deterministic code graph (SQLite)
|-- context/
|   |-- architecture.md
|   |-- stack.md
|   |-- setup.md
|   |-- decisions.md
|   `-- conventions.md
`-- patterns/
    |-- INDEX.md
    `-- README.md

この時点では、context/*.md と patterns/* の各ファイルはすべて空のテンプレートです。mex-agent setup がコードベースを読み込んで内容を埋めることはありません。長いプロンプト（「COPY ABOVE THIS LINE」のバナーで区切られています）が表示されるので、コーディングエージェントのチャットに貼り付ける必要があります。エージェントのセッションで、スキャフォールドにプロジェクト固有の内容を書き込みます。scripts/install.sh はバナーを検出して警告を表示するため、この手順が気付かないうちに飛ばされることはありません。

このプロンプトを自動化する際の注意点として、mex の後続の「Has population finished?」というグラウンディング手順は TTY でしか実行されません（confirmAndCaptureGrounding は stdin が TTY でない場合に終了します。mex-agent 0.7.1 で検証済みです）。そのため、mex-agent setup を非対話型で実行すると、グラウンディング情報の取得がスキップされます。エージェントがスキャフォールドへの入力を済ませたら、mex-agent graph ground を一度実行してください。install.sh はこの手順をリマインドします。

また、対話形式で選択したリポジトリルートのプロジェクトアンカーファイルも書き込みます（mex は「Which AI tool do you use?」と尋ねます）。このファイルは、そのプロンプトに回答するとスキルが自動的に有効にする「ルールドキュメント」です（install.sh は --tool で回答を指定します。デフォルトは codex です）。

ツール	mex が書き込むプロジェクトアンカー
Claude Code	CLAUDE.md
Codex	AGENTS.md
Cursor	.cursorrules
Windsurf	.windsurfrules
GitHub Copilot	.github/copilot-instructions.md
OpenCode	.opencode/opencode.json

jeo、gjc、jeopi は mex 独自の検出テーブルに専用の行がありませんが、3つとも Codex と同じ方法でプロジェクトルートの AGENTS.md を読み込みます。このリポジトリ自体の AGENTS.md に基づくスキル指示も、その方法で読み込まれます。そのため、install.sh のデフォルトである --tool codex を指定すれば、jeo／gjc／jeopi にルールドキュメントが自動的に適用されます。これはアンカーファイルのみを対象としています。アンカーファイルが参照する Wiki の内容（.mex/context/*.md、.mex/patterns/*）には、上記の Step 2 のとおり、エージェントに貼り付ける手順が引き続き必要です。実際のプロジェクト固有の内容を取得するには、この手順を省略できません。実際に存在するものは、bash .agent-skills/mex/scripts/mex.sh doctor（Step 6）で確認してください。

Step 3: ROUTER.md に入力する

.mex/ROUTER.md を編集し、一般的なエージェントタスクと関連する Wiki ページを対応付けます。

# ROUTER.md

## Task: add a new API endpoint

Load:
- context/architecture.md
- context/conventions.md
- patterns/http-handlers.md

Don't load:
- context/decisions.md (unless the endpoint changes a prior decision)

Step 4: グラフと Wiki を最新の状態に保つ

mex-agent graph          # rebuild the deterministic code graph after code changes
mex-agent check          # validate paths, links, staleness, and grounded symbols
mex-agent sync           # repair drift with targeted agent prompts
mex-agent graph scope "<task description>"   # compact, task-relevant context

mex-agent check は AI トークンを一切消費しません。機械的な検証を行うコマンドです。差分が見つかると、mex-agent sync はプロジェクト全体を再発見させるのではなく、対象を絞った差分をエージェントに渡します。

Step 5: MCP サーバー — 公開されていないため、提供を約束しないでください

上流のモノレポにある packages/mex-mcp は Wiki とイベントログを MCP ツールとして公開していますが、現時点ではnpm に公開されておらず、リリース版の mex-agent パッケージにも mex mcp CLI サブコマンドは含まれていません。現在これを実行する方法は、mex のチェックアウト内でソースからビルドすることだけです。

git clone https://github.com/mex-memory/mex
cd mex && npm run build --workspace mex-mcp

Claude Code、Cursor、jeo、gjc、jeopi、OpenCode のユーザーに、mex が「MCP サーバーとしてインストールされる」と伝えないでください。まだサポートされている登録コマンドはありません。mcp add の呼び出しを作り上げるのではなく、README の MCP サーバーのセクション（https://github.com/mex-memory/mex#mcp-server）で公開状況を確認してください。

Step 6: 読み取り専用の環境チェック

bash .agent-skills/mex/scripts/mex.sh doctor [project_path]
bash .agent-skills/mex/scripts/mex.sh check <project_path> [extra mex check args...]
bash .agent-skills/mex/scripts/mex.sh graph <project_path> [extra mex graph args...]

doctor が検査するのは環境のみです（Node.js のバージョン、mex-agent の解決状況、Git リポジトリ、.mex/ のスキャフォールド、プロジェクトアンカー）。パッケージをインストールしたり、プロジェクトのメモリを変更したりすることはありません。check／graph は実際の mex-agent CLI に処理をそのまま渡す薄いラッパーです。mex-agent 0.7.1 で動作を検証したところ、mex-agent check は .mex/graph.db を更新する場合があります。共有ワークツリーや変更のあるワークツリーをバイト単位で変更せずに保つ必要がある場合は、スクラッチコピー上で実行してください。

ベストプラクティス

1. 手動の手順ではなく、install.sh を使用する — 冪等性があり（.mex/ がすでに存在する場合は mex-agent setup をスキップします）、mex が選択したアンカーファイルを報告するため、手作業でのコピー＆ペーストによるミスを防げます。
2. アンカーは ROUTER.md です — インテリジェントなルーターにより、エージェントが wiki 全体を読み込まずに済みます。タスクとコンテキストの対応付けは、短く具体的にしてください。
3. 主張の根拠をコードに結び付ける — アーキテクチャ上の決定にはフロントマターの grounds_to を使用し、正確なシンボルフィンガープリントにひも付けておきます。
4. セッション前に確認し、その後同期する — mex-agent check で古くなった情報を検出し、mex-agent sync で修正に使える簡潔なコンテキストをエージェントに提供します。0.7.1 では check 中に graph.db が更新される場合があるため、読み取り専用の監査にはスクラッチコピーを使用してください。
5. wiki をバージョン管理する — .mex/ は Markdown/JSONL 形式です。メモリの変化を追跡できるよう、Git にコミットしてください。
6. 複数の言語に対応 — mex は TypeScript、JavaScript、Python、Rust を処理します。プロジェクトに複数の言語が混在している場合、コードグラフにもそれらが反映されます。
7. MCP が接続済みだと決して主張しない — MCP パッケージは上流で未公開です。Step 5 ではソースからのビルド手順のみを記載し、それ以外をユーザーに伝える前に README を再確認してください。
8. テレメトリーはオプトインではなくオプトアウトです — mex はデフォルトで匿名のコマンド名、バージョン、OS を送信します。ユーザーが気にする場合は、DO_NOT_TRACK=1、MEX_TELEMETRY=0、または mex-agent config set telemetry off を案内してください。

参考資料

• references/commands.md — ワークフローの段階別にまとめたコマンドリファレンス
• scripts/install.sh — ワンショット自動インストーラー （スキルの登録 + mex-agent のインストール + setup/graph/check）
• scripts/mex.sh — 読み取り専用の診断機能 + 簡易的な check/graph ラッパー
• Mex GitHub Repository
• Mex Docs
• Mex MCP server status — MCP 連携を約束する前に公開状況を確認してください
• プロジェクト標準： .agent-skills/skill-standardization/SKILL.md

例

例 1：自動インストールしてエージェントのコンテキストを振り分ける

bash .agent-skills/mex/scripts/install.sh ~/code/my-project
# Edit .mex/ROUTER.md to map your task types

インストール時に作成されたルートアンカーファイル（例：AGENTS.md）が表示されるため、jeo/gjc/jeopi/Codex 形式のエージェントは、そのプロジェクトで次のセッションを開始するとすぐにそれを読み込み、それ以上の設定は不要です。

例 2：エージェントのセッション後にドリフトを検出する

cd ~/code/my-project
mex-agent check
# Reports stale paths, broken links, symbol changes
mex-agent sync
# Generates a compact diff for the agent to review

例 3：プロジェクトに mex を推奨する前に環境を確認する

bash .agent-skills/mex/scripts/mex.sh doctor /path/to/project
# Reports: Node.js version, resolved mex-agent status, Git repo status,
# .mex/ scaffold presence, and which project anchor file exists

例 4：エージェントメモリーモードに移行した後でセットアップを再実行する

bash .agent-skills/mex/scripts/install.sh ~/code/my-homelab --mode agent-memory --force
# Adds HEARTBEAT.md conventions for long-running operational agents