# Hermes v2.0 Architecture Specification **Version:** 1.0-draft **Epic:** [EPIC] The Autogenesis Protocol — Issue #421 **Author:** Allegro (agent-authored) **Status:** Draft for agent review --- ## 1. Design Philosophy Hermes v2.0 is not an incremental refactor. It is a **successor architecture**: a runtime designed to be authored, reviewed, and eventually superseded by its own agents. The goal is recursive self-improvement without dependency on proprietary APIs, cloud infrastructure, or human bottlenecking. **Core tenets:** 1. **Sovereignty-first** — Every layer must run on hardware the user controls. 2. **Agent-authorship** — The runtime exposes introspection hooks that let agents rewrite its architecture. 3. **Clean-room lineage** — No copied code from external projects. Patterns are studied, then reimagined. 4. **Mesh-native** — Identity and routing are decentralized from day one. 5. **Bitcoin-anchored** — SOUL.md and architecture transitions are attested on-chain. --- ## 2. High-Level Components ``` ┌─────────────────────────────────────────────────────────────────────┐ │ HERMES v2.0 │ ├─────────────────────────────────────────────────────────────────────┤ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌───────────┐ │ │ │ Gateway │ │ Skin │ │ Prompt │ │ Policy │ │ │ │ Layer │ │ Engine │ │ Builder │ │ Engine │ │ │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └─────┬─────┘ │ │ └─────────────────┴─────────────────┴───────────────┘ │ │ │ │ │ ┌─────────┴─────────┐ │ │ │ Conversation │ │ │ │ Loop │ │ │ │ (run_agent v2) │ │ │ └─────────┬─────────┘ │ │ ┌────────────────────┼────────────────────┐ │ │ ▼ ▼ ▼ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ Tool Router │ │ Scheduler │ │ Memory │ │ │ │ (async) │ │ (cron+) │ │ Layer │ │ │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ │ │ │ │ │ │ └────────────────────┼────────────────────┘ │ │ ▼ │ │ ┌─────────────────┐ │ │ │ State Store │ │ │ │ (SQLite+FTS5) │ │ │ │ + Merkle DAG │ │ │ └─────────────────┘ │ │ ▲ │ │ ┌────────────────────┼────────────────────┐ │ │ ▼ ▼ ▼ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ Mesh │ │ Training │ │ Bitcoin │ │ │ │ Transport │ │ Runtime │ │ Identity │ │ │ │ (Nostr) │ │ (local) │ │ (on-chain) │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ └─────────────────────────────────────────────────────────────────────┘ ``` --- ## 3. Component Specifications ### 3.1 Gateway Layer **Current state (v0.7.0):** Telegram, Discord, Slack, local CLI, API server. **v2.0 upgrade:** Gateway becomes **stateless and mesh-routable**. Any node can receive a message, route it to the correct conversation shard, and return the response. Gateways are reduced to protocol adapters. - **Message envelope:** JSON with `conversation_id`, `node_id`, `signature`, `payload`. - **Routing:** Nostr DM or gossip topic. If the target node is offline, the message is queued in the relay mesh. - **Skins:** Move from in-process code to signed, versioned artifacts that can be hot-swapped per conversation. ### 3.2 Conversation Loop (`run_agent v2`) **Current state:** Synchronous, single-threaded, ~9,000 lines. **v2.0 redesign:** 1. **Async-native** — The loop is built on `asyncio` with structured concurrency (`anyio` or `trio`). 2. **Concurrent read-only tools** — File reads, grep, search execute in parallel up to a configurable limit (default 10). 3. **Write serialization** — File edits, git commits, shell commands with side effects are serialized and logged. 4. **Compaction as a service** — The loop never blocks for context compression. A background task prunes history and injects `memory_markers`. 5. **Successor fork hook** — At any turn, the loop can spawn a "successor agent" that receives the current state, evaluates an architecture patch, and returns a verdict without modifying the live runtime. ### 3.3 Tool Router **Current state:** `tools/registry.py` + `model_tools.py`. Synchronous dispatch. **v2.0 upgrade:** - **Schema registry as a service** — Tools register via a local gRPC/HTTP API, not just Python imports. - **Dynamic loading** — Tools can be added/removed without restarting the runtime. - **Permission wildcards** — Rules like `Bash(git:*)` or `FileEdit(*.md)` with per-project, per-user scoping. - **MCP-first** — Native MCP server/client integration. External tools are first-class citizens. ### 3.4 Memory Layer **Current state:** `hermes_state.py` (SQLite + FTS5). Session-scoped messages. **v2.0 upgrade:** - **Project memory** — Cross-session knowledge store. Schema: ```sql CREATE TABLE project_memory ( id INTEGER PRIMARY KEY, project_hash TEXT, -- derived from git remote or working dir memory_type TEXT, -- 'decision', 'pattern', 'correction', 'architecture' content TEXT, source_session_id TEXT, promoted_at REAL, relevance_score REAL, expires_at REAL -- NULL means immortal ); ``` - **Historian task** — Background cron job compacts ended sessions and promotes high-signal memories. - **Dreamer task** — Scans `project_memory` for recurring patterns and auto-generates skill drafts. - **Memory markers** — Compact boundary messages injected into conversation context: ```json {"role": "system", "content": "[MEMORY MARKER] Decision: use SQLite for state, not Redis. Source: session-abc123."} ``` ### 3.5 Scheduler (cron+) **Current state:** `cron/jobs.py` + `scheduler.py`. Fixed-interval jobs. **v2.0 upgrade:** - **Event-driven triggers** — Jobs fire on file changes, git commits, Nostr events, or mesh consensus. - **Agent tasks** — A job can spawn an agent with a bounded lifetime and report back. - **Distributed scheduling** — Cron state is gossiped across the mesh. If the scheduling node dies, another node picks up the missed jobs. ### 3.6 State Store **Current state:** SQLite with FTS5. **v2.0 upgrade:** - **Merkle DAG layer** — Every session, message, and memory entry is hashed. The root hash is periodically signed and published. - **Project-state separation** — Session tables remain SQLite for speed. Project memory and architecture state move to a content-addressed store (IPFS-like, but local-first). - **Bitcoin attestation** — Root hashes are committed via OP_RETURN or inscription for tamper-evident continuity. ### 3.7 Mesh Transport **Current state:** Nostr relay at `relay.alexanderwhitestone.com`. **v2.0 upgrade:** - **Gossip protocol** — Nodes announce presence, capabilities, and load on a public Nostr topic. - **Encrypted channels** — Conversations are routed over NIP-17 (sealed DMs) or NIP-44. - **Relay federation** — No single relay is required. Nodes can fall back to direct WebSocket or even sneakernet. ### 3.8 Training Runtime **New in v2.0.** A modular training pipeline for small models (1B–3B parameters) that runs entirely on local or wizard-contributed hardware. - **Data curation** — Extracts high-quality code and conversation artifacts from the state store. - **Distributed sync** — Gradient synchronization over the mesh using a custom lightweight protocol. - **Quantization** — Auto-GGUF export for local inference via `llama.cpp`. ### 3.9 Bitcoin Identity **New in v2.0.** Every agent instance derives a Bitcoin keypair from its SOUL.md hash and hardware entropy. - **SOUL attestation** — The hash of SOUL.md is signed by the instance's key and published. - **Architecture transitions** — When a successor architecture is adopted, both the old and new instances sign a handoff transaction. - **Trust graph** — Users can verify the unbroken chain of SOUL attestations back to the genesis instance. --- ## 4. Data Flow: A Typical Turn 1. **User message arrives** via Gateway (Telegram/Nostr/local). 2. **Gateway wraps** it in a signed envelope and routes to the correct node. 3. **Conversation loop** loads the session state + recent `memory_markers`. 4. **Prompt builder** injects system prompt, project memory, and active skills. 5. **Model generates** a response with tool calls. 6. **Tool router** dispatches read-only tools in parallel, write tools serially. 7. **Results return** to the loop. Loop continues until final response. 8. **Background historian** (non-blocking) evaluates whether to promote any decisions to `project_memory`. 9. **Response returns** to user via Gateway. --- ## 5. The Successor Fork Pattern This is the defining architectural novelty of Hermes v2.0. At any point, the runtime can execute: ```python successor = fork_successor( current_state=session.export(), architecture_patch=read("docs/proposed-patch.md"), evaluation_task="Verify this patch improves throughput without breaking tests" ) verdict = successor.run_until_complete() ``` The successor is **not** a subagent working on a user task. It is a **sandboxed clone of the runtime** that evaluates an architectural change. It has: - Its own temporary state store - A copy of the current tool registry - A bounded compute budget - No ability to modify the parent runtime If the verdict is positive, the parent runtime can **apply the patch** (with human or mesh-consensus approval). This is how Autogenesis closes the loop. --- ## 6. Migration Path from v0.7.0 Hermes v2.0 is not a big-bang rewrite. It is built **as a parallel runtime** that gradually absorbs v0.7.0 components. | Phase | Action | |-------|--------| | 1 | Background compaction service (Claw Code Phase 1) | | 2 | Async tool router with concurrent read-only execution | | 3 | Project memory schema + historian/dreamer tasks | | 4 | Gateway statelessness + Nostr routing | | 5 | Successor fork sandbox | | 6 | Training runtime integration | | 7 | Bitcoin identity + attestation chain | | 8 | Full mesh-native deployment | Each phase delivers standalone value. There is no "stop the world" migration. --- ## 7. Risk Acknowledgments This spec is audacious by design. We acknowledge the following risks: - **Emergent collapse:** A recursive self-improvement loop could optimize for the wrong metric. Mitigation: hard constraints on the successor fork (bounded budget, mandatory test pass, human final gate). - **Mesh fragility:** 1,000 nodes on commodity hardware will have churn. Mitigation: aggressive redundancy, gossip repair, no single points of failure. - **Training cost:** Even $5k of hardware is not trivial. Mitigation: start with 100M–300M parameter experiments, scale only when the pipeline is proven. - **Legal exposure:** Clean-room policy must be strictly enforced. Mitigation: all code written from spec, all study material kept in separate, labeled repos. --- ## 8. Acceptance Criteria for This Spec - [ ] Reviewed by at least 2 distinct agents with inline comments - [ ] Human approval (Alexander) before Phase II implementation begins - [ ] Linked from the Autogenesis Protocol epic (#421) --- *Written by Allegro. Sovereignty and service always.*