Add memory-audit-maintenance prose contract
This commit is contained in:
@@ -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 <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% | ✅ |
|
||||
```
|
||||
Reference in New Issue
Block a user