[Skip to content](https://github.com/mrmoe28/hermes-context-optimization#start-of-content)

You signed in with another tab or window. [Reload](https://github.com/mrmoe28/hermes-context-optimization) to refresh your session.You signed out in another tab or window. [Reload](https://github.com/mrmoe28/hermes-context-optimization) to refresh your session.You switched accounts on another tab or window. [Reload](https://github.com/mrmoe28/hermes-context-optimization) to refresh your session.Dismiss alert

{{ message }}

[mrmoe28](https://github.com/mrmoe28)/ **[hermes-context-optimization](https://github.com/mrmoe28/hermes-context-optimization)** Public

- [Notifications](https://github.com/login?return_to=%2Fmrmoe28%2Fhermes-context-optimization) You must be signed in to change notification settings
- [Fork\\
0](https://github.com/login?return_to=%2Fmrmoe28%2Fhermes-context-optimization)
- [Star\\
0](https://github.com/login?return_to=%2Fmrmoe28%2Fhermes-context-optimization)


master

[**1** Branch](https://github.com/mrmoe28/hermes-context-optimization/branches) [**0** Tags](https://github.com/mrmoe28/hermes-context-optimization/tags)

[Go to Branches page](https://github.com/mrmoe28/hermes-context-optimization/branches)[Go to Tags page](https://github.com/mrmoe28/hermes-context-optimization/tags)

Go to file

Code

Open more actions menu

## Folders and files

| Name | Name | Last commit message | Last commit date |
| --- | --- | --- | --- |
| ## Latest commit<br>[![mrmoe28](https://avatars.githubusercontent.com/u/196083366?v=4&size=40)](https://github.com/mrmoe28)[mrmoe28](https://github.com/mrmoe28/hermes-context-optimization/commits?author=mrmoe28)<br>[Initial commit: Hermes context optimization guide](https://github.com/mrmoe28/hermes-context-optimization/commit/9b514a3dd25ffefb62aa65cafb5c6e8f98420eaa)<br>3 weeks agoJun 12, 2026<br>[9b514a3](https://github.com/mrmoe28/hermes-context-optimization/commit/9b514a3dd25ffefb62aa65cafb5c6e8f98420eaa) · 3 weeks agoJun 12, 2026<br>## History<br>[1 Commit](https://github.com/mrmoe28/hermes-context-optimization/commits/master/) <br>Open commit details<br>[View commit history for this file.](https://github.com/mrmoe28/hermes-context-optimization/commits/master/) 1 Commit |
| [examples](https://github.com/mrmoe28/hermes-context-optimization/tree/master/examples "examples") | [examples](https://github.com/mrmoe28/hermes-context-optimization/tree/master/examples "examples") | [Initial commit: Hermes context optimization guide](https://github.com/mrmoe28/hermes-context-optimization/commit/9b514a3dd25ffefb62aa65cafb5c6e8f98420eaa "Initial commit: Hermes context optimization guide") | 3 weeks agoJun 12, 2026 |
| [scripts](https://github.com/mrmoe28/hermes-context-optimization/tree/master/scripts "scripts") | [scripts](https://github.com/mrmoe28/hermes-context-optimization/tree/master/scripts "scripts") | [Initial commit: Hermes context optimization guide](https://github.com/mrmoe28/hermes-context-optimization/commit/9b514a3dd25ffefb62aa65cafb5c6e8f98420eaa "Initial commit: Hermes context optimization guide") | 3 weeks agoJun 12, 2026 |
| [README.md](https://github.com/mrmoe28/hermes-context-optimization/blob/master/README.md "README.md") | [README.md](https://github.com/mrmoe28/hermes-context-optimization/blob/master/README.md "README.md") | [Initial commit: Hermes context optimization guide](https://github.com/mrmoe28/hermes-context-optimization/commit/9b514a3dd25ffefb62aa65cafb5c6e8f98420eaa "Initial commit: Hermes context optimization guide") | 3 weeks agoJun 12, 2026 |
| View all files |

## Repository files navigation

# Hermes Context & Token Optimization

[Permalink: Hermes Context & Token Optimization](https://github.com/mrmoe28/hermes-context-optimization#hermes-context--token-optimization)

A step-by-step guide to audit and massively reduce token waste in [Hermes Agent](https://github.com/NousResearch/hermes-agent) sessions. Based on real production tuning that cut input-to-output ratios from 100:1 to manageable levels.

* * *

## What Problem This Solves

[Permalink: What Problem This Solves](https://github.com/mrmoe28/hermes-context-optimization#what-problem-this-solves)

Hermes sessions accumulate massive token overhead:

- **Skills auto-injected every turn** (~5-15K tokens)
- **Full memory dump every turn** (~1,500 tokens)
- **Unpruned conversation history** (grows without bound)
- **Verbose tool outputs** returned verbatim

**Real session data:**

| Session | Messages | Input Tokens | Output Tokens | Ratio |
| --- | --- | --- | --- | --- |
| "Prompt caching" | 23 | 824,916 | 7,742 | **106:1** |
| "Whisper install" | 86 | 475,850 | 4,841 | **98:1** |

Most tokens are overhead — not actual generation.

* * *

## Quick Audit

[Permalink: Quick Audit](https://github.com/mrmoe28/hermes-context-optimization#quick-audit)

Run this to diagnose your own bloat:

```
# Find your Hermes state.db (usually ~/.hermes/state.db)
python3 << 'PYEOF'
import sqlite3, sys

db = sys.argv[1] if len(sys.argv) > 1 else "~/.hermes/state.db"
db = db.replace("~", "/home/" + __import__("getpass").getuser())

conn = sqlite3.connect(db)
c = conn.cursor()

# Current session
c.execute('''
  SELECT id, title, message_count, input_tokens, output_tokens
  FROM sessions ORDER BY started_at DESC LIMIT 1
''')
row = c.fetchone()
if row:
    sid, title, msgs, inp, out = row
    ratio = inp / (out or 1)
    print(f"Session: {title}")
    print(f"  Messages: {msgs} | Input: {inp:,} | Output: {out:,} | Ratio: {ratio:.0f}:1")

    # Breakdown by role
    c.execute('''SELECT role, COUNT(*), SUM(token_count) FROM messages
                 WHERE session_id=? GROUP BY role''', (sid,))
    print("  By role:")
    for r in c.fetchall():
        print(f"    {r[0]}: {r[1]} msgs, {r[2] or 0:,} tokens")
conn.close()
PYEOF
```

**Danger signs:**

- Ratio > 50:1
- `tool` messages dominating token count
- Message count > 60 but few user messages

* * *

## The 7 Optimizations (Apply in Order)

[Permalink: The 7 Optimizations (Apply in Order)](https://github.com/mrmoe28/hermes-context-optimization#the-7-optimizations-apply-in-order)

### 1\. Prune Unused Skills

[Permalink: 1. Prune Unused Skills](https://github.com/mrmoe28/hermes-context-optimization#1-prune-unused-skills)

Hermes injects ALL matching skills into context every turn. Disable domains you don't use.

```
# Temporarily hide skill directories (prefix with dot)
cd ~/.hermes/skills
for d in apple creative data-science diagramming dogfood email gaming gifs media note-taking red-teaming smart-home social-media tts-autoplay; do
  if [ -d "$d" ] && [ ! -d ".$d" ]; then
    mv "$d" ".$d"
  fi
done
```

> **Tip:** Don't delete them — just rename with a `.` prefix. Re-enable later by removing the dot.

**Impact:** ~3,000-8,000 tokens saved per turn.

* * *

### 2\. Cap Context Window

[Permalink: 2. Cap Context Window](https://github.com/mrmoe28/hermes-context-optimization#2-cap-context-window)

Force Hermes to prune old messages before they bloat the prompt.

```
# ~/.hermes/config.yaml
model:
  context_length: 32768      # or 65536 for larger models
  ollama_num_ctx: 32768      # Ollama-specific
```

**Impact:** Sets a hard ceiling on maximum bloat.

* * *

### 3\. Reduce max\_turns

[Permalink: 3. Reduce max_turns](https://github.com/mrmoe28/hermes-context-optimization#3-reduce-max_turns)

Rotate sessions before history becomes unwieldy.

```
# ~/.hermes/config.yaml
agent:
  max_turns: 30              # was 60
```

**Impact:** Forces session refresh at 30 turns instead of 60.

* * *

### 4\. Enable Auto-Compaction

[Permalink: 4. Enable Auto-Compaction](https://github.com/mrmoe28/hermes-context-optimization#4-enable-auto-compaction)

Hermes will auto-summarize old messages into a compressed blob.

```
hermes config set agent.compact true
```

Or edit `~/.hermes/config.yaml`:

```
agent:
  compact: true
```

**Impact:** Cuts stale history by ~60%.

* * *

### 5\. Configure Context Compression

[Permalink: 5. Configure Context Compression](https://github.com/mrmoe28/hermes-context-optimization#5-configure-context-compression)

Fine-tune how aggressive the pruning is.

```
# ~/.hermes/config.yaml
compression:
  enabled: true
  threshold: 0.7          # compress when context hits 70% of limit
  target_ratio: 0.2         # keep 20% of threshold as summary
  protect_last_n: 40        # never compress last 40 messages
  protect_first_n: 3        # keep first 3 messages (usually system prompt)
  hygiene_hard_message_limit: 1000
```

**Impact:** Automatically manages context without manual intervention.

* * *

### 6\. Cap Tool Output

[Permalink: 6. Cap Tool Output](https://github.com/mrmoe28/hermes-context-optimization#6-cap-tool-output)

Prevent verbose terminal/web search results from flooding the prompt.

```
# ~/.hermes/config.yaml
tool_output:
  max_bytes: 50000
  max_lines: 2000
  max_line_length: 2000
```

Also set file read limits:

```
file_read_max_chars: 100000
```

**Impact:** Prevents a single `cat` or `curl` from dumping 50K+ tokens.

* * *

### 7\. Prune Memory Store

[Permalink: 7. Prune Memory Store](https://github.com/mrmoe28/hermes-context-optimization#7-prune-memory-store)

User profile + memory notes are injected every turn. Default: ~3,500 chars memory + 2,000 chars profile.

**Rules:**

- Delete anything session-specific (PR numbers, commit SHAs, "fixed bug X")
- Keep only: preferences, environment facts, conventions, contact methods
- If memory is >80% full, audit and purge stale entries

```
# Check current memory usage
hermes config show | grep -A2 "memory"
```

**Impact:** ~500-1,500 tokens saved per turn.

* * *

## Bonus: Session Rotation with External Memory

[Permalink: Bonus: Session Rotation with External Memory](https://github.com/mrmoe28/hermes-context-optimization#bonus-session-rotation-with-external-memory)

Even with all optimizations, long-running sessions eventually bloat. The fix: **rotate into an Obsidian vault**.

### Setup

[Permalink: Setup](https://github.com/mrmoe28/hermes-context-optimization#setup)

1. Create an Obsidian vault at `~/Documents/Obsidian Vault`
2. Structure:
   - `Index.md` — master map
   - `projects/` — active work
   - `tech-stack/` — configs, infra
   - `decisions/` — why we chose X over Y
   - `meeting-notes/` — dated calls
   - `scratch/` — transient notes

### Workflow

[Permalink: Workflow](https://github.com/mrmoe28/hermes-context-optimization#workflow)

At ~25 turns, write a summary:

```
# Session Summary — 2026-06-12

**Topic:** Token optimization for Hermes
**Session ID:** abc123

## What we did
- Disabled 13 unused skill domains
- Set context_length: 32768, max_turns: 30
- Enabled auto-compaction and compression

## Decisions
- Keep Ollama on CT 100 via autossh tunnel (port 11435)
- Use Telegram as primary notification channel

## Files changed
- ~/.hermes/config.yaml
- ~/.hermes/skills/* (disabled via dot-prefix)

## Next steps
- [ ] Test with vLLM for true KV caching
- [ ] Monitor token ratios weekly
```

Save to `~/Documents/Obsidian Vault/tech-stack/Hermes-Token-Optimization.md`.

### Resume

[Permalink: Resume](https://github.com/mrmoe28/hermes-context-optimization#resume)

Start a new Hermes session with:

```
Load context from ~/Documents/Obsidian Vault/tech-stack/Hermes-Token-Optimization.md and continue
```

**Result:** Read file once (~500 tokens) instead of carrying 25 turns (~12K tokens). **Net save: ~11K tokens per rotation.**

* * *

## Ollama-Specific Notes

[Permalink: Ollama-Specific Notes](https://github.com/mrmoe28/hermes-context-optimization#ollama-specific-notes)

**Ollama does NOT persist KV cache across API calls.** Each request re-runs the full prefill. `keep_alive` only keeps model weights in VRAM.

```
# Still useful — avoids cold starts
ollama_num_ctx: 32768
keep_alive: -1              # keep model loaded indefinitely
```

For true prompt caching (KV state reuse), use **vLLM** instead of Ollama.

* * *

## Before vs After

[Permalink: Before vs After](https://github.com/mrmoe28/hermes-context-optimization#before-vs-after)

| Metric | Before | After |
| --- | --- | --- |
| Input/output ratio | 100:1 | ~10-20:1 |
| Baseline overhead/turn | ~8K tokens | ~3.5K tokens |
| Session burn (typical) | 300-800K tokens | 80-200K tokens |
| Context headroom | ~24K | ~29K |
| Auto-prune trigger | 60 turns | 30 turns |

* * *

## Files in This Repo

[Permalink: Files in This Repo](https://github.com/mrmoe28/hermes-context-optimization#files-in-this-repo)

| File | Purpose |
| --- | --- |
| `README.md` | This guide |
| `examples/config-after.yaml` | Optimized Hermes config |
| `examples/config-before.yaml` | Reference baseline config |
| `scripts/token-audit.sql` | SQLite queries for session diagnostics |
| `scripts/session-summary-template.md` | Markdown template for Obsidian rotation |
| `scripts/skill-prune.sh` | One-liner to disable unused skill domains |

* * *

## References

[Permalink: References](https://github.com/mrmoe28/hermes-context-optimization#references)

- [Hermes Agent Docs](https://hermes-agent.nousresearch.com/docs)
- [Ollama API Docs](https://github.com/ollama/ollama/blob/main/docs/api.md)
- [vLLM Prefix Caching](https://docs.vllm.ai/en/latest/features/automatic_prefix_caching.html)

* * *

_Last updated: 2026-06-12 \| Tested on Hermes Agent with Ollama + OpenRouter backends_

## About

Step-by-step guide to optimize Hermes Agent context windows and token usage — based on real production tuning


### Resources

[Readme](https://github.com/mrmoe28/hermes-context-optimization#readme-ov-file)

### Uh oh!

There was an error while loading. [Please reload this page](https://github.com/mrmoe28/hermes-context-optimization).

[Activity](https://github.com/mrmoe28/hermes-context-optimization/activity)

### Stars

[**0**\\
stars](https://github.com/mrmoe28/hermes-context-optimization/stargazers)

### Watchers

[**0**\\
watching](https://github.com/mrmoe28/hermes-context-optimization/watchers)

### Forks

[**0**\\
forks](https://github.com/mrmoe28/hermes-context-optimization/forks)

[Report repository](https://github.com/contact/report-content?content_url=https%3A%2F%2Fgithub.com%2Fmrmoe28%2Fhermes-context-optimization&report=mrmoe28+%28user%29)

## [Releases](https://github.com/mrmoe28/hermes-context-optimization/releases)

No releases published

## [Packages\  0](https://github.com/users/mrmoe28/packages?repo_name=hermes-context-optimization)

No packages published

## [Contributors\  1](https://github.com/mrmoe28/hermes-context-optimization/graphs/contributors)

- [![@mrmoe28](https://avatars.githubusercontent.com/u/196083366?s=64&v=4)](https://github.com/mrmoe28)[**mrmoe28** mrmoe28](https://github.com/mrmoe28)

## Languages

- [Shell100.0%](https://github.com/mrmoe28/hermes-context-optimization/search?l=shell)

You can’t perform that action at this time.