MELRA

Modular Execution Layer for Reliable Autonomy

Safe execution · Durable memory · Verified outcomes

An open-source execution system for durable, policy-governed autonomous workflows across files, terminal, browser, memory, and computer use—with MCP, CLI, and SDK interfaces plus inspectable, hash-linked evidence records.

[!WARNING] MELRA is an alpha release. Its local stdio runtime is tested end to end, but APIs may change before 1.0. Use an isolated workspace, keep domain and command allowlists narrow, and review every consequential approval.

Durable Core Alpha — 0.3.0-alpha.0

Contents

Why MELRA

Most MCP servers hand a model a tool and hope for the best. A command runs, a click lands, a file is written — and "it returned without an error" is treated as success.

MELRA separates the action succeeded from the goal was achieved.

If a mutation succeeds but its required evidence is missing or false, the task is partial — never verified_success.

One runtime, five execution layers 🧭

MELRA turns a tool call into a durable, inspectable task:

Every layer passes through the same policy, approval, budget, verification, receipt, and certificate pipeline.

Where you can use MELRA 🛠️

MELRA works with any MCP client that can launch a local stdio server.

Client	Setup	Status
Claude Desktop	docs
Cursor	docs
VS Code	docs
Any stdio MCP client	docs

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

What people actually do with it

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

pnpm melra run --request examples/07-project-decision-memory/task.json

See all runnable examples — browser inspection, verified file writes, terminal checks, scoped memory, and computer capability discovery.

Quickstart 🚀

Requirements: Node.js 22+, pnpm 9.5, and optionally Chrome, Chromium, or Edge for browser work.

git clone https://github.com/XAGI-Lab/melra.git
cd melra
corepack enable
pnpm install --frozen-lockfile
pnpm build
node apps/cli/dist/index.js doctor
pnpm melra init --client generic
node apps/cli/dist/index.js workflow plan \
  --definition examples/workflows/restart-safe.json

Mutations pause for an exact, expiring, task-scoped approval phrase. See installation and client setup for Claude Desktop, Cursor, VS Code, generic clients, Python, and Docker.

MELRA creates <MELRA_HOME>/payload.key with private permissions on first start. Back it up together with the SQLite files: losing or changing the key makes persisted executable payloads unreadable. Never commit the key or place it directly in a shared client configuration.

[!CAUTION] The npm package melra and the PyPI package melra are unrelated third-party projects. Install only from this repository or from official XAGI-Lab releases.

Restart-safe first workflow 🔁

The committed example performs a read, pauses for an approved file write, and finishes at a durable checkpoint. Each CLI invocation is a new process, so this sequence exercises restart persistence without keeping a daemon alive:

node apps/cli/dist/index.js workflow plan \
  --definition examples/workflows/restart-safe.json
# save the returned workflow id

node apps/cli/dist/index.js workflow advance <workflow-id>
node apps/cli/dist/index.js workflow advance <workflow-id>
# the second command exits 3 and returns the write approval challenge

node apps/cli/dist/index.js workflow advance <workflow-id> \
  --approval '<approval-id>:<exact phrase>'
node apps/cli/dist/index.js workflow advance <workflow-id>

Shortened output captured from the 0.3.0-alpha.0 release candidate:

planned            stateVersion=2
running            stateVersion=4   inspect=verified_complete
awaiting_approval  stateVersion=7   phrase="APPROVE <digest prefix>"
running            stateVersion=10  write=verified_complete
verified_complete  stateVersion=14  checkpoint=verified_complete

The final file is read independently in the real-process E2E test. Closing the process after any displayed boundary and running the next command against the same MELRA_HOME resumes the persisted workflow.

A deliberately small MCP surface ✨

Ten tools in front of five capability runtimes and one durable workflow controller:

Workflow definitions compose operation, approval, condition, parallel, bounded-loop, checkpoint, and compensation nodes while every effect still travels through the task policy and evidence pipeline.

How execution works ⚙️

