A cognitive-architecture AI coding agent that lives in your terminal — multi-tier memory, a causal work graph and durable orchestration, as one npm i -g binary with no server to run.
npm install -g @vaibhav_dangaich/mnex
This page is a little macOS. Explore the mnex folder, or press ⌘K for a terminal you can actually type in.
Three commands to a working agent. The second stores your API key; the third installs the shell hook and file watcher.
$ npm install -g @vaibhav_dangaich/mnex $ mnex init # paste your OpenAI or Gemini key $ mnex service start # shell hook + filewatcher + daemon
Keys live in ~/.config/mnex/.env (written by mnex init) or ~/.mnex.env. Only one model provider is required.
# one of these two OPENAI_API_KEY=sk-... GEMINI_API_KEY=... # optional — cross-device semantic recall SUPERMEMORY_API_KEY=... # optional — local-first routing, zero cost for simple queries OLLAMA_URL=http://localhost:11434 OLLAMA_MODEL=llama3.2:3b # optional — index your repos into memory GITHUB_TOKEN=ghp_...
Pre-rename locations (~/.config/ai-agent, ~/.ai-agent/plugins) are still read and migrated on first access, so existing state isn't stranded.
| Command | What it does |
|---|---|
mnex ask "question" | Default path — the router picks memory, Ollama, or cloud. |
mnex ask "…" --agent | LangGraph agent with the planner → critic loop. |
mnex ask "…" --agent --trace | Same, plus the per-node execution trace. |
mnex ask "…" --route cloud | Force a route: memory, ollama or cloud. |
| Command | What it does |
|---|---|
mnex remember "fact" | Store a permanent fact in project memory. |
mnex status | Current context and memory status. |
mnex graph stats | Node and edge counts by type and relation. |
mnex graph search "text" | FTS5 search across commits, edits, commands, conversations. |
mnex graph ask "<nl>" | Natural language → SQL, read-only and guarded. |
mnex profile | Developer DNA: languages, error patterns, productive hours. |
| Command | What it does |
|---|---|
mnex review | Reviewer, tester and docsmith fan out over git diff HEAD. |
mnex eval run | Run the suite and diff against the saved baseline. |
mnex suggest export | Stream DPO-compatible JSONL from your accept/reject history. |
mnex stats --days 7 | LLM telemetry: calls, tokens, cost, latency, route. |
mnex plugin scaffold <n> | Create ~/.mnex/plugins/<n>.js from a template. |
| Command | What it does |
|---|---|
mnex github --index | Index your repos into memory as a durable run. |
mnex github --resume | Resume an interrupted index without redoing finished repos. |
mnex workflow | List durable runs with per-run step progress. |
mnex workflow show --id <id> | Per-step status, attempt counts and errors. |
mnex workflow doctor | Show the active backend; probe Temporal if selected. |
mnex worker | Long-lived Temporal worker (opt-in backend only). |
Eight stores with different lifetimes. Fast-decaying tiers stay cheap to query; permanent ones carry structure.
| Tier | Store | Lifetime | Role |
|---|---|---|---|
| Episodic | episodic.json | 3 hours | Raw stream of terminal commands and file edits. |
| Working | working.json | session | Current task, recent errors, blockers, decisions. |
| Local semantic | memory.json | permanent | Facts you explicitly asked it to remember. |
| Cloud semantic | Supermemory | cross-device | Vectorised recall across machines and projects. |
| Causal graph | causal.db | permanent | Typed nodes and edges — the structure of your work. |
| Telemetry | telemetry.db | permanent | Every LLM call: provider, tokens, cost, latency. |
| Preferences | preferences.json | permanent | Accept/reject history, few-shot into the planner. |
| Workflow log | workflows.db | 30 days | Durable step log and outbound sync outbox. |
Every JSON write is atomic (temp-then-rename) so a crash mid-write can't corrupt a tier. Every SQLite tier runs WAL with a busy_timeout, so the CLI and the background watcher can write concurrently without SQLITE_BUSY.
Indexing 50+ repos is hundreds of API calls over several minutes — long enough to be interrupted by ^C, a closed laptop or a rate limit. Every long operation is a checkpointed run.
$ mnex github --index --max 55 [1/55] repo:VaibhavDangaich/Sagepilot [2/55] repo:VaibhavDangaich/Context_graph ↻ repo:…/Portfolio: attempt 1 failed, retrying in 2s ^C $ mnex github --resume [1/55] repo:…/Sagepilot (already done, skipped) [2/55] repo:…/Context_graph (already done, skipped) ✅ newly indexed: 52 ⏭ skipped: 3
Each step is keyed by sha256(run + step + input), with object keys sorted before hashing. A completed step returns its stored output and its body is never called again.
random(0, min(cap, base·2ⁿ)). Plain exponential backoff makes every interrupted client retry in lockstep.
If a response carries Retry-After, or x-ratelimit-remaining: 0 with a reset, that is obeyed instead of the computed delay.
404, 422 and 401 are deterministic — retrying only burns rate-limit budget. Only 429, 5xx and transport errors retry.
The embedded engine is the default because a globally-installed CLI shouldn't require a server. Teams already running Temporal can opt in and get its event history and visibility UI — with no calling code changing.
$ npm i @temporalio/client @temporalio/worker \ @temporalio/workflow @temporalio/activity $ export MNEX_ORCHESTRATOR=temporal $ mnex workflow doctor # client → server → worker → activity $ mnex github --index
| embedded (default) | temporal (opt-in) | |
|---|---|---|
| Infrastructure | none | Temporal cluster or Cloud |
| Durability | SQLite step log | Temporal event history |
| Node | ≥ 18 | ≥ 20.3 |
| Install weight | 0 — bundled | ~147 packages |
| Works offline | yes | no |
Verified against a live cluster by SIGKILL-ing a worker mid-run: zero completed activities re-ran, but the activity in flight when the worker died was retried — its completion was never reported. Only completed work is never repeated, which is why mnex activities are written to be idempotent.
The shell hook runs mnex log after every command you type, so startup cost is paid constantly. Heavy model libraries are now loaded only by the commands that need them.
| Command | Before | After | Change |
|---|---|---|---|
mnex logevery shell command | 344 ms · 68.9 MB | 75 ms · 49.5 MB | −78% · −19.4 MB |
mnex --version | 160 ms · 66.3 MB | 87 ms · 45.3 MB | −46% · −21.0 MB |
mnex status | 267 ms · 68.5 MB | 169 ms · 48.7 MB | −37% · −19.8 MB |
Measured on Node v25, warm cache, mean of 8 runs; peak RSS via /usr/bin/time -l. A regression test asserts on the import graph rather than wall-clock time, so it stays stable in CI.
$ git clone https://github.com/VaibhavDangaich/MNEX.git $ cd MNEX && npm install $ npm test # 58 unit tests — no API key needed $ npm run smoke # module loading, CLI wiring, packaging
The one test needing a real cluster is skipped unless MNEX_TEMPORAL_ADDRESS is set. CI runs on Node 18, 20 and 22 plus macOS.
$ temporal server start-dev $ MNEX_TEMPORAL_ADDRESS=localhost:7233 npm test $ node scripts/verify/temporal-resume.js # crash-resume proof
A cognitive-architecture AI coding agent that lives in your terminal. Multi-tier memory, a causal work graph, durable orchestration — as one npm i -g binary with no server to run.