Roadmap

This document describes the planned evolution of Hercules — a tiny, self-improving AI micro-agent on C# / .NET 10. The goal is not to build one large assistant, but to make the smallest possible autonomous unit that can later be composed into an agent mesh: a network of specialized micro-agents that discover, call, and learn from each other, similar to how microservices form an application architecture.

For the current state of the project, see CHANGELOG-EN.md.
For the mesh architecture concept, see docs/AGENT-MESH-EN.md.

Design constraints for a micro-agent

Every feature on this roadmap is evaluated against these constraints:

Phase 1 — Single autonomous unit (now → Q3 2026)

Goal: prove that one Hercules agent can operate independently, learn from its own traffic, and expose a clean API.

flowchart LR
    User["User / Telegram / Web UI"] -->|request| AgentCore["AgentCore"]
    AgentCore -->|route| Skills["Skills (local)"]
    AgentCore -->|fallback| LLM["LLM provider (external)"]
    AgentCore -->|read/write| Memory["Memory (Markdown/JSON)"]
    AgentCore -->|log| SQLite["SQLite metrics"]
    AgentCore -->|response| User
# Initiative Outcome
1 Core agent loop AgentCore handles a request, routes it to a skill or direct LLM call, updates memory, and logs metrics.
2 Skill lifecycle Skill creation, versioning, improvement, and deletion are fully automated with human-in-the-loop for high-risk changes.
3 Hybrid storage Markdown/JSON for skills and memory + SQLite for logs and metrics; no external dependencies.
4 Multi-provider LLM YandexGPT, Ollama Cloud/Local, LM Studio through Microsoft.Extensions.AI with automatic fallback.
5 Interfaces CLI REPL, Telegram bot, ASP.NET Core Minimal API, Astro web UI.
6 Tests and benchmarks dotnet test ≥ 70 % coverage; dotnet run --benchmark measures skill hit rate, latency, and memory growth.

Deliverable: a standalone micro-agent anyone can run locally.

Phase 2 — Composable skills and tool use (Q4 2026)

Goal: turn skills into portable, self-contained units that can be imported, exported, and chained. This is the foundation for agent templates used in IoT deployments.

# Initiative Outcome
7 Skill package format A skill is a folder with skill.meta.json, skill.prompt.md, skill.tests.json, and optional tool.schema.json.
8 Skill marketplace data/Skills/marketplace/ with import/export CLI commands and a public template repository.
9 Semantic routing SkillRouter ranks skills by query embedding similarity, not just keyword triggers.
10 Tool registry Skills declare tools (HTTP, file-system, shell, database, GPIO/MQTT) loaded from data/Tools/ with allow/deny lists.
11 Agent templates Pre-built skill + memory + tool bundles for vertical scenarios (greenhouse, energy, cold-chain, server closet).

Deliverable: one agent can compose multiple skills and tools internally, and a new vertical deployment starts from a template, not from scratch.

Phase 3 — Inter-agent protocol (Q1 2027)

Goal: make agents talk to each other over a lightweight, language-agnostic protocol.

flowchart LR
    AgentA["Agent A\nmanifest + skills"] -->|intent envelope| Bus["HTTP / gRPC / message bus"]
    Bus -->|intent envelope| AgentB["Agent B\nmanifest + skills"]
    Registry[("Capability registry")] -->|lookup| Bus
# Initiative Outcome
12 Agent manifest Each agent publishes agent.manifest.json: name, version, capabilities, skills, endpoint, auth method.
13 Capability registry A local registry (file or SQLite) lists known agents and what each can do.
14 Inter-agent message format Standard JSON envelope: requestId, sender, intent, payload, replyTo, timeout.
15 Transport options HTTP/gRPC endpoints plus optional message-bus adapter (RabbitMQ, NATS, Azure Service Bus).
16 Discovery mechanisms Static config, mDNS/Bonjour, and registry lookup.

Deliverable: two Hercules agents can discover each other and route a request from one to the other.

Phase 4 — Mesh orchestration (Q2 2027)

Goal: a network of micro-agents behaves like one coherent agent system, with capability-aware routing, bounded delegation, retries, observability, shared learning, and optional distributed backends for larger meshes.

flowchart TD
    User["User request"] --> Router["Mesh router"]
    Router -->|2a. local skill| Local["Local skills"]
    Router -->|2b. forward intent| Peer["Best peer agent"]
    Router -->|2c. fan-out| Peers["Peer A\nPeer B\nPeer C"]
    Peers --> Judge["Verifier / LLM judge"]
    Local --> Response["Typed response"]
    Peer --> Response
    Judge --> Response
    Response --> User
    Eval["Distributed reflection"] --> Skills["Candidate skill versions"]
