How mex Turns Git-Tracked Markdown Into Persistent Memory for AI Coding Agents

Hook

Your AI coding agent forgets everything between sessions. You've written the same architectural explanation to Claude seventeen times this month. What if your agent had actual long-term memory that stayed honest as your codebase evolved?

Context

AI coding agents like Claude Code, Cursor, and GitHub Copilot have a fundamental problem: they're stateless. Every conversation starts from zero. You end up copying the same architectural context into chat windows, maintaining sprawling instruction files that balloon to thousands of lines, or watching agents confidently suggest patterns you deprecated three sprints ago.

The naive solution is a single massive instruction file—CLAUDE.md or .cursorrules that documents everything. This works until it doesn't. Past 500 lines, these files become unmaintainable. Agents load the entire blob into every context window regardless of task, burning tokens. Worse, there's no mechanism to detect when the documentation drifts from reality. That migration to microservices you documented in January? The agent still thinks you're running a monolith because nobody updated line 247 of the instruction file. mex attacks this from two angles: a router-based context system that loads only task-relevant slices of your documentation, and an offline drift detection CLI that validates scaffold integrity without consuming a single API token.

Technical Insight

mex's architecture splits agent memory into two complementary systems. The scaffold is git-tracked markdown files with YAML frontmatter for machine-readable metadata. The CLI is a TypeScript validator that checks scaffold health using filesystem analysis and git log parsing—no AI calls required.

The router pattern is the key innovation. Instead of dumping your entire knowledge base into every prompt, you create a tiny anchor file (AGENTS.md or CLAUDE.md) that delegates to ROUTER.md:

---
last_updated: 2025-01-15
---
# Agent Router

Before starting any task, check this router to load relevant context.

## Task Type → Context Files

- **Database changes**: Load `context/database-architecture.md` + `patterns/migration-checklist.md`
- **API endpoints**: Load `context/api-conventions.md` + `context/auth-flow.md`
- **Frontend components**: Load `patterns/component-structure.md` + `context/design-tokens.md`
- **Infrastructure**: Load `context/deployment-pipeline.md` + `decisions/001-kubernetes-over-ecs.md`

## General Context (always available)
- `context/tech-stack.md` - Current dependencies and versions
- `decisions/` - Architectural decision records

Each referenced file uses YAML frontmatter to declare dependencies and update timestamps:

---
last_updated: 2025-01-10
dependencies:
  - context/database-architecture.md
  - decisions/003-postgres-partitioning.md
edges:
  - patterns/migration-checklist.md
---
# API Conventions

All REST endpoints follow these patterns:
- Auth via Bearer tokens (see context/auth-flow.md)
- Pagination using cursor-based approach
- Error responses use RFC 7807 Problem Details

The CLI validates this structure with eleven distinct checkers. Path validation confirms every file referenced in dependencies actually exists. Dependency cross-referencing detects orphaned files. The staleness checker parses git log to flag files untouched in 90+ days. Package.json coverage analysis compares scripts mentioned in documentation against actual package.json contents.

Running mex check produces a scored drift report:

$ mex check

✓ Path validation: 100/100
✗ Staleness: 67/100
  - context/api-conventions.md: 127 days old, 43 commits in related files
  - decisions/002-graphql-sunset.md: 91 days old
✗ Dependency coverage: 80/100
  - context/database-architecture.md mentions postgres v14, package.json shows v15
✓ Cross-references: 100/100

Overall score: 86.75/100

Critically, this runs in milliseconds and costs zero tokens. Compare this to vector database approaches that burn API credits on every similarity search, or RAG systems that re-embed documentation on each query.

When drift is detected, mex sync generates targeted repair prompts. Instead of 'regenerate everything,' it produces surgical instructions:

The following scaffold files have drifted from codebase reality:

1. context/api-conventions.md (127 days old)
   - 43 commits in src/api/ since last update
   - Review recent changes and update authentication section

2. Dependency mismatch in context/database-architecture.md
   - Document claims postgres v14
   - package.json shows postgres v15.2
   - Update version references and check for breaking changes

You feed this to your AI agent, it makes corrections, you re-run mex check until the score improves. The loop is manual but focused—you're fixing specific drift, not regenerating the entire memory structure.

The append-only event log adds an audit trail without database overhead:

$ mex log decision "Switching from REST to tRPC for internal APIs"
$ mex log note "Auth middleware refactored to support OAuth2 + API keys"

This writes JSONL to .mex/events.jsonl:

{"timestamp":"2025-01-15T10:23:45Z","type":"decision","content":"Switching from REST to tRPC for internal APIs","author":"git-user"}
{"timestamp":"2025-01-15T14:17:22Z","type":"note","content":"Auth middleware refactored to support OAuth2 + API keys"}

Grep-friendly, git-diffable, trivial to pipe into analysis scripts. No PostgreSQL, no MongoDB, just files.

The tool-agnostic design generates config for multiple AI platforms from the single scaffold. Run mex init and it creates .clinerules for Cursor, .github/copilot-instructions.md for GitHub Copilot, and CLAUDE.md for Claude Code—all pointing to the same router structure. Update the scaffold once, regenerate configs as needed.

Gotcha

mex validates structure, not semantics. The drift checkers confirm files exist, dependencies are declared, and timestamps are fresh—but they cannot detect conceptual incorrectness. Your architecture doc can claim 'we use event sourcing' while the codebase is a CRUD app with ActiveRecord, and mex will report a perfect 100/100 score as long as the files are recently updated and cross-references resolve.

Staleness detection uses calendar days as a proxy for relevance, which breaks for stable documentation or low-activity projects. A decision that remains valid for six months gets flagged as stale simply because the file hasn't been touched. The checker has no concept of 'this is still correct'—it only knows 'this is old.' Pattern reuse depends entirely on discipline. Nothing enforces that agents actually consult ROUTER.md or follow the context loading convention. A developer can bypass the entire scaffold by writing prompts from scratch, and mex has no runtime hooks to prevent it. The sync flow generates repair prompts, but verification is manual. You run the agent, re-check drift, repeat until scores improve. There's no automated semantic diff or test harness to confirm fixes actually addressed root causes versus just updating timestamps to game the staleness checker.

Verdict

Use if: You're managing a multi-month codebase with AI agents and keep re-explaining the same architectural context across sessions. You have established patterns worth preserving (coding conventions, deployment procedures, decision rationale) and want git-tracked memory that stays honest as code evolves. You value instant, offline validation over semantic understanding and are willing to manually drive the drift repair loop. Skip if: You're doing exploratory prototyping where project state changes hourly and documentation would be outdated before you finish writing it. Your team doesn't use AI agents as primary development tools—this solves a problem you don't have. You need semantic correctness validation rather than structural checks, or you want fully autonomous agents that self-heal drift without human intervention. Also skip if single-file instructions still work for your scale; mex's complexity only pays off when router-based context loading saves meaningful tokens.