MELRA

MELRA

Modular Execution Layer for Reliable Autonomy

AI エージェントが実行内容を決定します。MELRA は、ツール呼び出しの承認、検証、復旧の方法を管理します。

MELRA を介してルーティングするエージェントのツール呼び出し向け、オープンソースのローカル実行ランタイムです。 各呼び出しをポリシーに照らして確認し、必要に応じて承認を求め、宣言された 証拠を検証し、実行から結果までの内容を秘匿化したレシートに記録します。各タスクで、MELRA は 変更操作を最大 1 回だけディスパッチします。不確実な結果は再実行せず、照合のために保留します。 外部への副作用を厳密に 1 回だけにできるかどうかは、引き続きプロバイダーに依存します。 ほかのツールを介して行われる呼び出しは、MELRA の管理対象外です。

対応環境  

26 秒のデモ  ·  クイックスタート  ·  仕組み  ·  動作を見る  ·  ドキュメント  ·  貢献  ·  ディスカッション  ·  Product Hunt での公開

26 秒のデモ

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

警告

MELRA はアルファ版ソフトウェアです。 ローカルランタイムはエンドツーエンドでテスト済みですが、API は 1.0 より前に変更される可能性があります。隔離されたワークスペースを使用し、ドメインとコマンドの許可リストを 必要最小限に保ち、承認する前に内容を必ず確認してください。

クイックスタート

Node.js 22.13 以降、または 23.4 以降が必要です。エージェントが作業するプロジェクトから、1 つのコマンドですべてをセットアップできます。

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

そのディレクトリがエージェントのワークスペースとなり、ファイル操作とコマンド操作の境界になります。setup はその場所を表示し、ホームディレクトリ、その親ディレクトリ、または / をワークスペースにする場合は確認を求めます。別の場所を選ぶには、MELRA_WORKSPACE を設定してください。

ターミナルで実行すると、setup は簡単なウィザードになります。安全なローカルポリシーを書き込み、お使いのマシン上のエージェントアプリを探して、どのアプリで MELRA を使うかを尋ね、そのアプリの設定ファイルに MELRA を書き込みます。ファイル内のほかの設定はそのまま残し、最初に .bak ファイルを保存します。

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.

その後、エージェントアプリを再起動し（Claude Code では、プロジェクトのサーバーを一度承認する必要があります）、たとえば 「melra を使ってシステム情報を表示して」 のように頼んでください。これで完了です。

注意

このプロジェクトが公開しているのは、@melra/ npm スコープ内のパッケージ（@melra/cli は CLI）と、Python SDK の wheel があるリリースのみです。スコープのない npm パッケージ melra や PyPI パッケージ melra はこのプロジェクトのものではありません。このスコープ、リポジトリ、またはリリースからインストールしてください。

MELRA が役に立ったら、リポジトリにスターを付けて、ほかのエージェント開発者にも見つけてもらいましょう。Cursor やほかのクライアントで試していますか？クライアント名とそのバージョン、OS、MELRA のバージョン（npx @melra/cli@alpha version）をissue #184で共有してください。部分的なテスト結果も役立ちます。

MELRA とは？

AI エージェントは、もはや会話するだけではありません。ユーザーに代わってファイルを編集し、コマンドを実行し、ウェブサイトを操作し、API を呼び出します。これに伴って 4 つの疑問が生じますが、多くのエージェントはそれぞれ異なる方法で答えるか、まったく答えません。

MELRA は、サポート対象のエージェントをまたいで、MELRA 経由でルーティングされたツール呼び出しに関するこれらの問いに、一か所で答えます。これらの呼び出しについては、オペレーティングシステムがアプリの下で動作するように、エージェントの下で動作します。

**LLM が推論します。ハーネスがループを管理します。MELRA は、MELRA 経由でルーティングされた呼び出しのエフェクトのライフサイクルを管理します。**モデルやエージェントを切り替えても、MELRA のポリシー、承認、認証情報、履歴、レシートはそのまま維持できます。

エージェントとの連携

