savemaintenance — Memory System Reconcile Pipeline

One-shot tool for keeping the three-tier memory system coherent. Cross-references the conversation log against files on disk, rebuilds the FTS5 index, runs a full audit. Zero external dependencies.

The Problem

The three-tier memory system (log → FTS5 index → files) is designed for consistency, but things drift:

• Files get deleted but their log entries remain (orphans)
• Files get added outside the save workflow but never get indexed
• The FTS5 index gets stale
• The topic map and stub index need regeneration

savemaintenance is the repair pipeline for all of the above. Run it weekly, or after any bulk operation on saved conversations.

Usage

# Copy the pipeline to the workspace
cp -r {baseDir}/. ~/.openclaw/workspace/savemaintenance/

# Dry run first — see what would change
cd ~/.openclaw/workspace/savemaintenance && python3 full-reconcile.py --dry

# Full repair: backup → reconcile → rebuild → audit
./run.sh

# Or run individual steps
python3 full-reconcile.py --step backup
python3 full-reconcile.py --step reconcile
python3 full-reconcile.py --step rebuild
python3 full-reconcile.py --step audit

What It Does

1. Backup

Copies conversation-log.md and topic-index.json to timestamped backups.

2. Reconcile

• Removes log entries where the .md file no longer exists
• Adds entries for .md files not in the log (reads # Title from file content)
• Sorts all entries by date descending
• Updates the header count

3. Rebuild

Regenerates the FTS5 index at /dev/shm/memory-index.db from scratch.

4. Audit

Reports: orphan entries, missing files, index coherence, directory hygiene.

Scripts

Snapshots

python3 snapshot.py                # Auto-timestamped snapshot
python3 snapshot.py take <tag>     # Named snapshot
python3 snapshot.py list           # List all snapshots

Snapshots go to backups/ by default.

Edge Cases Handled

• Empty log file — creates a fresh log from scratch
• New files added between runs — adds them without removing existing entries
• Deleted files still in log — entries are removed
• Renamed files — detected as "dead entry + new orphan" pair
• Dry run — preview changes without writing anything

Default Paths

Set OPENCLAW_WORKSPACE env var to override ~/.openclaw/workspace.

Dependencies

• Python 3.8+ (standard library only — no pip packages)
• SQLite3 FTS5 (bundled with Python)
• The save skill from ClawHub (for memory-index.py)