mex

Open source alternative to BuildBetter, Mem0, Zep and Augment Code

1.8K stars
MIT
Active this week
Last commit 3 days ago

Last verified Oct 20, 2026

Manage persistent AI coding agent memory with a structured wiki, code graph, and drift detection. MIT licensed, works with Claude Code, Cursor, and Codex.

Visit website GitHub1.8K

Read the full breakdownWho it is for, how it works, trade-offs, the quick start and the FAQ

who it's for

Who mex is for#

Solo engineers running intensive AI coding sessions

Developers who use Claude Code, Cursor, or Codex for multi-hour sessions gain the most from mex. Instead of explaining the project architecture from scratch at the start of each session, the agent loads the wiki and picks up where the last session ended. The code graph also enables compact, task-relevant context retrieval that does not flood the context window.

Skip if:

Skip mex if you use AI tools only occasionally or for isolated, self-contained tasks. For one-off scripts or greenfield projects with no established conventions, the setup overhead exceeds the benefit.

Team leads managing AI coding conventions across developers

Team leads who want consistent AI-generated code can promote shared conventions, decisions, and patterns into a repository-level wiki that every developer's agent reads. New hires inherit the team's context on their first day without a separate onboarding step.

Skip if:

Skip if your team has fewer than three developers all working in the same repository with the same agent. At very small scale, a single shared CLAUDE.md file may be sufficient without the overhead of drift detection and graph grounding.

Homelab and infrastructure operators running persistent agents

mex includes an agent-memory mode (`mex setup --mode agent-memory`) that adds a HEARTBEAT.md contract and cleanup conventions for operational environments. In an independent community test on OpenClaw, agent-memory mode passed 10 of 10 structured homelab scenarios and reduced loaded context by about 60% on average.

Skip if:

Skip agent-memory mode if your use case is a standard software development repository. The default setup mode is the right starting point for codebases.

the problem

The problem it solves#

AI coding agents start every session from scratch. The architecture knowledge, past decisions, active conventions, and edge cases that took weeks to accumulate disappear when the session ends. Teams typically respond by maintaining large rules files, but those files have no mechanism to detect drift: when a module gets renamed, the rules file still references the old name; when a decision gets reversed, the agent keeps enforcing the old rule. Over time the documentation diverges from the implementation, and agents enforce conventions that no longer match the code.

At the team level, the problem multiplies. Each developer maintains their own rules file, so each agent learns the codebase a different way. Two engineers working in the same repository end up with agents that know different things, enforce different standards, and produce inconsistent output. There is no shared source of truth, no visibility into what each agent actually knows, and no way for a lead to govern the conventions the whole team should follow.

how mex solves it

How it solves it#

Deterministic code graph with Tree-sitter and SQLite

mex indexes TypeScript, TSX, JavaScript, JSX, Python, and Rust symbols and relationships using a local SQLite database built by Tree-sitter. The graph is built in about 7 seconds for a mid-size repository and stored on disk, making it reproducible and fast to query without network calls or AI tokens.

Task-aware context routing

Instead of loading the entire wiki into every agent context window, mex uses a ROUTER.md that selects only the architecture notes, decisions, conventions, and task patterns relevant to the current job. On the mex repository benchmark, graph scope retrieval is 916x more compact than the full corpus and achieves 100% expected-symbol recall on five real-agent tasks.

Drift detection without AI tokens

`mex check` validates paths, commands, dependencies, links, code-grounded symbol references, and staleness across the entire wiki without calling any AI model. When repairs are needed, `mex sync` gives the agent targeted context instead of asking it to rediscover the whole project.

Code-grounded wiki entries

Wiki pages can reference exact code graph nodes via frontmatter and inline `mex://` links. When a referenced function moves, is renamed, or disappears, mex identifies the affected knowledge, re-binds confident renames automatically, and surfaces ambiguous changes for the agent to resolve.

Multi-tool support for major AI coding agents

mex installs the appropriate project anchor for Claude Code (CLAUDE.md), Codex (AGENTS.md), Cursor (.cursorrules), Windsurf (.windsurfrules), GitHub Copilot (.github/copilot-instructions.md), and OpenCode. Neovim users have a dedicated integration guide. An MCP package is available for local development builds.

strengths · trade-offs

Strengths and trade-offs#

Strengths

MIT licensed with no cloud dependencyThe core CLI is MIT licensed and runs entirely on your local infrastructure. No external service, no API key, and no data sent to a third-party provider are required. The wiki lives as plain Markdown files in the repository, version-controlled alongside the code.
Works across every major AI coding tool from one wikimex is vendor-neutral: one wiki serves Claude Code, Cursor, Codex, Windsurf, Copilot, and OpenCode simultaneously. Switching agents does not invalidate the shared memory or require rebuilding context from scratch.
Knowledge stays grounded in the implementationUnlike documentation files that drift silently, mex wiki entries can be linked to exact code graph nodes. When implementation changes break a link, the drift check surfaces it before the agent acts on stale information. Confident renames are rebound automatically during sync.

