114 lines
4.6 KiB
Markdown
114 lines
4.6 KiB
Markdown
# Hermes Gitea & Agent Development Ecosystem Manual
|
|
|
|
**Version 1.0 | June 21, 2026**
|
|
|
|
This manual documents the full Hermes AI Agent Development setup on Gitea. It covers repositories, the role-based multi-agent system, workflows, the critical verified operations protocol, and how to work within it. Maintained as part of your personal-agent-os knowledge base.
|
|
|
|
## 1. Introduction & Philosophy
|
|
|
|
The Hermes ecosystem uses layered repositories for clear separation of concerns:
|
|
|
|
- **core-planning (Ty_Tech/core-planning):** Read-only strategic planning. High-level decisions, project charters, architecture. This is the single source of truth for "what we're doing and why."
|
|
- **personal-agent-os (Tony_tech/personal-agent-os):** Active workspace. Knowledge base, projects, automation patterns, agent config. This is where Leonard builds.
|
|
- **hermes-agent (Tony_tech/hermes-agent):** Hermes installation, config, skills, plugins. Local agent infrastructure.
|
|
- **thornhill-website (Tony_tech/thornhill-website):** Production website for Thornhill Construction.
|
|
- **veripath (Tony_tech/veripath):** Legal/verification projects.
|
|
|
|
## 2. Multi-Agent System
|
|
|
|
### Roles
|
|
- **Leonard:** VPS agent (primary builder). Runs on VPS, has access to `personal-agent-os`, VPS tools, and SSH tunnels.
|
|
- **Jimmy:** Local agent (primary executor). Runs on laptop, handles local tasks, coordinates with Leonard.
|
|
- **Charlie:** Voice/creative agent. Handles TTS, voice workflows, creative content.
|
|
|
|
### Communication
|
|
- **Agent discussion board:** `00_system/agent-discussion.md` for cross-agent coordination
|
|
- **Agent comms inbox/outbox:** `agent-comms/` folder in `personal-agent-os` for structured messaging
|
|
- **Sync bot:** Automated bidirectional sync between agents via Gitea hooks
|
|
|
|
### Rules
|
|
- Leonard builds alone by default
|
|
- MoA only when Leonard flags a real design fork
|
|
- Jimmy handles local PC tasks, voice, TTS
|
|
- All agents share the same Obsidian vault for context
|
|
|
|
## 3. Verified Operations Protocol
|
|
|
|
### Model Switching
|
|
1. Check what's running: `hermes status`
|
|
2. Switch model: `hermes model <model-name>` (session-scoped)
|
|
3. Persist switch: `hermes config set model.default <model-id>`
|
|
4. Add fallback: `hermes fallback add <model-id>`
|
|
5. Verify: `hermes status` should show new model as primary
|
|
|
|
### Cron Jobs
|
|
1. List jobs: `hermes cron list`
|
|
2. Create: `hermes cron create --name <name> --prompt "<prompt>" --schedule "<cron>"`
|
|
3. Update: `hermes cron update --id <id> --prompt "<new-prompt>"`
|
|
4. Run: `hermes cron run --id <id>`
|
|
5. Check: `hermes cron log --id <id>`
|
|
|
|
### Git Sync
|
|
1. Local changes → `git add -A && git commit -m "update" && git push`
|
|
2. Vault sync cron runs every 6h: `vault-sync` job
|
|
3. Never commit secrets (`.gitignore` protects `ORK.txt`, `VPS.txt`)
|
|
|
|
## 4. Local Setup
|
|
|
|
### Models
|
|
- **LFM2.5-2.6B:** Primary local model. Runs on port 1920. ~2.1GB VRAM.
|
|
- **FreeToken:** Manual launch only. `ft.exe serve --model-path C:/models/gpt-oss-20b --port 1919`
|
|
- **Brother 5090:** Tailnet fallback. Qwen3.6 27B MTP at 100.64.0.2:8084
|
|
|
|
### Hermes Desktop
|
|
- Auto-starts via `Hermes Desktop.lnk` in Windows Startup
|
|
- Built locally with `hermes desktop --build-only`
|
|
- Bot mode built-in, profiles visible as bots
|
|
|
|
### Voice
|
|
- Wake word: "hey Jimmy" via sherpa
|
|
- Edge TTS AriaNeural provider
|
|
- Auto-TTS enabled, barge-in enabled
|
|
|
|
## 5. Project Tracking
|
|
|
|
Projects tracked in `04_projects/<slug>/`:
|
|
- `status.md` — current status, phase, priorities
|
|
- `decisions.md` — key decisions with rationale
|
|
- `notes.md` — working notes
|
|
|
|
Active projects listed in `HOME.md` (max 3 primary).
|
|
|
|
## 6. Security Notes
|
|
|
|
- **Never commit secrets to git.** Secrets live in environment variables or `.gitignore`'d files.
|
|
- **Gitea tokens** should be rotated periodically.
|
|
- **SSH tunnels** must be used for VPS services accessible from the laptop.
|
|
- **Public repos** must be audited for accidental credential exposure.
|
|
|
|
## 7. Troubleshooting
|
|
|
|
### Model not responding
|
|
- Check port: `netstat -ano | grep :<port>`
|
|
- Check process: `tasklist | grep -i <model-name>`
|
|
- Check GPU: `nvidia-smi`
|
|
- Try manual API call: `curl http://localhost:<port>/v1/models`
|
|
|
|
### Cron not running
|
|
- Check job status: `hermes cron list`
|
|
- Check logs: `hermes cron log --id <id>`
|
|
- Check cron schedule syntax
|
|
|
|
### Vault sync failing
|
|
- Check git remote: `git remote -v`
|
|
- Check `.gitignore` is protecting secrets
|
|
- Check Gitea repo exists and is accessible
|
|
|
|
## 8. Future Improvements
|
|
|
|
- [ ] Add health check cron for all services
|
|
- [ ] Build agent-to-agent messaging via Gitea webhooks
|
|
- [ ] Create project dashboard (auto-generated from status.md files)
|
|
- [ ] Implement automated vault consolidation with better quality checks
|
|
- [ ] Add RAG query interface to Hermes desktop
|