# Initiative Outcome
17 Mesh router When a local skill is missing, ineligible, or below its confidence threshold, the agent forwards the request to the most suitable trusted peer agent based on capability, policy, health, latency, and expected quality.
18 Fan-out / fan-in A request can be broadcast to several eligible agents under strict concurrency and budget limits; responses are validated against schemas and selected by deterministic rules, voting, or an optional judge model.
19 Retry and circuit breaker Failed peer calls use deadline-aware retries, exponential backoff with jitter, per-peer circuit breakers, and bulkheads. Non-idempotent operations are never retried blindly and require idempotency keys.
20 Distributed reflection Reflection reports include peer-agent performance, routing decisions, failure patterns, and suggest new skills, routing rules, or peer relationships. They create proposals, not unreviewed production changes.
21 Shared memory sync Selected memory facts and skills can be synchronised between trusted agents using explicit namespaces, provenance, conflict-resolution rules, TTL, encryption in transit, and per-field data-classification policy.
22 Verification pipeline High-impact or safety-sensitive answers can be checked by verifier skills, numeric validators, policy enforcers, or independent peer agents before being returned or acted upon.
23 Delegation boundaries The mesh limits hop count, fan-out width, cumulative tool calls, total cost, and elapsed time per request. Agents may decline delegation rather than exceeding their policy or capacity.
24 Human-in-the-loop escalation Ambiguous, low-confidence, destructive, or policy-sensitive operations are escalated with a concise action plan and context for human approval. Execution gates are enforced by code, not by prompts alone.
25 Mesh observability Every local and inter-agent step emits correlated traces, metrics, and structured logs. Mesh traffic, routing decisions, retries, and backing-store interactions are visible and attributable per request and per agent.
26 Mesh backends abstraction IMeshBus, ITaskQueue, and IMeshStateStore interfaces decouple mesh orchestration from concrete backends. A single-host mesh continues to run with in-process queues and SQLite by default.
27 Redis/Valkey coordination backend Optional RESP-compatible in-memory backend (Redis or Valkey) provides working memory, distributed locks, and ephemeral queues for coordination at higher concurrency. Durable truth remains in SQLite/PostgreSQL.
28 NATS / JetStream transport option Optional NATS messaging backbone provides subject-based routing, queue groups for load-balanced agent workers, and JetStream streams for durable, at-least-once delivery and replay when agents disconnect.
29 PostgreSQL shared state backend Optional PostgreSQL-backed state store holds cross-agent workflow state, shared skill registries, evaluation records, and audit logs. Job queues use SKIP LOCKED patterns for moderate-throughput agent execution.
30 Backend profiles and degradation Deployment profiles declare whether the mesh uses only local SQLite, Redis/Valkey, NATS, PostgreSQL, or combinations. If a backend becomes unavailable, agents degrade to local-only mode or stop accepting new delegations according to policy, instead of failing silently.
31 Mesh evaluation suite Reproducible scenarios measure task success, safety denials, routing quality, latency, cost, resilience, and degradation when a peer, tool, backend, or LLM provider fails or becomes slow.

Deliverable: a mesh of 3–5 Hercules agents can safely answer queries that no single agent could answer alone, with bounded cost and explainable delegation. Larger swarms can opt into Redis/Valkey, NATS, and PostgreSQL backends through configuration profiles, without making any external service mandatory for a single local agent.

Phase 5 — IoT/edge fleet and mesh operations (Q3 2027)

Goal: make the mesh production-ready, observable, and governable — including fleets of low-cost edge devices.

# Initiative Outcome
32 Mesh dashboard Web UI shows live agent topology, traffic between agents, per-agent health, and skill usage heatmap.
33 Centralized logging and tracing Every inter-agent call has a traceId; logs can be shipped to OpenTelemetry/Loki/etc.
34 Identity and trust Mutual TLS or API-key trust between agents; per-agent access control lists for skills and memory.
35 Rate limiting and quotas Per-agent and per-skill rate limits; LLM cost budgets across the mesh.
36 Lifecycle management CLI and API to start, stop, update, and rollback agents in the mesh.
37 Edge provisioning SD-card image / Docker image for Raspberry Pi with first-boot Wi-Fi and API-key activation flow.
38 Offline resilience Agent buffers sensor logs and outgoing alerts; syncs with mesh/cloud when connectivity returns.
39 Fleet templates One template per vertical (greenhouse, cold-chain, closet, vending) with validated hardware bill of materials.
40 Security operations Fleet-wide identity rotation, credential revocation, certificate renewal, signed package verification, vulnerability reporting, and security audit export.
41 Configuration and policy rollout Signed, versioned configuration and policy bundles with staged rollout, local validation, expiry, rollback, and last-known-good fallback.
42 Local-first degradation When the cloud LLM, peers, or network are unavailable, the agent follows a configured safe fallback: deterministic rules, local skills, reduced-capability models, queued work, and operator notification.
43 Backup and recovery Encrypted backups cover configuration, skills, selected memory, SQLite data, and device identity; restore procedures are automated and regularly tested.
44 Operational SLOs Every template declares availability, response-time, data-loss, recovery-time, and cost objectives together with alert thresholds and runbooks.