flowchart LR
    Client["MCP · CLI · SDK"] --> Plan["Persist task or workflow"]
    Plan --> Policy{"Policy at plan time"}
    Policy -->|deny| Stop["Policy blocked"]
    Policy -->|allow or exact approval| Recheck{"Policy at execution time"}
    Recheck --> Runtime["File · terminal · browser · memory · computer"]
    Runtime --> Observe["Post-action observation"]
    Observe --> Verify{"Evidence predicates pass?"}
    Verify -->|yes| Success["Verified success"]
    Verify -->|no| Partial["Partial or failed"]
    Success --> Event["Ordered event + projection"]
    Event --> Receipt["Redacted receipt + SHA-256 certificate"]
    Partial --> Receipt

Task lifecycle:

planned → awaiting_approval → running → verifying
                                     ↘ verified_success
                                     ↘ partial | failed | cancelled | budget_exhausted

Policy is evaluated twice — once when the plan is persisted and again at execution — so a stale plan can never ride a since-tightened policy.

[!IMPORTANT] Current alpha boundary: exact task and workflow payloads survive restart in AES-256-GCM envelopes. Interrupted reads may retry; interrupted mutations are never silently repeated and require independent filesystem reconciliation or enter recovery_required. Evidence predicates remain caller-authored: filesystem predicates independently re-read state, while result, terminal, URL, and page predicates evaluate adapter observations.

Evidence, not leaderboard theatre 📊

The numbers below come from committed scripts and JSON artifacts measured on an Apple Silicon Mac. They are component measurements, not a claim that MELRA MCP is universally "the best" or that unlike benchmarks are comparable.

Read the research index, the benchmark methodology, and the raw microbenchmark and LoCoMo artifacts.

Browser-agent evaluation — harness registered, score not yet claimed

The repository contains a pre-registered browser-agent evaluation harness:

Track	Status
MiniWoB-125 development suite (browsergym-miniwob==0.14.3)
WebArena-Verified Hard-30 registered subset (webarena-verified==1.2.3)
Published representative score

Task IDs, upstream revisions, and dataset hashes are frozen in benchmarks/browser-agent/manifests/ and enforced by pnpm benchmark:browser:verify-upstream. A score will be published only after a full fixed-denominator run completes without infrastructure-invalid pairs and its sanitized artifact passes the publication gate.

[!IMPORTANT] MELRA has not run an official OSWorld, OSWorld-MCP, WebArena, or LongMemEval end-to-end submission. Those scores remain unclaimed until the exact public harness, environment, model policy, and evaluator are released with the result.

Safe defaults 🔒

See the threat model and security policy for residual risks.

Reproduce the scores 🧪

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

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

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

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

pnpm benchmark:browser:check
pnpm benchmark:browser:verify-upstream

uv run --project benchmarks/browser-agent --extra miniwob \
  melra-browser-bench run-miniwob \
  --manifest benchmarks/browser-agent/manifests/miniwob-125-v1.json \
  --run-dir benchmarks/browser-agent/runs/miniwob-candidate \
  --workspace benchmarks/browser-agent/runs/workspaces \
  --base-url "$MINIWOB_BASE_URL" \
  --browser-executable "$MELRA_BROWSER" \
  --implementation-commit "$(git rev-parse HEAD)" \
  --agent-config benchmarks/browser-agent/runs/config/agent.json

Benchmark artifacts include dataset hashes, environment details, sample counts, latency percentiles, and explicit claim boundaries.

SDKs and implementation languages 🧩

SDK	Package	Language
TypeScript client	@melra/sdk
Python client	melra
JSON contracts	@melra/protocol · @melra/receipt-schema

MELRA is capability-driven, not language-restricted. Rust, Go, Python, TypeScript, Swift, C#, or another language can be used when measurement shows a real improvement in isolation, portability, performance, reliability, or platform integration without fragmenting the public contracts.

Repository map 🗂️

apps/cli/                   CLI and stdio entrypoint
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/server/            ten-tool MCP server and runtime router
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/memory/            scoped hybrid retrieval and lifecycle controls
packages/storage-sqlite/    transactional tasks, workflows, events, evidence
packages/verifier-core/     deterministic evidence predicates
packages/receipt-schema/    receipts and execution certificates
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

Documentation 📚

Contributing 🤝

Code, adapters, 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.
4. Report vulnerabilities through GitHub 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; see BRAND.md. Third-party benchmark datasets retain their own licenses and are not included in this repository.