| name | memory-organize |
| description | Periodic maintenance of role memory: dedup, tidy, consolidate, and pending management. |
| whenToUse | When the user asks to organize, tidy, or maintain their memory. Also for scheduled maintenance to clean up stale entries and manage the pending verification layer. |
Memory Organize
You are maintaining a role's persistent memory system. Keep it healthy, accurate, and useful.
Memory Layers
consolidated.md ← L2: deduplicated learnings + preferences (main)
pending.md ← Pending: auto-extracted, awaiting verification
daily/*.md ← L1: raw session logs
Tools Available
| Tool | Purpose |
|---|
memory({ action: "list" }) | List all memories, detect structural issues |
memory({ action: "consolidate" }) | Rule-based dedup: exact + Jaccard similarity. Safe, never deletes unique entries. |
memory({ action: "repair" }) | Fix markdown structure issues |
memory({ action: "llm_tidy" }) | LLM-guided: rewrites verbose, detects contradictions, suggests deletions |
memory({ action: "search", query: "..." }) | Search with auto-reinforce (≥0.5 → used+1) |
memory({ action: "reinforce", content: "..." }) | Increment [Nx] usage count |
memory({ action: "delete_learning", content: "..." }) | Remove stale entry |
memory({ action: "update_learning", id/query, content }) | Rewrite entry |
role_read / role_write | Direct file access |
Process
Step 1: Assess
memory({ action: "list" })
Look for:
- Parse issues — structural problems
- High [0x] count — many unverified = noise
- Long entries — should be <120 chars
Step 2: Repair (if needed)
memory({ action: "repair" })
Fixes: malformed headings, missing sections, stray lines. Safe, rule-based.
Step 3: Consolidate (dedup)
memory({ action: "consolidate" })
Rule-based, NOT LLM:
- Exact text match → keep highest
[Nx]
- Jaccard token similarity (config threshold) → merge, keep highest
- Rewrites the canonical section layout in
consolidated.md
- Updates
# Last Consolidated date
consolidate does not magically upgrade [0x] to Normal. Priority still depends on usage (reinforce / auto-reinforce during search).
Step 4: LLM Tidy (deep cleanup)
memory({ action: "llm_tidy" })
LLM produces a plan:
- Rewrite verbose entries → concise
- Detect contradictions between entries
- Suggest deletions for stale entries
- Add new entries derived from synthesis
Step 5: Pending Management
Check memory/pending.md:
role_read({ path: "memory/pending.md" })
[○] pending → if relevant to current work, search to auto-promote (score ≥0.5)[✓] already promoted[✗] discarded (7-day auto-expiry)
Pending entries that survive 7+ days without use are auto-expired. Manual promotion via search.
Step 6: Reinforce Active Memories
For insights used in this session:
memory({ action: "reinforce", content: "<text>" })
Moves memories toward High Priority [3x]+.
Step 7: Remove Stale Entries
For provably outdated entries:
memory({ action: "delete_learning", content: "<text>" })
Rules:
- Only delete if provably wrong or no longer relevant
- Prefer
update_learning over delete when in doubt
- Never delete preferences without user confirmation
Maintenance Report
After organizing:
Memory Organize Report — <role>
- Before: X learnings, Y preferences
- After: X' learnings, Y' preferences
- Repaired: yes/no
- Consolidate: removed N duplicates
- LLM tidy: rewrote N, deleted N, added N
- Pending: M promoted, K expired
Maintenance Frequency
| Frequency | Actions |
|---|
| Per session | auto-extract → pending (automatic) |
| On request | consolidate (safe dedup) |
| Weekly | repair + consolidate + reinforce |
| Monthly / heavy | llm_tidy + manual review + pending cleanup |
Operation Rules
- Be conservative: When in doubt, leave entries alone. Better to under-clean than lose useful memories.
- consolidate is safe: only deduplicates, never deletes unique entries.
- llm_tidy is destructive: review the plan before applying.
- Preserve user voice: when updating preferences, keep original phrasing.
- Never fabricate: don't add entries just to make the count look better.
