206 lines
8.7 KiB
Markdown
206 lines
8.7 KiB
Markdown
---
|
||
kind: responsibility
|
||
name: memory-audit-maintenance
|
||
description: >
|
||
Systematic audit and reorganization of an agent's native memory (MEMORY.md,
|
||
USER.md, SOUL.md). Categorizes entries, redistributes to correct homes,
|
||
verifies live configs, and frees up char budget. Run when memory usage
|
||
exceeds 85% or on explicit user request ("memory audit", "memory maintenance").
|
||
---
|
||
|
||
## Quickstart — How to Run This Contract
|
||
|
||
### For the Agent Running This Contract
|
||
|
||
Read this section first. It tells you exactly what to do.
|
||
|
||
**When to run:**
|
||
- User says: `"memory audit"`, `"memory maintenance"`, `"clean up memory"`, `"memory is full"`
|
||
- You detect that your `memory` store usage exceeds 85% in a write attempt
|
||
- It's been 2+ weeks since the last audit
|
||
|
||
**How to run (via OpenProse CLI):**
|
||
```bash
|
||
# Default — 85% threshold, verify configs, compress entries
|
||
prose run memory-audit-maintenance
|
||
|
||
# Softer audit — only flag issues, don't rewrite files
|
||
prose run memory-audit-maintenance compress_entries=false
|
||
|
||
# Hard audit — stricter limits
|
||
prose run memory-audit-maintenance memory_threshold=90 max_memory_chars=800 max_user_chars=300
|
||
```
|
||
|
||
### How to Follow the Template (Manual)
|
||
|
||
If `prose` CLI is not available:
|
||
|
||
1. **Read both memory files:** `cat ~/.hermes/memories/MEMORY.md` and `cat ~/.hermes/memories/USER.md`
|
||
2. **Check in-memory usage:** Use the `memory` tool with no args
|
||
3. **Categorize every entry** using the Categorization Guide below
|
||
4. **Rewrite MEMORY.md** — technical configs only, 800–1,100 chars max
|
||
5. **Rewrite USER.md** — identity + preferences only, 300–500 chars max
|
||
6. **Verify live configs** — curl each endpoint, check each model
|
||
7. **Sync in-memory** — Add summary markers (or just leave file as source of truth)
|
||
8. **Report** using the Example Output template at the bottom
|
||
|
||
## Maintains
|
||
|
||
- last_audit: timestamp — When the last full audit was completed
|
||
- memory_usage_pct: number — Current memory store usage percentage
|
||
- user_usage_pct: number — Current user store usage percentage
|
||
- total_entries_categorized: number — How many entries were audited
|
||
- entries_moved: number — How many entries changed location
|
||
- entries_deleted: number — How many stale entries were removed
|
||
- live_configs_verified: array — Which configs were verified against live systems
|
||
- known_issues: array — Problems found during audit (stale keys, dead services)
|
||
|
||
## Parameters
|
||
|
||
- memory_threshold: number — Usage % that triggers audit (default: 85, max: 95)
|
||
- verify_configs: boolean — Whether to live-check configs after audit (default: true)
|
||
- compress_entries: boolean — Whether to shorten verbose entries (default: true)
|
||
- remove_session_notes: boolean — Strip "currently doing X" markers (default: true)
|
||
- max_memory_chars: number — Target max chars for MEMORY.md after audit (default: 1100)
|
||
- max_user_chars: number — Target max chars for USER.md after audit (default: 500)
|
||
|
||
## Continuity
|
||
|
||
The audit cycle is **event-driven**, not just cron-based:
|
||
|
||
- **On threshold breach**: If memory usage exceeds `memory_threshold`, wake immediately
|
||
- **On user request**: `"memory audit"`, `"memory maintenance"`, `"clean up memory"` — explicit trigger
|
||
- **Retrospective**: Every 2-4 weeks if no other trigger fired — check for gradual bloat
|
||
- **On config change**: After major provider swaps or infrastructure migrations, verify live configs
|
||
- **On new agent onboarding**: Run once as part of initialization to establish clean baseline
|
||
|
||
## Success Criteria (What Makes a Memory Audit "Good")
|
||
|
||
The audit is considered COMPLETE when ALL of these pass:
|
||
|
||
### Inventory Complete
|
||
- MEMORY.md content read and categorized
|
||
- USER.md content read and categorized
|
||
- In-memory `memory` and `user` store usage percentages recorded
|
||
- Every entry tagged with: `Infrastructure | Identity | Preference | Operating Rule | Historical | Session Note`
|
||
|
||
### Redistribution Correct
|
||
- Identity entries → USER.md
|
||
- Preference entries → USER.md
|
||
- Technical config entries → MEMORY.md
|
||
- Operating rules → Skill file or SOUL.md
|
||
- Historical snapshots (dated checkpoints) → Deleted
|
||
- Session notes ("currently doing X") → Deleted
|
||
|
||
### Files Compact
|
||
- MEMORY.md ≤ `max_memory_chars` chars
|
||
- USER.md ≤ `max_user_chars` chars
|
||
- No duplicate information across files
|
||
- No frustration signals or verbose descriptions
|
||
- § separator between entries (standard convention)
|
||
|
||
### Configs Verified
|
||
- API keys confirmed in `.env` file (grep, not read)
|
||
- Model names in memory match live `config.yaml`
|
||
- Endpoints in memory respond to curl/health checks
|
||
- Credential pairs (username/token, email/password) match deployed state
|
||
- Any mismatch corrected in memory with ✅/❌ labels
|
||
|
||
### In-Memory Synced
|
||
- Summary marker added to `memory` store: "MEMORY.md rewritten <date>. Holds only tech configs."
|
||
- Summary marker added to `user` store: "Home channel: <channel>. USER.md rewritten <date>."
|
||
- Usage confirmed dropped below 60% after sync
|
||
|
||
### Skill Created/Updated (if applicable)
|
||
- Operating rules that belong in a skill → created via `skill_manage`
|
||
- Existing skills verified not to conflict with memory content
|
||
- Skill category appropriate and description searchable
|
||
|
||
## Remembers
|
||
|
||
Each audit stores:
|
||
- Entry categorization decisions (why X went to USER instead of MEMORY)
|
||
- What was deleted (stale snapshots, session notes)
|
||
- What was verified (configs that passed live checks)
|
||
- What failed verification (configs that need user attention)
|
||
- Known tool quirks (memory replace/remove failures)
|
||
- Compression patterns used (how verbose entries were shortened)
|
||
|
||
## Audit Rules
|
||
|
||
### Rule 1: Read Before Delete
|
||
Never delete an entry without first reading it and categorizing it. Show the user a summary of what will change if unsure about a categorization.
|
||
|
||
### Rule 2: Categories Are Mutual Exclusive
|
||
Each entry belongs to exactly ONE category:
|
||
- **Identity** — "Jerome, Florida, Telegram @mejerome19"
|
||
- **Preference** — "Single-account first for AWS"
|
||
- **Technical Config** — "SearXNG on storepve:8888"
|
||
- **Operating Rule** — "Never go rogue on infrastructure"
|
||
- **Historical Snapshot** — "Baseline v30 from Jun 26" (DELETE)
|
||
- **Session Note** — "Currently performing memory audit" (DELETE)
|
||
|
||
### Rule 3: Rules Belong in Skills
|
||
If an entry is a procedure, protocol, or mandate (`"do X this way"`, `"never do Y"`) — it belongs in a skill file, not MEMORY.md. Check `skills_list` first; create via `skill_manage` if no match exists.
|
||
|
||
### Rule 4: Verify Live Before Trusting Memory
|
||
Every config entry in MEMORY.md must be verified against the live system:
|
||
- Model name → `grep config.yaml`
|
||
- API key → `grep .env`
|
||
- Service URL → `curl` health check
|
||
- Credentials → cross-reference with deployed state
|
||
|
||
### Rule 5: Work Around the `memory` Tool
|
||
The `memory` tool's `remove` and `replace` actions use strict text matching that can fail on special characters. If a remove/replace fails repeatedly:
|
||
- Do not retry more than 2 times
|
||
- Add a new summary marker entry instead
|
||
- Report to user: "File on disk updated; in-memory store has stale leftovers"
|
||
- The file on disk (MEMORY.md, USER.md) is the source of truth regardless
|
||
|
||
### Rule 6: Report Before Asking
|
||
Don't ask the user "should I delete X?" for session notes or historical snapshots — those are always safe to delete. Only ask about ambiguous categorizations or cross-file moves of preference data.
|
||
|
||
## Execution
|
||
|
||
1. **Read state** — Read MEMORY.md, USER.md, check in-memory usage via `memory` tool
|
||
2. **Categorize** — Tag every entry with its category
|
||
3. **Prepare rewrites** — Draft compressed MEMORY.md and USER.md:
|
||
- MEMORY.md: Technical configs only (800-1100 chars)
|
||
- USER.md: Identity + preferences only (300-500 chars)
|
||
4. **Write files** — Overwrite MEMORY.md and USER.md
|
||
5. **Verify live configs** — Check every config entry against actual system state
|
||
6. **Sync in-memory** — Add summary markers to `memory` and `user` stores
|
||
7. **Create/update skills** — Move operating rules to skill files if needed
|
||
8. **Report** — Output clean status table with before/after/verification
|
||
|
||
## Example Output
|
||
|
||
```
|
||
## Memory Audit Complete ✅
|
||
|
||
| File | Before | After | Reduction |
|
||
|---|---|---|---|
|
||
| MEMORY.md | 1,653 chars | 1,077 chars | ~35% |
|
||
| USER.md | 860 chars | 418 chars | ~51% |
|
||
|
||
### What Moved
|
||
| Entry | From | To |
|
||
|---|---|---|
|
||
| Identity + Preferences | MEMORY.md | USER.md |
|
||
| Agent boundary rule | MEMORY.md | SOUL.md (persona) |
|
||
| Baseline v30 snapshot | MEMORY.md | Deleted |
|
||
|
||
### Config Verification
|
||
| Config | Live Check | Status |
|
||
|---|---|---|
|
||
| DeepSeek model | config.yaml: deepseek-chat | ✅ |
|
||
| DeepSeek key | .env found | ✅ |
|
||
| SearXNG endpoint | :8888 curl 200 | ✅ |
|
||
|
||
### Memory Usage
|
||
| Store | Before | After | Status |
|
||
|---|---|---|---|
|
||
| memory | 91% | 59% | ✅ |
|
||
| user | 85% | 41% | ✅ |
|
||
```
|