the-nexus/docs/hermes-v2.0-architecture.md

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