MELRA は Model Context Protocol に対応しているため、あらゆる MCP クライアントで利用できます。次のクライアントでは、melra setup --client <name> を実行すると、クライアント独自の形式と場所に設定を書き込みます。また、melra doctor を実行すると、それぞれが MELRA を参照しているか確認できます。

エージェント	--client	書き込まれる設定
Claude Code	claude-code	<project>/.mcp.json
Claude Desktop	claude-desktop	claude_desktop_config.json
OpenAI Codex CLI	codex	~/.codex/config.toml
Cursor	cursor	~/.cursor/mcp.json
🟦 VS Code（Copilot エージェントモード）	vscode	<project>/.vscode/mcp.json
Gemini CLI	gemini	~/.gemini/settings.json
Windsurf	windsurf	~/.codeium/windsurf/mcp_config.json
Zed	zed	Zed の settings.json（コメントを保持）
🧩 Cline	cline	Cline の cline_mcp_settings.json
⬛ OpenCode	opencode	~/.config/opencode/opencode.json
👻 Kiro	kiro	~/.kiro/settings/mcp.json
🪿 Goose	goose	~/.config/goose/config.yaml
▶️ Continue	continue	<project>/.continue/mcpServers/melra.yaml
⚡ Amp	amp	~/.config/amp/settings.json
🦞 OpenClaw	openclaw	~/.openclaw/openclaw.json（mcp.servers）
⚕️ Hermes Agent（Nous Research）	hermes	~/.hermes/config.yaml（mcp_servers）
GitHub Copilot CLI	copilot	~/.copilot/mcp-config.json
🐉 Qwen Code	qwen	~/.qwen/settings.json
🅰️ Auggie（Augment）	auggie	~/.augment/settings.json
Warp	warp	~/.warp/.mcp.json
Junie（JetBrains）	junie	~/.junie/mcp/mcp.json
🤖 Factory Droid	droid	~/.factory/mcp.json
🌙 Kimi Code	kimi	~/.kimi-code/mcp.json
🪁 Kilo Code	kilo	~/.config/kilo/kilo.jsonc（コメントを保持）
🧪 LM Studio	lmstudio	~/.lmstudio/mcp.json
🔌 その他	generic	標準の mcpServers ブロックを出力

独自のエージェントを構築していますか？TypeScript SDK または Python SDK をご利用ください。どちらも、MELRA を起動するか、すでに稼働中の MELRA にループバック HTTP またはプライベート Unix ソケット経由で接続できます。エージェントのフレームワークについては、フレームワークの例をご覧ください。LangChain / LangGraph、OpenAI Agents SDK、Vercel AI SDK、公式 MCP SDK が含まれています。

メモ

名前付きクライアントが検証済みとマークされるのは、ソースのチェックアウトではなく、リリース済みパッケージがそのクライアントで検出、計画、承認、実行、キャンセル、レシート取得に合格した場合に限られます。クライアントごとのステータスは COMPATIBILITY.md に記載されています。

仕組み

エフェクトとは、エージェントが MELRA 経由で実行する、範囲が限定された操作のことです。file.write、 terminal.run、browser.click、http.request などがあります。MELRA はルーティングされた各エフェクトを、 計画ステップと実行ステップに分けた 9 つの段階で処理します（単一のタスクでは、melra_plan の後に melra_execute を実行します）。そのため、計画時には何も実行されません。

以下は、開発者モードで最初から最後まで実行する変更の例です。 強制モードでは、チャレンジにフレーズは含まれません。 会話の外で melra approve <task-id> を実行して承認します。また、エージェントの melra_execute は承認を一切送信しません。

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

最終ステータスの意味と、エージェントが次に行うべきこと：

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

エージェントが接続すると、MELRA はこのループの簡潔なガイド（MCP サーバーの instructions）も送信します。これにより、誰かがプロンプトエンジニアリングをしなくても、モデルは 証拠を宣言し、ステータスを確認し、結果が不明なときに決して盲目的に再試行しないことを把握できます。

動作を確認する

