mex Project Memory
A code-grounded, drift-aware project memory system for AI coding agents.
The evidence presents the code graph and SQLite data as local, describes telemetry as limited to command name, version, and operating system, and documents inspection plus several opt-out mechanisms. Generated artifacts are reviewable, version-controlled Markdown. Deductions apply because telemetry implementation code is absent, setup, sync, and anchor installation write to the repository without evidence of per-change confirmation or a complete preview, and rollback guidance is incomplete. Dependencies use broad caret ranges; CI runs npm ci but shows no audit, lockfile evidence, dependency-update process, or supply-chain controls. Author, repository, and license attribution are clear, while enterprise publisher identity remains unknown.
The README, package manifest, CI workflow, and tests are broadly consistent about runtime requirements, commands, checkers, and graph capabilities. Tests demonstrate structured issue codes, severity levels, and some graceful behavior. The main deduction is that SECURITY.md supports only 0.2.x while the package is version 0.7.1, creating a material maintenance inconsistency. Graceful continuation when SQLite or grammars fail is documented but not supported by supplied implementation or tests, and failure-message evidence covers only part of the product.
The intended audiences and scenarios are thorough: multiple coding agents, persistent operational memory, several languages, Windows and WSL, and Neovim are addressed, with explicit anchor mappings. Deductions apply because language and relationship coverage is not universal, MCP is unpublished, and the boundaries of agent-memory mode are only summarized. Commands and routing triggers are clear, but the evidence does not fully explain how setup or sync constrains autonomous edits, resolves ambiguity, or selects context.
Information architecture, directory layout, workflow, command reference, installation paths, Windows notes, and examples are unusually complete. The distinction between the mex-agent package and mex executable is explicit and stable, and the MIT metadata matches the supplied license. Deductions apply because important limitations are delegated to documentation not included here, CHANGELOG and CONTRIBUTING are referenced without their contents, and no dedicated FAQ is shown. A maintainer name, email, and response targets are supplied, but the stale security-version table weakens the update path and maintenance-responsibility evidence.
Markdown wiki pages, JSONL command envelopes, symbol identifiers, drift findings, and targeted expansion commands are directly usable by both humans and agents, offering clear structural value beyond a single large instruction file. Deductions apply because the efficiency and recall claims rely mainly on a self-reported benchmark involving one repository and small task sets, while the referenced methodology and result files are absent. Installation overhead, indexing cost beyond one example, ongoing wiki maintenance, and end-to-end token economics are not comprehensively measured.
Many README claims correspond to package metadata, CI smoke tests, and detailed checker unit tests, which expose concrete expected codes and behaviors. Deductions apply because core implementation files, the lockfile, telemetry code, benchmark results, and evaluation methodology are not supplied, leaving security, performance, and some graph claims traceable only to documentation or test intent. Full credit for fact-inference separation is justified because the README expressly limits its benchmark to one repository and small task sets and distinguishes compact retrieval from universal end-to-end savings.
- This is a low-confidence static review; the CLI, tests, build, and benchmarks were not executed.
- SECURITY.md lists only 0.2.x as supported while package.json is 0.7.1; confirm the current security-support and patch channel before adoption.
- Before running setup or sync on a real repository, commit or back up existing files and inspect the proposed .mex artifacts and agent configuration anchors.
- The telemetry privacy statement is not verified by supplied implementation code; sensitive repositories should disable telemetry explicitly and independently inspect network behavior.
- No lockfile, dependency audit, or supply-chain hardening evidence is supplied; review transitive dependencies and installation behavior before deployment.
- Performance, recall, and community-test results are limited self-reported evidence and should not be generalized to other repositories or agent workflows.
What does this agent do, and when should you use it?
mex is a repo-local CLI that maintains a structured Markdown wiki for AI coding agents and connects project knowledge to concrete code symbols. It builds a deterministic code graph with Tree-sitter and SQLite across TypeScript, TSX, JavaScript, JSX, Python, and Rust, including Express route-to-handler relationships. At task time, an agent follows a small project anchor and ROUTER.md to load selected architecture notes, decisions, conventions, and a compact graph neighborhood instead of rescanning the entire repository. After meaningful work, mex can preserve decisions and patterns, while `mex check` and `mex sync` detect or repair drift in paths, links, dependencies, indexes, stale content, and grounded symbols. Its primary output lives under `.mex/` as human-editable, reviewable, version-controlled files; an unpublished local MCP package also exposes the wiki and event-log implementation.
The workflow begins with mex setup, which inspects the repository, runs mex graph, creates .mex/AGENTS.md, .mex/ROUTER.md, the context/ and patterns/ directories, and events/decisions.jsonl, then asks the coding agent to populate the wiki from graph evidence and installs the appropriate project anchor. mex graph scope "<task>" returns a scored neighborhood of relevant symbols, signatures, relationships, node IDs, and selection reasons under a hard estimated-token budget; mex graph get <node-id> expands selected symbols. mex graph query where-defined, who-calls, and what-calls, together with mex impact, provide structural queries and change-impact analysis. Wiki claims can bind to graph nodes through grounds_to frontmatter or navigable mex:// links. mex check calculates wiki health and drift, while mex sync supplies targeted context to repair changed, moved, missing, or inconsistent knowledge. Additional commands include mex log, mex timeline, and mex heartbeat for event recording, history, and persistent-agent health checks.
- A team maintaining a large TypeScript, JavaScript, Python, or Rust repository wants each new coding-agent session to inherit architecture and conventions without another full-source scan.
- A frequently refactored project needs to detect when documented functions, files, dependencies, or symbol references have changed, moved, or disappeared.
- A team using Claude Code, Codex, Cursor, Windsurf, GitHub Copilot, or OpenCode wants a repository-level context anchor tailored to each supported coding tool.
- A developer tracing behavior or planning a change wants queries for definitions, callers, callees, and the wiki material affected by a symbol or file.
- A homelab, infrastructure workspace, or long-running operational agent needs the optional agent-memory mode with a HEARTBEAT.md contract and cleanup conventions.
What are this agent's strengths and limitations?
- Project memory remains ordinary Markdown inside the repository, so humans and agents can read, edit, review, and version it without relying on a hosted knowledge store.
- The deterministic Tree-sitter and SQLite graph lets important claims point to exact symbols and detects when those symbols change, move, or disappear.
- Task routing and token-budgeted graph neighborhoods return compact signatures and relationships before an agent expands selected source symbols.
- Setup documents anchors for Claude Code, Codex, Cursor, Windsurf, GitHub Copilot, and OpenCode, while the project describes itself as provider-neutral.
- Filesystem and lexical checks remain available without a graph; failures to load SQLite or an individual grammar degrade with a warning instead of disabling the whole CLI.
- Node.js 22.5 or newer is required, and adopting the local npm CLI adds repository setup and ongoing maintenance steps.
- The MCP package is not published; users must build
packages/mex-mcplocally, and the CLI remains the primary release. - Symbol indexing is explicitly documented only for TypeScript, TSX, JavaScript, JSX, Python, and Rust, so equivalent graph support for other languages is unproven.
- Agents are expected to update project state, decisions, and reusable patterns after meaningful work, making wiki quality dependent on consistent workflow participation.
- The published benchmark covers the mex repository, six scripted retrieval tasks, and five real-agent tasks; it is directional evidence rather than proof of universal savings.
- Anonymous command, version, and OS telemetry is enabled on an opt-out basis, so privacy-sensitive teams must disable it explicitly.
How do you install or deploy this agent?
Install Node.js 22.5 or newer, then run npx mex-agent setup from the project root. No prior global installation is required; the npm package is named mex-agent, while the CLI command remains mex. For a global command, run npm install -g mex-agent. On Windows, the recommended setup works in Command Prompt, PowerShell, or WSL. If using the legacy setup.sh flow, installation, build, and CLI commands must run in the same environment. No API credentials are documented as installation requirements.
How do you use this agent?
Start with npx mex-agent setup. After setup, run mex check to validate wiki health and code grounding, mex sync to repair drift, or mex graph scope "trace the authentication flow" to retrieve compact context for a task; expand required symbols with mex graph get <node-id>. Replace mex with npx mex-agent when it is not installed globally. For a pre-0.7 mex project, run mex graph followed by mex graph ground to add grounds_to metadata and mex:// references without rewriting existing prose. Use mex setup --mode agent-memory for the persistent operational-agent layout.
How does this agent compare with similar options?
Compared with conventional project documentation or a single oversized instruction file, mex divides knowledge into task-routed Markdown pages and grounds selected claims in code-graph symbols. This enables drift detection and targeted context loading, but introduces the cost of building the graph, maintaining the .mex/ wiki, and running check or sync workflows after changes.
FAQ
Does mex require a paid model or a specific API key?
Does telemetry upload source code or repository paths?
mex telemetry inspect and opt out with DO_NOT_TRACK=1, MEX_TELEMETRY=0, or mex config set telemetry off.What happens if the graph or a language grammar cannot load?
Can an existing mex wiki gain symbol grounding without being rewritten?
mex graph and then mex graph ground. The migration preserves existing prose while adding focused grounds_to entries and navigable mex:// references, and it is documented as safe to rerun.Is MCP required to use mex?
mex-agent CLI. packages/mex-mcp exposes wiki and event-log functions as MCP tools, but it is not published and must be built locally with npm run build --workspace mex-mcp.