mex 项目记忆
为编程智能体建立可追溯、可检测漂移的代码库知识库。
证据表明核心图谱和 SQLite 数据在本地处理，遥测仅声明收集命令名、版本和操作系统，并提供检查及多种退出方式；生成物是可审查、可版本控制的 Markdown。扣分在于未提供遥测实现代码以核实声明，setup、sync 和工具锚点安装会写入仓库但材料未显示逐项确认机制或完整变更预览，回滚说明也不完整。依赖使用宽松的插入符范围，CI 虽运行 npm ci，却未显示审计、锁文件、依赖更新或供应链检查。作者、仓库和许可证归属清楚，但发布者企业身份仍属未知。
README、package.json、CI 和测试对 Node 版本、命令、检查器及图谱能力大体一致；测试展示了结构化问题代码、严重级别和若干降级路径。扣分在于 SECURITY.md 只把 0.2.x 列为受支持版本，而包版本为 0.7.1，形成明显维护信息漂移。材料声明 SQLite 或语法加载失败时可警告并继续，但未提供相关实现或测试；错误消息覆盖也只由部分检查器测试体现。
受众和场景定义充分，涵盖多种编码代理、持久代理记忆、多语言图谱、Windows、WSL 和 Neovim，并明确列出工具锚点。扣分在于语言和关系支持并非通用，MCP 尚未发布，agent-memory 模式的行为边界只作概述；路由和命令触发方式清楚，但 setup 或 sync 如何约束代理自主修改、处理歧义和选择上下文的细节不足。
信息架构、目录树、工作流程、命令表、安装方式、Windows 注意事项和示例都很完整；npm 包名 mex-agent 与 CLI 名 mex 的区别得到明确解释，MIT 文本及元数据一致。扣分在于已知限制主要通过被引用但未提供的文档承载，CHANGELOG 和 CONTRIBUTING 仅被链接而没有内容证据，FAQ 不是独立组织。维护者姓名、邮箱和报告时限可见，但安全支持版本过时，削弱了版本更新路径和维护责任的清晰度。
Markdown wiki、JSONL 命令输出、符号 ID、漂移问题及精确扩展命令都适合直接供人和代理使用，且相较单一大文件提供明确的结构化增益。扣分在于效率与召回收益主要来自单仓库、小规模任务的自报 benchmark，其详细方法和结果文件未随材料提供；安装依赖、索引时间、维护 wiki 的持续成本以及端到端 token 收益没有得到全面量化。
README 中许多功能主张能与 package.json、CI 烟雾测试及检查器单元测试相互对应，测试用例也具体展示了预期代码和行为。扣分在于关键实现源码、锁文件、遥测代码、benchmark 结果和评估方法未提供，因此安全、性能及部分图谱主张只能追踪到说明或测试意图。值得肯定的是 README 明确把 benchmark 限定为单仓库和少量任务，并区分紧凑检索与普遍端到端节省，事实与推论分离较好。
- 这是低置信度静态审查；未执行 CLI、测试、构建或 benchmark。
- SECURITY.md 仅声明支持 0.2.x，但 package.json 为 0.7.1；采用前应确认当前安全支持范围和补丁渠道。
- 在真实仓库运行 setup 或 sync 前，应先备份或提交现有文件，并检查其将创建或修改的 .mex 文件及代理配置锚点。
- 遥测隐私声明未由所给实现代码验证；敏感代码库应明确禁用遥测并核查实际网络行为。
- 未提供锁文件、依赖审计或供应链加固证据；部署前应独立审查传递依赖和安装脚本。
- 性能、召回和社区测试结果属于有限范围的自报证据，不应直接推广到其他代码库或代理工作流。
这个 Agent 能做什么，适合哪些场景？
mex 是一个运行在项目本地的 CLI，为 AI 编程智能体维护结构化 Markdown wiki，并把知识关联到实际代码符号。它使用 Tree-sitter 和 SQLite 构建确定性代码图，支持 TypeScript、TSX、JavaScript、JSX、Python 和 Rust，还能识别 Express 路由与处理器的关系。任务开始时，智能体通过小型锚点文件、ROUTER.md 和图检索按需加载架构、决策、约定及相关符号，而不是扫描整个仓库。工作结束后，mex 可记录决策和模式，并通过 mex check 与 mex sync 检测或修复路径、链接、依赖、索引、陈旧内容及符号引用漂移。主要交付物位于仓库的 .mex/ 目录，可由人或智能体阅读、编辑、评审和纳入版本控制；另有尚未发布的本地 MCP 包复用 CLI 的 wiki 与事件日志实现。
端到端流程从 mex setup 开始：它检查仓库、运行 mex graph 建立本地代码图、创建 .mex/AGENTS.md、.mex/ROUTER.md、context/、patterns/ 和 events/decisions.jsonl，再让编程智能体依据图证据填充 wiki，并安装对应工具的项目锚点。mex graph scope "<task>" 在估算令牌预算内返回带评分的相关符号邻域、签名、关系、节点 ID 和选择理由；mex graph get <node-id> 可展开指定符号。mex graph query where-defined、who-calls、what-calls 与 mex impact 用于结构查询和影响分析。知识页可以通过 grounds_to 前置元数据或 mex:// 链接绑定代码节点；mex check 检查 wiki 健康度和漂移，mex sync 根据定向上下文处理失效、移动或变化的符号。mex log、mex timeline 和 mex heartbeat 分别记录事件、读取时间线及执行持久智能体健康检查。
- 维护大型 TypeScript、JavaScript、Python 或 Rust 仓库的团队，希望新一轮编程智能体会话直接获得已有架构与约定，而不是重新扫描全部源码。
- 频繁重构的项目，希望发现文档所引用的函数、文件或依赖已更改、移动或消失，并获得定向修复上下文。
- 使用 Claude Code、Codex、Cursor、Windsurf、GitHub Copilot 或 OpenCode 的团队，需要为不同工具安装对应的仓库级上下文锚点。
- 需要追踪调用关系或变更影响的开发者，可通过图查询和
mex impact定位定义、调用方、被调用项及关联 wiki 内容。 - 维护 homelab、基础设施工作区或长期运行智能体的操作者，可使用
mex setup --mode agent-memory增加 HEARTBEAT.md 契约和清理约定。
这个 Agent 有哪些优点和局限？
- 知识以普通 Markdown 保存在仓库中，可读、可编辑、可评审并可纳入版本控制，而不是锁在外部服务中。
- Tree-sitter 与 SQLite 构建确定性本地代码图，知识声明可绑定到具体符号，并能检测符号变化、移动或消失。
- 任务路由与硬性估算令牌预算下的图邻域检索，可先返回紧凑签名和关系，再按节点定向展开源码。
- 同时提供 Claude Code、Codex、Cursor、Windsurf、GitHub Copilot 和 OpenCode 的项目锚点，且明确声明供应商中立。
- 图功能不可用时仍可继续运行文件系统和词法检查；单个 SQLite 或语法组件加载失败会警告并降级。
- 要求 Node.js 22.5 或更高版本，且主要发布形态是本地 npm CLI，会增加项目工具链与维护步骤。
- MCP 包尚未发布；只能从源码构建
packages/mex-mcp，当前主要发行产品仍是 CLI。 - 图索引语言仅明确覆盖 TypeScript、TSX、JavaScript、JSX、Python 和 Rust，其他语言的符号级能力没有证据。
- 需要智能体在有意义的工作后持续更新状态、决策和模式；wiki 的质量仍取决于这一维护流程。
- 公开基准来自 mex 自身仓库、六项脚本检索任务和五项真实智能体任务，不能证明所有项目都能获得相同收益。
- 默认收集可匿名退出的命令名、版本和操作系统遥测；对遥测敏感的团队需要显式关闭。
如何安装或部署这个 Agent？
前提是 Node.js 22.5 或更高版本。在项目根目录运行 npx mex-agent setup，无需先全局安装；npm 包名是 mex-agent，但生成的 CLI 命令是 mex。若需全局命令，可运行 npm install -g mex-agent。Windows 推荐在命令提示符、PowerShell 或 WSL 中运行 npx mex-agent setup；若使用旧版 setup.sh，安装、构建和 CLI 命令必须处于同一环境。安装不需要 README 所列出的 API 凭据。
如何使用这个 Agent？
首次可直接运行 npx mex-agent setup。设置完成后，在项目根目录执行 mex check 检查 wiki 和代码绑定，执行 mex sync 修复漂移，或用 mex graph scope "trace the authentication flow" 获取某项任务的紧凑上下文，再通过 mex graph get <node-id> 展开必要符号。未全局安装时，将示例中的 mex 换成 npx mex-agent。旧项目可依次运行 mex graph 和 mex graph ground，在保留现有文字的同时增加 grounds_to 与 mex:// 引用。需要智能体记忆模式时运行 mex setup --mode agent-memory。
这个 Agent 与同类方案有什么区别？
与一次编写后逐渐陈旧的普通项目文档或单个巨型指令文件相比，mex 把知识拆成由 ROUTER.md 按任务选择的 Markdown 页面，并将关键声明绑定到代码图符号。其优势是可以检测重构造成的漂移并只加载相关上下文；代价是必须建立代码图、维护 .mex/ wiki，并在工作后运行检查或同步流程。
常见问题
是否需要付费模型或特定 API 密钥？
源码或路径会通过遥测上传吗？
mex telemetry inspect 检查载荷，并以 DO_NOT_TRACK=1、MEX_TELEMETRY=0 或 mex config set telemetry off 退出。代码图或某种语法加载失败后还能使用吗？
能否给已有 mex 项目增加符号绑定而不重写文档？
mex graph 和 mex graph ground；迁移流程会保留原有文字，并添加精简的 grounds_to 条目和可导航的 mex:// 引用，且可重复运行。MCP 是使用 mex 的必要条件吗？
mex-agent CLI。packages/mex-mcp 提供相同 wiki 与事件日志功能的 MCP 工具，但尚未发布，需要在本地用 npm run build --workspace mex-mcp 构建。