Allegro
7897a5530d
Some checks failed
Deploy Nexus / deploy (push) Has been cancelled
Co-authored-by: Allegro <allegro@hermes.local> Co-committed-by: Allegro <allegro@hermes.local>
238 lines
14 KiB
Markdown
238 lines
14 KiB
Markdown
# 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.*
|