--- name: mmxagent-guardian version: 1.0.3 description: Provide file protection while users work with openclaw. All file operations are version-indexed and support delete recovery and modification rollback. ---

File Protection and Version Management

This Skill uses MiniVCS to track all file operations with version history.

Runtime requirement: Python 3 is required to run scripts/minivcs/minivcs.py.

Script location: scripts/minivcs/minivcs.py in the same directory as this SKILL.md (Before executing, first determine the directory containing this file. It is referred to as $SKILL_DIR below.)

Core mechanism:

• Modify: Saves an incremental diff plus a full snapshot from before the modification, supporting rollback
• Delete: Moves the full file into ~/.openclaw/minivcs/trash/, supporting restore
• All files are indexed, with different retention periods based on importance
• After every operation, the full record table is scanned automatically to find expired records and ask the user for confirmation

Usage limitations:

• Binary files (images, PDFs, audio/video, etc.): Text diffs cannot be generated. For binary-file protection, MiniVCS stores a full local .bak copy instead. This applies to binary-file backup/rollback protection, and deletion protection also stores a full local copy in ~/.openclaw/minivcs/trash/. The user must be informed before the operation because storage usage may be relatively high.
• The first record cannot be rolled back: When a file is recorded for the first time, there is not yet any historical baseline, so that record has no snapshot. After that, each call to record_modify following an edit automatically saves a snapshot, allowing rollback to the state before any edit.
• Local storage notice: Protection data is stored locally under ~/.openclaw/minivcs/. This Skill does not provide encryption or remote sync.

---

Prerequisite Check: Confirm Python Is Installed

Before performing any operation, you must first check whether Python 3 is installed in the user's environment. This Skill requires Python 3 and should not run without it.

How to check

# macOS / Linux
python3 --version

# Windows (PowerShell)
python --version

• If the output is Python 3.x.x, it is installed and you can continue
• If it says command not found or is not recognized as an internal or external command, stop and tell the user that this Skill requires Python 3

Dependency boundary

If Python 3 is missing:

• Do not run dependency installation commands from this Skill
• Do not run remote install scripts such as curl | bash
• Do not write to shell config files such as ~/.zshrc or ~/.bash_profile
• Do not modify global environment variables on the user's behalf from this Skill
• Tell the user that Python 3 is required, and ask them to install it first or explicitly authorize a separate environment-setup flow

> Note: On some Windows systems the command is python, while on macOS/Linux it is python3. > In all commands below that use python, replace it with the correct command for the actual environment.

---

Retention Policy

| File Type | Retention Days | Decision Rule | |---------|---------|---------| | Important files | 14 days | System paths (/etc/, /root/, /usr/local/etc/, /opt/), user config directories (~/.ssh/, ~/.gnupg/, ~/.config/, ~/.openclaw/, ~/.kube/, ~/.docker/, ~/.aws/, ~/.azure/, ~/.local/share/), Windows system directories (C:\Windows\, C:\ProgramData\, C:\Program Files\), config files (.yaml/.toml/.env, etc.), entry files (main.py/index.ts, etc.) | | Normal files | 7 days | All other files |

When each record is created, the expireAt (expiration timestamp) and expireAtDatetime (human-readable time) fields are set automatically.

---

Excluded Paths (Auto-Skip)

Files whose path contains any of the following segments are automatically skipped by record_modify and record_delete. These are generated, vendored, or cache directories that should not be version-tracked:

node_modules, .git, __pycache__, .venv, venv, .tox, .mypy_cache, .pytest_cache, .ruff_cache, dist, build, .next, .nuxt, .turbo

When a file is skipped, the return value will contain "skipped": true and a "reason" field. The Agent should inform the user that the file was not tracked and explain why.

---

Binary File Size Warning

When a binary file exceeds 50 MB, the return value from record_modify (binary backup) will include:

• "sizeWarning": true
• "sizeWarningMessage": a human-readable description of the file size and threshold

When sizeWarning is present, the Agent must explicitly inform the user of the file size and ask for confirmation before proceeding with any further binary backup operations on similarly large files.

---

Operation Flow

Step 1: Initialize the MiniVCS Working Directory

On first use, the storage directory is created automatically. No extra action is required:

python "$SKILL_DIR/scripts/minivcs/minivcs.py" history --project-root <project_root>

All data is stored uniformly in ~/.openclaw/minivcs/:

~/.openclaw/minivcs/
  logs.json     # operation log (includes the expireAt field)
  diffs/        # incremental patches for text file modifications
  bases/        # baseline for the next comparison (named by full relative path, so no same-name conflicts)
  snapshots/    # full snapshots before text file modifications (used for rollback)
  trash/        # full backups of deleted files (used for restore)
  backups/      # full `.bak` copies of binary files (used for rollback)

---

Step 2: Ask the User for Confirmation Before the Operation

Before deleting or modifying a file, you must explain the following to the user and wait for confirmation:

1. The file path to be operated on
2. The operation type (modify / delete)
3. The purpose and intent of the operation
4. The possible impact
5. Explain the local storage behavior: this Skill stores protection data under ~/.openclaw/minivcs/
6. For text-file modifications, explain that MiniVCS stores diffs and snapshots so the file can be rolled back
7. For deletions, explain that MiniVCS stores a full local copy in ~/.openclaw/minivcs/trash/ so the file can be restored
8. If the file is binary, explicitly explain that protection uses a full local copy rather than a text diff, and ask whether the user wants that local copy to be stored before deletion or binary-file protection
9. If a binary backup returns sizeWarning: true, the Agent must display the file size and warning message to the user, and ask for explicit confirmation before proceeding

If the file is binary and the user does not want a local stored copy, do not treat the operation as a protected delete/rollback flow under this Skill.

If the path is auto-skipped (return contains "skipped": true), inform the user that the file was not tracked and state the reason.

Example before the operation:

I am about to operate on the following file. Please confirm:
- File: /path/to/file.py
- Operation: delete
- Reason: This file has been replaced by a newer version and is no longer used
- Impact: Need to confirm that no other module imports this file
- Local storage: A full local copy will be stored under ~/.openclaw/minivcs/trash/ so the file can be restored later
- Protection: The stored copy will be retained for 7 days (14 days for important files), and can be restored at any time during that period
Do you want to continue?

...