---
name: memory-governance
description: >
  Manage Hermes memory cap, run prune audits, and bump limits with receipts.
  Trigger when the user asks to increase memory, check memory usage, audit
  memory, prune memory, or change memory_char_limit. Also trigger when
  memory hits the cap and you need to decide what to keep vs drop.
  Covers the audit procedure, the config change workflow, and the
  governance rule that cap bumps require prune-audit evidence first.
---

# Memory Governance

## Governance Rule

Memory cap bumps require prune-audit evidence first. No exceptions.
The weekly cron `memory-audit-prune` (Mon 07:00 UTC) is the formal
audit cycle; ad-hoc audits are fine when the user asks.

Current cap: 12,000 chars (was 8,000, bumped 2026-08-12 after audit
showed 10,709 bytes of essential content with <2% prune savings).

## Prune-Audit Procedure

When asked to audit or before any cap bump:

1. Read both memory files:
   - `/root/.hermes/memories/MEMORY.md` (system/ops notes)
   - `/root/.hermes/memories/USER.md` (user preferences)

2. Count bytes and lines:
   ```
   wc -c <file>   # bytes per file
   wc -l <file>   # line count
   ```

3. Triage every entry:
   - LOCKED: operational safety knowledge (kill switches, auth tokens,
     brand palettes, fallback chains, kill-switch dates, etc.)
   - COMPRESSIBLE: verbose descriptions that can shorten without loss
   - STALE: no longer-relevant entries (retired tools, resolved bugs)

4. Produce a receipt table:

   | Entry | Bytes | Verdict |
   |---|---|---|
   | <name> | <size> | LOCKED / compressible / stale |

5. Calculate:
   - Current total bytes
   - Prune ceiling (after removing stale + compressible)
   - Gap to current cap
   - Headroom if bumped to proposed new cap

6. Report findings. Do NOT bump the cap until the user reviews the
   receipt and confirms.

## Cap-Change Workflow

The memory cap lives in `config.yaml` under `memory.memory_char_limit`.

**Do NOT patch config.yaml directly** — the agent security guard blocks it.
Use the Hermes CLI instead:

```bash
/root/.hermes/venv/bin/hermes config set memory.memory_char_limit <NEW_VALUE>
```

Verify the change took effect by reading the config or running
`hermes config get memory.memory_char_limit`.

## What Goes in Memory vs Skills vs Vault

| Destination | Content |
|---|---|
| **MEMORY.md** | System facts, gotchas, skill pointers, kill-switch dates |
| **USER.md** | User preferences, style rules, business context |
| **Skills** | How-to procedures, workflows, debugging paths |
| **Vault** | Full documents, detailed references, session archives |

Memory = facts + gotchas + skill pointers only. Procedures go in skills,
documents go in the vault.

## Pitfalls

- **Don't dump conversation transcripts into memory.** Extract only the
  durable facts.
- **Don't add bracket-style placeholders** (`[PERSON_NAME]`) — Rob flags
  this as noise. Use real names when context allows.
- **Don't suggest deleting AppData folders** — Rob's environment has
  sporadic re-login behavior; rename-over-delete for app subfolders only.
- **Memory entries don't need § separator lines** between every entry —
  they waste ~3 bytes each. Group related entries without separators.
- **The 8K → 12K bump (2026-08-12)** proved that prune audits rarely
  yield >2% savings when memory is already lean. Future bumps should
  follow the same audit-first pattern.

## Support Files

- `references/audit-receipt-template.md` — markdown template for
  presenting prune-audit findings to Rob.