xagi-lab/melra

[!WARNING] MELRA is alpha software. The local runtime is tested end to end, but APIs may change before 1.0. Use an isolated workspace, keep domain and command allowlists narrow, and read every approval before you give it.

---

What is MELRA?

AI agents no longer just talk. They edit files, run commands, click through websites and call APIs on your behalf. Four questions come with that, and most agents answer them differently, or not at all:

MELRA answers those questions once, in one place, for every agent. It sits underneath your agent, the way an operating system sits underneath your apps:

The LLM reasons. The harness manages the loop. MELRA owns the effect lifecycle. Swap the model or the agent on Friday; your policies, approvals, credentials, history and receipts are still there on Monday.

---

Quick start

You need Node.js 22.13 or newer. One command sets everything up:

npx @melra/cli@alpha setup

In a terminal, setup is a short wizard. It writes a safe local policy, finds the agent apps on your machine, asks which one should use MELRA, and writes MELRA into that app’s own config file, keeping everything else in it (and saving a .bak first):

Which MCP client should use MELRA?

  1)   Claude Code                      detected: 'claude' on PATH
  2)   Cursor                           detected: config file found
  3)   Gemini CLI                       detected: config folder found
  ...

Choose 1-26 [1]: 1
Write it into ~/project/.mcp.json? [Y/n]

  ✓  Policy       ~/.melra/policy.json
  ✓  Claude Code  ~/project/.mcp.json

Next: Start claude in this workspace and approve the 'melra' server when it asks; 'claude mcp list' then shows it connected.

Then restart your agent app (Claude Code asks you to approve a project’s server once) and ask it to do something, for example “use melra to show me the system info”. That’s it.

[!CAUTION] The unscoped npm package melra and the PyPI package melra are unrelated third-party projects. This project publishes only under the @melra/ npm scope: @melra/cli is the CLI. Install from that scope, from this repository, or from the official releases.

If MELRA helps, star the repository so other agent builders can find it. Trying it in Cursor or another client? Share the client and its version, your OS, and your MELRA version (npx @melra/cli@alpha version) in issue #184; partial test results are useful too.

---

Works with your agent

MELRA speaks the Model Context Protocol, so any MCP client can use it. For these, melra setup --client writes the config in the client’s own format and location, and melra doctor tells you whether each one is pointed at MELRA:

Building your own agent? Use the TypeScript SDK or the Python SDK. Both can spawn MELRA or connect to one that is already running over loopback HTTP or a private Unix socket. For agent frameworks, see the framework examples: LangChain / LangGraph, the OpenAI Agents SDK, the Vercel AI SDK, and the official MCP SDKs.

[!NOTE] A named client is marked verified only after the released package, not a source checkout, passes discovery, planning, approval, execution, cancellation and receipt retrieval in that client. Per-client status lives in COMPATIBILITY.md.

---

How it works

Every action an agent wants to take is called an effect: file.write, terminal.run, browser.click, http.request, and so on. MELRA does exactly nine things to every effect, split across two calls so that nothing runs at planning time:

Here is one change from start to finish, in developer mode. In enforced mode the challenge carries no phrase: you approve with melra approve outside the conversation, and the agent’s melra_execute sends no approval at all.

sequenceDiagram
    autonumber
    participant A as Your agent
    participant M as MELRA
    participant You
    participant W as Your system
    A->>M: melra_plan: write notes.md, evidence "file contains 'done'"
    M->>M: type, classify, check policy, record
    M-->>A: awaiting_approval + challenge "APPROVE 3f9c…"
    A->>You: May I write notes.md?
    You-->>A: yes
    A->>M: melra_execute with the exact phrase
    M->>M: policy again, not already done?
    M->>W: write the file (under a budget)
    M->>W: read it back, independently
    M-->>A: verified_success + receipt

What the final status means, and what an agent should do next:

When an agent connects, MELRA also sends it a short guide to this loop (the MCP server’s instructions), so a model knows to declare evidence, read the status, and never blindly retry an unknown outcome, without anyone prompt-engineering it.

---

See what it is doing

You can see every action, its policy decision, its evidence and its receipt, from the terminal or the browser. Nothing here can approve or start work, and approval phrases are never displayed.

---

Safe by default

---

Why MELRA

