MELRA

MELRA

Módulo de Execução em Layer para Robusta Autonomia

Seu agente de IA decide o que fazer. A MELRA garante que isso aconteça com segurança, exatamente uma vez e de forma comprovável.

Um kernel de autonomia de código aberto: a camada pela qual toda ação do agente passa a caminho de seus arquivos, terminal, navegador, desktop e APIs. Ela verifica cada ação contra suas regras, pede sua aprovação antes de qualquer coisa arriscada, executa exatamente uma vez, confirma que realmente funcionou e mantém um comprovante. Qualquer agente, qualquer modelo, as mesmas garantias.

Funciona com  

Início rápido  ·  Como funciona  ·  Veja o que está fazendo  ·  Documentação  ·  Discussões

[!WARNING] A MELRA é um software alfa. O runtime local é testado de ponta a ponta, mas as APIs podem mudar antes do 1.0. Use um workspace isolado, mantenha as listas de permissões de domínio e comandos restritas e leia cada aprovação antes de concedê-la.

O que é a MELRA?

Os agentes de IA não apenas conversam mais. Eles editam arquivos, executam comandos, navegam por sites e chamam APIs em seu nome. Quatro perguntas vêm com isso, e a maioria dos agentes as responde de forma diferente, ou nem responde:

A MELRA responde a essas perguntas uma vez, em um só lugar, para todos os agentes. Ela fica abaixo do seu agente, da mesma forma que um sistema operacional fica abaixo dos seus aplicativos:

O LLM raciocina. O harness gerencia o loop. A MELRA controla o ciclo de vida do efeito. Troque o modelo ou o agente na sexta-feira; suas políticas, aprovações, credenciais, histórico e comprovantes continuarão lá na segunda-feira.

Início rápido

Você precisa do Node.js 22 ou mais recente. Um único comando configura tudo:

npx @melra/cli@alpha setup

Em um terminal, setup é um assistente curto. Ele escreve uma política local segura, encontra os aplicativos de agente na sua máquina, pergunta qual deve usar a MELRA e a escreve no arquivo de configuração do próprio aplicativo, preservando todo o resto (e salvando um .bak primeiro):

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]

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

Em seguida, reinicie o aplicativo do seu agente (o Claude Code pede que você aprove o servidor de um projeto uma vez) e peça para ele fazer algo, por exemplo "use melra para mostrar as informações do sistema". É isso.

[!CAUTION] O pacote npm sem escopo melra e o pacote PyPI melra são projetos de terceiros não relacionados. Este projeto publica apenas sob o escopo npm @melra/: @melra/cli é a CLI. Instale a partir desse escopo, deste repositório ou das releases oficiais.

Funciona com seu agente

A MELRA fala o Model Context Protocol, então qualquer cliente MCP pode usá-la. Para estes, melra setup --client <name> escreve a configuração no formato e local do próprio cliente, e melra doctor informa se cada um está apontando para a MELRA:

Agente	--client	Configuração que ele escreve
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 (modo agente do Copilot)	vscode	<project>/.vscode/mcp.json
Gemini CLI	gemini	~/.gemini/settings.json
Windsurf	windsurf	~/.codeium/windsurf/mcp_config.json
Zed	zed	Zed settings.json (comentários preservados)
🧩 Cline	cline	Cline's 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 (comentários preservados)
🧪 LM Studio	lmstudio	~/.lmstudio/mcp.json
🔌 Qualquer outra coisa	generic	imprime o bloco mcpServers padrão

Construindo seu próprio agente? Use o TypeScript SDK ou o Python SDK. Ambos podem iniciar a MELRA ou conectar-se a uma já em execução via HTTP loopback ou um socket Unix privado. Para frameworks de agentes, veja os exemplos de frameworks: LangChain / LangGraph, o OpenAI Agents SDK, o Vercel AI SDK e os SDKs MCP oficiais.