MELRA が処理した各アクションとそのポリシー判定を、ターミナルまたはブラウザーから確認できます。実行結果がある場合は、それぞれの証拠とレシートも確認できます。ここから承認したり、作業を開始したりすることはできず、承認フレーズが表示されることもありません。

ターミナルから $ melra status MELRA 0.3.0-alpha.19 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 は Node、SQLite、ブラウザー、ポリシーをチェックし、お使いのエージェントアプリのうち MELRA を参照しているものを報告します。問題を修正するためのコマンドも表示されます。

ブラウザーから： melra serve --http --open 概要、検索可能なタスクリスト、ライブイベントストリーム付きの永続的なワークフローを確認できます。 スマートフォンの画面幅に対応し、ライトモードとダークモードで表示でき、厳格な Content-Security-Policy を適用して配信されます。

デフォルトで安全

MELRA の理由

LLM は 何を するかを決めます。ハーネスは、そこに至るまでのループを実行します。それでも、結果として生じる影響が許可されているかを判断し、不確かな変更の再実行を避け、何が起きたかを証明し、処理の途中でクラッシュしても復旧できる仕組みが必要です。現在、こうした仕組みはエージェントのハーネスごとに再構築され、ハーネスとともに消えてしまいます。MELRA はその仕組みを切り出し、エージェントに依存しない形にしたものです。

よく混同される 2 つのレイヤーと並べると、次のようになります。

多くの MCP サーバーがこうした機能を実現できる可能性はあります。どのサーバーも実現できないと主張しているわけではありません。違いは、MELRA ではこれらがツールごとのオプションではなく、実行契約になっていることです。この境界は一部提供済みです。MELRA_MODE=enforced によって、MELRA が管理するすべての経路は閉じられますが、ハーネスがカーネルの外側からファイルシステムにアクセスするのを防ぐ OS レベルの分離は、運用者が構築する必要があります。すぐに実行できる強化済みデプロイ手順は、今後提供される予定です（#52）。

機能の判断基準。 リクエストが通常の決定的なソフトウェアから来た場合でも意味があるものは、すべて MELRA に属します。たとえば、認可、冪等性、認証情報の分離、復旧、検証、影響履歴です。プロンプトの最適化、LLM のメモリ、モデルの選択、プランナー、エージェントの個性は、上位のハーネスに属します。そのため、MELRA の実行経路がモデルを呼び出すことはありません。

できること

エフェクトアダプター

カーネルが契約であり、これらは同梱される実装です。すべてが同じポリシー、承認、予算、検証、レシート、証明書のパイプラインを通ります。これを省略するアダプターは、アダプターとは言えません。

データベース、クラウド、SaaS のアダプターは設計中で、ロードマップに記載されています。現時点では同梱されていません。ユーザーに関するセマンティックメモリー（設定、会話履歴）は、ここではなくハーネスに属します。

意図的に小さくしたツール群

アダプターの前面に 12 個のツールと、永続的なワークフローコントローラーを 1 つ備えています。CLI、両方の SDK、ループバック HTTP、Unix ソケットは、同じ 12 個の操作にアクセスします。このリストはカーネルの契約であり、MCP 固有の API ではありません。

判定では宣言どおりに判定者が記録され、証明書ではレシートに宣言された主体である executedBy の横に記載されます。MCP 経由では、human: の判定者であってもハーネスの申告にすぎません。melra judge からの cli: の判定者だけが、オペレーター用インターフェースを通じたものです。

モデルがすでに知っているツール名を使いたいですか？ MELRA_HARNESS_TOOLS=1 を設定すると、これらに加えて 13 個のツール（read_file、write_file、run_command、browser_click、approve、…）が利用可能になります。別の実行経路が追加されるわけではありません。それぞれが通常のタスクを構築し、同じパイプラインを実行します。通常のツール名を参照してください。

永続性があり、再起動に安全なワークフロー

ワークフローでは、operation、approval、condition、parallel、bounded_loop、 checkpoint、compensation、human_input、delegation ノードを組み合わせます。すべての効果は 引き続きタスクパイプラインを経由します。以下の各 CLI 呼び出しは新しいプロセスとして実行されるため、 デーモンなしで再起動時の永続性を検証できます。

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

