prose-contracts/memory-audit-maintenance.prose.md

kind, name, description

kind	name	description
responsibility	memory-audit-maintenance	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):

# 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 . Holds only tech configs."
• Summary marker added to user store: "Home channel: . USER.md rewritten ."
• 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% | ✅ |