memory-cleanup

name	memory-cleanup
description	Audits all memory systems in a Perseus environment, identifies stale or superseded stores (Mem0, Mempalace, old vector DBs, garbled federation artifacts), and deletes them. Keeps Perseus Mneme (the live system) as the single source of truth. Run periodically or when upgrading Perseus versions.
tags	["maintenance","memory","cleanup","housekeeping"]
requires	[]

Memory Cleanup Skill

Audits and purges stale memory systems from a Perseus environment, keeping Perseus Mneme as the single source of truth. Run after upgrading Perseus, after switching memory backends, or whenever memory feels noisy.

---

Philosophy

Retaining old context is not as important as staying on the latest tooling and pushing the envelope. Old memory systems accumulate noise, cause federation artifacts, and slow down recall. When in doubt, delete.

The live Perseus Mneme index (~/.perseus/memory/) is always the source of truth. Everything else is a candidate for removal.

---

Trigger Phrases

• "clean up memory"
• "purge stale memory systems"
• "memory cleanup"
• "reflect and clean"
• "audit memory"

---

Workflow

Step 1 — Audit All Memory Locations

Check for the following known memory system locations:

# Perseus (live — keep)
ls -lht ~/.perseus/memory/        # Mneme BM25 index files
ls -lht ~/.perseus/checkpoints/   # Session waypoints

# Rovo Dev sessions (live — keep)
ls ~/.rovodev/sessions/
ls ~/.codex/memories/

# Stale systems (candidates for deletion)
ls ~/.mem0/                       # Mem0 library (superseded by Mneme)
ls ~/.mempalace/                  # Mempalace (superseded by Mneme)
ls ~/.cache/chroma/               # Orphaned Chroma vector stores
ls ~/.cache/code-nemo/            # Nemo memory (if present)
ls ~/.local/share/perseus/        # Old single-file perseus installs

Report findings in a table:

Location	Last Modified	Size	Status
~/.perseus/memory/	{date}	{N} files	✅ Live — keep
~/.perseus/checkpoints/	{date}	{N} files	✅ Live — keep
~/.mem0/	{date}	{size}	🗑️ Stale — delete
~/.mempalace/	{date}	{size}	🗑️ Stale — delete
~/.cache/chroma/	{date}	{size}	⚠️ Check — may be active

---

Step 2 — Check for Garbled Federation Artifacts

Perseus @memory with federation enabled can write low-quality blended content from other workspaces. Check the newest memory files:

ls -lt ~/.perseus/memory/ | head -5

For each file written in the current session, read the first 5 lines. If the content is incoherent, references unknown projects, or contains placeholder text ([... Table Continuation ...], Subagent:, etc.), it is a garbled federation artifact — delete it.

Flag: any file where the content does not match your actual work context.

---

Step 3 — Check for Stale Venv Installs

Old Perseus venvs can accumulate stale perseus.py files that shadow the installed package:

find ~ -path "*/site-packages/perseus.py" 2>/dev/null

If found, check the version:

head -5 {path}/perseus.py   # look for version comment

If older than the system Perseus version (perseus --version), delete the stale file and reinstall in the venv:

# delete via delete_file tool, then:
{venv}/bin/pip install --force-reinstall perseus-ctx

---

Step 4 — Delete Confirmed Stale Files

Use delete_file for each stale file identified. Do not use bash rm — use the delete_file tool to maintain audit trail.

Always delete:

• ~/.mem0/ — entire contents (Mem0 library, superseded by Perseus Mneme)
• ~/.mempalace/ — entire contents (Mempalace, superseded by Perseus Mneme)
• Any garbled federation artifacts in ~/.perseus/memory/
• Stale perseus.py in venv site-packages (see Step 3)

Check before deleting:

• ~/.cache/chroma/ — may be used by active tools (check config first)
• ~/.local/share/perseus/ — used by launchd watchdog scripts; update rather than delete

Never delete:

• ~/.perseus/memory/ — live Mneme index
• ~/.perseus/checkpoints/ — session waypoints
• ~/.perseus/config.yaml — configuration
• ~/.rovodev/AGENTS.md — rendered context
• ~/.codex/ — Rovo Dev session index

---

Step 5 — Verify Clean State

After deletions, confirm:

ls ~/.mem0/ 2>/dev/null || echo "mem0: clean ✅"
ls ~/.mempalace/ 2>/dev/null || echo "mempalace: clean ✅"
ls ~/.perseus/memory/ | wc -l   # should be same count minus deleted artifacts

Report final state:

Memory Cleanup Complete
═══════════════════════
✅ ~/.perseus/memory/    — {N} files (live Mneme index)
✅ ~/.perseus/checkpoints/ — {N} files (session waypoints)
🗑️  ~/.mem0/             — deleted ({N} files)
🗑️  ~/.mempalace/        — deleted ({N} files)
🗑️  {garbled files}     — deleted ({N} files)

Single source of truth: Perseus Mneme ✅

---

Cadence

Trigger	When
After Perseus version upgrade	Always
After switching memory backends	Always
Weekly maintenance	Optional — run with reflect
When memory feels noisy or federated content is garbled	On demand

---

Live-Store Hygiene Is Automatic — Not Part of This Skill

This skill removes stale external/competing memory backends. Hygiene of the live Perseus Vault store (decay, archiving, dedup, consolidation) is a separate, scheduled, non-LLM mechanism — do not try to prune the live store by hand from this skill.

• One-command enable (nightly pass + weekly VACUUM): perseus cron create --job maintain --install (on native Windows: perseus schtasks create --job maintain --install, and cron create --install auto-routes there)
• Preview what hygiene would do (zero mutation): perseus vault maintain --dry-run
• Config: the hygiene: block in ~/.perseus/config.yaml (master switch off by default; dry_run: true bakes a report-only first week into the scheduled entry).

Everything the pass does is a reversible archive — verified/pinned memories are never auto-archived, and hard deletion is never scheduled.

---

Known Stale Systems (as of 2026-05-27)

System	Location	Status	Superseded By
Mem0	~/.mem0/	Deprecated	Perseus Mneme
Mempalace	~/.mempalace/	Deprecated	Perseus Mneme
Chroma (standalone)	~/.cache/chroma/	Check context	Perseus Mneme
Code-Nemo	~/.cache/code-nemo/	Check context	Perseus Mneme
Old single-file perseus	~/.local/share/perseus/	Update, don't delete	pip install

---

Notes for Multi-Environment Use

When running this skill on a new Perseus environment (different machine or workspace), the stale system locations are the same but the active paths may differ. Always:

1. Run Step 1 audit first — don't assume the same stale systems exist
2. Confirm perseus --version and ~/.perseus/config.yaml are present before deleting anything
3. Check ~/.local/share/perseus/ — on some environments this is used by active launchd jobs and should be updated, not deleted

---

Part of the Perseus skill library. Compatible with Rovo Dev CLI, Claude Code, and any MCP-enabled assistant. See: https://github.com/Perseus-Computing-LLC/perseus