AI 에이전트(AI agents)는 세션 사이의 모든 것을 잊어버립니다. mex는 에이전트에게 영구적이고 탐색 가능한 프로젝트 메모리(project memory)를 제공하여, 모든 세션이 차가운 프롬프트 덤프(cold prompt dump) 대신 올바른 컨텍스트(context)와 함께 시작되도록 합니다.

npx mex-agent setup

대부분의 에이전트 메모리 설정은 하나의 거대한 지침 파일(instruction file)이 됩니다. 이는 잠시 동안은 작동하지만, 곧 컨텍스트 윈도우(context window)를 가득 채우고, 토큰(tokens)을 낭비하며, 실제 코드베이스(codebase)에서 벗어나게 됩니다.

mex는 에이전트 메모리를 위한 구조화된 마크다운 스캐폴드(markdown scaffold)를 생성합니다:

AGENTS.md

/CLAUDE.md

— 도구 로드용 아주 작은 앵커(anchor)ROUTER.md

— 작업별 컨텍스트를 위한 라우팅 테이블(routing table)context/

— 아키텍처(architecture), 스택(stack), 설정(setup), 결정 사항(decisions), 관례(conventions)patterns/

— 주의 사항 및 검증 단계가 포함된 재사용 가능한 작업 가이드.mex/events/decisions.jsonl

— mex log를 통한 추가 전용(append-only) 노트

CLI는 해당 스캐폴드의 무결성을 유지합니다. AI 토큰을 소비하지 않고도 경로, 명령, 의존성, 패턴 인덱스, 노후화(staleness), 스크립트 커버리지를 확인합니다. 괴리(drift)가 나타나면, mex sync가 타겟팅된 프롬프트를 구축하여 에이전트가 오래된 부분만 수정하도록 합니다.

npm 패키지 이름은 mex가 이미 사용 중이었기 때문에 mex-agent로 명명되었습니다. CLI 명령어는 여전히 mex입니다.

npx mex-agent setup

설정(Setup) 과정은 .mex/ 스캐폴드를 생성하고, 어떤 AI 도구를 사용하는지 묻고, 코드베이스를 사전 스캔하며, 메모리 파일을 채우기 위한 타겟팅된 프롬프트를 생성합니다. 약 5분 정도 소요됩니다.

설정이 끝나면 mex를 전역(globally)으로 설치할 수 있습니다:

mex check # 괴리 점수(drift score)
mex sync # 괴리 수정(fix drift)

전역 설치를 건너뛰려면 npx를 사용하세요:

npx mex-agent check
npx mex-agent sync

나중에 언제든지 전역으로 설치할 수 있습니다:

npm install -g mex-agent

에이전트(agent)는 자동으로 로드되는 아주 작은 파일로 시작합니다. 해당 파일은 ROUTER.md를 가리키며, 라우터(router)는 현재 작업에 필요한 컨텍스트(context)만을 로드합니다. 유의미한 작업이 완료된 후, GROW 단계는 프로젝트 상태, 결정 사항, 작업 패턴을 업데이트하여 스캐폴드(scaffold)가 시간이 지남에 따라 더욱 유용해지도록 합니다.

편집 가능한 소스: docs/diagrams/context-routing.excalidraw

8개의 체커(checker)가 실제 코드베이스를 기준으로 스캐폴드를 검증합니다. 토큰 소모 0, AI 사용 0입니다.

점수는 100점에서 시작합니다. mex는 오류(error)당 10점, 경고(warning)당 3점, 정보(info)당 1점을 차감합니다.

편집 가능한 소스: docs/diagrams/drift-sync.excalidraw

모든 명령은 프로젝트 루트(root)에서 실행됩니다. 전역(globally)으로 설치하지 않았다면, mex를 npx mex-agent로 대체하여 사용하세요.

mex setup은

사용 중인 도구가 무엇인지 묻고 적절한 설정 파일(config file)을 생성합니다.

Neovim 사용자는 Claude Code, Avante.nvim, Copilot.vim 및 일반적인 플러그인 설정을 위해 docs/vim-neovim.md를 사용할 수 있습니다.

AI 기반 농업 음성 헬프라인인 Agrow에서 mex를 테스트한 실제 출력 결과입니다.

설정 전 스캐폴드(Scaffold before setup):

## 현재 프로젝트 상태 (Current Project State)
<!-- 작동 중인 기능. 아직 구축되지 않은 기능. 알려진 문제점.
중요한 작업이 완료될 때마다 이 섹션을 업데이트하세요. -->

설정 후 스캐폴드(Scaffold after setup):

## 현재 프로젝트 상태 (Current Project State)
**작동 중 (Working):**
- 음성 통화 파이프라인 (Twilio -> STT -> LLM -> TTS -> 응답)
...

설정 후 패턴(Patterns) 디렉토리:

patterns/
├── add-api-client.md
├── add-language-support.md
...

커뮤니티 구성원이 OpenClaw에서 Ubuntu 24.04, Kubernetes, Docker, Ansible, Terraform, 네트워킹 및 모니터링을 포함하는 10가지 구조화된 홈랩 (homelab) 시나리오를 통해 독립적으로 테스트했습니다. 10/10 테스트 통과. 드리프트 점수 (Drift score): 100/100.

mex setup --mode agent-memory

명령어는 "프로젝트"가 코드 저장소(repo)가 아닌 운영 환경인 지속성 에이전트 (persistent agents)를 위한 스캐폴드를 생성합니다. 이는 HEARTBEAT.md를 추가합니다.

mex를 구조화되고 작업 라우팅된 메모리로 정의하는 계약(contract) 및 템플릿을 제공합니다:

ROUTER.md는 현재 운영 상태를 추적하고 에이전트를 적절한 메모리 파일로 라우팅합니다.
context/는 아키텍처, 스택, 컨벤션 (conventions), 설정 및 결정 사항을 저장합니다.
patterns/는 반복되는 런북 (runbooks)을 저장합니다.
.mex/events/decisions.jsonl은 mex log를 통해 추가 전용 (append-only) 노트와 근거를 저장합니다.

mex heartbeat는 의도적으로 mex check보다 가볍게 설계되었습니다. 이는 last_updated 프론트매터 (frontmatter)와 메모리 정리 메타데이터를 읽고, 상태가 깨끗하면 HEARTBEAT_OK를 출력하며, 에이전트가 오래된 컨텍스트나 메모리 파일을 검토해야 할 때만 보고합니다. 지속성 에이전트 워크스페이스에서 하트비트를 반복적으로 실행하려면 mex watch --interval을 사용하세요.

선택적 설정은 .mex/config.json에 위치합니다. 누락된 값은 기본값으로 대체됩니다.

{
"staleness": {
"warnDays": 30,
...

기여를 환영합니다. 설정 및 가이드라인은 CONTRIBUTING.md를 참조하세요.

릴리스 기록은 CHANGELOG.md를 참조하세요.