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:

  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:

  {"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:

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.