mex

Summary

mex is an open-source ai-coding-agent that maps a codebase, structuring what coding agents learn into Markdown and maintaining connections to the underlying code. It requires no upfront cost and is run as a command-line tool via `npx mex-agent setup`. It is intended for application developers who need agents to start coding sessions with relevant architectural context rather than performing full-repository scans. Its documentation positions it alongside tools concerned with knowledge centralization around codebases, and it has active development shown by its presence on npm and GitHub.

Persistent project memory for AI coding agents. Structured scaffold + drift detection CLI.

Command line

Values are placeholders taken from each option’s declared default. Nothing is executed here — the output shown is a recording of a run that already happened.

Release history

1. v0.7.3 Aug 26, 2026 · issue 009

   mex v0.7.3 adds mex graph repair for in-place graph recovery and makes mex check fully read-only with staleness reporting.

   └──▷ GET THIS VERSION
   copy

   $ git clone --branch v0.7.3 https://github.com/mex-memory/mex.git
   # already have the repo? check out this version:
   $ git checkout v0.7.3

   └──▷ TRY IT
   Recover a graph left in an inconsistent state by an interrupted build without discarding and rebuilding from scratch.
   copy

   $ mex graph repair

   • ›Adds mex graph repair subcommand to checkpoint a stranded write-ahead log and verify store integrity in place, recovering a graph left behind by an interrupted build without requiring a full rebuild.
   • ›Changes mex check to open the last published graph read-only and report how many source files the graph is behind, instead of silently re-staging the corpus on every run.
   • ›Adds semanticDiagnostics option to CompilerExtractionOptions to make the per-file semantic type-check pass opt-in, reducing wall-clock and memory cost that previously scaled with the installed dependency surface.
   • ›Graph stores advance to schema v3: binary MinHash sketches, integer band hashes, integer fingerprint references, and the composite primary key as the only index — yielding roughly 36–40% smaller stores with lossless migration from v2.
   • ›TypeScript projects are now extracted one compiler program at a time, releasing each Program and TypeChecker before the next is created, cutting peak RSS from 5.17 GB to 2.11 GB on a 3,254-file repository.
   +1 moreshow less

   • ›Discovered TypeScript projects are now configured with skipLibCheck and noEmit, scoping compilation to symbol and type queries rather than a full emit.
   └──▷ BREAKING ON UPGRADE

   • !The compiler extractor version advances to typescript-5.9-v2, so the first mex graph run after upgrading performs a full rebuild regardless of prior graph state.
   • !Schema-v2 .mex/graph.db files migrate to v3 losslessly the next time a writing command runs (mex graph, mex sync, or mex graph ground); read-only commands report rebuild guidance until migration has run. Schema-v1 stores still require a one-time mex graph rebuild.
2. v0.7.2 Aug 20, 2026 · issue 004

   mex v0.7.2 adds source-backed graph retrieval, compiler-resolved TypeScript extraction, and two new drift checkers

   └──▷ GET THIS VERSION
   copy

   $ git clone --branch v0.7.2 https://github.com/mex-memory/mex.git
   # already have the repo? check out this version:
   $ git checkout v0.7.2

   └──▷ TRY IT
   Get source-backed, token-budgeted scope for a task query so an agent can answer from a single graph call instead of expanding node IDs or reopening files.
   copy

   $ mex graph scope "how does the authentication middleware handle token expiry"

   • ›mex graph scope now defaults to bounded source-backed retrieval, returning meta, source, flow, and summary JSONL records prioritized by relevance and execution-path confidence instead of a minimal manifest.
   • ›Adds compiler-backed TypeScript extraction via the TypeScript compiler API, resolving calls, imports, inheritance, containment, callback flow, and declaration-aware source regions (TypeScript 5.9.3 is now an exact runtime dependency).
   • ›Adds evidence-aware JSONL protocol v3 records for source ranges, directed execution flows, summaries, omissions, and trustworthy fallback guidance.
   • ›Scope budgets now adapt to repository size and enforce per-response file, node, flow, and source ceilings, distinguishing mandatory evidence from optional truncation.
   • ›Adds checkFrontmatterCompleteness drift checker to mex check, flagging context/*.md and patterns/*.md files missing recommended frontmatter fields (name, description, last_updated).
   +3 moreshow less

   • ›Adds checkStalePatterns drift checker to mex check, flagging pattern files with no inbound reference from ROUTER.md or any context/*.md file.
   • ›Adds source-chunk search, parser-health metadata, and graph-integrity reporting.
   • ›checkToolConfigSync now skips user-authored files lacking the scaffold marker and identifies the actual managed config that drifted rather than always blaming the first file in the list.
   └──▷ BREAKING ON UPGRADE

   • !TypeScript 5.9.3 is now an exact runtime dependency; projects using a different TypeScript version will need to pin or align to 5.9.3 for graph construction to work.
3. v0.7.0 Jul 25, 2026 · issue 004

   mex v0.7.0 adds a local SQLite code knowledge graph with TS/JS/Python/Rust extraction and new mex graph + mex impact commands.

   └──▷ GET THIS VERSION
   copy

   $ git clone --branch v0.7.0 https://github.com/mex-memory/mex.git
   # already have the repo? check out this version:
   $ git checkout v0.7.0

   └──▷ TRY IT
   Build the code graph for your project, then inspect the blast radius of a specific symbol before refactoring it.
   copy

   $ mex graph && mex impact <node-id>

   Retrieve a compact, scored task neighborhood around a symbol to feed focused context to an agent.
   copy

   $ mex graph scope <node-id>

   Retro-ground an existing pre-0.7 scaffold to attach grounds_to code-node entries without rewriting prose.
   copy

   $ mex graph ground

   • ›Adds mex graph, mex graph scope, mex graph query, mex graph get, and mex impact commands for graph building, compact task-neighborhood retrieval, structural lookup, targeted source expansion, and blast-radius analysis.
   • ›Adds mex graph ground to idempotently retro-ground populated pre-0.7 scaffolds while preserving their prose.
   • ›Introduces inline mex://<node-id> anchors for navigable symbol mentions, with warning-only drift detection and durable sync repair.
   • ›Adds a twelfth drift checker for grounds_to code-node grounding, covering drift, gone, ambiguous, and durable moved-node repair behavior.
   • ›Builds a deterministic local SQLite code graph (stored in .mex/graph.db) for TypeScript, TSX, JavaScript, JSX, Python, and Rust, with cross-file resolution, body hashes, MinHash fingerprints, and LSH reconciliation.
   +3 moreshow less

   • ›Adds an Express reference resolver that links route registrations to handler nodes in the code graph.
   • ›Delivers a deterministic JSONL agent protocol with explicit detail levels, scored selection reasons, stable ordering, node quotas, and a hard estimated-output-token ceiling.
   • ›Ships reproducible retrieval and agent evaluation harnesses under evaluate/.
   └──▷ BREAKING ON UPGRADE

   • !Minimum Node.js version is now 22.5 (raised from the previous minimum) because the graph engine requires it.