An LLM decides what to do. A harness runs the loop that gets it there. Something still has to decide whether the resulting effect is allowed, avoid replaying uncertain mutations, prove what happened, and survive a crash in the middle. Today that machinery is rebuilt inside every agent harness, and it dies with the harness. MELRA is that machinery, factored out and made agent-independent.

Next to the two layers it is most often mistaken for:

Plenty of MCP servers can do these things; this is not a claim that none of them do. The difference is that in MELRA they are the execution contract rather than a per-tool option. The boundary is partly shipped: MELRA_MODE=enforced closes every door MELRA owns, but the OS isolation that stops a harness reaching the filesystem around the kernel is the operator’s to build; runnable hardened deployment recipes are still to come (#52).

The feature test. Anything that would still make sense if the request came from ordinary deterministic software belongs in MELRA: authorisation, idempotency, credential isolation, recovery, verification, effect history. Prompt optimisation, LLM memory, model selection, a planner and agent personality belong to the harness above. That is why nothing in MELRA’s execution path ever calls a model.

---

What it can do

Effect adapters

The kernel is the contract; these are its shipped implementations. Every one passes through the same policy, approval, budget, verification, receipt and certificate pipeline; an adapter that skipped it would not be an adapter.

Database, cloud and SaaS adapters are designed and on the roadmap, not shipped today. Semantic memory about the user (preferences, conversation history) belongs to the harness, not here.

A deliberately small tool surface

Eleven tools in front of the adapters and one durable workflow controller. The CLI, both SDKs, loopback HTTP and the Unix socket reach the same eleven operations; this list is the kernel contract, not an MCP-specific API.

Prefer tool names your model already knows? Set MELRA_HARNESS_TOOLS=1 and thirteen more appear alongside these (read_file, write_file, run_command, browser_click, approve, …). They are not a second path: each one builds an ordinary task and runs the same pipeline. See ordinary tool names.

Durable, restart-safe workflows

Workflows compose operation, approval, condition, parallel, bounded_loop, checkpoint, compensation, human_input and delegation nodes, and every effect still travels through the task pipeline. Each CLI call below is a new process, so this exercises restart persistence with no daemon:

melra workflow plan --definition examples/workflows/restart-safe.json   # save the id
melra workflow advance 
melra workflow advance           # exits 3 with the write's approval challenge
# developer mode echoes the phrase; enforced mode runs `melra approve ` instead
melra workflow advance  --approval ':'
melra workflow advance 

planned            stateVersion=2
running            stateVersion=4   inspect=verified_complete
awaiting_approval  stateVersion=7   phrase="APPROVE "   (developer mode)
running            stateVersion=10  write=verified_complete
verified_complete  stateVersion=14  checkpoint=verified_complete

Stop the process after any line and the next command resumes from the same MELRA_HOME. Interrupted reads may retry; interrupted changes are never silently repeated. They are settled by re-observation, or they park in recovery_required.

---

Evidence and benchmarks

Numbers come from committed scripts and JSON artifacts, with dataset hashes and claim boundaries. They are component measurements, not a claim that MELRA is “the best” or that unlike benchmarks are comparable.

Raw artifacts: core microbenchmarks, LoCoMo and GovBench.

The repository also contains a pre-registered browser-agent harness (MiniWoB-125 and the WebArena-Verified Hard-30 registered subset) whose task IDs, upstream revisions and dataset hashes are frozen. Its score is not yet claimed: it will be published only after a full fixed-denominator run passes the publication gate. MELRA has not run an official OSWorld, WebArena or LongMemEval submission.

---

For developers

Runnable examples cover a read-only system task, a verified file write, a terminal check, browser inspection, scoped memory, computer capability discovery, a governed API call, independent verification, and a restart-safe workflow.

---

Documentation

---

Contributing

Code, adapters, client integrations, benchmark harnesses, verifier predicates, documentation and threat analysis are all welcome.

1. Read CONTRIBUTING.md and the Code of Conduct.
2. Sign your commits under the DCO (git commit -s).
3. Run pnpm check before opening a pull request; it also checks links, the environment-variable table and the CHANGELOG shape.
4. Report vulnerabilities through private vulnerability reporting, never in a public issue.

---

License

Software and documentation are licensed under the Apache License 2.0. The official logo and hero artwork are licensed under CC BY-ND 4.0. Third-party benchmark datasets keep their own licenses and are not included in this repository.