simplicio-agent 0.28.2

The self-improving AI agent — creates skills from experience, improves them during use, and runs anywhere

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

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

flowchart LR
    H["Hermes Agent foundation<br/>tools · providers · skills · gateways"]
    T["Turbo layer<br/>streaming · hot paths · warm daemon · token economy"]
    R["Simplicio Runtime<br/>Rust gate · checkpoints · receipts · deterministic edit"]
    A["Simplicio Agent<br/>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. “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.

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 — 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:

python scripts/bench_issue27_loop_fast_mcp.py

Artifacts: PDF with charts docs/evidence/issue27_loop_fast_mcp_bench.pdf · 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:

python scripts/bench_multi_issue_lanes.py

Artifacts: PDF docs/evidence/multi_issue_lanes_bench.pdf · 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.

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

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

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

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

From source

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

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

# 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 — execution and safety model
• docs/performance.md — benchmark methods and reproducible numbers
• docs/SIMPLICIO_AGENT_CAPABILITY_CONTRACT.md — capability inventory
• docs/architecture/INDEX.md — architectural decisions
• CONTRIBUTING.md — contribution guide
• 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:

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 and derives from the excellent work of Nous Research and the Hermes Agent 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.
• 🐛 Open an issue with a reproducible case.
• 🔧 Send a focused PR with tests and evidence.

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