どの行の後でもプロセスを停止できます。次のコマンドは同じ MELRA_HOME から再開します。中断された読み取りは再試行される場合がありますが、中断された変更が黙って 繰り返されることはありません。再観測によって確定するか、recovery_required で停止します。

workflow advance と resume は、実行が正常な場合は終了コード 0、承認待ちの場合は 3、--input 待ちの場合は 4、 失敗した場合、partially_complete または cancelled で終了した場合、あるいは復旧が必要な場合は 2 で終了します。workflow plan、pause、suspend は、 実行を計画または停止した場合に終了コード 0 で終了します。完了、キャンセル、失敗した実行の一時停止または中断は拒否されます。workflow inspect は、どの状態でも 終了コード 0 で終了します。workflow cancel は、実行を cancelled にした場合は終了コード 0、すでに完了している実行の場合など、そうならなかった場合は 1 で終了します。 エラーは終了コード 1 です。

エビデンスとベンチマーク

数値は、コミット済みのスクリプトと JSON アーティファクトに基づいており、データセットのハッシュと主張の範囲を明示しています。これらはコンポーネントの測定値であり、MELRA が「最高」であるという主張でも、比較条件の異なるベンチマーク同士を比較できるという主張でもありません。

生のアーティファクト：コアマイクロベンチマーク、 LoCoMo、および GovBench。

リポジトリには、事前登録済みのブラウザーエージェント用ハーネス（MiniWoB-125 と WebArena-Verified Hard-30 の登録済みサブセット）も含まれています。タスク ID、上流リビジョン、 データセットのハッシュは固定されています。スコアはまだ公表していません。固定された分母での全件実行が公表ゲートを通過した後に限り、公表します。MELRA は公式な OSWorld、WebArena、LongMemEval の提出を行っていません。

# 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: 362 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

開発者向け

SDK パッケージ TypeScript @melra/sdk Python melra（型付き、3.11–3.14） 📜 JSON コントラクト @melra/protocol, @melra/receipt-schema どちらの SDK も、ローカルサーバーを起動するか、HTTP または Unix ソケット経由で実行中のサーバーに接続します。 トークンは常に明示的に渡され、オプトインしない限り、リモートホストへの平文 HTTP 接続は拒否されます。

CLI の概要 目的 コマンド ガイド付きセットアップ melra setup このマシンを確認 melra doctor サーバーを起動（stdio / HTTP / socket） melra serve · --http --open · --socket <path> アクティビティを確認 melra tasks · watch · status タスクを1つ実行 melra run --request task.json エージェントが計画したタスクを承認 melra approve <task-id> · ブラウザーの場合：melra console タスクの意味に関する質問に回答 melra judge <task-id> --judgement <id> --verdict yes|no|cannot_tell レシートを調査 melra inspect <task-id> ポリシーをテスト melra policy test --request task.json 適合性を確認 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

実行可能な例では、読み取り専用のシステムタスク、検証済みのファイル書き込み、ターミナルチェック、ブラウザーの調査、スコープ付きメモリ、コンピューター機能の検出、ガバナンスされた API 呼び出し、独立した検証、再起動に対応したワークフローを取り上げています。

ドキュメント

コントリビューション

コード、アダプター、クライアント統合、ベンチマーク用ハーネス、検証述語、ドキュメント、脅威分析を歓迎します。

1. CONTRIBUTING.mdと行動規範をお読みください。
2. DCO に基づいてコミットに署名してください（git commit -s）。
3. プルリクエストを作成する前にpnpm checkを実行してください。リンク、環境変数の表、CHANGELOG の形式もチェックされます。
4. 脆弱性は非公開の脆弱性報告を通じて報告してください。公開課題では報告しないでください。

ライセンス

ソフトウェアとドキュメントはApache License 2.0の下でライセンスされています。公式ロゴとヒーローアートワークはCC BY-ND 4.0の下でライセンスされています。サードパーティのベンチマークデータセットにはそれぞれ独自のライセンスが適用され、このリポジトリには含まれていません。