Deliverable: Hercules mesh can be deployed as a set of small services behind a gateway, and as a fleet of Raspberry Pi edge agents, with operational visibility, signed configuration rollouts, encrypted backups, declared SLOs, and graceful degradation when external services are unavailable.

Phase 6 — Performance and high availability hardening (Q4 2027)

Goal: close all critical and high-severity findings from the performance and HA review. Make the agent and mesh safe under concurrent load, production-grade observable, and resilient to partial failures without silent data loss or thread starvation.

flowchart TD
    Req["Concurrent request"] --> AgentCore["AgentCore\nscoped session state"]
    AgentCore -->|async| Storage["SQLite / Memory\nthread-safe, no sync-over-async"]
    AgentCore -->|async| LLM["ResilientLLMClient\nper-call provider/model"]
    AgentCore -->|IHttpClientFactory| Tools["Tools / Mesh transport\nresilience handlers"]
    Req --> Kestrel["Kestrel\nrate limiter + compression"]
    Kestrel --> HealthChecks["Health checks\nSQLite, LLM, mesh, disk"]
    Shutdown["Graceful shutdown"] --> Drain["Drain in-flight\nstop accepting new"]
    Backpressure["Backpressure"] --> Bounded["Bounded channels\nDLQ fixes"]
# Initiative Outcome
45 Critical correctness fixes SQLite access is thread-safe with no sync-over-async wrappers; NATS JetStream messages are properly acked/naked/termed; QuotaService rate-limit buckets are correctly cleaned; outbox synced-state preserves bounded-queue prune logic.
46 High-availability fixes Captive DI dependencies and singleton mutable state are eliminated; ResilientLLMClient carries provider/model per call; all sync-over-async in hot paths and background timers is removed; IHttpClientFactory with standard resilience handlers is used everywhere; real health checks back liveness/readiness probes; graceful shutdown drains in-flight requests; Kestrel limits, framework rate limiter, response compression, and output cache are configured; router health, Redis CAS, Postgres reconnect, and DI registration anti-patterns are fixed.
47 Performance polish Cache stampede is prevented with per-key dedup; eviction is O(log n) with sorted expiry index; ProposalStore is cached with FileSystemWatcher; StringBuilder pooling reduces GC pressure; OTel console exporter is gated, process instrumentation is enabled, histogram buckets are explicit, and retry logging is sampled; bounded channels and DLQ requeue provide backpressure; miscellaneous hardening covers DelegationBoundary TTL, ResilientTransport semaphore trim, CORS defaults, backup passphrase enforcement, SLO real metrics, audit filters, and silent-catch logging.

Deliverable: Hercules agent and mesh handle concurrent load without thread starvation or data corruption, degrade gracefully under partial failures with real health-check visibility, drain in-flight work on shutdown, and are production-observable with correct per-call attribution and sampled logging.

Epic — Hercules Studio (Q1 2028)

Goal: a desktop IDE application (Electron + Vue 3) for managing, configuring, and orchestrating multiple Hercules agents from a single workstation. Studio connects to already-running agents, scans the machine, provides fine-grained configuration, a skill editor with C# file-based apps, a mesh explorer, an agent consensus mode, and a BPMN-like workflow designer.

Full Epic documentation: docs/EPIC_Hercules_Studio/ Backend prerequisites: Phase 8 in backlog

flowchart TD
    Studio["Hercules Studio\nElectron + Vue 3"] -->|REST API\nX-Api-Key| AgentA["Agent A\n:8421"]
    Studio -->|REST API| AgentB["Agent B\n:8422"]
    Studio -->|REST API| AgentC["Agent C\n:8423"]
    AgentA <-->|mesh intent| AgentB
    AgentB <-->|mesh intent| AgentC
    Studio -->|clientId/secret| WFS["hercules-\nworkflow-server"]
    WFS -->|mesh intent| AgentA
    WFS -->|mesh intent| AgentB
    WFS -->|mesh intent| AgentC
# Initiative Outcome
48 Hercules Studio IDE Desktop IDE application: agent scanning, multi-agent management, CheckIn/CheckOut, chat, skill editor with Monaco, mesh explorer, tool/MCP management, fine-grained config, agent consensus, BPMN workflow designer.
49 Backend prerequisites Port migration to 8421, dual API keys (contribute+system), CheckIn/CheckOut protocol, system restart, MCP hot-reload, SkillSdk NuGet, context distillation, Postgres session store, hercules-workflow-server, workflow graph model + executor, DelegatedTask persistence, parent/child tasks, checkpoint persistence.

Deliverable: operators manage multiple Hercules agents from a single IDE, create and push skills with C# file-based apps, configure LLM/mesh/quotas at runtime, convene agent consensus, and design and run multi-agent BPMN workflows.

Long-term vision

Hercules becomes a runtime for agent meshes: tiny, self-improving, single-purpose agents that discover each other, delegate work, share skills, and learn collectively. A mesh can live on one machine, across a LAN, or in the cloud — composed like microservices, but with built-in reasoning, memory, and adaptation.

How to influence the roadmap