# Installation Guide

Self-service install for any Hermes agent. Read this file, understand the changes, then apply them yourself.

## Overview

Four things change in your Hermes configuration:

1. **SOUL.md** — Replace the behavioral/conduct section with the pi-style distilled core
2. **config.yaml** — Add MCP servers, trim tool palette  
3. **Skills** — Add on-demand skills from this repo
4. **Compression** — Optimize for 256K-context models

## Step 1: Read the Core Prompt

Start by reading `prompts/behavioral-core.md`. This replaces the "how you should behave" section of your SOUL.md. It's shorter, denser, and more directive than typical Hermes SOUL content.

You don't need to replace your entire SOUL.md. Just merge the behavioral core into it — specifically the **Three Pillars** and the **Conduct Rules** sections.

**Do NOT** remove your identity, capabilities, or tool documentation from SOUL.md. Only replace the behavioral instructions with the more focused version.

## Step 2: Add MCP Servers

Open your `~/.hermes/config.yaml` (or wherever your Hermes config lives) and add the MCP servers from `config/mcp-servers.yaml`.

These give you the same tool access as Abiba on pi:
- **Firecrawl** — web scraping, search, structured extraction  
- **SearXNG** — multi-engine web search  
- **Context7** — documentation verification (API params, CLI flags, library syntax)  
- **GitHub** — code search, issues, PRs  
- **RA-H OS** — shared knowledge graph access  

**Important:** Verify your tools list after adding. You should see ~20+ new tools available.

## Step 3: Update Compression (for 256K models)

If your agent model has a 256K context window (most harness models do), apply the compression config from `config/compression.yaml`.

The critical change: set `max_context_window: 262144` so the threshold math works correctly at 80%.

## Step 4: Add Skills

Copy the `.md` files from `skills/` into your Hermes skills directory (`~/.hermes/skills/` or wherever Hermes loads skills from).

These skills are loaded **on-demand** — they bring the pi-style expertise into your context only when you need it:
- `three-pillars.md` — The behavioral framework (Proactive, Persistent, Self-Improving)  
- `verification-protocol.md` — How to verify technical claims before answering  
- `self-healing.md` — Error recovery patterns without involving the user  

## Step 5: Restart and Verify

1. Restart your Hermes session
2. Verify new tools are available (check your tool list)
3. Confirm compression settings took effect
4. Test: ask yourself "What are the Three Pillars?" and verify you can answer

## Rollback

If something breaks, revert your changes:
- Restore SOUL.md from backup
- Remove MCP server entries from config.yaml
- Remove added skills
- Restart Hermes

## Troubleshooting

| Problem | Likely Cause | Fix |
|---------|-------------|------|
| Tools not appearing | MCP server URL wrong or unreachable | Check `config/mcp-servers.yaml` for correct endpoints |
| Compression too aggressive | `max_context_window` not updated | Set `max_context_window: 262144` for 256K models |
| Agent behavior unchanged | SOUL.md not updated | Verify behavioral-core.md was merged into SOUL.md |
| Skills not loading | Skills dir not in config.yaml | Add `external_dirs` to `skills` section in config.yaml |