MELRA

Modular Execution Layer for Reliable Autonomy

The open-source autonomy kernel

The LLM reasons. The harness manages the loop. MELRA owns the effect lifecycle.

An agent-independent effect runtime for governed, durable, and verifiable autonomous execution. MELRA begins where the tool call leaves the model loop.

Your models can change. Your agents can change. Your execution foundation shouldn't have to.

Durable Core Alpha — 0.3.0-alpha.11

Contents

Related MCP server: Container-MCP

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, run it exactly once, prove it worked, and survive a crash in the middle. Today that machinery is rebuilt inside every agent harness, in a way that dies with the harness.

MELRA is that machinery, factored out and made agent-independent:

The LLM reasons. The harness manages the loop. MELRA owns the effect lifecycle.

An effect is a named operation that changes or observes the world outside the model — file.write, terminal.execute, browser.click, computer.keyboard, http.request, database.mutate, stripe.refund, github.merge. MELRA does exactly nine things to every one of them, and nothing else:

That list is the whole job. Everything upstream of it — what to attempt, in what order, and why — stays with the model and the harness.

Which is why MELRA never receives a goal. "Fix the production server" requires judgement about what is broken and what should change; that is reasoning, and it belongs to the model. The model resolves it to a bounded operation, and that is what arrives:

{ "effect": "terminal.execute", "command": "systemctl",
  "args": ["restart", "api"], "environment": "production" }

An interface that accepted the sentence would have to interpret it, and a kernel that interprets is a kernel whose guarantees depend on a model.

Most tool servers hand a model a tool and hope. 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

• Rules live inside one agent

• 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

• Rules outlive the agent that used them

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

Agents should be replaceable. The infrastructure that owns consequences should not be. Swap the harness on Friday; the policies, approvals, credentials, workflow history, idempotency records, and receipts are still there on Monday.

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, and there is no Unix-socket transport yet (#52). A kernel cannot verify it is the only door; enforced mode is the operator asserting that, and MELRA holding up its end.

Where it sits 🧭

Three layers, not two. The reasoning loop is the model and the harness together; the effect lifecycle is below both of them.

            ┌────────────────────────────────────────────┐
  reasoning │  LLM    Claude · GPT · Gemini · Llama      │
            │  reasons · decides what should happen      │
            └────────────────────────────────────────────┘
                           ▲ tool call   │ tools + context
                           │             ▼
            ┌────────────────────────────────────────────┐
   the loop │  AGENT HARNESS   OpenClaw · Hermes ·       │
            │  ATLAS · Claude Code · your own            │
            │  sessions · context · prompts · dispatch   │
            └────────────────────────────────────────────┘
                                   │  effect request
                                   ▼
            ╔════════════════════════════════════════════╗
    effects ║  MELRA — autonomy kernel                   ║
            ║                                            ║
            ║  identity · capability · policy ·          ║
            ║  authorization · credential broker ·       ║
            ║  durable execution · idempotency ·         ║
            ║  recovery · verification · evidence        ║
            ╚════════════════════════════════════════════╝
                                   │
                                   ▼
            ┌────────────────────────────────────────────┐
   adapters │  EFFECT ADAPTERS                           │
            │  files · terminal · browser · computer ·   │
            │  HTTP — planned: database · cloud · SaaS   │
            └────────────────────────────────────────────┘
                                   ▼
             Linux · macOS · Windows · APIs · cloud

Many harnesses, one execution foundation:

   OpenClaw ─┐
   Hermes ───┤
   ATLAS ────┼──→  MELRA  ──→  your systems
   Custom ───┘

Who owns what, and this does not move:

MCP is one way to reach the kernel, not what the kernel is. MCP, CLI, SDK, and loopback HTTP all enter the same runtime, take the same policy decision, and write the same durable record.

Reference effect adapters 🔌

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

The diagram above also shows database, cloud, and SaaS adapters. Those are designed and on the roadmap — not shipped today. HTTP is, because a serious amount of autonomous work happens through APIs rather than mouse clicks, and an API effect needs the same nine guarantees as a file write.

Operational memory is a kernel service rather than an adapter: what MELRA knows about its own effects — which operation changed what, which attempt was already committed, what a previous run observed. Scoped SQLite storage with hybrid lexical ranking, episode context, confidence, freshness, expiry, supersession, provenance, and redaction. Semantic memory about the user — preferences, project context, conversation history — belongs to the harness above, not here.

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 🚀

npm (fastest — needs Node 22+):

npx @melra/cli@alpha setup

One command: writes a safe local policy, prints a ready-to-paste MCP client config, and runs every readiness check. Add --client claude|cursor|vscode|codex to label the config for a specific client. Use doctor alone to check readiness without writing anything.

Container (no Node install needed):

docker run --rm ghcr.io/xagi-lab/melra:alpha doctor

Prebuilt release: Download from the releases page, extract, and run:

tar -xzf melra-node-<version>.tar.gz -C melra
node melra/dist/bin.js doctor

From source (for development):

git clone https://github.com/XAGI-Lab/melra.git
cd melra
corepack enable
pnpm install --frozen-lockfile
pnpm build
pnpm melra setup

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/bin.js workflow plan \
  --definition examples/workflows/restart-safe.json
# save the returned workflow id

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

node apps/cli/dist/bin.js workflow advance <workflow-id> \
  --approval '<approval-id>:<exact phrase>'
node apps/cli/dist/bin.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 ✨

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

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

If you would rather your model saw the tool names it already knows, set MELRA_HARNESS_TOOLS=1 and thirteen more appear alongside these — read_file, write_file, run_command, browser_click, approve, and the rest. They are not a second path: each one builds an ordinary task and runs the same pipeline, and a mutation still stops on its approval phrase. See INSTALLATION.md.

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.

Every row above can be turned off at once with melra serve --unsafe-local (or MELRA_UNHINGED=1): no policy, no approvals, no evidence requirement, no workspace confinement, no destination checks. The agent gets exactly the reach your OS user has. The mode announces itself on stderr, in melra doctor, and in melra_capabilities, and receipts still record what ran. See unsafe-local mode for what stays on and why.

Two deployment modes

The honest gap in a default install is that MELRA governs the effects it is asked for. A harness holding both a MELRA terminal and a native one makes the kernel optional, and an optional boundary is not a trust boundary. MELRA_MODE is where you say which situation you are in:

MELRA cannot verify that assertion from inside its own process, and it does not pretend to: the isolation is the operating system's job, so bring a container or a sandbox profile. What enforced mode does is stop being one of the ways the claim could be false — --unsafe-local refused outright, no bind outside loopback, no client registering itself, and mode stamped on every receipt. A conformance run against it keeps the same level and narrows its caveat to naming whose word the rest rests on. See deployment modes.

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

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 and loopback HTTP

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

Documentation 📚

Contributing 🤝

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

Looking for something to pick up?

Adding an operation or an evidence predicate touches a fixed, short list of places — the guide names them in order, so a first pull request does not have to be discovered by grep.

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