# Simplicio Agent

> Local-first autonomous agent: Hermes speed plus Rust determinism, gated actions, checkpoints, evidence receipts, MCP, skills, and multi-model freedom.

- **Type:** MCP server
- **Install:** `agentstack add mcp-wesleysimplicio-simplicio-agent`
- **Verified:** Pending review
- **Seller:** [wesleysimplicio](https://agentstack.voostack.com/s/wesleysimplicio)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [wesleysimplicio](https://github.com/wesleysimplicio)
- **Source:** https://github.com/wesleysimplicio/simplicio-agent

## Install

```sh
agentstack add mcp-wesleysimplicio-simplicio-agent
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

Simplicio Agent

Simplicio speed. Simplicio determinism. Verified delivery.

  The local-first autonomous agent that reasons broadly, executes through a Rust control plane,
  gates every consequential action, and proves the work before it says “done”.

  
  
  
  

  Why Simplicio ·
  vs Hermes ·
  Architecture ·
  Install ·
  Star History

  🌍 Languages
  🇬🇧 English |
  🇧🇷 Português |
  🇪🇸 Español |
  🇫🇷 Français |
  🇩🇪 Deutsch |
  🇮🇹 Italiano |
  🇯🇵 日本語 |
  🇰🇷 한국어 |
  🇨🇳 简体中文 |
  🇷🇺 Русский |
  🇵🇱 Polski |
  🇹🇷 Türkçe |
  🇳🇱 Nederlands |
  🇮🇳 हिन्दी |
  🇸🇦 العربية

---

## Why Simplicio

Most agents optimize the conversation. Simplicio optimizes the **entire delivery path**.

| Pillar | What Simplicio adds | Why it matters |
|---|---|---|
| ⚡ **Speed** | Streaming, fast JSON/serde paths, lazy schemas, warm daemon, deterministic routing, token-aware working set | Less waiting and less context waste |
| 🛡️ **Determinism** | Compiled Rust runtime, action gate, mechanical edits, checkpoints and undo | The model proposes; the runtime controls effects |
| ✅ **Proof** | HBP evidence chain, watcher recomputation, receipts, progressive validation and delivery gates | “Done” becomes auditable evidence, not a sentence |
| 🧠 **Memory** | Project guardian, runtime guardian, durable attempts, skill memory and local retrieval | The agent reuses what worked and avoids oscillation |
| 🌐 **Reach** | CLI, MCP, desktop, messaging gateways, plugins, skills and model/provider freedom | One governed agent across the surfaces you already use |
| 🏠 **Ownership** | Local-first execution, local model ladder and user-owned state | Your machine, your data, your rules |

```mermaid
flowchart LR
    A["Intent"] --> B["Map + retrieve"]
    B --> C["Reason + plan"]
    C --> D{"Action gate"}
    D -->|authorized| E["Deterministic execution"]
    D -->|blocked| C
    E --> F["Validate"]
    F --> G{"Watcher recomputes"}
    G -->|mismatch| H["Checkpoint / correct"]
    H --> C
    G -->|verified| I["Receipt + delivery"]
```

## Hermes → Simplicio Agent

  

Simplicio Agent is an independent, public fork of [NousResearch/hermes-agent](https://github.com/NousResearch/hermes-agent). It keeps the upstream strengths—broad tools, provider choice, skills, messaging, learning and fast interaction—then evolves the execution model around the Simplicio Runtime.

This is **inheritance plus evolution**: Hermes remains the origin and receives attribution; Simplicio is the product identity, control plane and delivery contract.

```mermaid
flowchart LR
    H["Hermes Agent foundationtools · providers · skills · gateways"]
    T["Turbo layerstreaming · hot paths · warm daemon · token economy"]
    R["Simplicio RuntimeRust gate · checkpoints · receipts · deterministic edit"]
    A["Simplicio Agentfast · governed · reversible · verifiable"]
    H --> T --> A
    R --> A
```

## Simplicio vs official Hermes Agent

Comparison snapshot: **15 July 2026**, against the public `main` branch of [official Hermes Agent](https://github.com/NousResearch/hermes-agent). “Simplicio advantage” means a capability present and documented in this repository; it does not imply that Hermes is weak or unsuitable for its own goals.

### Measured shared hot paths

Reproduce with `python3 scripts/benchmark_vs_upstream.py --upstream ../hermes-agent`. Methodology and limits are documented in [`docs/performance.md`](docs/performance.md).

| Shared probe | Simplicio Agent | Official Hermes | Measured gain |
|---|---:|---:|---:|
| JSON encode, tool result | 2.8 µs | 33.1 µs | **12.0×** |
| JSON decode, tool args | 0.6 µs | 1.8 µs | **3.1×** |
| Canonicalize tool args | 1.2 µs | 5.2 µs | **4.5×** |
| Token estimate, 200 messages | 634 µs | 677 µs | **1.07×** |
| CLI cold import | 66.4 ms | 117.6 ms | **1.77×** |

> These are focused microbenchmarks captured on Linux/Python 3.11, not a claim that every end-to-end task is 12× faster. Run the benchmark on your hardware.

### Difference-by-difference

| Area | Official Hermes Agent | Simplicio Agent advantage |
|---|---|---|
| Product core | Python agent runtime | Hermes-derived agent fused with the compiled Simplicio Rust control plane |
| Canonical CLI | `hermes` | `simplicio-agent`; `hermes` remains a deprecated compatibility alias |
| Effect control | Tool/runtime policies | Unified mutation classification and fail-closed action gate |
| Mechanical changes | Model/tool-written operations | Zero-token deterministic edit plans when the change is mechanical |
| Recovery | Task-specific retries | Checkpoints, undo paths and transaction-aware recovery |
| Completion | Agent decides it is finished | Evidence-gated loop plus independent watcher recomputation |
| Evidence | Logs and tool results | Typed receipts plus append-only HBP evidence lineage |
| Performance posture | General-purpose defaults | Fast installers enable serde, fast JSON and uvloop by default |
| JSON/serialization | Standard shared path | `orjson`/`msgspec` fast path with pure-Python fallback |
| Native hot paths | Python-first | Optional PyO3 hot path plus compiled Rust execution kernel |
| Startup | Standard CLI lifecycle | Lazy boot path plus optional warm daemon |
| Context economy | Compression and memory | Working-set LRU, cold references, TF-IDF scoring, token cache and prefetch |
| Tool output economy | Normal tool payloads | TOON boundary and token-saver compaction with telemetry |
| Routing | Model/tool routing | Deterministic no-LLM route first, then local/remote escalation ladder |
| Repository context | Agent reads tools/files | Runtime map + mapper + zero-copy orientation pack |
| Runtime knowledge | Loaded instructions | Helo guardian ranks runtime capabilities and mutation paths |
| Project knowledge | Conversation/project memory | Isa guardian ranks project docs, examples and local memory |
| External discovery | Web tools when selected | Levi is explicitly gated: external lookup only after local guardians miss |
| Parallel work | Subagents and tool concurrency | Governed fan-out, leases, worktree isolation, backpressure and receipts |
| Orchestration | Agent loop | Bounded `simplicio-loop` with converge/drain modes and anti-oscillation journal |
| Self-modification | General development workflow | Explicit self-mutation isolation, promotion and handoff contract |
| Validation | Tests selected by workflow | Progressive validation, watcher gate, DoD and delivery certificate surfaces |
| Observability | Logs, sessions and integrations | Stage timers, token savings, lane readiness, receipts and runtime status |
| Local execution | Supports local and remote models | Local-first decision ladder with governed shared inference pool |
| Contracts | Tool/API conventions | Versioned `simplicio.* /v1` envelopes across task, progress, effects and evidence |
| Safety at scale | Host/tool safeguards | CPU, disk, queue, timeout, iteration and “never explode” caps |
| Compatibility | Upstream ecosystem | Keeps upstream capabilities while migrating toward native Simplicio identity |

## Verified execution, not performative autonomy

  

Every consequential run follows a bounded path. Authorization is separated from possibility; evidence is part of execution; rollback is designed in rather than improvised afterward.

```mermaid
sequenceDiagram
    participant U as User
    participant A as Simplicio Agent
    participant R as Rust Runtime
    participant W as Watcher
    participant E as Evidence Ledger
    U->>A: Goal + constraints
    A->>R: Typed task and proposed effects
    R->>R: Gate + checkpoint
    R-->>A: Authorized receipts
    A->>R: Execute + validate
    R->>W: Claimed result
    W->>W: Recompute independently
    alt evidence matches
        W->>E: Append verified receipt
        E-->>U: Auditable delivery
    else mismatch
        W-->>A: Correct or roll back
    end
```

## Architecture

```mermaid
flowchart TB
    subgraph Interfaces["Interfaces"]
      CLI["CLI"]
      MCP["MCP"]
      MSG["Messaging"]
      DESK["Desktop / TUI"]
    end
    subgraph Agent["Simplicio Agent"]
      REASON["Reasoning + provider freedom"]
      SKILLS["Skills + plugins"]
      MEMORY["Isa · Helo · Levi"]
      LOOP["Evidence-gated loop"]
    end
    subgraph Runtime["Simplicio Runtime — Rust"]
      MAP["Map + contracts"]
      GATE["Action gate"]
      EDIT["Mechanical edit"]
      CHECK["Checkpoint / undo"]
      VERIFY["Validate + HBP receipts"]
    end
    Interfaces --> Agent
    REASON --> LOOP
    SKILLS --> LOOP
    MEMORY --> LOOP
    LOOP --> Runtime
    MAP --> GATE --> EDIT --> CHECK --> VERIFY
```

The narrow waist is intentional: the model reasons and coordinates; the runtime owns deterministic effects, evidence and recovery.

## Install and first run

### Requirements

- Python 3.11 or newer
- Git
- macOS, Linux, WSL2, Termux, or Windows PowerShell

### macOS, Linux, WSL2 and Termux

```bash
curl -fsSL https://simpleti.com.br/simplicio/install.sh | sh
simplicio-agent setup
simplicio-agent doctor
simplicio-agent
```

The installer creates `~/.simplicio_agent/`, installs the compiled Simplicio Runtime, and bootstraps the first-party Python control plane (`simplicio-loop`, `simplicio-mapper`, and `simplicio-dev-cli`) through the `ecosystem` extra. During setup, choose a model provider and add its credential when prompted. `doctor` verifies the CLI, provider configuration, Runtime binding, and neural-memory availability.
### Windows PowerShell

```powershell
irm https://simpleti.com.br/simplicio/install.ps1 | iex
simplicio-agent setup
simplicio-agent doctor
simplicio-agent
```

### From source

```bash
git clone https://github.com/wesleysimplicio/simplicio-agent.git
cd simplicio-agent
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -e ".[fast,ecosystem]"
simplicio-agent setup
simplicio-agent doctor
```

### Direct PyPI control-plane install

```bash
python3 -m pip install --upgrade "simplicio-agent[all,ecosystem]"
curl -fsSL https://raw.githubusercontent.com/wesleysimplicio/simplicio/master/install.sh | sh
simplicio doctor --json
simplicio memory status --json
```

For a local `simplicio-fast` checkout, set `SIMPLICIO_FAST_SOURCE_ROOT` before running the installer; the local compiled kernel is adopted only when `target/release/simplicio` exists.
On Windows, activate the environment with `.venv\\Scripts\\Activate.ps1`.

### First commands

```bash
# Start an interactive Simplicio Agent session
simplicio-agent

# Reconfigure the provider, model, tools, or gateways
simplicio-agent setup

# Diagnose installation and Runtime integration
simplicio-agent doctor

# Inspect the Runtime's live capability contract
simplicio runtime map --for-llm markdown --repo .
```

The `hermes` command and `~/.hermes/` state are supported only as migration compatibility. New installations, documentation, and automation must use `simplicio-agent` and `~/.simplicio_agent/`.

Useful references:

- [`docs/SIMPLICIO_OPERATIONAL_MANUAL.md`](docs/SIMPLICIO_OPERATIONAL_MANUAL.md) — execution and safety model
- [`docs/performance.md`](docs/performance.md) — benchmark methods and reproducible numbers
- [`docs/SIMPLICIO_AGENT_CAPABILITY_CONTRACT.md`](docs/SIMPLICIO_AGENT_CAPABILITY_CONTRACT.md) — capability inventory
- [`docs/architecture/INDEX.md`](docs/architecture/INDEX.md) — architectural decisions
- [`CONTRIBUTING.md`](CONTRIBUTING.md) — contribution guide
- [`SECURITY.md`](SECURITY.md) — security policy

## Star History

  
    
    
    
  

## Lineage, license and community

Simplicio Agent is licensed under the [MIT License](LICENSE) and derives from the excellent work of [Nous Research](https://nousresearch.com) and the [Hermes Agent contributors](https://github.com/NousResearch/hermes-agent/graphs/contributors). See the repository history and license notices for attribution.

- ⭐ Star this repository if verified, local-first autonomy is the direction you want.
- 💬 Join the [Simplicio Discord](https://discord.gg/wM6tr7xVb).
- 🐛 Open an [issue](https://github.com/wesleysimplicio/simplicio-agent/issues) with a reproducible case.
- 🔧 Send a focused PR with tests and evidence.

Simplicio Agent — possibility is cheap; action is gated; completion is proved.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [wesleysimplicio](https://github.com/wesleysimplicio)
- **Source:** [wesleysimplicio/simplicio-agent](https://github.com/wesleysimplicio/simplicio-agent)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-wesleysimplicio-simplicio-agent
- Seller: https://agentstack.voostack.com/s/wesleysimplicio
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.