---
name: hermes-cross-profile-config
description: "Apply Hermes configuration changes across multiple profiles. Covers the bulk-update pattern, session auto-prune, curator tuning, and the one-at-a-time execution workflow."
version: 1.1.0
---

# Hermes Cross-Profile Configuration

Apply configuration changes to all Hermes profiles systematically, one at a time.

## Bulk Update Pattern

When the user wants a config change applied to all profiles:

1. **Survey first.** Use `execute_code` with yaml parsing to read current state across all profiles. Present findings before acting.
2. **Wait for go-ahead.** The user prefers discuss-first. Do not execute until they say "do it", "apply", "go", or "now."
3. **Choose the right strategy:**
   - **Base config inheritance** — if the key is one that all profiles should inherit (e.g., `plugins.hermes-memory-store.auto_extract`), set it once in `~/.hermes/config.yaml`. Per-profile configs inherit from base; only profiles that explicitly override the key will differ. This is the preferred approach for global defaults.
   - **One profile at a time** — if the key must be set per-profile (e.g., profile-specific overrides, or the user explicitly wants per-profile writes), apply changes sequentially using `hermes -p <profile> config set <key> <value>`.
4. **Report progress.** After each profile, state which one just completed and the count (e.g., "dev done. Now dgx (2/14).")
5. **Verify.** Run a final sweep to confirm all profiles have the new value.

Never batch or parallelize profile config changes — the user wants sequential, visible progress.

## Session Auto-Prune

Sessions are stored in `~/.hermes/state.db` (SQLite with FTS5). Auto-prune is **off by default** — the docs recommend keeping it off unless `state.db` is meaningfully affecting performance, since session history powers `session_search` recall.

### Config Keys

| Key | Default | Description |
|-----|---------|-------------|
| `sessions.auto_prune` | `false` | Enable automatic cleanup of ended sessions |
| `sessions.retention_days` | `90` | Keep ended sessions this many days (minimum: 1) |
| `sessions.min_interval_hours` | `24` | Don't sweep more often than this |
| `sessions.vacuum_after_prune` | `true` | Reclaim disk space after pruning |

- Only **ended** sessions are pruned. Active sessions are never touched.
- Pruning fires at CLI/gateway startup, at most once per `min_interval_hours`.
- After pruning, `state.db` gets VACUUM'd to shrink the file.
- Manual: `hermes sessions prune --older-than N`

### Limitations

- `retention_days` only accepts whole numbers. Sub-day granularity (e.g., 12 hours) is not possible. Minimum is `1` (24 hours).
- Config changes need a gateway restart for `sessions.auto_prune` to take effect on the gateway tick.

## Curator (Skill Auto-Prune)

**Separate system from session pruning.** The curator manages SKILLS, not sessions. When a user says "auto prune," clarify which system they mean.

### Config Keys (defaults)

| Key | Default | Description |
|-----|---------|-------------|
| `curator.enabled` | `true` | Enable background skill maintenance |
| `curator.interval_hours` | `168` | Days between curator runs (7 days) |
| `curator.min_idle_hours` | `2` | Agent must be idle this long before running |
| `curator.stale_after_days` | `30` | Mark unused skills stale |
| `curator.archive_after_days` | `90` | Archive long-unused skills |
| `curator.consolidate` | `false` | LLM umbrella-building pass (opt-in, costs tokens) |
| `curator.prune_builtins` | `true` | Archive unused bundled skills too |
| `curator.backup.keep` | `5` | Number of tar.gz snapshots to retain |

- Only touches skills with `created_by: "agent"` provenance. Hub-installed skills are off-limits.
- Never deletes — worst outcome is archival to `~/.hermes/skills/.archive/`, recoverable with `hermes curator restore`.
- Pinned skills are exempt from auto-transitions.
- Runs on inactivity check, not a cron daemon.

## AGENTS.md Bulk Editing

When the user wants a rule, convention, or directive added to AGENTS.md across all profiles:

1. **Survey first.** List all profile workspace dirs (`ls -d /home/n8n/workspace/*/`). Read every AGENTS.md in parallel to find insertion points. Note which files have a `## Conventions` section and which don't.
2. **Identify non-profile dirs.** Some workspace dirs (e.g., `skillz`, `stt-server`, `default`) have no corresponding `~/.hermes/profiles/<name>/` — these are loose dirs, not profiles. Skip them. Also skip AGENTS.md files that don't exist on disk (the in-context snapshot may be stale).
3. **Insert under `## Conventions` where it exists.** Use `###` sub-heading for the new rule. Anchor the patch on the last line of the Conventions section before the next `##` header.
4. **Create a `## Conventions` section where it doesn't exist.** For minimal AGENTS.md files (dgx, people, vscode, research), add `## Conventions` with the rule as the only content.
5. **Apply broadly, then selectively remove.** The user may say "for all" then later exclude specific profiles. Apply to all first, then remove from the excluded ones. This is faster than trying to guess which profiles to skip upfront.
6. **Verify with a grep sweep.** After all patches land, run `grep -c "Rule Name" /home/n8n/workspace/*/AGENTS.md` to confirm every target file has exactly one match.

### Pitfalls specific to AGENTS.md editing

- **AGENTS.md may not exist on disk.** The in-context snapshot loaded at session start can be stale. Always `read_file` before patching — if the file doesn't exist, ask whether to create it or skip.
- **Workspace dirs ≠ profile dirs.** `ls /home/n8n/workspace/` may show more dirs than `ls ~/.hermes/profiles/`. Only patch workspaces that have a corresponding profile.
- **Different file structures.** Some AGENTS.md files have `## Conventions`, some have `## Notes`, some are minimal stubs. Read every file before patching — don't assume a uniform structure.
- **The user's profile count may be wrong.** The user may say "11 profiles" when the filesystem has 14. Trust the filesystem, but flag the discrepancy.

## Skill Directory Copying Across Profiles

When the user wants a skill (or set of skills) copied to all profiles:

1. **Survey first.** Use `execute_code` to check which profiles have the skill and at what version. Present a table: profile, skill version (or MISSING), and whether it's current or stale.
2. **Wait for go-ahead.** The user prefers discuss-first. Do not execute until they say "do it", "apply", "go", or "now."
3. **Copy the full skill directory.** Use `cp -r` to copy the entire skill directory (SKILL.md + references/ + scripts/ + templates/ + assets/) from the source profile to each target. `rm -rf` the destination first to handle stale versions cleanly.
4. **Report progress.** After each profile, state which one just completed and the count.
5. **Verify.** Run a final sweep to confirm every target profile has the correct version.

**Pitfalls specific to skill copying:**
- **Copy the directory, not just SKILL.md.** Skills can have `references/`, `scripts/`, `templates/`, `assets/` subdirectories. `cp -r` the whole thing.
- **Remove stale copies first.** `rm -rf` the destination before copying to avoid leftover files from older versions.
- **Source is always the dev profile.** The canonical copy lives in `~/.hermes/profiles/dev/skills/`. Copy FROM dev TO others, never the reverse.
- **Profile count may change.** Always re-survey with `ls -d ~/.hermes/profiles/*/` — don't hardcode a count from a prior session.

## Pitfalls

- **Curator vs session prune confusion.** Users may say "auto prune" meaning either system. Clarify which one before acting.
- **`retention_days` is whole days only.** No sub-day granularity. Minimum is 1.
- **Config changes need gateway restart** for `sessions.auto_prune` to take effect on the gateway tick.
- **Don't act without go-ahead.** Survey and present, then wait for explicit direction before applying changes.