Hermes Agent — System Architecture

Architectural patterns and design decisions for how Hermes Agent, the vault, CI/CD, credentials, and data pipelines wire together. Running config (URLs, cron times, API keys) lives in the Digital Garden at Hermes Bot Infrastructure.

Design Principles

1. Secrets never enter LLM context — Every credential flows from Bitwarden Secrets Manager (BWS) directly into the subprocess consuming it. The agent never reads bws secret list/get output. This is enforced by a hard rule in the agent personality.
2. Scripts do structured work — Data transformation (formatting markdown, parsing APIs, appending CSVs) happens in deterministic scripts, not LLM reasoning. The agent orchestrates; scripts execute.
3. Silent unless necessary — Cron jobs use no_agent=True when possible. If the data hasn’t changed, stdout is empty and nothing is delivered. No LLM calls, no notifications.
4. Single source of truth per fact — Wiki and Garden do not duplicate each other. The wiki holds patterns and cross-domain knowledge; the garden holds instance-level running config and prose notes.
5. Auto-commit is safe for deterministic writes — Data-ingestion cron jobs (commute, hevy, nutrition) produce deterministic output. Git add + commit + push happens without review. Ambiguous changes (orphan pages, stale drafts) get filed for human review.

Layer Diagram

Users (Telegram, Web UI, Email)
    │
    ▼
Hermes Agent (OpenRouter → deepseek/deepseek-v4-flash)
    │
    ├── Gateway (Telegram systemd service)
    ├── Cron Scheduler (6+ jobs, 3 no_agent)
    ├── Web UI (Cloudflare tunnel + Access auth)
    ├── Webhooks (vault deploy events)
    └── Skills (procedural memory, 40+ installed)
            │
            ▼
        Hermes Vault (GitLab repo)
            ├── Digital Garden (human notes)
            ├── LLM Wiki (agent KB)
            └── CI/CD (Quartz v5 → Cloudflare Pages → riginski.org)

Key Patterns

BWS Credential Wrapper

Git, glab, himalaya — any CLI that needs authentication uses a shell wrapper that injects the secret from BWS at runtime. This keeps credentials out of config files and out of the LLM’s view. Pattern:

# ~/.hermes/scripts/git-with-bws.sh
export GIT_TOKEN=$(bws secret list ... | jq -r '...')
git -c credential.helper='!f() { ... }' "$@"

no_agent Data Pipeline (4 instances)

See cron-data-pipeline for the full pattern. All four share the same architecture:

• Commute tracker (Google Routes API → CSV)
• Hevy workout watchdog (Hevy API → workout notes)
• Nutrition consolidation (daily log → trends)
• Liberty 5 Pro deal watcher (Amazon price check)

Dual Vault Structure

See vault-organization for the full pattern. The vault splits into two collections at the root index page to serve different readers optimally.

Related Garden Notes

• Hermes Bot Infrastructure — running config, URLs, cron times
• Hevy API Integration — hevy.sh wrapper details
• Unified Site Migration Plan — domain/URL architecture

Related Skills

• credential-commands — BWS credential injection pattern
• hevy-workouts — Hevy API integration + workout pipeline
• food-logger — Nutrition tracking + consolidation
• obsidian — Vault conventions, CI/CD, research workflows
• llm-wiki — Wiki schema and ingestion rules