Melra README

MELRA

Modular Execution Layer for Reliable Autonomy

Your AI agent decides what to do. MELRA governs how tool calls are authorized, verified, and recovered.

An open-source local execution runtime for agent tool calls you route through MELRA. It checks each call against policy, requests approval when needed, verifies declared evidence, and keeps a redacted receipt of what runs to an outcome. For each task, MELRA dispatches mutations at most once; uncertain outcomes are parked for reconciliation instead of replay. Exactly-once external effects still depend on the provider. Calls made through other tools remain outside MELRA's control.

Works with  

26-second demo  ·  Quick start  ·  How it works  ·  See what it is doing  ·  Docs  ·  Contribute  ·  Discussions  ·  Product Hunt launch

26-second demo

https://github.com/user-attachments/assets/e5cf895d-7ea6-4797-a1ef-e69cc5860d3f

[!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.

Quick start

You need Node.js 22.13 or newer, or 23.4 or newer. From the project the agent should work in, one command sets everything up:

cd ~/project
npx @melra/cli@alpha setup

That directory becomes the agent's workspace, the boundary for its file and command operations. setup shows it, and asks before making your home directory, a directory holding it, or / the workspace; set MELRA_WORKSPACE to choose another.

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]

  ✓  Workspace    ~/project
  ✓  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. Or start it with 'melra launch claude-code', so MELRA's are the only tools it has that change anything.

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] This project publishes only under the @melra/ npm scope (@melra/cli is the CLI) and on its releases, where the Python SDK's wheel is. An unscoped npm package melra or a PyPI package melra is not this project's. Install from that scope, from this repository, or from the 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.

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 in one place for tool calls routed through it, across supported agents. It sits underneath your agent for those calls, the way an operating system sits underneath your apps:

The LLM reasons. The harness manages the loop. MELRA governs the effect lifecycle for calls routed through it. Swap the model or the agent; MELRA's policies, approvals, credentials, history and receipts can stay in place.

Works with your agent

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

Agent	--client	Config it writes	Tested
Claude Code	claude-code	<project>/.mcp.json	connected by hand
Claude Desktop	claude-desktop	claude_desktop_config.json	config checked against docs
OpenAI Codex CLI	codex	~/.codex/config.toml	config checked against docs (its own CLI parsed it)
Cursor	cursor	~/.cursor/mcp.json	config checked against docs
🟦 VS Code (Copilot agent mode)	vscode	<project>/.vscode/mcp.json	config checked against docs
Gemini CLI	gemini	~/.gemini/settings.json	config checked against docs
Windsurf	windsurf	~/.codeium/windsurf/mcp_config.json	config checked against docs
Zed	zed	Zed settings.json (comments kept)	config checked against docs
🧩 Cline	cline	Cline's cline_mcp_settings.json	config checked against docs
⬛ OpenCode	opencode	~/.config/opencode/opencode.json	connected by hand
👻 Kiro	kiro	~/.kiro/settings/mcp.json	config checked against docs
🪿 Goose	goose	~/.config/goose/config.yaml	config checked against docs
▶️ Continue	continue	<project>/.continue/mcpServers/melra.yaml	config checked against docs
⚡ Amp	amp	~/.config/amp/settings.json	config checked against docs
🦞 OpenClaw	openclaw	~/.openclaw/openclaw.json (mcp.servers)	config checked against docs
⚕️ Hermes Agent (Nous Research)	hermes	~/.hermes/config.yaml (mcp_servers)	connected by hand
GitHub Copilot CLI	copilot	~/.copilot/mcp-config.json	config checked against docs
🐉 Qwen Code	qwen	~/.qwen/settings.json	config checked against docs
🅰️ Auggie (Augment)	auggie	~/.augment/settings.json	config checked against docs
Warp	warp	~/.warp/.mcp.json	config checked against docs
Junie (JetBrains)	junie	~/.junie/mcp/mcp.json	config checked against docs
🤖 Factory Droid	droid	~/.factory/mcp.json	config checked against docs
🌙 Kimi Code	kimi	~/.kimi-code/mcp.json	config checked against docs
🪁 Kilo Code	kilo	~/.config/kilo/kilo.jsonc (comments kept)	config checked against docs
🧪 LM Studio	lmstudio	~/.lmstudio/mcp.json	config checked against docs
🔌 Anything else	generic	prints the standard mcpServers block	documented only

Tested says how far each one has been taken: run in CI (an automated suite drives it), connected by hand (its own CLI connected to a packed release over MCP, but no task was run from inside it; see COMPATIBILITY.md), config checked against docs (the file and format come from its documentation or source, and the CLI tests write and read them back), or documented only.

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: the official MCP SDKs' snippets run in CI with no model; the LangChain / LangGraph, OpenAI Agents SDK and Vercel AI SDK ones are documented only.

