MELRA

MELRA

Módulo de Ejecución en Capas para Autonomía Refiable

Tu agente de IA decide qué hacer. MELRA se asegura de que suceda de forma segura, una sola vez y de manera comprobable.

Un núcleo de autonomía de código abierto: la capa por la que pasa cada acción del agente en su camino hacia tus archivos, terminal, navegador, escritorio y APIs. Verifica cada acción contra tus reglas, te pregunta antes de cualquier cosa riesgosa, la ejecuta exactamente una vez, comprueba que realmente funcionó y guarda un recibo. Cualquier agente, cualquier modelo, las mismas garantías.

Funciona con  

Inicio rápido  ·  Cómo funciona  ·  Ver qué está haciendo  ·  Documentación  ·  Discusiones

[!WARNING] MELRA es software alfa. El runtime local está probado de extremo a extremo, pero las APIs pueden cambiar antes de 1.0. Usa un espacio de trabajo aislado, mantén las listas de permitidos de dominios y comandos estrechas, y lee cada aprobación antes de otorgarla.

¿Qué es MELRA?

Los agentes de IA ya no solo hablan. Editan archivos, ejecutan comandos, navegan por sitios web y llaman APIs en tu nombre. Cuatro preguntas vienen con eso, y la mayoría de los agentes las responden de manera diferente, o no las responden en absoluto:

MELRA responde esas preguntas una vez, en un solo lugar, para cada agente. Se sitúa debajo de tu agente, de la misma manera que un sistema operativo se sitúa debajo de tus aplicaciones:

El LLM razona. El harness gestiona el bucle. MELRA posee el ciclo de vida del efecto. Cambia el modelo o el agente el viernes; tus políticas, aprobaciones, credenciales, historial y recibos seguirán ahí el lunes.

Inicio rápido

Necesitas Node.js 22 o más reciente. Un comando configura todo:

npx @melra/cli@alpha setup

En una terminal, setup es un asistente breve. Escribe una política local segura, encuentra las aplicaciones de agente en tu máquina, pregunta cuál debería usar MELRA, y escribe MELRA en el archivo de configuración propio de esa aplicación, conservando todo lo demás (y guardando una .bak primero):

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.

Luego reinicia tu aplicación de agente (Claude Code te pedirá aprobar el servidor de un proyecto una vez) y pídele que haga algo, por ejemplo "usa melra para mostrarme la información del sistema". Eso es todo.

[!CAUTION] El paquete npm sin ámbito melra y el paquete PyPI melra son proyectos de terceros no relacionados. Este proyecto publica solo bajo el ámbito npm @melra/: @melra/cli es la CLI. Instala desde ese ámbito, desde este repositorio o desde los releases oficiales.

Funciona con tu agente

MELRA habla el Model Context Protocol, por lo que cualquier cliente MCP puede usarlo. Para estos, melra setup --client <name> escribe la configuración en el formato y ubicación propios del cliente, y melra doctor te dice si cada uno está apuntando a MELRA:

Agente	--client	Configuración que escribe
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 Copilot)	vscode	<project>/.vscode/mcp.json
Gemini CLI	gemini	~/.gemini/settings.json
Windsurf	windsurf	~/.codeium/windsurf/mcp_config.json
Zed	zed	Zed settings.json (comentarios conservados)
🧩 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 (comentarios conservados)
🧪 LM Studio	lmstudio	~/.lmstudio/mcp.json
🔌 Cualquier otra cosa	generic	imprime el bloque estándar mcpServers

¿Construyendo tu propio agente? Usa el SDK de TypeScript o el SDK de Python. Ambos pueden iniciar MELRA o conectarse a uno que ya esté ejecutándose a través de HTTP de bucle local o un socket Unix privado. Para frameworks de agentes, consulta los ejemplos de frameworks: LangChain / LangGraph, el OpenAI Agents SDK, el Vercel AI SDK y los SDK MCP oficiales.