Trade-offs

-Node.js 22.5 or newer requiredmex requires Node.js 22.5 or newer. Projects on older Node versions or locked-down CI environments that cannot update will need to address that before setup. The npm package name is `mex-agent` (not `mex`) because the shorter name was already taken on npm; the CLI command remains `mex`.
-MCP server not yet published to npmThe `mex-mcp` package, which exposes wiki and event-log functionality as Model Context Protocol tools, is available in the repository but not yet published to npm. Using it requires a local build step (`npm run build --workspace mex-mcp`). The primary release remains the `mex-agent` CLI.
-Team memory dashboard in Early Access onlyThe team-facing features (shared server-hosted memory, admin dashboard, aggregate drift scores, promotion workflows) are in Early Access and not yet publicly available as open source. Individual developers and small teams get full value from the CLI, but centralized governance requires joining the Early Access waitlist at mexmemory.com.

versus alternatives

mex vs alternatives#

mex vs Manually Maintained Rules Files

Most teams currently manage AI coding agent context through manually maintained files: CLAUDE.md for Claude Code, .cursorrules for Cursor, AGENTS.md for Codex. These work initially but do not scale. There is no mechanism to detect when the rules drift from the implementation, no way to route only the relevant context to a task, and no shared foundation when multiple developers each maintain their own version.

mex replaces the manual approach with a wiki that grows from real coding work, connects claims to exact code symbols, and detects when those claims stop being true. The drift detection step runs without any AI tokens, which keeps the maintenance cost low as the codebase grows.

mex vs Proprietary Agent Memory Features

Feature	mex	Commercial AI Tool Memory
License	MIT	Proprietary
Self-hosted	Yes (default)	No
Vendor-neutral	Yes	Per-tool only
Code-grounded	Yes	No
Drift detection	Yes	No
Version-controlled	Yes	Varies

Commercial AI coding platforms such as Cursor, GitHub Copilot, and Windsurf each have their own memory or instructions mechanism, but these are proprietary, siloed in one tool, and stored on the provider's infrastructure. A team that uses multiple agents or switches tools must maintain separate context files for each. mex externalizes the memory layer into the repository itself, so the same wiki serves every tool the team uses.

The scenario where proprietary tool memory wins: if your team is fully committed to one AI coding tool with no plans to change, and you want memory managed without any CLI setup overhead, the built-in context features of that tool are simpler. mex is the better choice when the team uses multiple agents, wants to version-control their conventions alongside the code, or needs drift detection that is not tied to a specific vendor.

install · quick start

Quick start#

bash

Install mex globally via npm, then run setup inside any repository to build the code graph and wiki. Node.js 22.5 or newer is required.
```bash
npm install -g mex-agent
mex setup
```

tech stack · detected from GitHub

What it's built on#

Languages: JavaScriptTypeScript
Frameworks: React

frequently asked

FAQ#

Is mex free to use?

Yes. The mex CLI (published on npm as mex-agent) is MIT licensed and free to run on your own machine or server. There are no credits, no rate limits, and no account required. The optional team dashboard with centralized drift management is in Early Access and may have different terms when it publicly launches.

Does mex send my code to an external service?

The core CLI does not send your code anywhere. The code graph is built locally using Tree-sitter and SQLite, and the wiki is stored as plain Markdown files in your repository. mex collects anonymous telemetry (command name, version, and OS only) that can be disabled with DO_NOT_TRACK=1, MEX_TELEMETRY=0, or mex config set telemetry off.

Which AI coding tools does mex work with?

mex currently supports Claude Code, Codex, Cursor, Windsurf, GitHub Copilot, and OpenCode. Setup installs the appropriate project anchor file for your tool: CLAUDE.md, AGENTS.md, .cursorrules, .windsurfrules, .github/copilot-instructions.md, or .opencode/opencode.json. Neovim users have a dedicated integration guide for Claude Code, Avante.nvim, Copilot.vim, and other plugins.

What programming languages does the mex code graph support?

As of v0.7.0, mex indexes TypeScript, TSX, JavaScript, JSX, Python, and Rust. It also has framework-aware support for Express route-to-handler relationships. If a language grammar cannot load, graph checks are skipped with a warning and the filesystem and lexical checkers continue to run on the rest of the wiki.

How is mex different from maintaining a CLAUDE.md or .cursorrules file?

A manually maintained rules file is static text with no link to your actual code. mex builds a structured wiki where entries can be grounded to exact code symbols. When those symbols change, mex detects the drift and surfaces what needs updating without spending AI tokens. It also routes context by task, so agents load the relevant architecture and conventions for the current job rather than the entire rules file.

also worth a look