# Hermes Token Overhead Audit & Optimization

## Background

Research (Issue #4379, June 2026) shows **~73% of each API call to Hermes is fixed overhead** (~13.9K tokens) — tool definitions + system prompt constants that never change between requests, regardless of model or provider.

## Token Breakdown Reference (Default Hermes Install)

| Component | Tokens | % of Request |
|-----------|--------|-------------|
| Tool definitions (31 tools) | 8,759 | 46.1% |
| System prompt (SOUL.md + skills catalog) | 5,176 | 27.2% |
| Conversation messages | 3,000–8,775 | 26.7% avg |

Worst offenders among tool defs: `cronjob` (729), `delegate_task` (699), `skill_manage` (699), `terminal` (693), `execute_code` (629). All 11 `browser_*` tools combined: 1,258 tokens.

## Audit Steps

### 1. AGENTS.md (~4K chars → ~1K tokens)
- Always loaded at session start into every turn's system prompt
- **Trim stale data**: old model lists, retired build refs, duplicate info also in memory
- **Keep concise**: SSH conventions as one liners, not paragraphs
- **Target**: under 2.5K chars (~625 tokens)

### 2. Memory (~2.7K chars → ~675 tokens, 91% capacity)
- 3,000 char limit. Near-full = no room for new facts
- **Remove stale**: failed experiments, settled build comparisons
- **Condense verbose**: fleet lists without removed-model baggage
- **Target**: under 1.5K chars (~375 tokens), ~50% capacity

### 3. SOUL.md (~2.3K chars → ~575 tokens)
- Overlaps heavily with Hermes built-in behavioral rules
- **Remove boilerplate** that duplicates system prompt defaults
- **Keep only** user-specific preferences
- **Target**: under 1K chars (~250 tokens)

### 4. Tool Definitions
- Controlled by `toolsets` in `~/.hermes/config.yaml`
- Default: 31 tools. Most sessions need 5-10
- **Restrict to essentials**: `file`, `terminal`, `skills`, `memory`, `session_search`, `todo`, `clarify`
- **Exclude** browser/image/video tools unless needed
- **Per-platform filtering** via `platform_toolsets` prevents browser tools on Telegram

```yaml
platform_toolsets:
  telegram:
    - hermes-telegram
agent:
  disabled_toolsets: '["homeassistant","feishu_doc","feishu_drive","yuanbao","x_search"]'
```

### 5. Compression Tuning
- `threshold: 0.5` → `0.3` compresses sooner on long sessions
- `protect_last_n: 12` → `10` reduces tail overhead
- `hygiene_hard_message_limit: 400` cap

### 6. Skills Catalog (~2,200 tokens, baked into Hermes core)
- The `<available_skills>` block is injected into every system prompt
- **Cannot be removed via config** — hardcoded in Hermes core
- Mitigation: keep SKILL.md descriptions brief (one-liner in frontmatter)

## Quick-Win Checklist

| Action | Token Savings | Effort |
|--------|:------------:|:------:|
| Trim AGENTS.md stale content | ~400/req | Low |
| Consolidate memory | ~300/req | Low |
| Restrict toolsets to 7 essentials | ~5,300/req | One-time |
| Add platform_toolsets for messaging | ~1,258/req | One-time |
| Tune compression (0.3 / 10) | Variable | One-time |
| Shorten SOUL.md | ~300/req | Low |
| Disable unused tool categories | ~500/req | One-time |

## References
- Hermes Issue #4379: "Token overhead analysis: 73% of each API call is fixed overhead"
- Hermes Docs: Tips & Best Practices / Context Files / Memory & Skills
- Reddit r/hermesagent: "Token Bloat — cut Hermes overhead by 71%"
- LumaDock: "Cut your Hermes Agent token bill in half"