[!NOTE] Un cliente nombrado se marca como verificado solo después de que el paquete publicado, no un checkout del código fuente, pase descubrimiento, planificación, aprobación, ejecución, cancelación y recuperación de recibos en ese cliente. El estado por cliente vive en COMPATIBILITY.md.

Cómo funciona

Cada acción que un agente quiere tomar se llama un efecto: file.write, terminal.run, browser.click, http.request, y así sucesivamente. MELRA hace exactamente nueve cosas a cada efecto, divididas en dos llamadas para que nada se ejecute en el momento de la planificación:

Aquí hay un cambio de principio a fin:

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

Lo que significa el estado final, y qué debería hacer un agente a continuación:

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

Cuando un agente se conecta, MELRA también le envía una guía breve de este bucle (el instructions del servidor MCP), para que un modelo sepa declarar evidencia, leer el estado y nunca reintentar a ciegas un resultado desconocido, sin que nadie haga prompt-engineering.

Ver qué está haciendo

Puedes ver cada acción, su decisión de política, su evidencia y su recibo, desde la terminal o el navegador. Nada aquí puede aprobar o iniciar trabajo, y las frases de aprobación nunca se muestran.

Desde la 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, el navegador y la política, e informa cuáles de tus aplicaciones de agente apuntan a MELRA, con el único comando que corrige cualquier problema.

En el navegador: melra serve --http --open Una vista general, una lista de tareas buscable y flujos de trabajo duraderos con un flujo de eventos en vivo. Funciona en ancho de teléfono y en modo claro y oscuro, y se sirve con una estricta Content-Security-Policy.

Seguro por defecto

Por qué MELRA

Un LLM decide qué hacer. Un arnés ejecuta el bucle que lo lleva allí. Algo aún tiene que decidir si el efecto resultante está permitido, ejecutarlo exactamente una vez, probar que funcionó y sobrevivir a un bloqueo en el medio. Hoy esa maquinaria se reconstruye dentro de cada arnés de agente, y muere con el arnés. MELRA es esa maquinaria, extraída y hecha independiente del agente.

Junto a las dos capas con las que se confunde más a menudo:

