mex

Mex — 面向 AI 编码 Agent 的持久项目记忆

Mex 会映射你的代码，将 Agent 学到的内容转化为结构化 Markdown，并使这些知识始终关联到其描述的实现。每次编码会话开始时，都会提供相关架构背景，而不必再次扫描整个代码仓库。

何时使用此技能

• 为 AI 辅助的代码库搭建新的项目脚手架（mex-agent setup）
• 构建以符号为依据、关联到精确源码位置的动态知识库
• 获取自动生成的项目锚点文件（AGENTS.md、CLAUDE.md、.cursorrules 等），让 Agent 将 mex 上下文作为常驻规则，无需手动配置
• 使架构笔记、决策和约定与代码保持同步
• 运行漂移检测（mex-agent check），发现过时文档
• 在有意义的变更后，将知识库同步回代码（mex-agent sync）
• 获取精简且针对任务的上下文，而非对整个代码仓库执行 grep（mex-agent graph scope "<task>"）
• 将现有的 0.7 之前项目迁移到图谱依据模式（mex-agent graph ground）

何时不使用此技能

• 项目没有值得保留为动态文档的重要历史或架构
• 文档完全由源码注释生成（仅文档字符串，不需要结构化记忆）
• 用户目前只想要 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 的版本符合 mex-agent 语义版本格式时才将其纳入查找；若找不到，则安装 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 多语言 TeX 格式，与此工具无关。运行 mex --version 即可区分：mex-agent 会输出一个纯语义版本号（例如 0.7.1）；TeX Live 则会输出 pdfTeX ...。install.sh 和 scripts/mex.sh 都会优先查找明确无歧义的 mex-agent 包装程序，同时报告任何与之冲突的裸 mex 命令，因此检测不会阻止执行。

步骤 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”横幅标出边界），你必须将其粘贴到编码 Agent 的聊天中；真正将项目专属内容写入搭建结构的，是该 Agent 会话。scripts/install.sh 会检测该横幅并打印警告，以免悄无声息地跳过这一步。

自动化这段提示词会带来一个后果：mex 后续的“是否已完成填充？” grounding 步骤仅支持 TTY（已在 mex-agent 0.7.1 中验证，confirmAndCaptureGrounding 会在 stdin 不是 TTY 时退出），因此以非交互方式运行 mex-agent setup 会跳过 grounding 捕获。Agent 填充完搭建结构后，运行一次 mex-agent graph ground；install.sh 会打印此提醒。

它还会在交互式选择后，于仓库根目录写入项目锚点文件（mex 会询问“你使用哪种 AI 工具？”）——回答这一个问题后，该技能会自动启用这一“规则文档”（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

mex 自己的检测表中没有为 jeo、gjc 和 jeopi 单独列出条目，但这三者都像 Codex 一样读取项目根目录下的 AGENTS.md——本仓库自身由 AGENTS.md 驱动的技能指令也是通过这种方式加载的。因此，install.sh 默认使用 --tool codex，会自动为 jeo/gjc/jeopi 提供规则文档。这只涵盖锚点文件；它所指向的 wiki 内容（.mex/context/*.md、.mex/patterns/*）仍需完成上文步骤 2 中的粘贴到 Agent 的操作——若要获得真实的项目专属内容，就无法跳过这一步。运行 bash .agent-skills/mex/scripts/mex.sh doctor（步骤 6）以验证实际存在的内容。

步骤 3：填充 ROUTER.md

编辑 .mex/ROUTER.md，将常见的 Agent 任务映射到相关 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)

步骤 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 token——它只是一个机械验证器。发现偏差时，mex-agent sync 会向 Agent 提供有针对性的差异，而不是让它重新探索整个项目。

步骤 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

不要告诉用户 mex 已“安装为 MCP 服务”，可用于 Claude Code、Cursor、jeo、gjc、jeopi 或 OpenCode——目前还没有受支持的注册命令。请查看 README 的 MCP 服务部分 （https://github.com/mex-memory/mex#mcp-server），以跟踪发布状态，而不要捏造 mcp add 调用。

步骤 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 是锚点 — 智能路由器可防止 Agent 加载整个 wiki。任务到上下文的映射应简短且具体。
3. 让声明有代码依据 — 对于架构决策，请使用 frontmatter grounds_to，确保它们始终关联到精确的符号指纹。
4. 会话前检查，同步后修复 — mex-agent check 可检测过时内容；mex-agent sync 可为 Agent 提供精简的修复上下文。由于 0.7.1 可能会在 check 期间刷新 graph.db，只读审计时请使用临时副本。
5. 对 wiki 进行版本控制 — .mex/ 是 Markdown/JSONL；将其提交到 Git，以便追踪记忆的演变。
6. 支持多种语言 — mex 支持 TypeScript、JavaScript、Python 和 Rust。如果项目混用多种语言，其代码图也会如此。
7. 绝不要声称 MCP 已接通 — MCP 软件包尚未在上游发布；第 5 步中只能记录从源代码构建的途径，并在告知用户其他信息前重新检查 README。
8. 遥测默认启用，而非默认关闭 — mex 默认会发送匿名的命令名称、版本和操作系统信息。如果用户在意，请说明 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 仓库
• Mex 文档
• Mex MCP 服务状态 — 在承诺 MCP 集成前确认发布状态
• 项目标准： .agent-skills/skill-standardization/SKILL.md

示例

示例 1：自动安装并路由 Agent 上下文

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 风格的 Agent 就能在该项目的下一个会话中读取它， 无需进一步设置。

示例 2：在 Agent 会话后检测偏移

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：切换到 Agent 记忆模式后重新运行设置

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