MAREF — Agent Governance Operating System

Multi-Agent Recursive Evolution Framework

The only open-source framework that treats agent governance as a first-class product, not a security feature. TLA+ formal model checking, 10/10 OWASP Agentic Top 10 risk coverage, and per-agent cryptographic identity — production-ready, Apache 2.0.

Website: maref.cc

Why MAREF?

Most agent frameworks (LangGraph, CrewAI, AutoGen) help you build multi-agent systems. MAREF helps you govern them. MAREF sits between your orchestration layer and your agents, enforcing safety boundaries, trust policies, and runtime guardrails.

Who Uses MAREF?

Star History

Core Capabilities

Governance Layer (World-Leading)

• Three Loop Meta-Patterns — Convergent / Exploratory / Interactive template library (v0.38.0)
• 10-State Gray Code Governance State Machine — Mathematically provable convergence (4-bit, Hamming distance=1)
• TLA+ Formal Verification — 5 model-checked invariants (state reachability, transition determinism, halt absorption, safety gate integrity, red line immutability)
• CircuitBreaker — Auto-lock after 3 consecutive failures + HALT absorb state + 30s cooldown
• Four-Tier Security Decision Tree — Rule→Mode→SafetyGate→User, 97% automation rate
• LoRA/Ontology Dual Drift Detection — KL/JS/Hellinger triple divergence + human arbitration
• Verifier Cross-Validation — VerifierRegistry + VerifierConsensus (weighted majority / unanimous)
• MAREFLoop Adapter — Connect any Loop to MAREF governance in 5 lines of code
• Zero-Trust Identity — Per-agent Ed25519 cryptographic identity, HMAC-signed decisions
• Verifiable Audit Chain — Ed25519-signed audit log entries aggregated into Merkle trees, cross-organization federated Merkle root via HTTP API, offline-verifiable inclusion proofs (VERIFY.md)

Operations Layer

• Desktop Agent Control — Screenshot→Parse→Keyboard/Mouse→Verify full loop (macOS/Linux/Windows)
• Multi-Agent Task Orchestration — TaskDAG decomposition + 5D agent distribution + Saga compensation transactions
• SubAgent Context Isolation — Git Worktree-style, 96% token savings
• Mobile→Desktop Task Bridging — mDNS discovery + idempotent task queue + SSE push
• Secure Browser Control — Playwright + secure domain whitelist + authenticated session management

Evolution Layer

• Recursive Self-Evolution Engine — C1(Observe)→C2(Optimize)→C3(Converge) triple loop
• Red-Blue Teaming — 200 rounds, 5 phases, attack intensity 2.47→18.98 (7.7×)
• Chaos Engineering — 5 types of LLM fault injection (latency/error/truncation/hallucination/timeout)
• Three-Temperature Memory Framework — Hot/Warm/Cold three-tier memory architecture
• Trust Engine v2 — 5-factor weighting + Goodhart anti-strategic manipulation detection

Ecosystem Layer

• A2A/MCP Dual Protocol — A2A v0.3 + MCP 6 transports
• Cross-Framework Adapters — AutoGen/CrewAI/LangGraph/Dify/Coze production-grade
• OpenTelemetry — Prometheus + Grafana + OTLP full-link observability
• Serverless Runtime — Lambda / Cloud Run ready
• TypeScript SDK — @maref/sdk npm package
• National Cryptography — SM2/SM3/SM4-GCM + AI identity certificates

Quick Start

5-Minute Guide

# 1. Install MAREF
pip install maref

# 2. Run environment diagnostics (15 checks)
python scripts/check_desktop_env.py

# 3. Launch desktop agent demo (safe dry-run mode)
maref desktop demo

# 4. Start Sidecar service
maref serve --port 8000

# 5. Open GUI
open http://localhost:8000

Quick Start Examples

Option 1: CLI Mode

# One-click install
pip install maref

# Query governance state
maref status

# Desktop agent demo
maref desktop demo

# Start service
maref serve --port 8000 --gui

Option 2: Python API

from maref_lite.governance import GovernanceOverlay
from maref_lite.state_machine import GovernanceState

overlay = GovernanceOverlay()
overlay._state_machine.transition(GovernanceState.OBSERVE)
overlay._state_machine.transition(GovernanceState.ANALYZE)
print(overlay.get_status())

# --- Loop Engineering (v0.36.0-rc) ---

from maref.loop.convergent import ConvergentLoop
from maref.loop.exploratory import ExploratoryLoop
from maref.loop.interactive import InteractiveLoop
from maref.loop.bridge import LoopGovernanceBridge

async def example():
    loop = ConvergentLoop(
        solve_fn=lambda x: {"score": 0.95, "output": x},
        max_rounds=10,
    )
    bridge = LoopGovernanceBridge()
    result = await bridge.run_governed(loop, "example input")
    print(result.stop_reason, result.rounds_completed)

Option 3: Full Project Example

# Clone repository
git clone https://github.com/maref-org/maref.git
cd maref

# Create virtual environment with uv (recommended)
uv venv
source .venv/bin/activate

# Install dependencies
uv pip install -e ".[all]"

# Run tests
pytest tests/ -v --tb=short

# Launch full demo
python examples/simple_integration_demo.py

FAQ

Architecture

                  MAREF: Agent Governance OS
    ┌─────────────────────────────────────────────────────────┐
    │  Application Layer ─── LangGraph / CrewAI / AutoGen     │
    │              / Anthropic (Orchestration/Control/Dev)     │
    │  ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─  │
    │  Governance Layer ─── MAREF (This Framework)             │
    │             · State Machine · Circuit Breaker            │
    │             · 4-Tier Decision Tree · Identity/Trust      │
    │             · Drift Detection · Formal Verification       │
    │  ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─  │
    │  Communication Layer ─── A2A / MCP (Google/Anthropic)    │
    └─────────────────────────────────────────────────────────┘

Competitive Analysis

Contributors

Latest Release

Health

Metric	Status
CI
Tests	11,416 —
Coverage	36.1% — (target: 85%)
CodeQL
Security
SonarCloud
Python
License
Version

Roadmap

• v0.1.0-v0.20.0: Engineering infrastructure + Formal verification + Sidecar + Drift detection + Chaos engineering + A2A + Identity + Orchestration + Desktop Agent → GA
• Phase Ω (R101-R150): 50 rounds of autonomous recursive evolution full reinforcement → v0.21.0 Final
• v0.30.0-GA: Human-agent collaboration layer + Memory layer + Skill marketplace + National crypto SM2/SM3/SM4-GCM + Technical whitepaper
• v0.35.0-rc: Loop Engineering narrative layer + Three meta-pattern architecture design + Verifier cross-validation + 60%+ module coverage
• v0.36.0-rc: maref.loop module implementation — ConvergentLoop / ExploratoryLoop / InteractiveLoop + LoopGovernanceBridge + TrustBoundary integration
• v0.38.0: Verifiable Audit Chain — Ed25519 audit log signing + Merkle auditor + Federated Merkle aggregation + offline verification CLI + HTTP API (VERIFY.md)
• v1.0: Full recursive evolution stack + Agent credit rating + Four-phase governance model
• v2.0: Meta-agent closure + Carbon-silicon symbiosis + Eight-trigram governance

License

Apache License 2.0 — LICENSE