# Hermes Configuration Audit

Systematic review of a Hermes Agent installation — config, memory, sessions, skills, and disk usage.

## Audit Checklist

### 1. Config.yaml Review
- **Provider reference**: `model.provider` must match a slug in `custom_providers`. Stale references cause auth failures.
- **Streaming conflict**: `display.streaming: true` vs `streaming.enabled: false` — the inner section overrides. Set both consistently.
- **Personality bloat**: 69 personality definitions in config, most unused. Keep only active ones.
- **Logging**: `max_size_mb` + `backup_count` should match actual log volume. If logs exceed the limit, rotation isn't working.
- **Compression**: Enable for heavy sessions (>1M tokens). Check `threshold` and `target_ratio`.
- **Session retention**: `sessions.retention_days` + `auto_prune: true` + `vacuum_after_prune: true` is the ideal combo.

### 2. Session DB Health
- Check `state.db` size. >200MB with many sessions = needs vacuum.
- Look for empty sessions (0 messages) — cleanup candidates.
- Verify `sqlite3` or Python `sqlite3` module for queries.
- Total token usage across sessions shows cumulative cost.

### 3. Disk Usage Profiling
- **venv/**: Usually 5-7GB. Can be rebuilt but not urgent.
- **node_modules/**: ~50-100MB. Dev dependency.
- **.git/**: Normal for active repos.
- **logs/**: Check rotation. 20MB+ = needs attention.
- **cache/**: Usually small (<1MB).
- **skills/**: Well-organized, check for orphaned directories.
- **.curator_backups/**: Old skill backups, can be pruned.
- **Untracked files**: Check for stray .md files in checkout root.

### 4. Skills Review
- Count directories in `~/.hermes/skills/`.
- Check `.bundled_manifest` for curator tracking.
- Look for `.curator_backups/` — old backups to prune.
- Symlinks to external skill dirs (e.g., `~/.agents/skills/`) are fine.

### 5. Best Practices from Docs
- **SOUL.md**: Move persona from config into `~/.hermes/SOUL.md` for cleaner separation.
- **Context files**: AGENTS.md in checkout is dev guide, not user context. Fine.
- **Prompt caching**: `long_lived_prefix: true` is good for heavy sessions.
- **Memory**: Keep MEMORY.md under 80%, USER.md under 80%.

## Pitfalls (Agent-Authored Config Edits)

- **`hermes config set` with arrays**: This CLI stores array/list values as **JSON strings** — `models: '[{"a":1}]'` instead of proper YAML list syntax. Always use Python yaml.dump() to write list/array values in config.yaml, or edit the file directly.
- **platform_toolsets.cli controls tool availability**: If you slim the CLI toolsets (e.g., from 28 tools to 7 after an audit), you lose `web` and `browser` tools — which means no web search. Always include them explicitly in `platform_toolsets.cli`: `['clarify', 'file', 'memory', 'session_search', 'skills', 'terminal', 'todo', 'web', 'browser']`
- **web.search_backend empty silences web_search**: Even with `"web"` in platform_toolsets, if `web.backend` and `web.search_backend` are empty strings, the web search registry silently strips `web_search`/`web_extract` from available tools. This is a distinct root cause from toolset slimming. Fix: `hermes config set web.search_backend ddgs`. The `web:` section often gets wiped by config rewrites — always verify it after any audit, update, or edit. See `hermes-diagnostics` skill reference `web-search-missing-diagnosis.md`.

## Quick Commands

```bash
# Config check
hermes config check
hermes config migrate

# Session stats
hermes sessions stats
hermes sessions prune --older-than 30

# Skill management
hermes skills list
hermes skills check
hermes skills update

# Health
hermes doctor
hermes status
```

## Session-Specific Findings (2026-05-26)

- Provider reference `custom:local` was stale — should be `custom:local-llm-(llama-swap)`
- Streaming conflict: `display.streaming: true` but `streaming.enabled: false`
- 69 personality definitions, only `concise` and `technical` used
- state.db at 289.7MB with 377 sessions
- Logs at 22MB, rotation not keeping up (max_size_mb: 5, backup_count: 3)
- .curator_backups/ at 5MB — old skill backups
- 4 untracked .md files in checkout root
- Memory: 69% MEMORY, 40% USER — well within limits
- Total tokens across sessions: 70.7M input + 6.9M output