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
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 foundation tools · providers · skills · gateways"]
T["Turbo layer streaming · hot paths · warm daemon · token economy"]
R["Simplicio Runtime Rust gate · checkpoints · receipts · deterministic edit"]
A["Simplicio Agent fast · 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.
### Measured benchmark — Issue #27 (Loop stack + MCP bus)
Task: [issue #27](https://github.com/wesleysimplicio/simplicio-agent/issues/27) — **MCP Server Unificado** (central bus).
**Important:** under STRICT, **simplicio-loop already includes Fast when it is operational** (`SIMPLICIO_FAST_MODE=required` at preflight; operator floor = mapper · **fast** · dev-cli). Fast is **not** a second product stacked on top of loop. The meaningful comparison is **baseline vs the full loop stack** (mapper + fast inside loop), optionally **+ Agent MCP** for #27.
| Lane | Path |
|---|---|
| **baseline** | Host-style full-file reads of MCP sources (no operators) |
| **loop** *(full stack)* | `preflight --strict` + mapper handoff + **simplicio-fast** build/understand/plan/context (the normal STRICT path) |
| **loop + Agent MCP** | same loop stack + MCP tool registry + behavioral AC prove `#27` |
*(An optional mapper-only isolation cut exists in the raw JSON for diagnostics only — it is **not** “loop without fast” in production.)*
**Stack:** `simplicio-loop 3.38.10` · `simplicio-fast 2.0.17` (bound by loop when up) · `mapper 0.26.0` · Runtime `3.5.5` · Agent MCP **19 tools**.
| Metric | baseline | **loop (mapper+fast)** | **loop + Agent MCP** |
|---|---:|---:|---:|
| **Wall time** | 0.20 s | 4.13 s | 5.95 s |
| **Est. tokens** *(context_bytes ÷ 4)* | ~63 916 | **~21 884** | ~22 088 |
| **Token savings vs baseline** | — | **~65.8%** | **~65.4%** |
| **Operator calls** | 0 | 7 | 8 |
| **simplicio-fast calls** *(inside loop path)* | 0 | **5** | **5** |
| **Success** | true | true | true (prove #27 `implemented`, tools≥15) |
**Is simplicio-fast acting?** **Yes — as part of the loop stack** (`fast_calls=5` on the loop lane: doctor, build, understand, plan, context). You do not “turn Fast on again”; loop STRICT already routes the hot path through it when the binary is operational.
**How to read this:**
- Full **loop stack** cuts **~66% est. tokens** vs flooding full MCP sources into context.
- **Wall clock** is higher with operators (cold preflight + snapshot + MCP prove); multi-turn **billed cost** is driven by context/tokens.
- **Agent MCP (#27)** adds ~1 s prove overhead and does **not** re-flood host context; measured **19 tools**, CLI fallback + restart watchdog.
**Step-by-step (loop + MCP wall seconds):** preflight 0.30 · fast_doctor 0.22 · fast_build 0.28 · fast_understand 0.23 · fast_plan 0.22 · fast_context 0.30 · mapper_handoff 0.46 · mcp_tools_and_prove27 1.07.
**Caveats (honest):** estimated tokens = `context_bytes / 4` (not provider-billed). Corpus is the MCP bus source fixture under `docs/evidence/` (reproducible), not a full monorepo cold build.
**Reproduce:**
```bash
python scripts/bench_issue27_loop_fast_mcp.py
```
**Artifacts:** PDF with charts [`docs/evidence/issue27_loop_fast_mcp_bench.pdf`](docs/evidence/issue27_loop_fast_mcp_bench.pdf) · metrics JSON [`docs/evidence/issue27_loop_fast_mcp_metrics.json`](docs/evidence/issue27_loop_fast_mcp_metrics.json).
### Multi-issue lane matrix (5 issues × 5 lanes)
Broader proof on **five issues from oldest → newest** (`#9`, `#96`, `#171`, `#322`, `#711`), same machine (Windows), stack `loop 3.38.10` · `fast 2.0.17` · `mapper 0.26.0` · Agent MCP **19 tools**.
| Lane | Meaning |
|---|---|
| **baseline** | Host full reads of related files (no operators) |
| **loop** | STRICT **full stack** (preflight + mapper + **Fast** — Fast is part of loop) |
| **loop_mcp** | Full loop stack + Agent MCP tool surface |
| **mcp_only** | Agent MCP only (capabilities + CLI fallback; no mapper/fast) |
| **loop_no_fast** | preflight + mapper with `FAST_MODE=off` (**diagnostic**, not production STRICT) |
**Mean estimated-token savings vs baseline (5 issues):**
| Lane | Mean savings | Median | Min | Max | Mean wall | Mean est. tokens | Fast calls | Success |
|---|---:|---:|---:|---:|---:|---:|---:|---:|
| **loop** | **~38.7%** | ~33.9% | **-31%** (#171 small baseline) | **~83%** (#96/#322) | ~49.7 s | ~21.1k | **5** | 100% |
| **loop_mcp** | **~38.5%** | ~33.6% | -32% | ~83% | ~53.2 s | ~21.2k | **5** | 100% |
| **loop_no_fast** | ~63.7% | ~60.9% | ~22% | ~90% | ~17.8 s | ~12.5k | 0 | 100% |
| **mcp_only** | ~99%* | ~99% | ~98% | ~100% | ~11 s | ~0.3k | 0 | 100% |
\* **mcp_only “~99% savings” is not free lunch:** it barely loads survey context (tool metadata only). It does **not** replace mapper/fast orientation. High % here means **low work**, not better delivery.
**Per-issue token savings % vs baseline (primary lanes):**
| Issue | Title (short) | baseline tok | loop % | loop_mcp % | loop_no_fast % | mcp_only %* |
|---|---|---:|---:|---:|---:|---:|
| **#9** | E2E bench Simplicio vs Hermes | ~32k | **~34%** | ~34% | ~61% | ~99% |
| **#96** | Bootstrap canônico PATH | ~125k | **~83%** | ~83% | ~90% | ~99% |
| **#171** | Memória autobiográfica | ~16k | **-31%**† | -32% | ~22% | ~98% |
| **#322** | Namespaces identidade | ~125k | **~83%** | ~83% | ~90% | ~99% |
| **#711** | Incident provider retries | ~28k | **~25%** | ~25% | ~56% | ~97% |
† **Negative savings:** baseline related-file set was already small; full loop still emits Fast understand/plan/context packets (~21k tok). More tokens than a tiny baseline dump, **more orientation value**.
**What this proves**
1. **Fast is acting inside loop** — mean `fast_calls = 5` on every `loop` / `loop_mcp` issue run.
2. **loop_no_fast often “saves more tokens”** because it skips Fast packets — that is **less work**, not a better production path.
3. **loop_mcp ≈ loop on tokens** (+~80 tok / +~3.5 s mean) — MCP is a **capability bus**, not the main compressor.
4. **mcp_only** is cheap on tokens and **does not** survey the repo like loop.
5. Savings **depend on baseline size**: huge related trees (#96/#322) → ~83%; small trees (#171) → loop can exceed baseline tokens while still being the correct STRICT path.
**Reproduce:**
```bash
python scripts/bench_multi_issue_lanes.py
```
**Artifacts:** PDF [`docs/evidence/multi_issue_lanes_bench.pdf`](docs/evidence/multi_issue_lanes_bench.pdf) · JSON [`docs/evidence/multi_issue_lanes_metrics.json`](docs/evidence/multi_issue_lanes_metrics.json) (per-run steps, peak tokens, wall ratios, success rates).
### 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 `~/.simplicio_agent/` 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
## Ecosystem bundle verification
The maintained bundle aligns the Agent control plane with the first-party Simplicio components:
- `simplicio-runtime` is the primary CLI/effect runtime;
- `simplicio-fast-rs` is shipped separately as the Rust acceleration kernel;
- `simplicio-loop`, `simplicio-mapper`, and `simplicio-dev-cli` are installed as adapters;
- `components.json` records the Agent commit, component paths, memory backend, and seed status.
After installing from a checkout, verify the bundle without relying on shell-specific paths:
```bash
simplicio doctor --json
simplicio contracts smoke --json
cat ~/.simplicio/agent/current/components.json
```
On Windows, use `install.ps1` with `SIMPLICIO_AGENT_SOURCE_ROOT` and optionally
`SIMPLICIO_FAST_SOURCE_ROOT`. On Linux/macOS, use `install.sh` with the same
variables. The installers preserve user memory and fail closed when a verified
Runtime artifact or an adapter cannot be resolved.
## 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.