[!NOTE] Um cliente nomeado é marcado como verificado apenas depois que o pacote publicado, não um checkout do código-fonte, passa por descoberta, planejamento, aprovação, execução, cancelamento e recuperação de comprovante nesse cliente. O status por cliente está em COMPATIBILITY.md.

Como funciona

Toda ação que um agente deseja realizar é chamada de efeito: file.write, terminal.run, browser.click, http.request e assim por diante. A MELRA faz exatamente nove coisas com cada efeito, divididas em duas chamadas para que nada seja executado no momento do planejamento:

Aqui está uma alteração do início ao fim:

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

O que o status final significa e o que um agente deve fazer em seguida:

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

Quando um agente se conecta, a MELRA também envia a ele um guia curto sobre esse loop (o instructions do servidor MCP), para que um modelo saiba declarar evidências, ler o status e nunca tentar novamente cegamente um resultado desconhecido, sem que ninguém precise fazer engenharia de prompt.

Veja o que está fazendo

Você pode ver cada ação, sua decisão de política, sua evidência e seu comprovante, a partir do terminal ou do navegador. Nada aqui pode aprovar ou iniciar trabalho, e as frases de aprovação nunca são exibidas.

No terminal $ melra status MELRA 0.3.0-alpha.12 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 verifica Node, SQLite, o navegador e a política, e informa quais dos seus aplicativos de agente apontam para a MELRA, com o único comando que corrige qualquer problema.

No navegador: melra serve --http --open Uma visão geral, uma lista de tarefas pesquisável e fluxos de trabalho duráveis com um stream de eventos ao vivo. Funciona em largura de celular e em claro e escuro, e é servido com uma Content-Security-Policy estrita.

Seguro por padrão

Por que MELRA

Um LLM decide o que fazer. Um harness executa o loop que o leva até lá. Algo ainda precisa decidir se o efeito resultante é permitido, executá-lo exatamente uma vez, provar que funcionou e sobreviver a uma falha no meio. Hoje essa maquinaria é reconstruída dentro de cada harness de agente, e ela morre com o harness. O MELRA é essa maquinaria, extraída e tornada independente de agente.

Ao lado das duas camadas com as quais é mais frequentemente confundido:

