From 8711840b264b9adbb610c748575269bc1674d85a Mon Sep 17 00:00:00 2001 From: Jerome Tabiri Date: Sun, 28 Jun 2026 13:20:27 -0400 Subject: [PATCH] Add memory-audit-maintenance prose contract --- memory-audit-maintenance.prose.md | 169 ++++++++++++++++++++++++++++++ 1 file changed, 169 insertions(+) create mode 100644 memory-audit-maintenance.prose.md diff --git a/memory-audit-maintenance.prose.md b/memory-audit-maintenance.prose.md new file mode 100644 index 0000000..a816180 --- /dev/null +++ b/memory-audit-maintenance.prose.md @@ -0,0 +1,169 @@ +--- +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"). +--- + +## 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% | ✅ | +```