Muchos servidores MCP pueden hacer estas cosas; esto no es una afirmación de que ninguno lo haga. La diferencia es que en MELRA son el contrato de ejecución en lugar de una opción por herramienta. El límite está parcialmente enviado: MELRA_MODE=enforced cierra cada puerta que MELRA posee, pero el aislamiento del SO que impide que un arnés llegue al sistema de archivos alrededor del kernel es responsabilidad del operador; las recetas de implementación endurecidas ejecutables aún están por venir (#52).

La prueba de características. Cualquier cosa que aún tendría sentido si la solicitud viniera de software determinista ordinario pertenece a MELRA: autorización, idempotencia, aislamiento de credenciales, recuperación, verificación, historial de efectos. Optimización de indicaciones, memoria del LLM, selección de modelos, un planificador y personalidad de agente pertenecen al arnés de arriba. Por eso nada en la ruta de ejecución de MELRA llama jamás a un modelo.

Qué puede hacer

Adaptadores de efectos

El kernel es el contrato; estas son sus implementaciones enviadas. Cada una pasa por la misma tubería de política, aprobación, presupuesto, verificación, recibo y certificado; un adaptador que la omitiera no sería un adaptador.

Los adaptadores de base de datos, nube y SaaS están diseñados y en la hoja de ruta, no enviados hoy. La memoria semántica sobre el usuario (preferencias, historial de conversación) pertenece al arnés, no aquí.

Una superficie de herramientas deliberadamente pequeña

Once herramientas frente a los adaptadores y un controlador de flujo de trabajo duradero. La CLI, ambos SDK, HTTP de bucle cerrado y el socket Unix llegan a las mismas once operaciones; esta lista es el contrato del kernel, no una API específica de MCP.

¿Prefieres nombres de herramientas que tu modelo ya conoce? Establece MELRA_HARNESS_TOOLS=1 y trece más aparecen junto a estas (read_file, write_file, run_command, browser_click, approve, …). No son una segunda vía: cada una construye una tarea ordinaria y ejecuta la misma tubería. Consulta nombres de herramientas ordinarios.

Flujos de trabajo duraderos y seguros ante reinicios

Los flujos de trabajo componen nodos operation, approval, condition, parallel, bounded_loop, checkpoint, compensation, human_input y delegation, y cada efecto aún viaja a través de la tubería de tareas. Cada llamada CLI a continuación es un proceso nuevo, así que esto ejercita la persistencia ante reinicios sin demonio:

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

Detén el proceso después de cualquier línea y el siguiente comando se reanuda desde el mismo MELRA_HOME. Las lecturas interrumpidas pueden reintentarse; los cambios interrumpidos nunca se repiten silenciosamente. Se resuelven mediante reobservación, o se estacionan en recovery_required.

Evidencia y benchmarks

Los números provienen de scripts confirmados y artefactos JSON, con hashes de conjuntos de datos y límites de afirmaciones. Son mediciones de componentes, no una afirmación de que MELRA sea "el mejor" ni de que los benchmarks no comparables sean comparables.

Artefactos crudos: microbenchmarks del núcleo, LoCoMo y GovBench.

El repositorio también contiene un harness de agente de navegador pre-registrado (MiniWoB-125 y el subconjunto registrado WebArena-Verified Hard-30) cuyos IDs de tarea, revisiones ascendentes y hashes de conjuntos de datos están congelados. Su puntuación aún no se afirma: se publicará solo después de que una ejecución completa de denominador fijo pase la puerta de publicación. MELRA no ha ejecutado una presentación oficial de OSWorld, WebArena o 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 desarrolladores

SDKs Paquete TypeScript @melra/sdk Python melra (tipado, 3.11–3.14) 📜 Contratos JSON @melra/protocol, @melra/receipt-schema Ambos SDKs inician un servidor local o se conectan a uno en ejecución a través de HTTP o un socket Unix. El token siempre se pasa explícitamente, y HTTP plano a un host remoto se rechaza a menos que optes por ello.

CLI de un vistazo Objetivo Comando Configuración guiada melra setup Verificar esta máquina melra doctor Servir (stdio / HTTP / socket) melra serve · --http --open · --socket <path> Ver actividad melra tasks · watch · status Ejecutar una tarea melra run --request task.json Aprobar una tarea que un agente planeó melra approve <task-id> Inspeccionar un recibo melra inspect <task-id> Probar una política melra policy test --request task.json Verificar conformidad 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

Los ejemplos ejecutables cubren una tarea de sistema de solo lectura, una escritura de archivo verificada, una verificación de terminal, inspección de navegador, memoria con alcance, descubrimiento de capacidades de computadora, una llamada API gobernada, verificación independiente y un flujo de trabajo seguro ante reinicios.

Documentación

Contribución

Código, adaptadores, integraciones de clientes, harnesses de benchmarks, predicados de verificación, documentación y análisis de amenazas son todos bienvenidos.

1. Lee CONTRIBUTING.md y el Código de Conducta.
2. Firma tus commits bajo el DCO (git commit -s).
3. Ejecuta pnpm check antes de abrir una solicitud de extracción; también verifica enlaces, la tabla de variables de entorno y la forma del CHANGELOG.
4. Reporta vulnerabilidades a través de informe de vulnerabilidades privado, nunca en un issue público.

Licencia

El software y la documentación están licenciados bajo la Apache License 2.0. El logotipo oficial y las ilustraciones principales están licenciados bajo CC BY-ND 4.0. Los conjuntos de datos de benchmarks de terceros mantienen sus propias licencias y no se incluyen en este repositorio.