forked from Rockachopa/Timmy-time-dashboard
171 lines
6.0 KiB
Markdown
171 lines
6.0 KiB
Markdown
# Architecture
|
|
|
|
High-level system design of the Hermes/Timmy sovereign AI agent framework.
|
|
|
|
## Layers
|
|
|
|
The system has three layers, top to bottom:
|
|
|
|
```
|
|
SOUL.md (Bitcoin) Immutable moral framework, on-chain inscription
|
|
|
|
|
~/.timmy/ (Sovereign) Identity, specs, papers, evolution tracking
|
|
|
|
|
~/.hermes/ (Operational) Running agent, profiles, skills, cron, sessions
|
|
|
|
|
Fleet (VPS Agents) Ezra, Bezalel, Allegro — remote workers, Gitea, Ansible
|
|
```
|
|
|
|
## Core Components
|
|
|
|
### Agent Loop (run_agent.py)
|
|
|
|
Synchronous, tool-call driven conversation loop. The AIAgent class manages:
|
|
- API call budget with iteration tracking
|
|
- Context compression (automatic when window fills)
|
|
- Checkpoint system (max 50 snapshots)
|
|
- Trajectory saving for training
|
|
- Tool use enforcement for models that describe tools instead of calling them
|
|
|
|
```
|
|
while api_call_count < max_iterations:
|
|
response = LLM(messages, tools)
|
|
if response.tool_calls:
|
|
for call in response.tool_calls:
|
|
result = handle(call)
|
|
messages.append(result)
|
|
else:
|
|
return response.content
|
|
```
|
|
|
|
### Tool System
|
|
|
|
Central singleton registry with 47 static tools across 21+ toolsets, plus dynamic MCP tools.
|
|
|
|
Key mechanisms:
|
|
- **Approval system** — manual/smart/off modes, dangerous command detection
|
|
- **Composite toolsets** — e.g., debugging = terminal + web + file
|
|
- **Subagent delegation** — isolated contexts, max depth 2, max 3 concurrent
|
|
- **Mixture of Agents** — routes through 4+ frontier LLMs, synthesizes responses
|
|
- **Terminal backends** — local, docker, ssh, modal, daytona, singularity
|
|
|
|
### Gateway (Multi-Platform)
|
|
|
|
25 messaging platform adapters in `gateway/run.py` (8,852 lines):
|
|
|
|
telegram, discord, slack, whatsapp, homeassistant, signal, matrix,
|
|
mattermost, dingtalk, feishu, wecom, weixin, sms, email, webhook,
|
|
bluebubbles, + API server
|
|
|
|
Each platform has its own adapter implementing BasePlatformAdapter.
|
|
|
|
### Profiles
|
|
|
|
15+ named agent configurations in `~/.hermes/profiles/<name>/`. Each profile is self-contained:
|
|
- Own config.yaml, SOUL.md, skills/, auth.json
|
|
- Own state.db, memory_store.db, sessions/
|
|
- Isolated credentials and tool access
|
|
|
|
### Cron Integration
|
|
|
|
File-based lock scheduler, gateway calls tick() every 60 seconds.
|
|
- Jobs in `~/.hermes/cron/jobs.json`
|
|
- Supports SILENT_MARKER for no-news suppression
|
|
- Delivery to 15 platforms auto-resolved from origin
|
|
|
|
### Context Compression
|
|
|
|
ContextCompressor with 5-step pipeline:
|
|
1. Prune old tool results (cheap)
|
|
2. Protect head messages (system prompt + first exchange)
|
|
3. Protect tail by token budget (~20K tokens)
|
|
4. Summarize middle turns with auxiliary LLM
|
|
5. Iterative summary updates on subsequent compactions
|
|
|
|
### Auxiliary Client Router
|
|
|
|
Multi-provider resolution chain with automatic fallback:
|
|
- Text: OpenRouter → Nous Portal → Custom → Codex OAuth → Anthropic → Direct providers
|
|
- Vision: Selected provider → OpenRouter → Nous Portal → Codex → Anthropic → Custom
|
|
- Auto-fallback on 402/credit-exhaustion
|
|
|
|
## Data Flow
|
|
|
|
```
|
|
User Message
|
|
|
|
|
v
|
|
Gateway (platform adapter)
|
|
|
|
|
v
|
|
Session Store (SQLite, state.db)
|
|
|
|
|
v
|
|
Agent Loop (run_agent.py)
|
|
|
|
|
+---> Tool Registry (47 tools + MCP)
|
|
| |
|
|
| +---> Terminal (local/docker/ssh/modal)
|
|
| +---> File System
|
|
| +---> Web (search, browse, scrape)
|
|
| +---> Memory (holographic, fact_store)
|
|
| +---> Subagents (delegated, isolated)
|
|
|
|
|
+---> Auxiliary Client (vision, compression, search)
|
|
|
|
|
+---> Context Compressor (if window full)
|
|
|
|
|
v
|
|
Response → Gateway → Platform → User
|
|
```
|
|
|
|
## SOUL.md → Architecture Mapping
|
|
|
|
| SOUL.md Value | Architectural Mechanism |
|
|
|------------------------|------------------------------------------------|
|
|
| Sovereignty | Local-first, no phone-home, forkable code |
|
|
| Service | Tool system, multi-platform gateway |
|
|
| Honesty | Source distinction, refusal over fabrication |
|
|
| Humility | Small-model support, graceful degradation |
|
|
| Courage | Crisis detection, dark content handling |
|
|
| Silence | SILENT_MARKER in cron, brevity defaults |
|
|
| When a Man Is Dying | Crisis protocol integration, 988 routing |
|
|
|
|
## External Dependencies
|
|
|
|
| Component | Dependency | Sovereignty Posture |
|
|
|------------------------|-------------------|------------------------------|
|
|
| LLM Inference | OpenRouter/Nous | Fallback to local Ollama |
|
|
| Vision | Provider chain | Local Gemma 3 available |
|
|
| Messaging | Platform APIs | 25 adapters, no lock-in |
|
|
| Storage | SQLite (local) | Full control |
|
|
| Deployment | Ansible (local) | Sovereign, no cloud CI |
|
|
| Source Control | Gitea (self-host) | Full control |
|
|
|
|
## Novel Contributions
|
|
|
|
1. **On-Chain Soul** — Moral framework inscribed on Bitcoin as immutable conscience. Values as permanent, forkable inscription rather than mutable system prompt.
|
|
|
|
2. **Poka-Yoke Guardrails** — Five lightweight runtime guardrails eliminating entire failure categories (1,400+ failures prevented). Paper-ready for NeurIPS/ICML.
|
|
|
|
3. **Sovereign Fleet Architecture** — Declarative deployment for heterogeneous agent fleets. 45min manual → 47s automated with Ansible pipeline.
|
|
|
|
4. **Source Distinction** — Three-tier provenance tagging (retrieved/generated/mixed) for epistemic honesty in LLM outputs.
|
|
|
|
5. **Refusal Over Fabrication** — Detecting and preventing ungrounded hedging in LLM responses.
|
|
|
|
## What's Undocumented
|
|
|
|
Known documentation gaps (opportunities for future work):
|
|
- Profiles system (creation, isolation guarantees)
|
|
- Skills Hub registry protocol
|
|
- Fleet routing logic
|
|
- Checkpoint system mechanics
|
|
- Per-profile credential isolation
|
|
|
|
---
|
|
|
|
*For detailed code-level analysis, see [hermes-agent-architecture-report.md](hermes-agent-architecture-report.md).*
|
|
|
|
*Sovereignty and service always.*
|