Drift (Snapshot Archive)

Overview

Drift is a lightweight file snapshot system. Every time an agent calls write_file, edit_file, or append_file with a reason, drift automatically saves a content-addressed copy of the file. If something goes wrong, you can roll back any tracked file to a previous state.

Unlike git, drift works for any file path — including system files like /etc/hosts or files outside git repos. It’s a safety net, not a version control system.

How It Works

Drift stores snapshots in a single global archive at ~/.arma/drift/ (your home directory, shared across all projects):

~/.arma/drift/
├── index.json              # Manifest — maps file paths to snapshot entries
└── content/
    ├── a1b2c3d4...         # SHA256 content hash (deduplicated)
    └── e5f67890...

Each snapshot records:

Channel — which agent made the change
Path — the absolute file path
Reason — why the change was made (from the tool’s reason parameter)
Tool — which tool made the change (write_file, edit_file, append_file)
Timestamp — when the snapshot was taken
Hash — SHA256 of the file content (deduplicates identical content)

Automatic Snapshots

No explicit setup needed. When an agent runs:

edit_file: {"path": "src/auth.ts", "old_string": "...", "new_string": "...", "reason": "fixing-auth-timeout"}

Drift automatically:

Reads the file content after the edit
Computes its SHA256 hash
Stores the content in ~/.arma/drift/content/<hash> (deduplicated)
Appends an entry to ~/.arma/drift/index.json

Tools

Tool	Description
`drift_snapshot`	Explicitly save a snapshot of the current file state (with reason label)
`drift_snapshots`	List all snapshots, filterable by path or channel
`drift_status`	Show summary: total snapshots, storage size, tracked file paths
`drift_rollback <id>`	Restore a file to a previous snapshot state (also captures rollback as a new snapshot)
`drift_prune`	Remove old or stale snapshots. Supports `{ "days": 30 }` (age-based), `{ "staleOnly": true }` (files that no longer exist), or both.

Commands

Command	Description
`/drift status`	Show snapshot summary for current channel
`/drift snapshots`	List all snapshots with reasons and timestamps

Auto-Prune on Startup

Drift automatically prunes stale snapshots and enforces size limits on startup. Configure in ~/.armament/config.json:

{
  "drift": {
    "autoPruneStaleOnStart": true,
    "retentionDays": 90,
    "maxSizeBytes": 52428800
  }
}

Setting	Default	Description
`autoPruneStaleOnStart`	`true`	Remove snapshots for files that no longer exist on disk
`retentionDays`	`90`	Remove snapshots older than N days
`maxSizeBytes`	`52428800` (50MB)	Max total archive size. Oldest snapshots removed first when exceeded.

During startup, you’ll see a loading line:

Drift  ⟳ pruning, removing 5 stale snapshots, -4.2K (archive: 2 files, 1.2K)

This shows the number of snapshots pruned, space recovered, and current archive state.

Error Resilience

If the drift index becomes corrupted, drift automatically recreates it on the next operation. Snapshots are content-addressed, so no data is lost — only the index mapping is rebuilt from the content directory.

Use Cases

Safe exploration: Try a risky refactor knowing every edit is reversible
Multi-agent safety: Any channel can roll back changes made by another channel
Cross-project tracking: Works on any file path, not just git repos
Audit trail: Every change has a reason, channel, and timestamp

Storage

Drift uses SHA256 content-addressed storage — identical file content is stored only once. To manage growth:

Snapshots accumulate over time (deduplication keeps it compact)
drift_prune removes snapshots older than N days or for files that no longer exist
maxSizeBytes (default 50MB) auto-removes oldest snapshots when archive exceeds the limit
Drift works with any file, including binary files (though binary content is stored as-is)