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.

Durable Core Alpha — 0.3.0-alpha.0

Contents

Related MCP server: Container-MCP

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.

• Tool call executes immediately

• Success = no exception thrown

• Policy, if any, checked once

• Mutations are indistinguishable from reads

• Output is trusted

• No durable record

• Plan and execute are separate tool calls

• Success = declared evidence predicates passed

• Policy re-evaluated at execution time

• Mutations need evidence and an exact approval phrase

• Page content is explicitly marked untrusted

• Redacted receipt + SHA-256 execution certificate

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.

What people actually do with it

A coding client submits one bounded operation with the evidence it expects:

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

The task reaches verified_success only if the process exits 0. A process that runs and exits 1 is a completed action with failed evidence — reported as partial.

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

Records are scoped, provenance-tagged, and pass through secret redaction before they are persisted.

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.

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.

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:

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.

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

Contract and registered-selection checks run with no model and no network environment:

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

The MiniWoB development suite additionally needs the pinned MiniWoB++ assets, a built CLI (pnpm build), and an agent configuration whose api_key_env names a variable present in the environment:

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

Run outputs — HAR, screenshots, video, and transcripts — are Git-ignored and must never be committed.

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

SDKs and implementation languages 🧩

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.

Built in the open by XAGI Labs.

MELRA brand assets © XAGI Labs Private Limited, licensed CC BY-ND 4.0.