mex

mex creates a living documentation layer (a "Dynamic Wiki") that evolves alongside your code. Unlike static documentation, the mex Wiki is designed for AI coding agents to consume efficiently.

Core Workflow:

1. Mapping: mex uses Tree-sitter and SQLite to build a deterministic local code graph of symbols and relationships (supporting TypeScript, JavaScript, Python, and Rust).
2. Building: Agents use the graph to populate structured Markdown files in .mex/ (e.g., architecture.md, decisions.md, conventions.md).
3. Routing: Instead of loading the whole Wiki, agents use ROUTER.md to select only the context relevant to the current task.
4. Maintenance: mex check detects "drift" (when code changes make the Wiki outdated), and mex sync provides targeted context for an agent to fix it.

In v0.7.0, mex includes a specific resolver for the Express framework.

How it works

• Activation: The resolver activates automatically if express is found in your dependencies or devDependencies.
• Detection: It recognizes literal routes registered through app or router (e.g., app.get('/path', handler)).
• Output: It emits a route node and attempts to link the identifier handler to that route.

Limitations

This is a narrow, fixture-backed implementation. It does not support:

• Computed route strings.
• Inline callbacks as handlers.
• Handler arrays.
• Middleware chains.
• Registrations hidden behind arbitrary helper functions.
• Other frameworks like NestJS or Next.js.

import express from "express";

const app = express();
export function healthHandler(): void {}
app.get("/health", healthHandler);

To ensure documentation stays accurate, you can ground wiki assertions to exact nodes in the code graph. This allows mex to detect when a change in the code affects specific documentation.

Using YAML frontmatter

You can use the grounds_to key in the Markdown frontmatter to link a page to a specific node and fingerprint:

---
grounds_to:
  - node: "function:a3f8...c21"
    fingerprint: "mh:64:9f2a..."
---

Using navigable Markdown links

You can also create navigable references within the text using the mex:// protocol:

The authentication is applied by [`requireSession()`](mex://function:a3f8...c21).

The constants DEFAULT_SCAFFOLD_PATTERNS and DEFAULT_HEARTBEAT_PATTERNS are considered "soft" parts of the public API. While they are exported to allow you to extend them easily, their contents (the specific list of patterns) may change in any minor version.

Best Practice: If your application requires exact, predictable behavior, do not rely on these constants. Instead, pass your own explicit patterns to the relevant functions.

• For drift checking, pass scaffoldPatterns explicitly to runDriftCheck.
• For heartbeats, pass patterns explicitly to checkHeartbeat or runHeartbeat.

// Instead of relying on defaults, pass explicit patterns for stability
await runDriftCheck({
  scaffoldPatterns: ["src/**/*.ts", "docs/**/*.md"]
});

Patterns should be created for repeatable, project-specific workflows. Do not create patterns for generic tasks (e.g., "how to write a for loop").

Create a pattern when:

• A task type is common and has a repeatable workflow.
• There are non-obvious integration gotchas between components.
• A specific failure occurred that you want to prevent from recurring.
• A task requires a specific verification checklist to catch mistakes early.

Skip a pattern if:

• The guidance is already present in context/conventions.md with concrete examples.
• The task has no project-specific gotchas.

mex creates a repo-local, living wiki that evolves alongside your code. Instead of loading a massive instruction file, mex uses a multi-step routing process to provide agents with minimal, relevant context:

1. Map the codebase: mex graph builds a deterministic code graph using Tree-sitter and SQLite, indexing symbols and relationships.
2. Build the wiki: A structured Markdown wiki is created in the .mex/ directory (containing architecture.md, decisions.md, conventions.md, etc.).
3. Route context: Agents start with a small anchor file that points to ROUTER.md. The router selects only the relevant wiki pages and a compact code-graph neighborhood for the current task.
4. Keep it current: After work is completed, agents use mex sync to update the wiki and mex check to ensure the documentation hasn't drifted from the implementation.

The .mex/ directory contains both files managed by mex-agent and namespaces reserved for embedders.

Files Owned by mex (Do NOT edit or write to these)

These are managed, scanned, or written by mex-agent:

• Top-level scaffold files: ROUTER.md, AGENTS.md, SETUP.md, SYNC.md
• Scanned documents: context/*.md, patterns/*.md
• Logs and Config: events/decisions.jsonl, config.json
• Database: graph.db and its SQLite sidecar files

Reserved for Embedders (Safe to use)

Embedders can freely use these paths for custom data, as mex-agent will not write to them or scan them by default:

• .mex/traces/** (e.g., for long-form decision traces)
• .mex/failures/** (e.g., for postmortem records)

Note: If you need a new namespace under .mex/, it is recommended to open an issue first to avoid future conflicts with mex-agent features.

To ensure documentation remains accurate, you can anchor Wiki declarations to specific code symbols using frontmatter or inline links. This allows mex to detect when a function moves, changes, or disappears.

Using Frontmatter for declarations:

---
grounds_to:
  - node: "function:a3f8...c21"
    fingerprint: "mh:64:9f2a..."
---

Using Inline Links for navigation: Use the mex:// protocol to create navigable references within Markdown text:

Authentication is performed by [`requireSession()`](mex://function:a3f8...c21).