[!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

An effect is one bounded operation an agent routes through MELRA: file.write, terminal.run, browser.click, http.request, and so on. MELRA handles each routed effect in nine stages, split between a plan step and an execute step (for a single task, melra_plan then melra_execute) 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 <task-id> 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:

{
  "goal": "Run the repository checks",
  "operation": { "kind": "terminal", "action": "run", "command": "pnpm", "args": ["check"] },
  "requiredEvidence": [{ "type": "exit_code", "value": 0 }]
}

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 each action MELRA handled and its policy decision, and, for each that ran to an outcome, its evidence and receipt, from the terminal or the browser. Nothing here can approve or start work, and approval phrases are never displayed.

From the terminal textCopy $ melra status MELRA 0.4.0-alpha.2 developer mode Tasks 3 total: 1 awaiting_approval, 1 policy_blocked, 1 verified_success Waiting 1 waiting for approval HTTP 127.0.0.1:7457 not running $ melra tasks ID STATUS OPERATION UPDATED 64199678 awaiting_approval file.write 0s ago ca4aec7a policy_blocked terminal.run 1s ago a1285e0f verified_success system.info 1s ago $ melra watch # live, until Ctrl-C 6:07:21 PM task 882cf55c verified_success 6:07:22 PM task f813364c awaiting_approval melra doctor checks Node, SQLite, the browser and policy, and reports which of your agent apps point at MELRA, with the one command that fixes anything wrong.

In the browser: melra serve --http --open An overview, a searchable task list, and durable workflows with a live event stream. It works at phone width and in light and dark, and it is served with a strict Content-Security-Policy.

Safe by default

What actually guards an effect depends on the mode:

melra doctor says which of these hold on its protection line, and melra_capabilities reports approvals and sandbox beside mode.

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

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

A verdict records its judge as declared, and the certificate carries it beside executedBy, the receipt's declared principal. Over MCP even a human: judge is the harness's claim; only a cli: judge, from melra judge, came through an operator surface.

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 <workflow-id>
melra workflow advance <workflow-id>          # exits 3 with the write's approval challenge
# developer mode echoes the phrase; enforced mode runs `melra approve <task-id>` instead
melra workflow advance <workflow-id> --approval '<approval-id>:<exact phrase>'
melra workflow advance <workflow-id>

planned            stateVersion=2
running            stateVersion=4   inspect=verified_complete
awaiting_approval  stateVersion=6   phrase="APPROVE <digest prefix>"   (developer mode)
running            stateVersion=8   write=verified_complete
verified_complete  stateVersion=11  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.

workflow advance and resume exit 0 while the run is fine, 3 while it waits on an approval, 4 while it waits on an --input, and 2 once it has failed, ended partially_complete or cancelled, or needs recovery. workflow plan, pause and suspend exit 0 when they plan or halt the run; pausing or suspending a run that is complete, cancelled or failed is refused. workflow inspect exits 0 in any state. workflow cancel exits 0 when it leaves the run cancelled and 1 when it does not, as for a run already complete. Errors exit 1.

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.

# the full validation gate
pnpm check && pnpm evals && pnpm e2e && pnpm pack:check && pnpm security:audit
pnpm --filter @melra/evals evaluate:durable-core -- --publishable

# memory, browser, terminal and computer microbenchmarks
pnpm benchmark:core

# governance benchmark: 363 model-free cases, loopback fixtures only
pnpm benchmark:govbench

# LoCoMo (dataset not vendored: CC BY-NC 4.0)
git clone https://github.com/snap-research/locomo.git /tmp/locomo
pnpm benchmark:locomo -- --dataset /tmp/locomo/data/locomo10.json \
  --output docs/research/results/locomo-retrieval.json

# browser-agent harness contract checks (no model, no network)
pnpm benchmark:browser:check
pnpm benchmark:browser:verify-upstream

# hardened container and a real MCP smoke test
docker build -t melra:local . && docker run --rm melra:local doctor && pnpm docker:smoke

For developers

SDKs Package TypeScript @melra/sdk Python melra (typed, 3.11–3.14) 📜 JSON contracts @melra/protocol, @melra/receipt-schema Both SDKs spawn a local server or connect to a running one over HTTP or a Unix socket. The token is always passed explicitly, and plain HTTP to a remote host is refused unless you opt in.

CLI at a glance Goal Command Guided setup melra setup Check this machine melra doctor Serve (stdio / HTTP / socket) melra serve · --http --open · --socket <path> See activity melra tasks · watch · status Run one task melra run --request task.json Approve a task an agent planned melra approve <task-id> · in a browser: melra console Answer a task's semantic question melra judge <task-id> --judgement <id> --verdict yes|no|cannot_tell Inspect a receipt melra inspect <task-id> Test a policy melra policy test --request task.json Check conformance melra conformance

apps/cli/                   CLI and stdio entrypoint

kernel services
packages/protocol/          strict task, workflow, event and operation schemas
packages/runtime-core/      task/workflow lifecycle, events, recovery
packages/policy-core/       local policy and scoped approvals
packages/storage-sqlite/    transactional tasks, workflows, events, evidence
packages/verifier-core/     deterministic evidence predicates
packages/receipt-schema/    receipts and execution certificates
packages/memory/            operational memory: scoped retrieval and lifecycle
packages/server/            runtime composition, MCP, loopback HTTP and Unix socket

reference effect adapters
packages/file-runtime/      confined filesystem operations
packages/terminal-runtime/  shell-free process supervision
packages/browser-runtime/   isolated browser automation and stable-DOM wait
packages/computer-runtime/  governed local computer-use adapters
packages/http-runtime/      governed HTTP and API calls

clients and evidence
packages/sdk-ts/            TypeScript client SDK
sdk-py/                     Python client SDK
benchmarks/browser-agent/   pre-registered browser-agent evaluation harness
evals/                      safety and durable crash-recovery evaluations
scripts/                    benchmark and release checks
docs/research/              methods, findings and raw results
examples/                   runnable task examples

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), and sign the CLA once, on your first pull request.
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

The MELRA kernel, CLI and documentation are licensed under the GNU Affero General Public License v3.0 only, and XAGI Labs Private Limited also offers the kernel under a commercial license. The SDKs (@melra/sdk, @melra/protocol and the melra Python package), the examples and the code samples in the documentation stay under the Apache License 2.0, so code that only calls MELRA can use any license. Releases up to and including 0.3.0-alpha.22 were Apache-2.0 and stay so. LICENSING.md maps each path to its license and explains what the AGPL asks of a modified MELRA run as a network service.

The MELRA name and logo are covered by TRADEMARKS.md; the official logo and hero artwork are all rights reserved. Third-party benchmark datasets keep their own licenses and are not included in this repository.