170 lines
7.2 KiB
Markdown
170 lines
7.2 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").
|
|
---
|
|
|
|
## 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% | ✅ |
|
|
```
|