Context Guardian

Git-style version control for agent memory. Snapshot, diff, rollback — never lose context again.

Quick Start

# Take a snapshot of current memory state
python3 scripts/context-guardian.py snapshot

# List all snapshots
python3 scripts/context-guardian.py list

# Diff current state against a snapshot
python3 scripts/context-guardian.py diff --snapshot latest

# Rollback memory to a previous snapshot
python3 scripts/context-guardian.py rollback --snapshot 2026-04-05T060000

# Detect context loss (compare before/after compaction)
python3 scripts/context-guardian.py detect-loss

# Auto-backup setup (creates a cron job)
python3 scripts/context-guardian.py auto-backup --interval 6h

Commands

`snapshot` — Capture Memory State

Creates a timestamped snapshot of all context files:

• MEMORY.md, SOUL.md, USER.md, AGENTS.md
• All memory/*.md files
• HEARTBEAT.md, TOOLS.md, IDENTITY.md

Snapshots stored in memory/.context-snapshots/ as compressed JSON.

Options: --tag to name a snapshot, --files to snapshot specific files.

`list` — Browse Snapshot History

Shows all snapshots with timestamps, sizes, and tags.

Options: --limit for recent N, --verbose for file details.

`diff` — Compare Versions

Shows what changed between current state and a snapshot:

• Added lines (new information)
• Removed lines (potential context loss)
• Modified lines (changed information)
• File additions/deletions

Options: --snapshot , --file for specific file, --stat for summary only.

`rollback` — Restore Previous State

Restores memory files from a snapshot:

• Creates a pre-rollback snapshot first (safety net)
• Restores selected files or all files
• Shows what will change before applying

Options: --snapshot , --files for selective restore, --dry-run.

`detect-loss` — Context Loss Detection

Compares recent snapshots to identify information loss:

• Counts removed lines per file
• Flags files that shrunk significantly (>20% size decrease)
• Identifies specific lost content (dates, names, decisions, numbers)
• Reports preservation ratio (% of original content retained)

`auto-backup` — Scheduled Snapshots

Sets up automatic snapshots:

• Options: --interval <1h|6h|12h|24h>
• Configures an OpenClaw cron job
• Keeps last 30 snapshots (configurable with --keep )

`prune` — Clean Old Snapshots

Remove old snapshots to save space:

• --older-than — delete snapshots older than N days
• --keep — keep only the N most recent
• Always preserves tagged snapshots unless --include-tagged

How It Works

Snapshot Format

Each snapshot is a compressed JSON file containing:

{
  "id": "2026-04-05T060000",
  "tag": "pre-compaction",
  "timestamp": "2026-04-05T06:00:00Z",
  "files": {
    "MEMORY.md": { "hash": "sha256:...", "lines": 450, "size": 28000, "content": "..." },
    "memory/2026-04-05.md": { "hash": "sha256:...", "lines": 120, "size": 8400, "content": "..." }
  },
  "metadata": {
    "total_files": 25,
    "total_size": 180000,
    "agent_version": "4.2.0"
  }
}

Loss Detection Algorithm

1. Compare consecutive snapshots pairwise

2. For each file: compute line-level diff

3. Flag removals that contain high-value tokens (dates, numbers, proper nouns, decision keywords)

4. Calculate preservation ratio: (retained_high_value_lines / total_high_value_lines) × 100

5. Alert if preservation drops below 90%