# Hermes Agent

AI agent by Nous Research with persistent memory, skills, and messaging gateway. Primary model: Claude Sonnet 4.6 via local sub2api, with Grok 4.20 via grok2api as fallback. Runs on Pop!_OS VM alongside OpenClaw.

## Current Configuration

| Component | Platform | Detail | Status |
|---|---|---|---|
| VM | Pop!_OS 24.04 LTS | `sze@100.78.69.20` | Live |
| Hermes Agent | Installed via official script | Python 3.11 venv | Running |
| Primary model | Claude Sonnet 4.6 | via local sub2api (`http://127.0.0.1:8090/v1`) | Active |
| Fallback | Grok 4.20 Non-Reasoning | via local grok2api (`http://127.0.0.1:8000/v1`) | Active |
| Gateway | systemd user service | hermes-gateway.service | Running |
| Messaging | Not yet configured | WhatsApp/Telegram available | Pending |

## Model Fuel (same as OpenClaw)

| Provider | Endpoint | API Key Env | Model | Role |
|---|---|---|---|---|
| sub2api | `http://127.0.0.1:8090/v1` | `OPENAI_API_KEY` in `.env` | `claude-sonnet-4-6` | Primary |
| grok2api | `http://127.0.0.1:8000/v1` | `GROK2API_KEY` in `.env` | `grok-4.20-0309-non-reasoning` | Fallback |

## Coexistence with OpenClaw

| Service | Unit File | Config Dir | Port | Runtime |
|---|---|---|---|---|
| Hermes | `hermes-gateway.service` | `~/.hermes/` | N/A (no web dashboard) | Python 3.11 |
| OpenClaw | `openclaw-gateway.service` | `~/.openclaw/` | 18789 | Node.js |

Both are systemd user services with linger enabled. They share the same model backends (sub2api, grok2api) but have completely separate configs, sessions, and processes.

## Key Paths (on VM)

| Path | Purpose |
|---|---|
| `~/.hermes/config.yaml` | Main config (model, provider, display, tools) |
| `~/.hermes/.env` | API keys and secrets |
| `~/.hermes/SOUL.md` | Agent personality |
| `~/.hermes/memories/` | Persistent memory files |
| `~/.hermes/skills/` | Bundled + agent-created skills (90 bundled) |
| `~/.hermes/sessions/` | Chat session history |
| `~/.hermes/cron/` | Scheduled jobs |
| `~/.hermes/logs/` | Session logs |
| `~/.hermes/hermes-agent/` | Source code + venv |
| `~/.config/systemd/user/hermes-gateway.service` | Systemd service unit |

## Common Operations

```bash
# SSH into the VM
ssh sze@100.78.69.20

# Gateway management
hermes gateway start
hermes gateway restart
hermes gateway stop
hermes gateway status

# Interactive chat
hermes                    # Classic CLI
hermes --tui              # Modern TUI
hermes chat -q "question" -Q  # One-shot query (quiet mode)

# Configuration
hermes config             # View current config
hermes config edit        # Open config in editor
hermes model              # Interactive model picker
hermes fallback list      # Show fallback chain
hermes doctor             # Diagnose issues

# Model override
hermes chat -m grok-4.20-fast  # Use specific model for session

# Logs
journalctl --user -u hermes-gateway -f

# Update
hermes update
```

## Messaging Setup (pending)

```bash
# WhatsApp (Baileys-based, like OpenClaw)
hermes whatsapp           # Pair via QR code

# Telegram
# Set TELEGRAM_BOT_TOKEN in ~/.hermes/.env
# Set TELEGRAM_ALLOWED_USERS in ~/.hermes/.env
hermes gateway restart

# General setup wizard
hermes gateway setup
```

## Notes

- Hermes and OpenClaw share the same sub2api and grok2api backends but are fully independent services
- Playwright browser tools failed to install (needs sudo for system deps); browser automation unavailable
- ffmpeg not installed (TTS voice messages limited)
- ripgrep installed via cargo but may need PATH update for Hermes to find it
- Sub2api account pool can be temporarily exhausted (503); Hermes will fall through to grok2api fallback
- No messaging platforms configured yet -- run `hermes gateway setup` or configure `.env` manually