Muitos servidores MCP podem fazer essas coisas; isto não é uma afirmação de que nenhum deles faz. A diferença é que no MELRA elas são o contrato de execução, em vez de uma opção por ferramenta. O limite é parcialmente entregue: MELRA_MODE=enforced fecha todas as portas que o MELRA possui, mas o isolamento do SO que impede um harness de alcançar o sistema de arquivos ao redor do kernel é responsabilidade do operador; receitas de implantação endurecidas executáveis ainda estão por vir (#52).

O teste de recurso. Qualquer coisa que ainda faria sentido se a solicitação viesse de software determinístico comum pertence ao MELRA: autorização, idempotência, isolamento de credenciais, recuperação, verificação, histórico de efeitos. Otimização de prompt, memória de LLM, seleção de modelo, um planejador e personalidade de agente pertencem ao harness acima. É por isso que nada no caminho de execução do MELRA jamais chama um modelo.

O que ele pode fazer

Adaptadores de efeito

O kernel é o contrato; estas são suas implementações entregues. Cada uma passa pelo mesmo pipeline de política, aprovação, orçamento, verificação, recibo e certificado; um adaptador que o pulasse não seria um adaptador.

Adaptadores de banco de dados, nuvem e SaaS estão projetados e no roadmap, não entregues hoje. Memória semântica sobre o usuário (preferências, histórico de conversa) pertence ao harness, não aqui.

Uma superfície de ferramentas deliberadamente pequena

Onze ferramentas na frente dos adaptadores e um controlador de workflow durável. A CLI, ambos os SDKs, HTTP em loopback e o socket Unix alcançam as mesmas onze operações; esta lista é o contrato do kernel, não uma API específica de MCP.

Prefere nomes de ferramentas que seu modelo já conhece? Defina MELRA_HARNESS_TOOLS=1 e mais treze aparecem ao lado destas (read_file, write_file, run_command, browser_click, approve, …). Elas não são um segundo caminho: cada uma constrói uma tarefa comum e executa o mesmo pipeline. Veja nomes de ferramentas comuns.

Workflows duráveis e seguros contra reinicialização

Workflows compõem nós operation, approval, condition, parallel, bounded_loop, checkpoint, compensation, human_input e delegation, e todo efeito ainda viaja pelo pipeline de tarefas. Cada chamada de CLI abaixo é um novo processo, então isto exercita a persistência de reinicialização sem 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
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=7   phrase="APPROVE <digest prefix>"
running            stateVersion=10  write=verified_complete
verified_complete  stateVersion=14  checkpoint=verified_complete

Pare o processo após qualquer linha e o próximo comando retoma do mesmo MELRA_HOME. Leituras interrompidas podem tentar novamente; mudanças interrompidas nunca são silenciosamente repetidas. Elas são resolvidas por re-observação, ou estacionam em recovery_required.

Evidência e benchmarks

Os números vêm de scripts commitados e artefatos JSON, com hashes de conjuntos de dados e limites de reivindicações. Eles são medições de componentes, não uma afirmação de que o MELRA é "o melhor" ou que benchmarks diferentes são comparáveis.

Artefatos brutos: microbenchmarks do núcleo, LoCoMo e GovBench.

O repositório também contém um harness de agente de navegador pré-registrado (MiniWoB-125 e o subconjunto registrado WebArena-Verified Hard-30) cujos IDs de tarefa, revisões upstream e hashes de conjuntos de dados estão congelados. Sua pontuação ainda não é reivindicada: será publicada apenas após uma execução completa de denominador fixo passar pelo portão de publicação. O MELRA não executou uma submissão oficial OSWorld, WebArena ou 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

Para desenvolvedores

SDKs Pacote TypeScript @melra/sdk Python melra (tipado, 3.11–3.14) 📜 Contratos JSON @melra/protocol, @melra/receipt-schema Ambos os SDKs iniciam um servidor local ou conectam-se a um servidor em execução via HTTP ou socket Unix. O token é sempre passado explicitamente, e HTTP simples para um host remoto é recusado a menos que você opte por isso.

CLI em resumo Objetivo Comando Configuração guiada melra setup Verificar esta máquina melra doctor Servir (stdio / HTTP / socket) melra serve · --http --open · --socket <path> Ver atividade melra tasks · watch · status Executar uma tarefa melra run --request task.json Aprovar uma tarefa planejada por um agente melra approve <task-id> Inspecionar um recibo melra inspect <task-id> Testar uma política melra policy test --request task.json Verificar conformidade 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

Exemplos executáveis cobrem uma tarefa de sistema somente leitura, uma escrita de arquivo verificada, uma verificação de terminal, inspeção de navegador, memória com escopo, descoberta de capacidade de computador, uma chamada de API governada, verificação independente e um fluxo de trabalho seguro contra reinicializações.

Documentação

Contribuindo

Código, adaptadores, integrações de clientes, harnesses de benchmark, predicados de verificador, documentação e análise de ameaças são todos bem-vindos.

1. Leia CONTRIBUTING.md e o Código de Conduta.
2. Assine seus commits sob o DCO (git commit -s).
3. Execute pnpm check antes de abrir um pull request; ele também verifica links, a tabela de variáveis de ambiente e a forma do CHANGELOG.
4. Reporte vulnerabilidades através do relatório privado de vulnerabilidades, nunca em uma issue pública.

Licença

Software e documentação são licenciados sob a Apache License 2.0. O logotipo oficial e a arte de destaque são licenciados sob CC BY-ND 4.0. Conjuntos de dados de benchmarks de terceiros mantêm suas próprias licenças e não estão incluídos neste repositório.