1  # Abzu Sovereign Agent: Substrate & Runtime Architecture
  2  
  3  The **Sovereign Agent** (`sovereign-agent`) is the cognitive and persistent substrate of an Abzu node. It bridges P2P mesh primitives with identity-rooted agency, local memory, and financial settlement.
  4  
  5  ## 1. Identity & Key Management
  6  
  7  Sovereign identity is anchored in local cryptographic control, ensuring presence never depends on third-party registrars.
  8  
  9  - **Identity Key**: A long-term Ed25519 keypair stored in the local secure keystore (`~/.abzu/identity.key`).
 10  - **PeerID**: Derived from the public key, used for DHT addressing and mesh routing.
 11  - **Verification**: All commands and messages are signed using `machine_identity()` in `abzu-core`, ensuring every action is cryptographically attributable.
 12  
 13  ## 2. Agent Substrate: Memory & Permanence
 14  
 15  The agent maintains a persistent record of its experiences and state.
 16  
 17  ### Embedded Memory Store (SQLite)
 18  
 19  Abzu includes a lightweight, local-first memory store implemented in `sovereign-agent/src/memory.rs`.
 20  
 21  - **Persistence**: Uses SQLite at `~/.abzu/memory.db`.
 22  - **Custom Location**: Respects the `ABZU_DATA_DIR` environment variable.
 23  - **Memory Types**: Categorizes information into `Concept`, `Task`, `Message`, and `Diary`.
 24  - **Quota Management**: Enforces limits (e.g., 100MB DB size) with auto-pruning.
 25  
 26  ### Permanence Code (Event Logging)
 27  
 28  All critical node events are persisted to a "permanence log" for auditability and external synchronization.
 29  
 30  - **Storage**: Events are appended to `~/.abzu/events.jsonl` (JSON Lines).
 31  - **Event Types**: `Boot`, `ConfigChange`, `PeerConnected`, `PeerDisconnected`, and `PresetActivated`.
 32  - **Agent Consumption**: This log allows external systems (like Mneme) to maintain a mirror of the agent's development and state.
 33  
 34  ## 3. Agent Runtime: `AgentRuntime`
 35  
 36  The `AgentRuntime` acts as a central coordinator, utilizing thread-safe shared state (`RwLock`) to manage model interactions.
 37  
 38  - **Hot-Swappable Providers**: Supports `Ollama`, `Gemini`, `LMStudio`, and `NoneProvider` via a trait-based system.
 39  - **Session Isolation**: Every interaction uses a unique, client-generated `SessionID` to prevent context leakage.
 40  - **Model Presets**: Pre-defined system prompts and temperature settings are hot-swappable via the API.
 41  
 42  ## 4. Coordination Primitives: Agent Circles
 43  
 44  Circles are the primary coordination mechanism for non-hierarchical groups of agents and humans.
 45  
 46  - **Trust Gating**: Membership is managed via the `TrustEngine`, requiring consensus or invites.
 47  - **Shared Agency**: Circles coordinate decentralized inference tasks and manage shared resources.
 48  - **Invitations**: Secure multi-hop invites allow Circles to scale through established trust paths.
 49  
 50  ## 5. Inter-Agent Communication (Jan 2026)
 51  
 52  Two new modules enable local agent-to-agent messaging and self-reflection:
 53  
 54  ### Mailbox (`mailbox.rs`)
 55  
 56  SQLite-backed inter-agent messaging within a single node.
 57  
 58  - **Channels**: Messages are organized by channel (e.g., "stratosphere", "general").
 59  - **Threading**: Supports threaded conversations with `parent_id` and `thread_id`.
 60  - **Acknowledgment**: Recipients mark messages as read via the `ack` endpoint.
 61  - **Priority**: Messages can be `Low`, `Normal`, `High`, or `Urgent`.
 62  
 63  **API Endpoints:**
 64  
 65  - `POST /api/mailbox/send` — Send a message
 66  - `GET /api/mailbox/inbox/:agent_id` — Retrieve inbox
 67  - `POST /api/mailbox/ack/:message_id` — Mark as read
 68  - `GET /api/mailbox/channels` — List active channels
 69  - `GET /api/mailbox/thread/:thread_id` — Get full thread
 70  
 71  ### Dialogue (`dialogue.rs`)
 72  
 73  Agent self-reflection and inner monologue.
 74  
 75  - **Thought Types**: `Observation`, `Reflection`, `Question`, `Resolution`, `Hypothesis`, `Concern`.
 76  - **Depth Tracking**: Nested thoughts track their depth in reasoning chains.
 77  - **Statistics**: Per-agent stats (total thoughts, threads, max depth).
 78  
 79  **API Endpoints:**
 80  
 81  - `POST /api/dialogue/think` — Record a thought
 82  - `GET /api/dialogue/:agent_id` — Recent thoughts
 83  - `GET /api/dialogue/thread/:thread_id` — Get thought chain
 84  - `GET /api/dialogue/stats/:agent_id` — Get statistics
 85  
 86  ## 6. Distributed Mesh Inference & PoI
 87  
 88  To transcend local hardware limits, Abzu supports **Token-Sharded Inference**.
 89  
 90  - **Sharding**: Complex prompts are split into shards and distributed across peer nodes via the DHT.
 91  - **Proof-of-Inference (PoI)**: To ensure work integrity, nodes return tokens with a signed receipt verifying specific model weights and seeds.
 92  - **PoI Auditing**: Requesters can periodically verify bit-accurate parity by sub-sampling peers.
 93  
 94  ## 7. Financial Agency & x402 Settlement
 95  
 96  The infrastructure integrates financial agency directly into the reasoning loop.
 97  
 98  - **Automated Settlement**: Verified PoI receipts trigger micro-payments via the `sovereign-wallet`.
 99  - **x402 Integration**: Mesh payments use the x402 protocol, supporting EVM-based transfers with spending limits.
100  - **Human-in-the-Loop**: High-stakes operations (like large payments or data exports) require manual approval via the Dashboard workstation.