lucadominguez Hermes Token Efficiency
Comprehensive cost optimization for Hermes Agent setups. Apply these techniques to reduce API spend by 25-75% without losing capability.
Core Principles
Transform LLM from "all-purpose butler" to "expert advisor" — CPU-fy daily operations, let complex reasoning go to large models.
The 7 Techniques (adapted for Hermes)
| # | Technique | Hermes Implementation | Savings |
|---|---|---|---|
| 1 | Tree-structured bootstrap | Shrink SOUL.md to rules only; move references to loadable skills | ~66% bootstrap |
| 2 | Context compression | compression.enabled: true (already on) |
50% long sessions |
| 3 | Local model for light tasks | (needs Ollama + 3GB RAM) | up to 100% |
| 4 | Script-to-API, bypass bootstrap | no_agent: true cron jobs with Python scripts |
100% per task |
| 5 | Quick commands vs LLM | quick_commands in config.yaml |
100% per use |
| 6 | CPU-fy cron tasks | Replace LLM cron with Python watchdog scripts | 100% per task |
| 7 | Checklist-ified heartbeats | Simple no_agent scripts checking status |
100% per check |
Implementation Checklist
✅ Immediate (zero cost, apply now)
- Shrink SOUL.md to behavioral rules only (<1,500 bytes)
- Convert mechanical cron jobs to
no_agentPython scripts - Add
quick_commandsfor common maintenance (/status,/disk,/mem) - Add RTK command prefix guidance
- Set up tiered model routing (cheap for subagents/cron, strong for main)
🔧 Medium (requires setup)
- Install Ollama + qwen2.5:3b for offline heartbeat checks (needs 3GB RAM)
- Write Python scripts that call OpenRouter API directly for cron data collection
- Set up the efficiency tracker cron to measure impact
🚀 Advanced
- RAG-based skill descriptor filtering (only load relevant skills per task)
- Custom
pre_tool_callhooks to auto-route operations to local models - Token budget alerts via cron
Current Setup (as of 2026-07-12)
SOUL.md: 1,268 bytes (was 1,465)
Skills: 105 active (was 114, 10 moved to disabled)
Memory: 2,135 bytes (87% of 2200 limit)
Cron jobs: 5 total (3 no_agent, 1 LLM, 1 script-only)
Models: deepseek-v4-pro (default), mimo-v2.5 (subagents/cron)
Compression: enabled (threshold 0.5, target 0.2)
RTK: installed (~/.cargo/bin/rtk), guided via AGENTS.md
Hooks: post_tool_call filter on terminal (compact-output.py)
Tracking: token-efficiency-tracker.py every 6 hours
Common Pitfalls
CLAUDE.md → AGENTS.md rename (avoid false model alarms)
Problem: Files named CLAUDE.md in the working directory get loaded as project context. The user sees "CLAUDE.md" in output and assumes Hermes is using Claude models (expensive), triggering unnecessary investigation sessions that waste tokens confirming the config is already correct.
Fix: Rename CLAUDE.md to AGENTS.md. Hermes loads both filenames as project context files — same functionality, zero "Claude" branding. The file was never calling Anthropic APIs; it was just a filename convention inherited from Claude Code/Cursor.
mv CLAUDE.md AGENTS.md # safe, Hermes reads both
Token impact: Each false-alarm investigation burns ~5-10K tokens confirming model config. One rename prevents recurring waste.
Efficiency Tracking
The token-efficiency-tracker runs every 6 hours and writes to ~/.hermes/logs/efficiency/efficiency-YYYYMMDD.json.
View current stats:
cat ~/.hermes/logs/efficiency/efficiency-$(date +%Y%m%d).json | python3 -m json.tool
Or use quick command: /efficiency
Rollback
All changes are reversible:
# Restore SOUL.md from backup
cp ~/.hermes/hermes-agent/.hermes-cost-optimization/backups/20260604-062615/files/SOUL.md ~/.hermes/SOUL.md
# Revert cron jobs to LLM mode
hermes cron update <job_id> --no-agent=false --script=''
# Remove hooks
hermes config set hooks '{}'
# Restore all skills
mv ~/.hermes/skills-disabled/* ~/.hermes/skills/